LilyGo T5 S3 Pro / Pro Lite: own ED047TC2 waveform, boost-EN frontlight, and a real deep sleep

[jetaudio]

Everything here comes out of bringing the LilyGo T5 S3 Pro and Pro Lite up as a daily-driver reader. Most of it is board-specific, but three pieces are general and opt-in, so no other board changes behaviour unless its profile asks.

Both variants were tested on hardware. LILYGO publishes a schematic only for the Pro; the vendor states the variants share the core design, and the findings below held on both.

The panel was running on the wrong waveform

The board was using LovyanGFX's stock LUTs, whose fast bank drives only the two rails. Anti-aliasing greys had nowhere to land, so Panel_EPD::_draw_pixels() Bayer-dithered them to black — hard speckle along every glyph edge — and a clean refresh left pixels behind, because a two-level waveform never flashes both ways.

This adds a real ED047TC2 waveform (BoardT5S3/ED047TC2Waveform, generated by tools/gen_ed047tc2_waveform.py, selected against the panel temperature from the on-board thermistor), plus the driver seams it needs:

• LgfxEpdConfig::grayDark / grayLight — the canvas byte to write for a grey is a property of the board's LUT, not a constant. Panel_EPD quantises a canvas byte as (v + bayer - 8) >> 4, so only v == (level << 4) | 8 lands on one level for every Bayer cell; anything else alternates between two and shows as speckle. grayLevelByte() builds a safe value. Boards that set neither keep the even thirds the driver has always written.
• LgfxEpdConfig::grayNudgeInFastBank — true when the board's fast bank carries grey columns, which lets the grayscale push go out through the differential bank: no lut_eraser flash, and the same bank the B/W base used, so the per-pixel diff still skips what did not change. Left false elsewhere; those boards keep exactly the push they have today.
• displayGrayscaleFrame() / supportsGrayFrame() — a page and its greys reach the panel as one waveform. The two-push flow it replaces existed to normalize fringe pixels to black before a from-black grey nudge; grey columns are self-normalizing, so the base pass has nothing left to do and the page has no intermediate state to show. It also halves the drive imbalance per page turn. Falls back to a plain displayBuffer() where the driver cannot do it, or where output is inverted — the planes' meaning does not survive inversion.

A freeze worth flagging on its own

waitDisplay() can return before the refresh it was called for has begun. Panel_EPD::display() raises _display_busy, yields (vTaskDelay(1)), and only then posts the job; the yield lets the panel task reach the top of its loop, where it assigns _display_busy = remain unconditionally — false on an idle panel — clearing the flag the caller just raised. Between xQueueSend() returning and the task waking, the flag reads false for a refresh that has not started, so a caller that trusts it walks into the panel task's diff copy and tears it. Torn step state is how a pixel gets a step index that never terminates, remain never clears, and the next waitDisplay() blocks forever — the reader frozen with input still alive. settleDisplay() yields before waiting, so the task can ingest the job and re-raise the flag.

Board profile: the power latch is not real

The profile carried power.latch0 = GPIO2 with an M5Paper-style "main-power MOSFET, hold HIGH or the board dies on USB unplug" note. IO2 is nothing of the sort here: it is RTC_INT — the PCF8563's open-drain alarm output, pulled up through 10K — and the schematic shows no soft power latch anywhere. Power sequencing is the BQ25896's job, its /QON pin wired to the S4 button straight to ground.

holdPowerRails() drives latch pins OUTPUT HIGH first thing in setup(), so the stale entry had the firmware fighting the RTC's output on every alarm. Nothing had noticed while no alarm was armed — but now that the RTC is wired up (already on main), alarms and interrupts would simply never have been seen. latchConflictsWithBus() cannot catch this: it guards display and SD bus pins, and SensorsConfig carries no RTC interrupt pin to compare against.

The profile also gains a note at input.power that IO48 must not be mapped as Confirm — on the Pro Lite it reads spurious active-low pulses, which opened the reader menu by itself.

Deep sleep: the peripherals with no rail to cut

powerDownRailsForSleep() only ever cut rails, so a board with no gated rail was left alone entirely. Here that meant the GT911 kept scanning through deep sleep — several mA, on its own the difference between a milliamp-class and a microamp-class sleep.

Two holds fill the gap, both only where there is no rail to cut, and neither applied where the rail is cut (driving an input of an unpowered chip can back-power it through its protection diode):

• Touch parks in reset, opt-in per board via TouchConfig::holdResetInSleep rather than inferred from a missing powerEnable.
• SD chip-select is held deasserted, so a still-powered card idles deselected instead of floating into an undefined selection state once esp_sleep_config_gpio_isolate() runs.

gpio_hold_en survives the wake reset and a held pad silently swallows writes, so each hold has a matching release on the way back up — InputManager's GT911 and FT6336U bring-up now gpio_hold_dis() the reset pin before the reset dance, which would otherwise be a no-op leaving touch dead after the first wake, and only after a wake. SDCardManager::prepareForSleep() also unmounts cleanly, flushing SdFat's cache rather than leaving the card mid-transaction; boards that cut the SD rail want this too.

Frontlight on a boost converter

Here the PWM gates the EN pin of a PT4103 boost rather than driving the LEDs, which breaks two assumptions:

• Dimming. A boost emits no light for an on-time under its start-up window, so the dim end of a plain gamma curve falls below the physical floor and the light goes out — which is what blacked it at ordinary reading brightnesses. minHoldPermille remaps (0, full] onto [floor, full], keeping the curve's shape while making 1% the dimmest level the hardware can sustain; minStartPermille gives the off→on edge a brief burst at the ignition floor, since a boost sustains below the duty it can ignite from. Both default to zero — an identity mapping — so unconfigured boards are untouched. The PWM also runs at 1 kHz / 12-bit here; 13 bits made the attach fail outright.
• Sleep. off() writes a zero duty, but the pad still belongs to LEDC and sleep entry hands it to esp_sleep_config_gpio_isolate(), which floats it — what the light does then is down to an external pull (here, EN through a 100R). A frontlight left lit is the largest load a sleeping reader can carry, so prepareForDeepSleep() drives and latches it off, and begin() releases the hold on the next boot.

Notes for review

• Every general change is gated on a board-supplied field that defaults to the current behaviour: grayDark/grayLight, grayNudgeInFastBank, holdResetInSleep, minHoldPermille/minStartPermille. No other profile is touched.
• settleDisplay() is the one change that affects every LgfxEpdDriver board. 1.5.16 shipped this guard, 1.5.17 reverted it on a ghosting suspicion; the ghosting survived the revert, which clears it of that charge.
• docs/lilygo-t5s3-support.md is updated: it still listed the PCF8563 RTC and the capacitive home key as peripherals the SDK does not cover, though both landed in the profile earlier. The rest of the update covers what this PR adds.
• Builds clean for -e lilygo (Crosspoint firmware, ESP32-S3), and both variants were run on hardware.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AMRDM2sLYU4smqRpWH6fau