Add support for Lilygo T5-4.7 inch ESP32-S3 (aka "plus"/V2.3) e-paper module

[nickolay]

There's #1109 open for the original T5-4.7 module. This year the vendor introduced a new version of the module, which they call "T5 4.7 Inch E-paper V2.3" or "T5-4.7 Plus".

The vendor advertises the new ESP32-S3 chip and TF-card reader as the major new features, but there are multiple other differences as well. The pinout is incompatible, so any attempts to blindly run examples from #1109 on the new board without first figuring out the differences will fail.

I'll copy the description from the original feature request verbatim, as only the internals of the board are different; the use-case is the same:

Describe the problem you have/What new integration you would like
The Lyligo T5-4.7inch is a great e-paper module based on an ESP32. It has a resolution of 960*540, 16 gray level and support partial refresh. I would be great to have it integrated in ESPHome the same / similar way Waveshare e-paper screens and modules are.

Please describe your use case for this integration and alternatives you've tried:
To date there is no support for this module in ESPHome. The only support given by the maker is through Arduino IDE

Additional context
This is the maker's GitHub for this product: https://github.com/Xinyuan-LilyGO/LilyGo-EPD47

[nickolay]

So far I managed to get esphome run to flash the chip, based on vendor's demo:

esphome:
  name: lilygo
  platformio_options:
    upload_speed: 921600
    monitor_speed: 115200
    board_build.mcu: esp32s3
    board_build.f_cpu: 240000000L
    #uncommenting the following causes: .platformio/packages/framework-arduinoespressif32/tools/sdk/esp32s3/include/newlib/platform_include/assert.h:20:10: fatal error: sdkconfig.h: No such file or directory
    # board_build.arduino.memory_type: qspi_opi
    board_build.flash_size: 16MB
    board_build.flash_mode: qio
    board_build.flash_type: qspi
    board_build.psram_type: opi
    board_build.memory_type: qspi_opi
    board_build.boot_freq: 80m

esp32:
  variant: esp32s3
  board: esp32-s3-devkitc-1

  framework:
    type: arduino
    version: 2.0.3
    platform_version: 5.1.1

With the above, basic ESP32 functionality like OTA updates work normally.
It's easy to detect physical button presses:

binary_sensor:
  - platform: gpio
    pin: 
      number: GPIO21 #was GPIO39 on the previous board
      inverted: true
    name: "Button 1"
    on_press:
      - logger.log: PhysButton Pressed

Hopefully someone will have time to adapt the screen library.

Update: there are three implementations for the original board discussed in #1109:

• https://github.com/tiaanv/esphome-components (announcement) is a wrapper for the vendor's library https://github.com/Xinyuan-LilyGO/LilyGo-EPD47 (which I think is based on epdiy and modified to work with lilygo, but does not track upstream improvements very well)
• https://github.com/vbaksa/esphome (announcement) relies on upstream epdiy to do the drawing, which I believe is supposed to result in faster updates / less flickering? (Though never doing full redraws reportedly doesn't always work well.)
• https://github.com/ashald/esphome/tree/lilygo-t5-47 (announcement) also relies on upstream epdiy, but is optimized for performance / battery life by sacrificing greyscale support.

There's some work happening over at vroland/epdiy#203 for supporting ESP32-S3 in general and the new T5-4.7 in particular, but it's currently a bit too experimental for my taste, so I'm toying with approach similar to the one taken by tiaanv...

[nickolay]

I'm toying with approach similar to the one taken by tiaanv...

OK, the screen appears to work for me: https://github.com/nickolay/esphome-lilygo-t547plus

[besanur]

How did you flash, i was not able to flash it via esphome web. Only worked with esptool. I have a basic configuration to display the time, but it shows a wrong time, hour is alwas at 01:XX.
And if a look at esphome web ui in home-assistant the devices is not connected, but after i connect it to my computer and read logs via them after that it is connected the wifi.

My config:

esphome:
  name: lilygo
  platformio_options:
    # Unless noted otherwise, based on https://github.com/Xinyuan-LilyGO/LilyGo-EPD47/blob/1eb6119fc31fcff7a6bafecb09f4225313859fc5/examples/demo/platformio.ini#L37
    upload_speed: 921600
    monitor_speed: 115200
    board_build.mcu: esp32s3
    board_build.f_cpu: 240000000L
    board_build.arduino.memory_type: qspi_opi
    board_build.flash_size: 16MB
    board_build.flash_mode: qio
    board_build.flash_type: qspi
    board_build.psram_type: opi
    board_build.memory_type: qspi_opi
    board_build.boot_freq: 80m
    build_flags: # the first three defines are required for the screen library to function.
      - "-DBOARD_HAS_PSRAM"
      - "-DARDUINO_RUNNING_CORE=0" # TODO: this conflicts with the value from platformio's idedata, spewing a lot of warnings during the build.
      - "-DARDUINO_EVENT_RUNNING_CORE=0" # and this too
      # In addition to lilygo's settings:
      # To enable reading logs over USB until `hardware_uart: USB_CDC` support
      # is added to `logger:`, as detailed in <https://github.com/esphome/feature-requests/issues/1906>:
      - "-DARDUINO_USB_MODE=1"
      - "-DARDUINO_USB_CDC_ON_BOOT=1"

esp32:
  variant: esp32s3
  board: esp32-s3-devkitc-1

  framework:
    type: arduino
    # Just like in <https://community.home-assistant.io/t/enable-usb-cdc-to-log-hello-world-to-esp32-s3-dev-board-for-esphome/463164/10>
    # I had problems with newer versions; the following combination happens to work, so using it for now.
    version: 2.0.3
    platform_version: 5.1.1

logger:
  level: VERBOSE
  # hardware_uart: USB_CDC  # see note about <https://github.com/esphome/feature-requests/issues/1906> above

# Enable Home Assistant API
api:
  encryption:
    key: "rZjS7VS1G5PPFc7JLfwWYGMZ8LVg81Mokz9UUoCel00="

ota:
  password: "6903efa08992bfb72e6e2545357799ae"
  
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
    # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Lilygo-T5 Fallback Hotspot"
    password: "xHMGPUOTHBjX"

captive_portal:

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO21 #was GPIO39 on the previous board
      inverted: true
    name: "Button 1"
    on_press:
      - logger.log: PhysButton Pressed

external_components:
  source:
    type: local
    path: esphome-lilygo-t547plus/components/
  components: ["t547"]

time:
  - platform: homeassistant
    id: esptime

font: 
  - file: "fonts/Roboto-Regular.ttf"
    id: font_clock
    size: 78
    glyphs: [':', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9']

display:
  - platform: t547
    # rotation: 180
    update_interval: 30s
    lambda: |-
      it.strftime(it.get_width()/2, it.get_height()/2, id(font_clock), TextAlign::TOP_CENTER, "%H:%M", id(esptime).now());

[lehovec]

You can add platformio board configuration from LilyGo-EPD47 GitHub repository to esphome. I added lilygo-t5-74-plus.json file to /config/esphome/.esphome/build/[your-esphome-device]/boards and I am am able to flash without problems.

esphome:
  name: liligo-t5-47-epaper-plus
  platformio_options:
    board_dir: boards
    #include https://github.com/Xinyuan-LilyGO/LilyGo-EPD47/blob/master/platformio/boards/lilygo-t5-47-plus.json as custom board
    board: lilygo-t5-47-plus

esp32:
  variant: esp32s3
  board: lilygo-t5-47-plus

  framework:
    type: arduino
    # You don't need to specify version and platform_version

i2c:
  sda: GPIO17
  scl: GPIO18
  # There is some problems with i2c scan so turn scan off if problem appear on your board
  scan: false
  id: bus_a

external_components:
  - source: github://nickolay/esphome-lilygo-t547plus
    components: ["t547"]

display:
- platform: t547
  id: t5_display
  update_interval: 30s

[nickolay]

i was not able to flash it via esphome web. Only worked with esptool

I'm not sure how you can provide the necessary platformio_options via esphome web, so I'm flashing using the CLI (esphome run basic.yaml), as noted in the readme.

I'm always flashing over USB to be able to see the logs from the first startup, which are very useful to troubleshoot the occasional problems, like the device booting into safe mode (i.e. ignoring most of the config). I've also added the device to Home assistant manually.

You can add platformio board configuration from LilyGo-EPD47 GitHub repository to esphome

Cool tip, thanks!

[besanur]

You can add platformio board configuration from LilyGo-EPD47 GitHub repository to esphome. I added lilygo-t5-74-plus.json file to /config/esphome/.esphome/build/[your-esphome-device]/boards and I am am able to flash without problems.

esphome:
  name: liligo-t5-47-epaper-plus
  platformio_options:
    board_dir: boards
    #include https://github.com/Xinyuan-LilyGO/LilyGo-EPD47/blob/master/platformio/boards/lilygo-t5-47-plus.json as custom board
    board: lilygo-t5-47-plus

esp32:
  variant: esp32s3
  board: lilygo-t5-47-plus

  framework:
    type: arduino
    # You don't need to specify version and platform_version

i2c:
  sda: GPIO17
  scl: GPIO18
  # There is some problems with i2c scan so turn scan off if problem appear on your board
  scan: false
  id: bus_a

external_components:
  - source: github://nickolay/esphome-lilygo-t547plus
    components: ["t547"]

display:
- platform: t547
  id: t5_display
  update_interval: 30s

with this solution it works much better and without problems.. thank you

[pfruh]

Has anyone figured out how to read the battery voltage? According to https://github.com/Xinyuan-LilyGO/LilyGo-EPD47/blob/master/schematic/T5-4.7-Plus.pdf the pin should be GPIO14, but there I'm getting ESP32S3 doesn't support ADC on this pin.

[nickolay]

@kaeltis see Xinyuan-LilyGO/LilyGo-EPD47#87 for a C example, which seems to work okay. Didn’t try to use it from esphome yet.

[pfruh]

Thanks, I've forked an existing module that solved this for the old board revision and it seems to work.
I have pretty much no idea what I'm doing so this definitely needs improvements: https://github.com/kaeltis/esphome-lilygo-t547plus

[startQ341]

You can add platformio board configuration from LilyGo-EPD47 GitHub repository to esphome. I added lilygo-t5-74-plus.json file to /config/esphome/.esphome/build/[your-esphome-device]/boards and I am am able to flash without problems.

esphome:
  name: liligo-t5-47-epaper-plus
  platformio_options:
    board_dir: boards
    #include https://github.com/Xinyuan-LilyGO/LilyGo-EPD47/blob/master/platformio/boards/lilygo-t5-47-plus.json as custom board
    board: lilygo-t5-47-plus

esp32:
  variant: esp32s3
  board: lilygo-t5-47-plus

  framework:
    type: arduino
    # You don't need to specify version and platform_version

i2c:
  sda: GPIO17
  scl: GPIO18
  # There is some problems with i2c scan so turn scan off if problem appear on your board
  scan: false
  id: bus_a

external_components:
  - source: github://nickolay/esphome-lilygo-t547plus
    components: ["t547"]

display:
- platform: t547
  id: t5_display
  update_interval: 30s

a try your code but have a error code a try change jason file but same problem thanks for help

Processing obrazovka (board: lilygo-t5-47-plus; framework: arduino; platform: platformio/espressif32 @ 5.3.0)

Error: Could not load broken JSON: /config/esphome/.esphome/build/obrazovka/boards/lilygo-t5-47-plus.json

[lehovec]

@startQ341 error indicate that lilygo-t5-47-plus.json file is somehow corrupted. Try to download it from source repository again or check in some online json validator what is problem with that file.

[startQ341]

@lehovec
thank you for your help browser corrupted data while downloading

[zagnuts]

Thanks guys for this - it's working perfectly for me now, both screen and battery estimate. Only minor hassle is the lack of partial refresh support but hopefully that will become available eventually. Oh, and it would be nice to be able to disable that blinding blue light with something civilised like

status_led:
  pin:
    number: GPIO05
    inverted: True

rather than having to contemplate crushing it with pliers! (FWIW it can be done via epd_poweroff_all() apparently)