<![CDATA[DisplayEngineer]]>https://displayengineer.hashnode.devRSS for NodeTue, 27 Oct 2026 01:51:32 GMT60<![CDATA[Why your ST7701S screen goes black after a reboot in ESPHome]]>https://displayengineer.hashnode.dev/st7701s-black-after-reboot-esphome-reset-pinhttps://displayengineer.hashnode.dev/st7701s-black-after-reboot-esphome-reset-pinThu, 22 Oct 2026 06:17:35 GMTThe bug report that sent me into ESPHome's reset code keeps showing up in slightly different forms. Someone flashes a Waveshare ESP32-S3-Touch-LCD-4 over USB and the 480×480 ST7701S panel comes up fine. They unplug it, plug it back in, and get a lit backlight over a black screen. Reflash and the picture is back. Power cycle and it's gone again.

That's esphome#17636, opened in July against ESPHome 2026.6.5. Quick disclosure before I go on: I work at a display manufacturer, so I'm not exactly neutral about ST7701S panels. But "works after flashing, black after reboot" is nearly always about reset, not about porches or pixel clock. The controller isn't in a known state when the init commands show up, and SPI writes into a confused chip just vanish.

ESPHome 2026.10.0 came out on 21 October with a fix in exactly this area. I read through it, and on its own it does less than the changelog line makes it sound. You probably need to check one thing in your YAML too.

The fix is esphome#17646, "[mipi_rgb] Fix SWRESET delay for st7701s", from clydebarrow. In his words: "It's also been shown that the published delay (5ms) after reset for an ST7701S appears to be insufficient, and a longer delay is required to ensure proper initialisation." The PR also says an earlier change (#17504) had left a duplicate software reset in the ST7701S init sequence with no delay after it.

The diff matches that. In 2026.9.1 the ST7701S model in mipi_rgb started its init sequence with a bare (0x01,), the software reset command, and the very next thing sent was the 0xFF 0x77 0x01... page select. Nothing in between. In 2026.10.0 that line is gone. Reset now gets added in one place, get_sequence() in esphome/components/mipi/__init__.py: if you haven't configured a reset_pin it inserts SWRESET, and either way it follows with a settle delay. That delay is a per-model reset_delay that defaults to 10 ms, and the ST7701S class sets it to 50. The PR also reorders MipiRgbSpi::setup() so the RGB panel is created first, and the init sequence is only sent if that worked.

I wanted to see it in the generated code rather than take the diff's word for it, so I ran esphome compile --only-generate on 2026.10.0 with the SEEED-INDICATOR-D1 model. With a reset_pin set, the mipi_rgb_init_sequence[] array in main.cpp starts with 50, 255, which is a 50 ms delay marker. Without one it starts with 1, 0, 50, 255: SWRESET with no parameters, then the same 50 ms. So it does what it says.

One thing that tripped me up: reset_delay is a model default in Python, not a YAML option. The mipi_rgb docs don't list it and you can't set it per device. If 50 ms isn't enough for some odd panel, that needs a code change.

Now the part I found more interesting. The person who opened #17636 tested the PR on their board and wrote back: "Tested PR #17646, clean build, ESPHome 2026.7.0, USB flash. Does not fix it." It actually got a bit worse for them, because after a power cycle only Waveshare's factory firmware would bring the panel back.

What fixed it was the reset pin. Their board is the Rev 4.0 version, and on that one the LCD reset sits behind a CH32V003-based IO expander at 0x24 rather than the TCA9554 older revisions used. clydebarrow posted a Rev 4 config with reset_pin routed through the waveshare_io_ch32v003 component, pin 3, and the reply was "We have display working now and surviving power cycling." In 2026.10.0 the WAVESHARE-4-480X480 model in models/waveshare.py still has no reset pin of its own (it only requires PSRAM), so you have to add it yourself. The display part of that config looks like this:

display:
  - platform: mipi_rgb
    model: WAVESHARE-4-480X480
    reset_pin:
      waveshare_io_ch32v003: wave_io_hub
      number: 3

That only fits Rev 4. The maintainer warned in the thread that the expander changes between revisions, so check yours before copying it.

So my reading is that the longer delay is necessary but only half the story. A software reset can only reach a chip that's still listening on SPI. A hardware reset pulse doesn't care what state the controller got itself into.

Which brings me to the older platform: st7701s, still in 2026.10.0 and still what a lot of forum configs use. Its docs page has a SenseCAP Indicator example with reset_pin on a PCA9554, pin 5. The schema accepts it and display.py passes it to set_reset_pin(). But in st7701s.cpp the only place reset_pin_ appears is the LOG_PIN line in dump_config(). Nothing ever drives it. Your log shows a reset pin, and the pin just sits there.

There is a call to esp_lcd_panel_reset() in setup(), which sounds like a reset, but for an RGB panel ESP-IDF's rgb_panel_reset() in esp_lcd_panel_rgb.c only calls lcd_ll_fifo_reset() and lcd_ll_reset(). That's the ESP32-S3's own LCD peripheral. The panel never sees it. It also runs after the init sequence has already gone out over SPI. The only reset the old driver gives the ST7701S is the 0x01 at the top of canned init sequence 1, followed by delay(6). That's about the same 5-ish ms window the PR now calls insufficient.

I'm not claiming this is why every black-screen-after-reboot thread happens. Plenty of boards pull the panel's reset line high and come up clean from a real cold start, which is probably why the old platform has worked for so many people. On a warm reboot or an OTA restart, though, the panel stays powered and nothing resets it in hardware, and that's when I'd expect trouble.

mipi_rgb does pulse the pin. setup_enables_() in mipi_rgb.cpp drives it high, waits 5 ms, pulls it low for 5 ms, releases it, and the 50 ms from the init sequence comes after. If you're on platform: st7701s and your board has a named mipi_rgb model, moving over is usually a short job. For the SenseCAP Indicator it comes out like this, with bus and expander values from the ESPHome devices page for that board:

# Not tested on hardware. With an esphome: name block added,
# this passes `esphome config` on ESPHome 2026.10.0.
esp32:
  variant: esp32s3
  framework:
    type: esp-idf

psram:
  mode: octal
  speed: 80MHz

spi:
  - id: lcd_spi
    clk_pin: GPIO41
    mosi_pin: GPIO48
    miso_pin: GPIO47

i2c:
  - id: bus_a
    sda: GPIO39
    scl: GPIO40
    scan: false

pca9554:
  - id: pca9554a_device
    address: 0x20
    pin_count: 16

display:
  - platform: mipi_rgb
    model: SEEED-INDICATOR-D1
    id: sensecap_display
    update_interval: 1s
    reset_pin:
      pca9554: pca9554a_device
      number: 5
    lambda: |-
      it.fill(Color(255, 0, 0));

The reset_pin block is the whole point. The SEEED-INDICATOR-D1 model already puts CS on expander pin 4, but like the Waveshare one it doesn't define a reset pin, so if you copy the minimal three-line example from the devices page you get the software reset path instead. A solid red fill with update_interval: 1s is just a test. Swap in your real lambda or LVGL once the panel survives a few power cycles and a couple of OTA restarts.

If your board isn't a named model, there's a generic ST7701S model and a custom one in mipi_rgb, and the docs have a full custom example. While you're there, note that the other mipi_rgb change in this release, software rotation for pure RGB panels (#20757), says outright that ST7701S boards and CUSTOM are unchanged, so your mirror_x/mirror_y transform should keep validating.

If you're wiring an ST7701S panel into your own board rather than buying a dev kit, I keep the pinout and init notes on the ST7701S driver page on our site. The shorter ESPHome version of all this is in esphome-tft-display-examples on GitHub.

If you've got an ST7701S board that still goes black after a reboot on 2026.10.0 with a real reset pin wired in, I'd honestly like to hear which one it is.

]]><![CDATA[ESPHome Drops ili9xxx, st7789v and st7735 in 2027.5.0: Migrating SPI TFTs to mipi_spi]]>https://displayengineer.hashnode.dev/esphome-drops-ili9xxx-st7789v-and-st7735-in-2027-5-0-migrating-spi-tfts-to-mipi-spihttps://displayengineer.hashnode.dev/esphome-drops-ili9xxx-st7789v-and-st7735-in-2027-5-0-migrating-spi-tfts-to-mipi-spiMon, 19 Oct 2026 00:33:02 GMTESPHome has now put a date on the end of its legacy SPI display drivers. Four pull requests merged on 14 October 2026 (#20687 ili9xxx, #20688 st7735, #20689 st7789v, #20690 qspi_dbi) change the deprecation warning to: "The 'ili9xxx' component is deprecated and will be removed in ESPHome 2027.5.0, migrate to 'mipi_spi' instead." The PRs say the components have been deprecated since April 2026 and that the dated warning ships in 2026.11, six months before removal.

If a small SPI TFT (ILI9341, ST7789V, ST7735, ILI9488, ST7796S) runs on one of those drivers, this guide maps your old YAML onto mipi_spi and lists the likely problems.

Honesty note: we wrote every option, default and model name below from the current ESPHome docs and the esphome/esphome source on the dev branch (links at the end). We have not run these YAML snippets on hardware. Treat them as starting points and check each value on your own panel. qspi_dbi (quad-SPI panels, which move to mipi_spi with bus_mode: quad) is out of scope here.

The option map

Legacy option mipi_spi equivalent Watch out for
platform: ili9xxx / st7789v / st7735 platform: mipi_spi
model: ILI9341, ST7789V, ST7735, ILI9488, ILI9488_A, ST7796 Same names There is no ST7796S model. ST7796S panels use ST7796
model: TTGO TDisplay 135x240 (st7789v) model: T-DISPLAY
model: INITR_* (st7735) model: ST7735 One init sequence for all "tab" variants
device_width / device_height / col_start / row_start (st7735) dimensions: width / height / offset_width / offset_height
invert_colors (required in ili9xxx) invert_colors, default false The old st7789v driver always sent INVON
use_bgr (st7735), color_order (ili9xxx) color_order: bgr / rgb Default is bgr, but the ST7735 model defaults to rgb
eightbitcolor, eight_bit_color, color_palette: 8BIT color_depth: 8 No GRAYSCALE or IMAGE_ADAPTIVE palettes
SPI default 40 MHz (ili9xxx), 20 MHz (st7789v docs) data_rate, default 10 MHz unless a board preset overrides it A likely reason a migrated screen feels slower
rotation (software in ili9xxx) rotation, done in hardware when the chip supports it
transform (keys optional) transform: swap_xy, mirror_x, mirror_y all required, and dimensions must be set Use rotation instead unless the image is mirrored
backlight_pin (st7789v) none Drive the backlight with a separate output/light

dc_pin is required for single-bit SPI; cs_pin and reset_pin stay optional. Without cs_pin, mipi_spi falls back to SPI MODE3 and logs a warning; with one it uses MODE0.

Before / after pairs

ILI9341 240×320 (ili9xxx)

# BEFORE
display:
  - platform: ili9xxx
    model: ILI9341
    cs_pin: GPIO5
    dc_pin: GPIO4
    reset_pin: GPIO22
    invert_colors: false
    rotation: 90
    lambda: |-
      it.print(10, 10, id(font1), "Hello");

# AFTER - UNTESTED starting point
display:
  - platform: mipi_spi
    model: ILI9341        # native 240x320 portrait, mirror_x set by the model
    cs_pin: GPIO5
    dc_pin: GPIO4
    reset_pin: GPIO22
    data_rate: 40MHz      # ili9xxx used 40MHz by default; mipi_spi defaults to 10MHz
    invert_colors: false
    rotation: 90          # don't swap width/height by hand
    lambda: |-
      it.print(10, 10, id(font1), "Hello");

ST7789V 240×320 and 240×240

A full-size 240×320 ST7789V needs only model: ST7789V. Panels that use part of the controller's RAM need a dimensions block:

# BEFORE (st7789v, Custom 240x240)
display:
  - platform: st7789v
    model: Custom
    width: 240
    height: 240
    offset_width: 0
    offset_height: 0
    backlight_pin: GPIO21
    cs_pin: GPIO5
    dc_pin: GPIO16
    reset_pin: GPIO23

# AFTER - UNTESTED starting point
output:
  - platform: ledc
    pin: GPIO21
    id: bl_pwm
light:
  - platform: monochromatic
    output: bl_pwm
    name: "Display Backlight"
    restore_mode: ALWAYS_ON

display:
  - platform: mipi_spi
    model: ST7789V
    cs_pin: GPIO5
    dc_pin: GPIO16
    reset_pin: GPIO23
    invert_colors: true   # the old st7789v driver hard-coded inversion on
    dimensions:           # use the long form, not "240x240"
      width: 240
      height: 240
      offset_width: 0
      offset_height: 0

Why the long form? In the source (esphome/components/mipi/__init__.py), the 240x240 shorthand sets every offset and pad to zero. The long form lets the driver work out pad_height = 320 − 240 − 0 = 80 from the ST7789V's native 240×320 size, and the docs say padding is used to support hardware rotation. ESPHome's own GEEKMAGIC-SMALLTV preset, a 240×240 ST7789V, uses 0/0 offsets with invert_colors=True.

We keep a 240×320 ST7789V mipi_spi example for our PJ2801H22 module in qiren/esphome-tft-display-examples. It is marked TESTING-NEEDED for the same reason as this post.

ST7789V 135×240 (TTGO T-Display style)

# BEFORE
display:
  - platform: st7789v
    model: TTGO TDisplay 135x240
    backlight_pin: GPIO4
    cs_pin: GPIO5
    dc_pin: GPIO16
    reset_pin: GPIO23

# AFTER - UNTESTED starting point (generic 135x240 module)
display:
  - platform: mipi_spi
    model: ST7789V
    cs_pin: GPIO5
    dc_pin: GPIO16
    reset_pin: GPIO23
    invert_colors: true
    dimensions:
      width: 135
      height: 240
      offset_width: 52
      offset_height: 40

On the actual LilyGO board, model: T-DISPLAY presets the same 135×240 size, 52/40 offsets, CS 5, DC 16 and inversion. It does not preset a reset pin, so add reset_pin if your board has one wired. Drive the backlight on GPIO4 as in the previous example.

ST7735 128×160

# BEFORE
display:
  - platform: st7735
    model: INITR_18BLACKTAB
    cs_pin: GPIO5
    dc_pin: GPIO4
    reset_pin: GPIO22
    device_width: 128
    device_height: 160
    col_start: 0
    row_start: 0
    eight_bit_color: true

# AFTER - UNTESTED starting point
display:
  - platform: mipi_spi
    model: ST7735         # 128x160, color_order defaults to rgb for this model
    cs_pin: GPIO5
    dc_pin: GPIO4
    reset_pin: GPIO22
    color_depth: 8        # replaces eight_bit_color
    # if your old col_start/row_start were non-zero:
    # dimensions: {width: 128, height: 160, offset_width: <col_start>, offset_height: <row_start>}

Legacy "tab" variants with non-zero col_start/row_start need those values in dimensions. Because mipi_spi has a single ST7735 init sequence, mini 160×80 modules in particular need checking on the bench.

ILI9488 and ST7796S 320×480

# AFTER - UNTESTED starting point
display:
  - platform: mipi_spi
    model: ILI9488        # or ST7796 for ST7796S panels, or ILI9488_A
    cs_pin: GPIO10
    dc_pin: GPIO13
    reset_pin: GPIO41
    data_rate: 40MHz
    rotation: 90          # see note below

Two things to know. First, the legacy ili9xxx source declares its ILI9488 class as 480×320. The mipi_spi ILI9488 model is 320×480 portrait, so a landscape layout from the old driver probably needs rotation: 90 or 270. Second, the ILI9488 model defaults to pixel_mode: 18bit, which sends 3 bytes per pixel instead of 2, so expect a slower full refresh than on an ST7796 of the same size.

Where "Invalid offsets." comes from

When you give dimensions in long form, the driver computes pad = native − size − offset on each axis. A negative result raises Invalid offsets. On an ILI9341 (native 240×320), writing width: 320, height: 240 to get landscape gives pad_width = 240 − 320 = −80, and that fails. A maintainer said it plainly in #17074: keep the native orientation and use rotation.

Lambdas and LVGL

mipi_spi uses the standard display schema, so lambda: and pages: carry over unchanged. The frame buffer is always RGB whatever color_order you set, so your Color() values stay the same. Without PSRAM, and without an explicit buffer_size (12–100%), the driver picks a partial buffer under about 20 kB and calls your lambda several times per frame. Lambdas must therefore have no side effects. If there is no lambda and no LVGL, the driver shows a test card automatically, which is useful for bring-up.

With LVGL, the display needs no buffer of its own. Configure it with auto_clear_enabled: false and update_interval: never. LVGL's own buffer_size defaults to 100% and falls back to 12% at runtime if the allocation fails. The docs recommend 25% without PSRAM.

Symptom table

Symptom Likely cause after migrating Try
Black screen, backlight off st7789v's backlight_pin has no mipi_spi equivalent Add an output + light (or a GPIO switch)
White screen, backlight on No valid init: DC/CS swapped, wrong model, SPI too fast Check wiring, drop to 10 MHz, try the other likely controller (see below)
White screen on a 16-bit shift-register board after 2026.9.0 Regression, see next section Update to 2026.9.1 or later
Colours look like a negative invert_colors now defaults to false invert_colors: true (matches the old st7789v behaviour)
Red and blue swapped color_order Flip between bgr and rgb
Image shifted, garbage rows or columns at one edge Missing offsets, or WxH shorthand on a panel smaller than the controller Long-form dimensions with offset_width/offset_height
Invalid offsets at compile Width and height swapped by hand Native dimensions + rotation
Mirrored text Model default mirror_x (ILI9341, ST7796, ILI9488_A) does not match your glass transform: with all three keys plus dimensions
Noticeably slower refresh 10 MHz default instead of 40 MHz; small buffer without PSRAM; 18-bit ILI9488 Set data_rate; enable psram:; raise buffer_size
Out of memory / reboot loop Full-frame buffers in internal RAM color_depth: 8, smaller buffer_size, LVGL buffer_size: 25%, or PSRAM
Log: "defaulting to MODE3 due to lack of CS pin" No cs_pin Add cs_pin or set spi_mode explicitly

Known regression: white screen after 2026.9.0

#19732 reported a white screen on a Waveshare 4" TFT (model: WAVESHARE-4-TFT) after upgrading from 2026.8.2 to 2026.9.0, with no YAML change. Maintainer clydebarrow attributed it to #18529, which moved the D/C toggling inside the SPI bus lock to fix a shared-pin problem on the M5Stack CoreS3. #19745 restored the old sequence for the 16-bit (spi_16) path, and its release notes place it in 2026.9.1. This affects boards that drive the panel through a 16-bit shift register, not ordinary ILI9341/ST7789V breakouts. Still, pin your ESPHome version while migrating and read the mipi_spi changelog before upgrading.

Is it really an ILI9341?

Mislabeled modules are common. ESPHome itself ships three presets for one Sunton ESP32-2432S028 board: ILI9341 (micro-USB version), ST7789V and ILI9342 (dual-USB versions). Two ways to check:

  1. Try the models. With no lambda, mipi_spi shows a test card. Flash ST7789V with invert_colors: true, then ILI9341 with invert_colors: false, and keep the one with correct colours and geometry.
  2. Read the ID. ESPHome display drivers only write to the panel, so this needs a short Arduino or ESP-IDF sketch and the module's SDO/MISO line wired. Per the datasheets, the ILI9341 answers Read ID4 (0xD3) with 0x00 0x93 0x41 after a dummy byte. The ST7789V answers RDDID (0x04) with 0x85 0x85 0x52 by default. The ST7789V's ID bytes live in non-volatile memory that module makers can program, so treat an unexpected value as a hint, not proof.

Written by the DisplayEngineer team. We manufacture small TFT and LCD modules; our ST7789V datasheet, pinout and init-code notes cover the controller used in several of the panels above. Corrections from anyone who has tested these configs on real hardware are very welcome.

References

]]>