Skip to content

fix(headless): repair WebUI Navigator & serial mirror rendering under USE_DUMMY_TFT - #3114

Merged
bmorcelli merged 1 commit into
BruceDevices:devfrom
xleicheng:fix/headless-webui-render
Nov 19, 2026
Merged

bmorcelli merged 1 commit into
BruceDevices:devfrom
xleicheng:fix/headless-webui-render

Conversation

@xleicheng

@xleicheng xleicheng commented Nov 19, 2026 •

Copy link
Copy Markdown

Proposed Changes

Follow-up to #3095. After closing #3095, I tested both the official 1.17 release and the latest dev (fa6bcbf) on my headless ESP32-S3-WROOM-1 (N16R8). While boot/BLE fixes in 1.17+ worked, the WebUI Device Navigator and Companion App serial mirroring still suffered from severe rendering corruption under USE_DUMMY_TFT=1:

  • Menu icons & labels clipped on the sides (e.g., Channel Analyzer cut to Channel Anal).
  • drawOptions() menus (such as the Run in background / Exit prompt) overlapped vertically in a ~4px stack.
  • drawSubmenu() cards lost text centering, drew solid black boxes across rounded borders, and wiped half of the screen when scrolling.
  • MainMenu carousel/grid frames randomly disappeared or turned black due to ring-buffer wraparound and Z-order corruption.

Root Causes & Fixes (4 files):

  1. Fix inverted virtual panel dimensions (boards/ESP-General/ESP-General.ini)

    • esp32-s3-devkitc-1 set -DROTATION=1 without TFT_WIDTH/TFT_HEIGHT, falling back to precompiler_flags.h (240x135), which DisplayDrivers (dummy.h) and src/main.cpp swapped on odd rotation into a narrow 135x240 portrait canvas.
    • Explicitly defining -DTFT_WIDTH=240 and -DTFT_HEIGHT=320 with -DROTATION=1 produces the standard 320x240 landscape canvas.
  2. Fix virtual cursor & 1-arg transparent setTextColor under USE_DUMMY_TFT (include/tftLogger.h, src/core/tftLogger/tftLogger.cpp)

    • dummy.h's print()/println() never advances _cursorX/_cursorY, causing drawOptions() and setPadCursor() lines to stack every 4px. Added cursor/newline tracking inside tft_logger::print() guarded by #ifdef USE_DUMMY_TFT (physical display backends are untouched).
    • dummy.h's 1-arg setTextColor(c) leaves _textBgColor stale instead of transparent (c, c). Forwarded setTextColor(c) to (c, c) under #ifdef USE_DUMMY_TFT.
  3. Fix rect-invalidation height bug & text datum alignment (src/core/tftLogger/tftLogger.cpp)

    • log_drawString() and log_print() both multiplied the cleanup rectangle height by s.length() (s.length() * LH * currentTextSize()), wiping large portions of the screen below every label. Fixed both to use single-line LH * currentTextSize() and adjusted horizontal cleanup bounds for centered/right-aligned strings.
    • Normalized getTextDatum() (ML_DATUM, TC_DATUM, MC_DATUM, etc.) in log_drawString() so drawSubmenu() labels center properly inside rounded cards instead of shifting down across the bottom border.
  4. Fix ring-buffer replay order, Z-order & PSRAM log capacity (include/tftLogger.h, src/core/tftLogger/tftLogger.cpp)

    • Widened logWriteIndex and logCount from uint8_t to uint16_t and raised PSRAM MAX_LOG_ENTRIES from 64 to 256 (keeping asyncSerialQueue capped at 64 to avoid extra internal SRAM usage).
    • Fixed getBinLog() to replay entries in chronological ring-buffer order rather than raw index 0..logCount-1.
    • Updated pushLogIfUnique() to invalidate stale older duplicates and append at the tail so Z-order remains accurate across partial redraws.
  5. Fix WebUI Canvas text transparency & SCREEN_INFO switch fallthrough (embedded_resources/web_interface/index.js)

    • Added missing break; in case 99 (SCREEN_INFO) so it does not fall through into case 0 (FILLSCREEN) with input.fg === undefined.
    • Treated input.bg === input.fg as transparent text instead of forcing input.bg = 0 (which painted black boxes over highlight bars and card borders), used measured text width for opaque text backgrounds, properly stripped actual \n characters, and rounded color565toCSS RGB channels.

Visual Comparison (Before vs After)

Before (Official dev) After (Fixed)
Screenshot_2026-11-19-20-57-14-126_com android browser_1795093076945edit Screenshot_2026-11-19-21-15-49-182_com android browser-edit
Screenshot_2026-11-19-20-57-16-390_com android browser_1795093087602edit Screenshot_2026-11-19-21-16-20-104_com android browser-edit
1795094980138 1795094980226
1795094980190 1795094980235
1. WebUI Device Navigator

Before (dev fa6bcbf):

webui_dev.mp4

After (This PR):

webui_fix.mp4

2. Companion App (OTG Serial Mirror)

Before (dev fa6bcbf):

APP_dev.mp4

After (This PR):

APP_fixed.mp4

Types of Changes

  • Bugfix (non-breaking change which fixes headless WebUI & serial mirror UI rendering)

Verification

  • Hardware tested: ESP32-S3-WROOM-1 N16R8 (esp32-s3-devkitc-1-psram), tested standalone AP boot:
    • WebUI Device Navigator: Main menu carousel, Run in background / Exit (drawOptions), Bluetooth/WiFi submenus (drawSubmenu), BLE Spam parameter screen, and scrolling redraws all render cleanly with proper highlights and spacing.
    • Companion App OTG serial mirroring: Verified live screen mirroring renders cleanly without overlap or missing regions.
  • Cross-environment build verification:
    • pio run -e esp32-s3-devkitc-1-psram (PSRAM headless) — PASS
    • pio run -e esp32-s3-devkitc-1 (non-PSRAM headless) — PASS
    • pio run -e m5stack-cplus2 (physical TFT backend) — PASS

Testing

Verified manually on real ESP32-S3 N16R8 hardware and via multi-target PlatformIO compilation (esp32-s3-devkitc-1-psram, esp32-s3-devkitc-1, m5stack-cplus2).

Linked Issues

Follow-up to #3095

User-Facing Change

Fixed headless (`USE_DUMMY_TFT`) WebUI Device Navigator and serial mirror UI layout, clipping, alignment, and redraw corruption.

Further Comments

Hi @bmorcelli, following up on my promise in #3095 — I tested both 1.17 and latest dev on my headless ESP32-S3 N16R8 and tracked down the exact root causes behind the distorted WebUI Navigator & mirror rendering. All headless cursor/color workarounds are isolated under #ifdef USE_DUMMY_TFT so physical-display boards remain unaffected. Happy to adjust anything if needed!

@bmorcelli
bmorcelli merged commit a84de96 into BruceDevices:dev Nov 19, 2026
8 checks passed
@xleicheng

Copy link
Copy Markdown
Author

Thanks for reviewing and merging, @bmorcelli! ❤️

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants