Repository navigation
Conversation
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>
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.
With no I2C data bus configured,
initOrRestoreWireForOpenDisplay()callsWire.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_pinanddata_pin), so every upload after boot hangs the device.What happens
Wire.begin()runs beforeSPI.begin(), so SPI takes the pins back and the boot screen renders.Wire.end()runs and clearss_wire_open_display_ready.pwrmgm(true), thenfastepd_epaper_begin(), and both callWire.begin()again, so GPIO8/9 move to I2C.SPI.begin()returns early because the bus was never ended. The firstSPI.transfer16()inbbepInitIT8951()→it8951ProbeController()then never returns.The main loop stays stuck, so the
PIPE_WRITE_STARTACK is queued but never sent. The client times out after 30 s and falls back toDIRECT_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:
Wirestarts onesp32-s3-N16R8-extuartesp32-s3-N16R8On 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 fromWire.The EE03 is the only preset in
simple-config-presets.jsonthat 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:
pwr_pinto 0xFF ("keep EE03 SPI attached"). Withpwr_pinset, power-down ranconfigureDisplayPinsLowPower(), 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:
Wire.begin()default-pin fallback, and theinitOrRestoreWireForOpenDisplay()call on every panel power-up.SPI.end()for the FastEPD driver, so a laterSPI.begin()doesn't reclaim pins that something else has taken since.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 exampleSPI.end()beforeinitIT8951(), 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'sSDA/SCLagainst 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.Wire.begin()on the defaults as before.Wireon 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.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.
PIPE WRITE START, then[EPD session] acquire: COLD bring-up, then nothing. A later0x0070frame still arrived on the BLE side, so the link was fine and the main loop was stuck.fastepd_direct_write_reset()→fastepd_epaper_begin()→initIT8951()→it8951ProbeController()→it8951WriteCmdCode(). The last step logged wasSPI.transfer16(0x6000), afterSPI.beginTransaction()and the HRDY wait had both returned. The same call takes about 2 ms at boot.ITE_ENincluded, 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.initIT8951(), device wedgedBoot log with this branch:
Upload log with this branch (the warning is logged only once per boot, so it doesn't repeat here):
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