feat(t5s3-epaper): add InkHUD port for LilyGo T5 E-Paper S3 Pro#10211
Merged
thebentern merged 20 commits intomeshtastic:developfrom Apr 21, 2026
Merged
feat(t5s3-epaper): add InkHUD port for LilyGo T5 E-Paper S3 Pro#10211thebentern merged 20 commits intomeshtastic:developfrom
thebentern merged 20 commits intomeshtastic:developfrom
Conversation
Add a NicheGraphics EInk driver adapter for the 4.7" ED047TC1 parallel e-paper display used on the T5-E-Paper-S3-Pro (H752-01). The driver wraps FastEPD and handles the polarity difference between InkHUD's buffer format (0xFF = white) and FastEPD's (0x00 = white). Rewrite variants/esp32s3/t5s3_epaper/nicheGraphics.h which was an incomplete copy of the Heltec VM-E290 setup referencing undefined SPI pin macros and a non-existent BUTTON_PIN_SECONDARY. The board uses a parallel display, not the small SPI DEPG0290BNS800 that was referenced.
When MESHTASTIC_EXCLUDE_INPUTBROKER is defined (e.g. InkHUD builds), inputBroker is nullptr. Calling inputBroker->registerSource() in that state caused a LoadProhibited panic on any board that has both HAS_TOUCHSCREEN=1 and the InputBroker excluded. Add a null check before registerSource() to prevent the crash.
Set rotation=3 (270° CW) in nicheGraphics.h to correct for FastEPD scanning the ED047TC1 panel in portrait orientation, resulting in correct landscape display output.
…for InkHUD and FastEPD
…st safe-area dimensions
… displays Add Win1253-encoded FreeSans 18pt and 24pt font headers to support Greek script on larger InkHUD screens (e.g., the 4.7" ED047TC1 at ~234 DPI). Register FREESANS_24PT_WIN1253 and FREESANS_18PT_WIN1253 macros in AppletFont.h. Set fontLarge=24pt, fontMedium=18pt, fontSmall=12pt in nicheGraphics.h for the T5-E-Paper-S3-Pro.
Replace fullUpdate(CLEAR_FAST) with partialUpdate() for FAST display updates. FastEPD's partialUpdate() diffs pCurrent against pPrevious and only applies the update waveform to rows that have changed, leaving unchanged rows with a neutral signal. This reduces visible flicker on routine updates (new messages, position changes) — only the affected region of the screen refreshes. Full-screen CLEAR_SLOW updates are preserved for periodic ghosting cleanup, driven by InkHUD's setDisplayResilience() ratio.
Wire up BOARD_BL_EN (GPIO11) to InkHUD's LatchingBacklight driver. Enable the backlight menu item so users can toggle "Keep Backlight On" via Settings. The backlight turns on automatically when the menu opens and off when it closes.
- variant.h used PCF85063_RTC but the board has a PCF8563. The difference
is the RAM register: PCF85063 has 1 byte of RAM; PCF8563 does not. The
PCF85063 driver was trying to write this register on init, failing every
time, and setDateTime writes were silently discarded — RTC time was
never persisted across reboots. Switch to PCF8563_RTC/PCF8563_INT.
Before:
[E][SensorPCF85063.hpp:375] initImpl(): Failed to write to RAM memory
register. Maybe this chip is pcf8563.
Read RTC time from PCF85063 getDateTime as 2026-04-05 00:00:23
PCF85063 setDateTime 2026-04-05 18:40:59
Read RTC time from PCF85063 getDateTime as 2026-04-05 00:00:19 ← lost
After:
PCF8563 found at address 0x51
Read RTC time from PCF8563 getDateTime as 2026-04-05 18:58:37 ← persisted
PCF8563 setDateTime 2026-04-05 18:58:44
Read RTC time from PCF8563 getDateTime as 2026-04-05 18:58:44 ← round-trips
- GT911 touch was initialized with GT911_SLAVE_ADDRESS_L (0x5D), which
collides with the SFA30 air quality sensor also at 0x5D on the same
I2C bus. Switch to GT911_SLAVE_ADDRESS_H (0x14): the library drives
INT high during reset to program the GT911 to address 0x14,
eliminating the address conflict.
Before:
SFA30 found at address 0x5d
[I][TouchDrvGT911.hpp:568] initImpl(): Try using 0x5D as the device address
After:
SFA30 found at address 0x5d
[I][TouchDrvGT911.hpp:544] initImpl(): Try using 0x14 as the device address
Investigation findings
----------------------
Boot logs showed "SFA30 found at address 0x5d" on every cold power-on,
and AirQualityTelemetry was registering an SFA30 sensor. However, every
readMeasuredValues() call returned error 268 (0x010C = Sensirion
WriteError | I2cAddressNack), meaning the I2C write to 0x5D was being
NACK'd — inconsistent with a real SFA30.
Root cause: the GT911 touch controller latches its I2C address from the
INT pin level at reset time (GT911 datasheet §4.3). GPIO3 (INT) defaults
LOW on ESP32-S3 cold boot → GT911 always powers up at 0x5D
(SLAVE_ADDRESS_L). The I2C scanner runs before lateInitVariant() had a
chance to reprogram the chip.
The scanner's SFA30 detection (ScanI2CTwoWire.cpp) sends the 2-byte
command 0xD060 to 0x5D and requests 48 bytes back. GT911 ACKs the
write (treating it as a register address) and returns 48 bytes of
register data, passing the length check — a false-positive SFA30
detection.
Confirmed via second cold-boot log: after the previous commit moved GT911
to 0x14 in lateInitVariant(), address 0x5D *still* appeared in the scan
because the scanner runs first. The board has no physical SFA30 fitted.
Fix
---
Add the GT911 address-latch reset sequence to earlyInitVariant(), before
Wire is initialised and before the I2C scan runs. Per the datasheet:
drive RST LOW, drive INT HIGH (selects address 0x14 / SLAVE_ADDRESS_H),
hold >100 µs, release RST, wait >5 ms startup. GPIO-only, no Wire
dependency. lateInitVariant() then repeats this sequence internally via
touch.begin(); the double-reset is harmless.
Verified in boot log:
Before: "SFA30 found at address 0x5d", 5 I2C devices, NACK errors
After: no SFA30 entry, 4 I2C devices (TCA9535/PCF8563/BQ27220/BQ25896),
GT911 found at 0x14 and touch initialised successfully,
AirQualityTelemetry registers no sensors (correct — no SFA30 present)
Put GT911 into low-power standby (command 0x05) and drive BOARD_BL_EN LOW before deep sleep to avoid unnecessary current draw.
readTouch() now transforms raw GT911 axes to visual-frame coordinates based on the current display rotation (rotation=3 is the hardware identity). This ensures TouchScreenBase detects swipe direction correctly regardless of which rotation the user has selected. TouchInkHUDBridge dynamically sets joystick.alignment = (4-rotation)%4 on each touch event so that (rotation+alignment)%4==0 always, keeping nav calls pass-through without remapping. nicheGraphics.h now calls loadSettings() first so that rotation is persisted across reboots. rotation=3 and other first-boot defaults are only applied when tips.firstBoot is set. alignment is recomputed from the loaded rotation on every boot. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
touch.sleep() was called from variant_shutdown(), which runs inside cpuDeepSleep() — after Wire.end() had already torn down the I2C bus in doDeepSleep(). This caused Wire NULL TX buffer errors and left the GT911 awake during deep sleep. Register a CallbackObserver on notifyDeepSleep, which fires before Wire.end(), so the I2C command reaches the chip while the bus is live. Pattern matches LatchingBacklight and other NicheGraphics components. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Enable joystick mode post-begin so menu scroll and swipe-up/down gestures are not silently dropped by the joystick.enabled gate in Events.cpp. Activate DMs and Channel 0/1 applets with correct autoshow defaults matching the mini-epaper-s3 reference pattern. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
github-actions
Bot
added
the
hardware-support
This was referenced Apr 19, 2026
HarukiToreda
added
device-screen
Contributor
There was a problem hiding this comment.
Pull request overview
Adds InkHUD firmware support for the LilyGo T5 E-Paper S3 Pro by introducing a FastEPD-backed parallel e-paper driver, variant-specific initialization (touch, sleep, backlight), and larger Win1253 font options suitable for the 4.7" panel.
Changes:
- Added a new NicheGraphics E-Ink driver adapter for the ED047TC1 (FastEPD, parallel 960×540 with safe-area margins).
- Implemented T5-S3-ePaper-Pro variant wiring/init updates (GT911 address latch, InkHUD touch bridging, deep-sleep hooks, RTC macro fix).
- Hardened touchscreen initialization for builds where
inputBrokeris not instantiated; added larger Win1253 font macros for InkHUD.
Reviewed changes
Copilot reviewed 7 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| variants/esp32s3/t5s3_epaper/variant.h | Updates RTC defines to PCF8563 and contains board capability/pin definitions. |
| variants/esp32s3/t5s3_epaper/variant.cpp | Adds GT911 address-latch init, InkHUD touch event bridging, deep-sleep observer, and backlight shutdown hook. |
| variants/esp32s3/t5s3_epaper/nicheGraphics.h | Configures InkHUD for the ED047TC1 panel, applets, fonts, rotation/alignment, and backlight control. |
| src/input/TouchScreenImpl1.cpp | Adds null-guard when registering with inputBroker to avoid crashes when it’s not created. |
| src/graphics/niche/InkHUD/AppletFont.h | Adds 18pt/24pt Win1253 font macros for larger InkHUD displays. |
| src/graphics/niche/Drivers/EInk/ED047TC1.h | Declares the new FastEPD-backed ED047TC1 driver adapter and safe-area constants. |
| src/graphics/niche/Drivers/EInk/ED047TC1.cpp | Implements FastEPD initialization and safe-area blitting into the physical buffer for updates. |
Addressing PR review comments: Remove beginPolling(1, 0) after the blocking FastEPD update — it incorrectly set updateRunning=true for one loop cycle after the hardware was already done, causing busy() to briefly return true. Since isUpdateDone() always returns true, no polling is needed. Also fix stale comments: safe-area buffer size was 944×532, now 944×523; V_OFFSET_ROWS didn't exist, replaced with the actual V_OFFSET_TOP=9 / V_OFFSET_BOTTOM=8 constant names.
The InkHUD base config pulls in all of src/graphics/niche/ so every InkHUD device compiled ED047TC1.cpp, triggering the #error on line 48 for boards that define neither T5_S3_EPAPER_PRO_V1 nor V2. Wrap the file body with #ifdef T5_S3_EPAPER_PRO so it is only compiled for T5S3 targets. The #error is preserved inside the guard to catch future hardware revisions that forget to update the driver. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
thebentern
pushed a commit
that referenced
this pull request
Apr 21, 2026
* niche: add InkHUD port for LilyGo T5-E-Paper-S3-Pro (ED047TC1)
Add a NicheGraphics EInk driver adapter for the 4.7" ED047TC1 parallel
e-paper display used on the T5-E-Paper-S3-Pro (H752-01). The driver
wraps FastEPD and handles the polarity difference between InkHUD's
buffer format (0xFF = white) and FastEPD's (0x00 = white).
Rewrite variants/esp32s3/t5s3_epaper/nicheGraphics.h which was an
incomplete copy of the Heltec VM-E290 setup referencing undefined SPI
pin macros and a non-existent BUTTON_PIN_SECONDARY. The board uses a
parallel display, not the small SPI DEPG0290BNS800 that was referenced.
* fix: guard inputBroker null dereference in TouchScreenImpl1::init()
When MESHTASTIC_EXCLUDE_INPUTBROKER is defined (e.g. InkHUD builds),
inputBroker is nullptr. Calling inputBroker->registerSource() in that
state caused a LoadProhibited panic on any board that has both
HAS_TOUCHSCREEN=1 and the InputBroker excluded.
Add a null check before registerSource() to prevent the crash.
* niche: fix display rotation for T5-E-Paper-S3-Pro InkHUD port
Set rotation=3 (270° CW) in nicheGraphics.h to correct for FastEPD
scanning the ED047TC1 panel in portrait orientation, resulting in
correct landscape display output.
* fix: update buffer format descriptions and remove polarity inversion for InkHUD and FastEPD
* fix: update ED047TC1 driver to handle inactive pixel borders and adjust safe-area dimensions
* fix: comment out ruler diagnostic for E-Ink driver
* feat: implement TouchInkHUDBridge for direct touch event handling in InkHUD
* niche: add FreeSans 18pt/24pt Win1253 (Greek) fonts for larger InkHUD displays
Add Win1253-encoded FreeSans 18pt and 24pt font headers to support Greek
script on larger InkHUD screens (e.g., the 4.7" ED047TC1 at ~234 DPI).
Register FREESANS_24PT_WIN1253 and FREESANS_18PT_WIN1253 macros in AppletFont.h.
Set fontLarge=24pt, fontMedium=18pt, fontSmall=12pt in nicheGraphics.h for the
T5-E-Paper-S3-Pro.
* feat(ed047tc1): use true partial update for FAST refresh
Replace fullUpdate(CLEAR_FAST) with partialUpdate() for FAST display
updates. FastEPD's partialUpdate() diffs pCurrent against pPrevious
and only applies the update waveform to rows that have changed, leaving
unchanged rows with a neutral signal.
This reduces visible flicker on routine updates (new messages, position
changes) — only the affected region of the screen refreshes. Full-screen
CLEAR_SLOW updates are preserved for periodic ghosting cleanup, driven
by InkHUD's setDisplayResilience() ratio.
* feat(t5s3-epaper): enable frontlight via LatchingBacklight
Wire up BOARD_BL_EN (GPIO11) to InkHUD's LatchingBacklight driver.
Enable the backlight menu item so users can toggle "Keep Backlight On"
via Settings. The backlight turns on automatically when the menu opens
and off when it closes.
* Fix RTC chip (PCF8563 not PCF85063) and GT911 I2C address collision
- variant.h used PCF85063_RTC but the board has a PCF8563. The difference
is the RAM register: PCF85063 has 1 byte of RAM; PCF8563 does not. The
PCF85063 driver was trying to write this register on init, failing every
time, and setDateTime writes were silently discarded — RTC time was
never persisted across reboots. Switch to PCF8563_RTC/PCF8563_INT.
Before:
[E][SensorPCF85063.hpp:375] initImpl(): Failed to write to RAM memory
register. Maybe this chip is pcf8563.
Read RTC time from PCF85063 getDateTime as 2026-04-05 00:00:23
PCF85063 setDateTime 2026-04-05 18:40:59
Read RTC time from PCF85063 getDateTime as 2026-04-05 00:00:19 ← lost
After:
PCF8563 found at address 0x51
Read RTC time from PCF8563 getDateTime as 2026-04-05 18:58:37 ← persisted
PCF8563 setDateTime 2026-04-05 18:58:44
Read RTC time from PCF8563 getDateTime as 2026-04-05 18:58:44 ← round-trips
- GT911 touch was initialized with GT911_SLAVE_ADDRESS_L (0x5D), which
collides with the SFA30 air quality sensor also at 0x5D on the same
I2C bus. Switch to GT911_SLAVE_ADDRESS_H (0x14): the library drives
INT high during reset to program the GT911 to address 0x14,
eliminating the address conflict.
Before:
SFA30 found at address 0x5d
[I][TouchDrvGT911.hpp:568] initImpl(): Try using 0x5D as the device address
After:
SFA30 found at address 0x5d
[I][TouchDrvGT911.hpp:544] initImpl(): Try using 0x14 as the device address
* t5s3_epaper: fix GT911 ghost-SFA30 via early I2C address latch
Investigation findings
----------------------
Boot logs showed "SFA30 found at address 0x5d" on every cold power-on,
and AirQualityTelemetry was registering an SFA30 sensor. However, every
readMeasuredValues() call returned error 268 (0x010C = Sensirion
WriteError | I2cAddressNack), meaning the I2C write to 0x5D was being
NACK'd — inconsistent with a real SFA30.
Root cause: the GT911 touch controller latches its I2C address from the
INT pin level at reset time (GT911 datasheet §4.3). GPIO3 (INT) defaults
LOW on ESP32-S3 cold boot → GT911 always powers up at 0x5D
(SLAVE_ADDRESS_L). The I2C scanner runs before lateInitVariant() had a
chance to reprogram the chip.
The scanner's SFA30 detection (ScanI2CTwoWire.cpp) sends the 2-byte
command 0xD060 to 0x5D and requests 48 bytes back. GT911 ACKs the
write (treating it as a register address) and returns 48 bytes of
register data, passing the length check — a false-positive SFA30
detection.
Confirmed via second cold-boot log: after the previous commit moved GT911
to 0x14 in lateInitVariant(), address 0x5D *still* appeared in the scan
because the scanner runs first. The board has no physical SFA30 fitted.
Fix
---
Add the GT911 address-latch reset sequence to earlyInitVariant(), before
Wire is initialised and before the I2C scan runs. Per the datasheet:
drive RST LOW, drive INT HIGH (selects address 0x14 / SLAVE_ADDRESS_H),
hold >100 µs, release RST, wait >5 ms startup. GPIO-only, no Wire
dependency. lateInitVariant() then repeats this sequence internally via
touch.begin(); the double-reset is harmless.
Verified in boot log:
Before: "SFA30 found at address 0x5d", 5 I2C devices, NACK errors
After: no SFA30 entry, 4 I2C devices (TCA9535/PCF8563/BQ27220/BQ25896),
GT911 found at 0x14 and touch initialised successfully,
AirQualityTelemetry registers no sensors (correct — no SFA30 present)
* t5s3_epaper: add variant_shutdown() for touch sleep and backlight off
Put GT911 into low-power standby (command 0x05) and drive BOARD_BL_EN
LOW before deep sleep to avoid unnecessary current draw.
* t5s3_epaper: fix touch gesture routing and coordinate mapping
readTouch() now transforms raw GT911 axes to visual-frame coordinates
based on the current display rotation (rotation=3 is the hardware
identity). This ensures TouchScreenBase detects swipe direction
correctly regardless of which rotation the user has selected.
TouchInkHUDBridge dynamically sets joystick.alignment = (4-rotation)%4
on each touch event so that (rotation+alignment)%4==0 always, keeping
nav calls pass-through without remapping.
nicheGraphics.h now calls loadSettings() first so that rotation is
persisted across reboots. rotation=3 and other first-boot defaults are
only applied when tips.firstBoot is set. alignment is recomputed from
the loaded rotation on every boot.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* t5s3_epaper: fix GT911 sleep timing via notifyDeepSleep observer
touch.sleep() was called from variant_shutdown(), which runs inside
cpuDeepSleep() — after Wire.end() had already torn down the I2C bus in
doDeepSleep(). This caused Wire NULL TX buffer errors and left the GT911
awake during deep sleep.
Register a CallbackObserver on notifyDeepSleep, which fires before
Wire.end(), so the I2C command reaches the chip while the bus is live.
Pattern matches LatchingBacklight and other NicheGraphics components.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* t5s3_epaper: fix touch nav and applet defaults in nicheGraphics
Enable joystick mode post-begin so menu scroll and swipe-up/down
gestures are not silently dropped by the joystick.enabled gate in
Events.cpp. Activate DMs and Channel 0/1 applets with correct
autoshow defaults matching the mini-epaper-s3 reference pattern.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* Update nicheGraphics.h
* t5s3_epaper: fix ED047TC1 driver docs and remove spurious beginPolling
Addressing PR review comments:
Remove beginPolling(1, 0) after the blocking FastEPD update — it
incorrectly set updateRunning=true for one loop cycle after the
hardware was already done, causing busy() to briefly return true.
Since isUpdateDone() always returns true, no polling is needed.
Also fix stale comments: safe-area buffer size was 944×532, now
944×523; V_OFFSET_ROWS didn't exist, replaced with the actual
V_OFFSET_TOP=9 / V_OFFSET_BOTTOM=8 constant names.
* t5s3_epaper: clean up applet addition formatting in setupNicheGraphics
* t5s3_epaper: guard ED047TC1.cpp against non-T5S3 InkHUD builds
The InkHUD base config pulls in all of src/graphics/niche/ so every
InkHUD device compiled ED047TC1.cpp, triggering the #error on line 48
for boards that define neither T5_S3_EPAPER_PRO_V1 nor V2.
Wrap the file body with #ifdef T5_S3_EPAPER_PRO so it is only compiled
for T5S3 targets. The #error is preserved inside the guard to catch
future hardware revisions that forget to update the driver.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: HarukiToreda <116696711+HarukiToreda@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds Meshtastic InkHUD firmware support for the LilyGo T5 E-Paper S3 Pro (tested H752-01, but Claude took care to make it work for H752 too but can't test).
Hardware: 4.7" ED047TC1 parallel e-paper (960×540), GT911 capacitive touch, ESP32-S3, SX1262 LoRa, L76K GPS, BQ25896 charger, BQ27220 fuel gauge, PCF8563 RTC.
New files
src/graphics/niche/Drivers/EInk/ED047TC1.{h,cpp}— NicheGraphics driver adapter for the FastEPD library. Handles the 960×540 8-bit parallel panel with empirically-calibrated inactive-pixel safe-area margins (8px horizontal, 9/8px vertical).variants/esp32s3/t5s3_epaper/— variant header, init, and InkHUD config:variant.h: PCF8563 RTC fix (was incorrectly PCF85063), V1/V2 pin guardsvariant.cpp: GT911 I2C address latch inearlyInitVariant()to prevent false SFA30 detection; rotation-aware touch coordinate mapping;TouchInkHUDBridgeobserver routing touch events into InkHUD; GT911 deep-sleep observer;variant_shutdown()turning off backlight before deep sleepnicheGraphics.h: InkHUD config for the 4.7" screen — larger Win1253/Greek fonts (24pt/18pt/12pt), joystick mode enforced post-begin()for touch nav, all 7 user applets registered, LatchingBacklight onBOARD_BL_ENShared code (minimal, non-breaking)
src/input/TouchScreenImpl1.cpp: null-guard beforeinputBroker->registerSource()— prevents a LoadProhibited crash on any InkHUD build withHAS_TOUCHSCREEN=1(not sure if needed, will check again)src/graphics/niche/Fonts/FreeSans{18,24}pt_Win1253.h+AppletFont.h: larger Win1253/Greek-encoded font sizes for bigger InkHUD displaysNotes
t5s3_epaper_inkhudis markedboard_level = extra(experimental)PRIVATE_HW— pending protobuf assignmentT5_S3_EPAPER_PRO_V1) and V2 (T5_S3_EPAPER_PRO_V2) both supported via compile-time guards; V2 adds GPS and SD card🤝 Attestations