Skip to content

fix(display): don't start Wire on default pins that the display uses - #187

Open
LordMike wants to merge 1 commit into
OpenDisplay:mainfrom
LordMike:fix/wire-default-pins-display-clash
Open

LordMike wants to merge 1 commit into
OpenDisplay:mainfrom
LordMike:fix/wire-default-pins-display-clash

Conversation

@LordMike

Copy link
Copy Markdown
Contributor

With no I2C data bus configured, initOrRestoreWireForOpenDisplay() calls Wire.begin() with no arguments. That starts I2C on the board's default pins, which on ESP32-S3 are SDA=GPIO8 and SCL=GPIO9. On the Seeed EE03, those are the IT8951's SPI MISO and MOSI (dc_pin and data_pin), so every upload after boot hangs the device.

What happens

  • Boot: Wire.begin() runs before SPI.begin(), so SPI takes the pins back and the boot screen renders.
  • Power-down: after each refresh, Wire.end() runs and clears s_wire_open_display_ready.
  • Next upload: the cold bring-up runs pwrmgm(true), then fastepd_epaper_begin(), and both call Wire.begin() again, so GPIO8/9 move to I2C. SPI.begin() returns early because the bus was never ended. The first SPI.transfer16() in bbepInitIT8951() → it8951ProbeController() then never returns.

The main loop stays stuck, so the PIPE_WRITE_START ACK is queued but never sent. The client times out after 30 s and falls back to DIRECT_WRITE_START, which also gets no reply. It then disconnects, and the device stays wedged until it is reset.

With 2.27.1 on an EE03, every upload after boot failed this way. After the failed upload, the device also stopped advertising within a few minutes.

Why the EE03, and not the reTerminal E1003

The two boards share the same display SPI pinout: CLK=7, MISO (dc)=8, MOSI (data)=9. The difference is in the presets:

reTerminal E1003 preset EE03 preset
I2C data bus SCL=GPIO20, SDA=GPIO19 (SHT40, touch) none
Wire starts on GPIO19/20, from the data bus GPIO8/9, the board defaults, which are the display's MISO/MOSI
Build esp32-s3-N16R8-extuart esp32-s3-N16R8

On the E1003, initOrRestoreWireForOpenDisplay() always takes the data-bus branch, so it never reaches the default-pin fallback.

Several other ESP32-S3 presets also have no I2C bus and put a display pin on GPIO8/9: EE02, EE04, EE05, XIAO ESP32-S3 and Good Display 13.3". They don't hang because they use bb_epaper, not FastEPD: power-down calls SPI.end() for them, so the next bring-up starts SPI fresh and takes the pins back from Wire.

The EE03 is the only preset in simple-config-presets.json that combines all three conditions: no I2C bus, display pins on the default SDA/SCL, and the FastEPD driver.

Related EE03 fixes

This is the third EE03 problem where something else takes the panel's pins. The first two were worked around in the opendisplay.org preset on 2026-11-08:

  • OpenDisplay/opendisplay.org@61d3024 installs the non-extuart build on the EE03. The extuart build starts its log UART on GPIO43/44, which on the EE03 are PWR_EN and the panel's CS.
  • OpenDisplay/opendisplay.org@00973ef sets pwr_pin to 0xFF ("keep EE03 SPI attached"). With pwr_pin set, power-down ran configureDisplayPinsLowPower(), which took the SPI pins back as GPIOs. That commit's description matches this bug's symptom: "the boot screen draws, then every image transfer times out".

Both workarounds were applied on the device I tested. This bug is a third way into the same trap, and no preset setting avoids it short of configuring an I2C bus the board doesn't need.

Background

Three things together make this possible:

  • 7ffea91 (2026-06-19, 1.8) added the Wire.begin() default-pin fallback, and the initOrRestoreWireForOpenDisplay() call on every panel power-up.
  • 70ce214 (2026-07-24, 2.24.4/2.25.0) moved the IT8951 to FastEPD. Power-down skips SPI.end() for the FastEPD driver, so a later SPI.begin() doesn't reclaim pins that something else has taken since.
  • A preset with no I2C bus, whose FastEPD display uses the default SDA/SCL pins. Today that is only the EE03.

The second point is the underlying fragility: anything that reconfigures a display pin between transfers leaves SPI detached, with no error, until reset. This PR removes the I2C trigger. A broader hardening would have fastepd_epaper_begin() reattach the bus, for example SPI.end() before initIT8951(), so a cold bring-up recovers whatever took the pins. I left that out to keep this change small, but I'm happy to add it here or in a follow-up.

Fix

Before falling back to Wire.begin(), check the board's SDA/SCL against every configured display pin: clk, data, dc, cs, cs_2, reset and busy. If any of them match, don't start Wire, and log a warning once per boot.

  • The check only applies when no I2C data bus is configured, so boards with a data bus, including the E1003, are unaffected.
  • Boards whose default I2C pins don't clash with the display still get Wire.begin() on the defaults as before.
  • The no-bus bb_epaper presets listed above (EE02, EE04, EE05, XIAO ESP32-S3, Good Display 13.3") also stop starting Wire on GPIO8/9. They configure no I2C device, so nothing should depend on it, and they no longer briefly hand their SPI pins to I2C on every power-up. I haven't tested this on those boards.
  • A board that needs I2C on pins shared with the display has to configure a data bus, and the warning says so.

The check runs on each panel power-up. It costs at most 7 byte compares per display, plus one log line per boot. The nRF path (#else) is unchanged.

How it was traced

The device was connected over USB serial while Home Assistant pushed images over BLE.

  1. Release 2.27.1 logged PIPE WRITE START, then [EPD session] acquire: COLD bring-up, then nothing. A later 0x0070 frame still arrived on the BLE side, so the link was fine and the main loop was stuck.
  2. Debug builds that log each step of the cold bring-up narrowed it down: fastepd_direct_write_reset() → fastepd_epaper_begin() → initIT8951() → it8951ProbeController() → it8951WriteCmdCode(). The last step logged was SPI.transfer16(0x6000), after SPI.beginTransaction() and the HRDY wait had both returned. The same call takes about 2 ms at boot.
  3. The pin settings, invalid ITE_EN included, were ruled out first. The I2C fallback was confirmed as the cause by skipping it: with that one change, the cold bring-up finished in 2.1 s and the upload completed.

Tested

Tested on a Seeed EE03: ESP32-S3 N16R8, env esp32-s3-N16R8, panel IC 3001 at 1872x1404, 4 bpp, configured from the EE03 preset. Uploads went over BLE through Home Assistant and an ESPHome BLE proxy.

2.27.1 This branch
Boot renders renders, logs the warning once
Upload after boot hangs in the first SPI transfer of initIT8951(), device wedged 1,314,144 bytes (77 KB zlib) in 5.8 s, full refresh, 18.6 s end to end in Home Assistant

Boot log with this branch:

W: Default I2C pins (SDA=8 SCL=9) are display pins; Wire not started. Configure an I2C data bus if this board needs I2C.
I: Boot screen with QR rendered
I: [EPD session] force off
I: === Setup completed successfully ===

Upload log with this branch (the warning is logged only once per boot, so it doesn't repeat here):

I: === [BLE] PIPE WRITE START COMMAND (0x0080) ===
I: [EPD session] acquire: COLD bring-up
I: === [BLE] PIPE WRITE DATA COMMAND (0x0081) ===
I: === [BLE] PIPE WRITE END COMMAND (0x0082) ===
I: DW complete: 321 chunks, 1314144/1314144 bytes, zlib 77330 B on wire (16.99x), 5.83 s, 220.2 KB/s
I: EPD refresh: FULL (mode=0, end payload 0x00)
I: [EPD session] release: keep-alive disabled, powering off

Builds (clean checkout, pioarduino 55.03.39): esp32-s3-N16R8, esp32-s3-N16R8-extuart, esp32-c3-N4 and esp32-wrover-e-N4R8 all succeed. The other CI targets were not built locally.

🤖 Generated with Claude Code

With no I2C data bus configured, initOrRestoreWireForOpenDisplay()
calls Wire.begin() on the board's default pins. On ESP32-S3 those are
SDA=GPIO8 and SCL=GPIO9, which on the EE03 are the IT8951's SPI MISO
and MOSI. Every panel power-up moved them to I2C. FastEPD skips
SPI.end() at power-down, so the next SPI.begin() did not take them
back. The first SPI transfer in bbepInitIT8951() then hung, and every
upload after boot wedged the device.

Skip the default-pin Wire.begin() when SDA or SCL is a configured
display pin, and warn once per boot. Boards with an I2C data bus, or
whose default pins don't clash, are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant