# Waveshare ESP32-S3-RLCD-4.2 Initialization Race & Freeze Audit (2026-07-14)

## Overview
RLCD board (`waveshare-esp32-s3-rlcd`) suffered random freeze "stuck on weird state" requiring hard reset. Serial log triage via pyserial (15s capture) showed no Guru Meditation, only warnings. Root causes found in 3 layers: I2C driver CONFLICT, ES8311 codec blocking boot, ST7305 reset timing.

## File Map
- `Devices/waveshare-esp32-s3-rlcd/waveshare,esp32-s3-rlcd.dts` — devicetree, defines i2c0, spi0, sdmmc0, i2s0, gpio0
- `Devices/waveshare-esp32-s3-rlcd/Source/Configuration.cpp` — `initBoot()` powers amp GPIO46 + ES8311 init, `createDevices()` display + TwoButtonControl(GPIO18 KEY, GPIO0 BOOT)
- `Drivers/ST7305/Source/St7305Display.h/.cpp` — SPI display driver, reset pin GPIO41, CS 40, DC 5, SPI2 10MHz, `full_refresh=true`, buffer 120k (400x300), `monochrome=true`, `trans_size=0`
- `Tactility/Source/service/displayidle/DisplayIdle.cpp` — idle timer + wake logic (50d86de4 fix: run for all displays)

## Initialization Sequence (from serial log)

1. Bootloader 2nd stage → PSRAM 8MB 120MHz detected
2. `kernel: init` → `module: start waveshare-esp32-s3-rlcd` → `module: start platform-esp32`
3. `driver: add esp32_gpio, esp32_i2c, esp32_i2c_master, esp32_i2s, esp32_sdmmc, ...` — both legacy and NG I2C drivers registered
4. `device: start i2c0` → `esp32_i2c_master: start i2c0` (after fix) vs previously `esp32_i2c: start i2c0`
5. `E (907) i2c: CONFLICT! driver_ng is not allowed to be used with this old driver` — IDF 5.x forbids mixing old `i2c_driver_install` and new `i2c_new_master_bus` on same peripheral. Warning appears even when only one instance uses I2C0, because platform-esp32 registers both driver types globally. Benign after migration but indicates legacy driver still loaded.
6. `gpio: GPIO[13] InputEn:1 OutputEn:1 OpenDrain:1` / GPIO14 — I2C pins
7. `esp32_sdmmc_fs: Mounted /sdcard` — SD 1-bit, CLK 38, CMD 21, D0 39, D3 17
8. `SystemEvents: BootInitHalBegin` → `gpio46 HIGH` amp enable
9. `WaveshareRLCD: ES8311 codec initialized` (after 3770ac89 fix) vs previously missing or failed
10. `Devices: Registering ST7305` → `Hal: ST7305 starting` → `ST7305: Starting SPI panel IO creation` → `Hal: ST7305 started` (2160ms with delays vs 1828ms before)
11. `Tactility: DEBUG: Listing /sdcard` → `NTP: Restoring last known time`
12. `Bluetooth: Auto-enabling BLE` → `BLE host task started` + `GAP procedure...` + `startAdvertising: set_fields failed rc=4` (benign)
13. `ServiceRegistration: Adding Gps/wifi/Development/EspNow/WebServer` → `WebServerService: AP started SSID Tactility-5C7D 192.168.4.1` + `HttpServer Started port 80`
14. `McpSystem: Mono TCP Video stream server started 8081` + Color 8083
15. `LVGL: Starting LVGL task` → `Started ST7305` + `ButtonControl: Start`
16. `DisplayIdle: Monochrome/RLCD display detected: idle timer will run but auto-backlight off is disabled`
17. `Boot: Setup display` / `Boot: No backlight` → `Tactility: Registering internal apps` → `Loader: Start by id Launcher` → `GuiService: Showing Launcher`
18. `WifiBootSplashInit: Auto-enabling WiFi` → `WifiService: Enabled` → `STA_START` — auto-connects if SD has credentials

## Root Causes & Fixes (3770ac89 + 50d86de4)

### 1. I2C CONFLICT — legacy vs NG driver
**Before:**
```dts
#include <tactility/bindings/esp32_i2c.h>
i2c0 { compatible = "espressif,esp32-i2c"; port = <I2C_NUM_0>; ... }
```
- Platform registers both `esp32_i2c` (old) and `esp32_i2c_master` (new) drivers
- When i2c0 used old driver, IDF warns CONFLICT if any component uses `driver_ng` (i2c_master internal) — happens because `esp32_i2c_master` driver also calls NG API
- Could stall I2C bus if codec init fails

**After (3770ac89):**
```dts
#include <tactility/bindings/esp32_i2c_master.h>
i2c0 { compatible = "espressif,esp32-i2c-master"; port = <I2C_NUM_0>; clock-frequency = <400000>; pin-sda = <&gpio0 13>; pin-scl = <&gpio0 14>; }
```
- Now uses master driver, `esp32_i2c_master: start i2c0` in log, ES8311 initializes
- Warning `E i2c: CONFLICT!` still appears because platform still registers legacy driver type globally — upstream should remove legacy registration if all boards migrated, but not fatal after this fix
- Commit 3770ac89: 0x2b79c0 32% free

### 2. ES8311 Codec Init Blocking Boot
**Before:**
```cpp
auto* i2c_bus = device_find_by_name("i2c0");
if (i2c_bus) { error_t e = initCodec(i2c_bus); if (e!=NONE) LOG_E(...); }
```
- If ES8311 at 0x18 not responding (no pullups, power not stable), `i2c_controller_write_register_array` blocks 1s timeout per transaction, could lock bus → freeze

**After:**
```cpp
vTaskDelay(100ms); // after GPIO46 amp HIGH, power stabilize
if (i2c_controller_has_device_at_address(bus, 0x18, 200ms)==NONE) {
  initCodec(bus); // non-fatal, logs success
} else {
  LOG_W("ES8311 not found at 0x18, skipping");
}
```
- Probe first, non-fatal, 100ms delay for amp power, 200ms probe timeout
- Prevents bus lock if codec missing

### 3. ST7305 Reset Race — SPI Too Early

**Before:**
```cpp
esp_lcd_panel_reset(panelHandle);
esp_lcd_panel_init(panelHandle); // no delay
```

**After (Drivers/ST7305/Source/St7305Display.cpp):**
```cpp
esp_lcd_panel_reset(panelHandle);
vTaskDelay(150ms); // ST7305 datasheet needs >120ms after reset
esp_lcd_panel_init(panelHandle);
vTaskDelay(50ms);
```
- Prevents freeze on fast boot where SPI transaction sent before panel ready, leaving display stuck on garbage / weird state
- Observed `Hal: ST7305 started` time 1828ms → 2160ms (+330ms)

### 4. DisplayIdle Wake Logic Gated by supportsBacklight (50d86de4)

**Before (after MCP flash fix):**
```cpp
if (supportsBacklight) { if (!timeoutEnabled) restore else { if (inactive>=timeout) activate else if (dimmed) wake } }
```
RLCD `supportsBacklight==false` → entire idle/wake state machine skipped → once `displayDimmed=true`, never wakes → appears locked.

**After:**
Timeout logic runs for ALL displays, only `setBacklightDuty()` guarded by `supportsBacklight && display != nullptr`. See `references/display-idle.md`.

## Pin Conflicts to Watch

- GPIO9: ES3C28P BAT_ADC (ADC1_CH8) vs RLCD I2S BCLK pin 5 (not 9, but ES3C uses GPIO9 free, check DTS `pin-bclk` before reusing)
- I2C0 SDA 13 / SCL 14 — shared with nothing else on RLCD, but must be `i2c-master` compatible
- SPI0: CS 40, MOSI 12, SCLK 11, DC 5, RST 41 — exclusive
- SDMMC: CLK 38, CMD 21, D0 39, D3 17, 1-bit

## Screenshot Lock Contention + Permanent Freeze Related (fixed 6f095081)

See `references/mcp-system.md` + `references/display-idle.md` Screenshot Lock Contention + 50d86de4/6f095081 sections. Same root: ST7305 full_refresh heavy SPI copy holds LVGL lock 100ms, `handleApiScreenshot` 100ms timeout too short → `could not acquire LVGL lock` error. Also "screen is still showing the freezed image" even after 3770ac89 init fixes — cause was screensaver heavy animation auto-enter + video stream 5ms hog.

Fixes 6f095081 (build 0x2b79e0, same size, flashed):
- Screenshot API 100→500ms (WebServerService) + error msg "within 500ms"
- ScreenshotTask 50→300ms
- Video stream 5ms→30ms streaming, 50ms→100ms idle with comment "RLCD ST7305 SPI is slow and shared"
- DisplayIdle: for !supportsBacklight (RLCD) don't auto-enter screensaver, only wake — prevents heavy bouncing balls full_refresh that freezes
- Power cycle required to clear ST7305 RAM (RTS reset doesn't clear controller RAM, frozen image persists until USB unplug 3s)
- Verification 14 checks PASS hermes-verify-jw_55oxm.py

## Verification

- Serial log via pyserial 15-20s: check `CONFLICT` gone or benign, `ES8311 codec initialized`, `Hal: ST7305 started` ~2160ms, `Monochrome/RLCD detected`, no `Guru Meditation`, AP `Tactility-5C7D` up
- Ad-hoc script 16 checks PASS (DTS master, probe, delays, wake logic, MCP guard, build artifact)
- Build: `waveshare-esp32-s3-rlcd 0x2b79c0 32% free` flashed `/dev/cu.usbmodem101`

## Recommendations

1. For RLCD, default `displayTimeout = 0 (Never)` or `ScreensaverType::None` to avoid heavy bouncing balls full_refresh (120k pixels * SPI 10MHz = ~96ms per frame blocks UI)
2. Upstream: remove legacy `esp32_i2c` driver registration from platform-esp32 if all boards migrated to master, to eliminate CONFLICT warning entirely
3. Consider `trans_size` or partial refresh for ST7305 to reduce LVGL hold time, or lower SPI queue depth from 10 to 3