ruvnet--ruview/docs/adr/ADR-045-amoled-display-support.md

ADR-045: AMOLED Display Support for ESP32-S3 CSI Node

Status

Proposed

Context

The ESP32-S3 board (LilyGO T-Display-S3 AMOLED) has an integrated RM67162 QSPI AMOLED display (536x240) and 8MB octal PSRAM that were unused by the CSI firmware. Users want real-time on-device visualization of CSI statistics, vital signs, and system health without relying on an external server.

Constraints

• Binary was 947 KB in a 1 MB partition — needed 8MB flash + custom partition table
• SPIRAM was disabled in sdkconfig despite hardware having 8MB PSRAM
• Core 1 is pinned to DSP (edge processing) — display must use Core 0
• Existing CSI pipeline must not be affected

Available APIs

Thread-safe edge APIs already exist (edge_get_vitals(), edge_get_multi_person()) — the display task only reads from these, no new synchronization needed.

Decision

Add optional AMOLED display support with the following architecture:

Hardware Abstraction Layer

• display_hal.c/h: RM67162 QSPI panel driver + CST816S capacitive touch via I2C
• Auto-detect at boot: probe RM67162 and check SPIRAM; log warning and skip if absent

UI Layer

• display_ui.c/h: LVGL 8.3 with 4 swipeable views via tileview widget
• Dark theme (#0a0a0f) with cyan (#00d4ff) accent for three.js-like aesthetic
• Views: Dashboard (CSI amplitude chart + stats), Vitals (breathing + HR line graphs), Presence (4x4 occupancy grid), System (CPU, heap, PSRAM, WiFi, uptime, FPS)

Task Layer

• display_task.c/h: FreeRTOS task on Core 0, priority 1 (lowest)
• LVGL pump loop at configurable FPS (default 30)
• Double-buffered draw buffers allocated in SPIRAM

Compile-Time Control

• CONFIG_DISPLAY_ENABLE=y (default): compiles display code, auto-detects hardware at boot
• CONFIG_DISPLAY_ENABLE=n: zero-cost — no display code compiled
• CONFIG_SPIRAM_IGNORE_NOTFOUND=y: boots fine on boards without PSRAM

Flash Layout

8MB partition table (partitions_display.csv):

• Dual OTA partitions: 2 x 2MB (supports larger binaries with LVGL)
• SPIFFS: 1.9MB (for future font/asset storage)
• NVS + otadata + phy: standard sizes

Core/Task Layout

Task	Core	Priority	Impact
WiFi/LwIP	0	18-23	unchanged
OTA httpd	0	5	unchanged
display_task	0	1	NEW — lowest priority
edge_task (DSP)	1	5	unchanged

Dependencies

• LVGL ~8.3 (via ESP-IDF managed components)
• espressif/esp_lcd_touch_cst816s ^1.0
• espressif/esp_lcd_touch ^1.0

Consequences

Positive

• Real-time on-device stats without network dependency
• Zero impact on CSI pipeline (display reads thread-safe APIs, runs at lowest priority)
• Graceful degradation: works on boards without display or PSRAM
• SPIRAM enabled for all boards (benefits WASM runtime too)
• 8MB flash + dual OTA 2MB partitions give headroom for future features

Negative

• Binary size increase (~200-300 KB with LVGL)
• SPIRAM + 8MB flash config is specific to T-Display-S3 AMOLED boards
• Boards with only 4MB flash need CONFIG_DISPLAY_ENABLE=n and the old partition table

Risks

• RM67162 init sequence is board-specific; other AMOLED panels may need different commands
• QSPI bus conflicts if other peripherals use SPI2_HOST (currently unused)

New Files

File	Purpose
main/display_hal.c/h	RM67162 QSPI + CST816S touch HAL
main/display_ui.c/h	LVGL 4-view UI
main/display_task.c/h	FreeRTOS task, LVGL pump
main/lv_conf.h	LVGL compile config
partitions_display.csv	8MB partition table
idf_component.yml	Managed component deps

Modified Files

File	Change
sdkconfig.defaults	8MB flash, SPIRAM, custom partitions
main/CMakeLists.txt	Conditional display sources + deps
main/main.c	+1 include, +5 lines guarded init
main/Kconfig.projbuild	"AMOLED Display" menu