feat(lilygo-t5-47): Add BSP for the LilyGo T5 4.7" ESP32-S3 e-paper board

[finger563]

Description

Adds a Board Support Package for the LilyGo T5 4.7" (ESP32-S3) e-paper board
(espp::LilyGoT547), wrapping the epdiy
library for the ED047TC1 960×540 16-level-grayscale panel, plus two reusable
driver components it depends on.

BSP features (components/lilygo-t5-47/):

• E-paper display via epdiy (LCD_CAM parallel bus): power on/off, clear, a
  grayscale framebuffer, and partial/full updates.
• LVGL 9 integration — an L8 grayscale display whose flush batches each refresh
  cycle's dirty areas into a single panel update; selectable update mode
  (MODE_GC16 grayscale vs fast mono MODE_DU) and touch-aware display
  rotation.
• GT911 capacitive touch as an LVGL input device (polled — the board's controller
  config is query-mode), plus the capacitive home button.
• PCF8563 RTC (via the register-compatible espp::Bm8563 driver).
• BQ27220 battery fuel gauge.
• PCA9535 I/O expander (the same chip epdiy drives) incl. the "IO48" button.
• Frontlight, BOOT button, qwiic bus accessor, microSD (SPI), and power-off via
  BQ25896 ship mode.
• All on-board I2C peripherals share epdiy's bus (100 kHz), handed to epdiy via
  epd_init_with_config() so there is a single shared I2C master.

New reusable components:

• components/bq27220/ — TI BQ27220 I2C battery fuel-gauge driver.
• components/pca9535/ — PCA9535 / PCA9555 16-bit I2C GPIO-expander driver.

Example: an interactive LVGL GUI (Gui class) with a live RTC clock, a
toggle-able stats panel (battery / touch / IO48- and home-button state), and
buttons for frontlight, rotation, stats, full-refresh, and power-off; the update
mode follows the stats panel (GC16 while shown for legibility, DU while hidden
for a snappy clock).

Docs pages and CI example-build entries are included for all three components.

Motivation and Context

There was no espp BSP for the LilyGo T5 4.7" e-paper board. E-paper on the
ESP32-S3 (parallel LCD_CAM timing, waveforms, grayscale, partial updates) is
non-trivial, so this wraps the well-supported epdiy library and exposes the whole
board — display, LVGL, touch, RTC, battery, I/O expander, frontlight, microSD,
and power management — behind a single easy-to-use component, matching the other
espp BSPs. The bq27220 and pca9535 drivers are broadly useful on their own and
are factored out as standalone components.

How has this been tested?

• Builds: all example projects compile cleanly with idf.py build — the BSP
  example (esp32s3), the bq27220 example (esp32), and the pca9535 example
  (esp32s3). Added to .github/workflows/build.yml.
• Hardware: verified on a physical LilyGo T5 4.7" ePaper S3 PRO:
  • e-paper bring-up + LVGL grayscale UI, and display rotation (layout re-flows,
    touch stays aligned);
  • GT911 touch (coordinates, orientation, and the capacitive home button);
  • PCF8563 RTC (live clock), BQ27220 battery readings, PCA9535 IO48 button;
  • frontlight toggle and BQ25896 ship-mode power-off (wakes on the PWR button);
  • an on-boot I2C bus scan confirmed every device (0x20 expander, 0x51 RTC,
    0x55 gauge, 0x5D touch, 0x68 TPS, 0x6B PMIC).

Screenshots (if appropriate, e.g. schematic, board, console logs, lab pictures):

Console (I2C bus scan on boot):

Scanning internal I2C bus...
I2C device found at 0x20 (PCA9535 expander)
I2C device found at 0x51 (PCF8563 RTC)
I2C device found at 0x55 (BQ27220 gauge)
I2C device found at 0x5D (GT911 touch)
I2C device found at 0x68 (TPS65185)
I2C device found at 0x6B (BQ25896 PMIC)

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update
• Hardware (schematic, board, system design) change
• Software change

Checklist:

• My change requires a change to the documentation.
• I have added / updated the documentation related to this change via either README or WIKI

Software

• I have added tests to cover my changes.
• I have updated the .github/workflows/build.yml file to add my new test to the automated cloud build github action.
• All new and existing tests passed.
• My code follows the code style of this project.

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

Pull request overview

Adds a new ESPP Board Support Package (BSP) for the LilyGo T5 4.7" ESP32-S3 e-paper board, plus two new reusable I2C driver components (BQ27220 fuel gauge and PCA9535/9555 I/O expander). This integrates epdiy for the ED047TC1 panel, provides LVGL 9 support, and documents/build-tests the new components in CI.

Changes:

• Added espp::LilyGoT547 BSP component (display via epdiy, LVGL flush integration, touch, RTC, battery gauge, IO expander, frontlight, SD card, and ship-mode shutdown).
• Added new standalone components: bq27220 (fuel gauge) and pca9535 (I/O expander), each with examples and docs.
• Updated Sphinx/Doxygen docs and GitHub Actions CI build matrix to include the new examples.

Reviewed changes

Copilot reviewed 52 out of 52 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
doc/en/io_expander/pca9535.rst	Adds PCA9535/9555 documentation page.
doc/en/io_expander/pca9535_example.md	Adds docs include page for the PCA9535 example.
doc/en/io_expander/index.rst	Adds PCA9535 to IO expander docs index.
doc/en/dev_boards/lilygo/lilygo_t5_47.rst	Adds BSP documentation page for LilyGo T5 4.7".
doc/en/dev_boards/lilygo/lilygo_t5_47_example.md	Adds docs include page for the LilyGo T5 4.7" example.
doc/en/dev_boards/lilygo/index.rst	Adds the new LilyGo T5 4.7" page to the LilyGo boards index.
doc/en/battery/index.rst	Adds BQ27220 to battery docs index.
doc/en/battery/bq27220.rst	Adds BQ27220 documentation page.
doc/en/battery/bq27220_example.md	Adds docs include page for the BQ27220 example.
doc/Doxyfile	Adds new components’ headers and examples to Doxygen inputs/paths.
components/pca9535/README.md	PCA9535 component README.
components/pca9535/include/pca9535.hpp	Implements the PCA9535/9555 I2C expander driver.
components/pca9535/idf_component.yml	Component Manager manifest for pca9535.
components/pca9535/example/sdkconfig.defaults	Example default sdkconfig for pca9535.
components/pca9535/example/README.md	PCA9535 example README.
components/pca9535/example/main/pca9535_example.cpp	PCA9535 example application.
components/pca9535/example/main/Kconfig.projbuild	Kconfig options for PCA9535 example I2C pins/hardware.
components/pca9535/example/main/CMakeLists.txt	Example main component registration.
components/pca9535/example/CMakeLists.txt	Example project CMake (local components).
components/pca9535/CMakeLists.txt	pca9535 component build definition.
components/lilygo-t5-47/src/touch.cpp	GT911 bring-up and polling task + LVGL input integration.
components/lilygo-t5-47/src/sdcard.cpp	SPI bus init + FAT mount for microSD.
components/lilygo-t5-47/src/rtc.cpp	RTC bring-up using Bm8563 driver for PCF8563-compatible chip.
components/lilygo-t5-47/src/power.cpp	Ship-mode shutdown via PMIC register write.
components/lilygo-t5-47/src/lvgl.cpp	LVGL initialization + flush that writes to epdiy framebuffer and batches updates.
components/lilygo-t5-47/src/lilygo-t5-47.cpp	Core display initialization and basic display operations.
components/lilygo-t5-47/src/io_expander.cpp	PCA9535 bring-up (shared with epdiy) + IO48 button helper.
components/lilygo-t5-47/src/frontlight.cpp	Frontlight GPIO control.
components/lilygo-t5-47/src/buttons.cpp	BOOT button interrupt wiring (shared ISR service).
components/lilygo-t5-47/src/battery.cpp	BQ27220 bring-up on internal I2C bus.
components/lilygo-t5-47/README.md	BSP README including features and pin mapping.
components/lilygo-t5-47/include/lilygo-t5-47.hpp	BSP public API header and singleton interface.
components/lilygo-t5-47/idf_component.yml	Component Manager manifest for lilygo-t5-47 (includes epdiy git dependency).
components/lilygo-t5-47/example/sdkconfig.defaults	Example default sdkconfig (PSRAM/cache line/fonts/partition).
components/lilygo-t5-47/example/README.md	BSP example README describing the LVGL GUI behavior and hardware expectations.
components/lilygo-t5-47/example/main/lilygo-t5-47_example.cpp	BSP example app wiring up display, LVGL GUI, peripherals, and polling loop.
components/lilygo-t5-47/example/main/gui.hpp	GUI class interface + LVGL update task structure.
components/lilygo-t5-47/example/main/gui.cpp	GUI implementation (layout, buttons, update loop, refresh behavior).
components/lilygo-t5-47/example/main/CMakeLists.txt	Example main component registration.
components/lilygo-t5-47/example/CMakeLists.txt	Example project CMake (component manager enabled to fetch epdiy).
components/lilygo-t5-47/CMakeLists.txt	BSP component build definition and requirements.
components/bq27220/README.md	BQ27220 component README.
components/bq27220/include/bq27220.hpp	Implements the BQ27220 fuel gauge driver (little-endian standard commands).
components/bq27220/idf_component.yml	Component Manager manifest for bq27220.
components/bq27220/example/sdkconfig.defaults	Example default sdkconfig for bq27220.
components/bq27220/example/README.md	BQ27220 example README.
components/bq27220/example/main/Kconfig.projbuild	Kconfig options for BQ27220 example I2C pins/hardware.
components/bq27220/example/main/CMakeLists.txt	Example main component registration.
components/bq27220/example/main/bq27220_example.cpp	BQ27220 example application.
components/bq27220/example/CMakeLists.txt	Example project CMake (local components).
components/bq27220/CMakeLists.txt	bq27220 component build definition.
.github/workflows/build.yml	Adds CI build matrix entries for the new examples.

Comments suppressed due to low confidence (2)

doc/Doxyfile:146

• The new pca9535 example entry is out of order in EXAMPLE_PATH (it appears between mcp23x17 and mt6701), despite the file’s note to keep entries alphabetical. Please move it to the correct location in the list to keep maintenance simple.

This issue also appears on line 340 of the same file.
doc/Doxyfile:343

• The new pca9535 header entry is out of order in Doxyfile INPUT (it is listed before mt6701/odrive_ascii). The header list is intended to be alphabetical; please reorder the local block so pca9535 is placed correctly.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 52 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

components/lilygo-t5-47/src/lvgl.cpp:43

• If either LVGL draw-buffer allocation fails, the function returns without freeing the other buffer, leaking PSRAM and leaving the object in a partially-initialized state for subsequent calls.

  lvgl_buffer0_ =
      static_cast<uint8_t *>(heap_caps_malloc(buffer_bytes, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT));
  lvgl_buffer1_ =
      static_cast<uint8_t *>(heap_caps_malloc(buffer_bytes, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT));
  if (lvgl_buffer0_ == nullptr || lvgl_buffer1_ == nullptr) {
    logger_.error("Could not allocate LVGL draw buffers ({} bytes each)", buffer_bytes);
    return false;
  }

doc/en/dev_boards/lilygo/lilygo_t5_47_example.md:1

• The docs include path is incorrect for this file's location (doc/en/dev_boards/lilygo/...). As written it resolves under doc/en/, so the rendered page will fail to include the example README.
  components/lilygo-t5-47/include/lilygo-t5-47.hpp:207
• The header comment says the touch callback is invoked from an interrupt, but the implementation polls GT911 from a Task and calls the callback from that polling task. This matters for callback expectations (blocking/logging is OK in a task but not in an ISR).

  /// Initialize the GT911 capacitive touch controller on the internal I2C bus,
  /// and register an LVGL input device for it.
  /// \param callback Called (from the touch interrupt) with each new touch state
  /// \return true on success. initialize_display() must have been called first
  ///         (it creates the shared I2C bus).

[Copilot]

Pull request overview

Copilot reviewed 53 out of 53 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

components/lilygo-t5-47/src/touch.cpp:1

• This switch has no default: branch. If rotation_ ever holds an unexpected value, *x/*y will be left unchanged/undefined. Add a default: that sets a safe mapping (e.g., landscape) to guarantee outputs are always initialized.
  components/lilygo-t5-47/src/lvgl.cpp:43
• On allocation failure, this leaks whichever draw buffer was successfully allocated (and also leaves lvgl_buffer0_/lvgl_buffer1_ potentially non-null for subsequent calls). Free any allocated buffer(s) and reset both pointers to nullptr before returning false.

  const size_t buffer_bytes = static_cast<size_t>(w) * buffer_lines;
  lvgl_buffer0_ =
      static_cast<uint8_t *>(heap_caps_malloc(buffer_bytes, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT));
  lvgl_buffer1_ =
      static_cast<uint8_t *>(heap_caps_malloc(buffer_bytes, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT));
  if (lvgl_buffer0_ == nullptr || lvgl_buffer1_ == nullptr) {
    logger_.error("Could not allocate LVGL draw buffers ({} bytes each)", buffer_bytes);
    return false;
  }

components/lilygo-t5-47/include/lilygo-t5-47.hpp:45

• The class-level documentation says the BSP provides only the display, but the public API and README add many more features (LVGL, touch, RTC, battery, IO expander, SD, LoRa, etc.). Update this list (or remove it) so the header doc accurately reflects what the component exposes.

/// The class provides access to the following features:
/// - 4.7" 960x540 e-paper display (ED047TC1) via epdiy
///
/// The class is a singleton and can be accessed using the get() method.

[Copilot]

Pull request overview

Copilot reviewed 53 out of 53 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

components/lilygo-t5-47/include/lilygo-t5-47.hpp:436

• The touch-pin comment says RST is currently unused, but the implementation resets/straps the GT911 using both RST and INT (see gt911_reset in touch.cpp). This comment is now misleading for BSP users wiring/porting the board.

  // Touch (GT911) on the internal I2C bus. Pins from the T5 4.7" ePaper S3 PRO
  // factory firmware. RST is currently unused (the controller comes up at its
  // default address); it is kept here for a future explicit-reset sequence.
  static constexpr gpio_num_t touch_interrupt_io = GPIO_NUM_3;

components/lilygo-t5-47/src/lora.cpp:35

• The expander power-enable sequence uses the values returned by get_direction()/get_output() without checking ec first. If either read fails, the returned value can be stale/zero and the subsequent write can accidentally clobber other PORT0 bits, and the error may get cleared by a later successful write (BasePeripheral::write clears ec). Guard each step with if (!ec) before using the read value / issuing the next write.

    uint8_t dir = io_expander_->get_direction(espp::Pca9535::Port::PORT0, ec);
    io_expander_->set_direction(espp::Pca9535::Port::PORT0, dir & ~P00, ec); // P00 -> output
    uint8_t out = io_expander_->get_output(espp::Pca9535::Port::PORT0, ec);
    io_expander_->set_pins(espp::Pca9535::Port::PORT0, out | P00, ec); // P00 -> high (on)
    if (ec) {

components/lilygo-t5-47/include/lilygo-t5-47.hpp:208

• The initialize_touch() docs say the callback is called "from the touch interrupt", but touch is polled from a task (see touch_task_ and the 15ms wait in touch.cpp). This affects what users can safely do in the callback (it is not an ISR context).

This issue also appears on line 433 of the same file.

  /// Initialize the GT911 capacitive touch controller on the internal I2C bus,
  /// and register an LVGL input device for it.
  /// \param callback Called (from the touch interrupt) with each new touch state
  /// \return true on success. initialize_display() must have been called first
  ///         (it creates the shared I2C bus).

[Copilot]

Pull request overview

Copilot reviewed 53 out of 53 changed files in this pull request and generated no new comments.

Suppressed comments (7)

components/lilygo-t5-47/include/lilygo-t5-47.hpp:208

• This docstring says the touch callback is invoked "from the touch interrupt", but the implementation polls the GT911 from a task and calls the callback from that polling task context. Update the comment to avoid misleading users about callback threading/ISR restrictions (e.g., clarify it runs in the GT911 polling task).

  /// \param callback Called (from the touch interrupt) with each new touch state
  /// \return true on success. initialize_display() must have been called first
  ///         (it creates the shared I2C bus).

components/lilygo-t5-47/src/lora.cpp:13

• Other initialize_* methods in this BSP return true when the subsystem is already initialized (idempotent init). Returning false here makes initialize_lora() inconsistent and can cause callers to treat "already initialized" as an error. Consider returning true (keeping the warning) when lora_ is already set.

  if (lora_) {
    logger_.warn("LoRa radio already initialized, not initializing again!");
    return false;
  }

components/bq27220/include/bq27220.hpp:31

• The member comments on write/read use //< instead of Doxygen’s recognized trailing-member forms (typically ///< or /**< ... */). If these are intended to show up in generated API docs, switch them to ///< (or /**< ... */) for consistent documentation output.

    uint8_t device_address{DEFAULT_ADDRESS}; ///< Address of the BQ27220.
    BasePeripheral::write_fn write;          //< Function to write bytes to the device.
    BasePeripheral::read_fn read;            //< Function to read bytes from the device.

components/bq27220/example/main/bq27220_example.cpp:22

• ec is declared outside the task callback and is never cleared at the start of each polling iteration. If any call sets ec, subsequent iterations may keep observing a persistent error state (depending on how downstream helpers behave), preventing recovery. Prefer declaring a fresh std::error_code ec; inside the loop body each iteration (or explicitly ec.clear() before starting the sequence of reads).

  std::error_code ec;

components/bq27220/example/main/bq27220_example.cpp:40

• ec is declared outside the task callback and is never cleared at the start of each polling iteration. If any call sets ec, subsequent iterations may keep observing a persistent error state (depending on how downstream helpers behave), preventing recovery. Prefer declaring a fresh std::error_code ec; inside the loop body each iteration (or explicitly ec.clear() before starting the sequence of reads).

  auto task_fn = [&](std::mutex &m, std::condition_variable &cv) {

components/bq27220/example/main/bq27220_example.cpp:65

• ec is declared outside the task callback and is never cleared at the start of each polling iteration. If any call sets ec, subsequent iterations may keep observing a persistent error state (depending on how downstream helpers behave), preventing recovery. Prefer declaring a fresh std::error_code ec; inside the loop body each iteration (or explicitly ec.clear() before starting the sequence of reads).

    auto voltage = bq27220.get_voltage_mv(ec);
    if (ec) {
      return false;
    }
    auto current = bq27220.get_current_ma(ec);
    if (ec) {
      return false;
    }
    auto soc = bq27220.get_state_of_charge(ec);
    if (ec) {
      return false;
    }
    auto temperature = bq27220.get_temperature_celsius(ec);
    if (ec) {
      return false;
    }

components/lilygo-t5-47/include/lilygo-t5-47.hpp:43

• This feature list is incomplete relative to the public API added below (LVGL, touch, RTC, battery gauge, I/O expander, frontlight, microSD, LoRa, shutdown, etc.). Either expand the list to reflect the supported peripherals or remove the section to avoid documentation drift/misleading API summary.

/// The class provides access to the following features:
/// - 4.7" 960x540 e-paper display (ED047TC1) via epdiy