build: flash the board without manual BOOT/RESET presses

[DriftKingTW]

Flashing this board took two button presses: hold BOOT and tap RESET to enter
download mode, then tap RESET again afterwards to leave it. Both are fixable in
software, and both fixes are the ones the ecosystem prescribes.

Why the board needs this at all

Espressif's own boards carry a two-transistor auto-reset circuit that ties the
USB-UART bridge's DTR and RTS to GPIO0 and CHIP_PU (plus a 1–10 µF capacitor
on EN), and esptool's --before default_reset drives exactly that circuit.

This board has no bridge — it runs the S3's native USB (ARDUINO_USB_MODE=0) —
so there is nothing for DTR/RTS to reach, and esptool cannot reboot it in either
direction. That is a property of the hardware design, not a misconfiguration.

What changed

Entering download mode — scripts/enter_bootloader.py, a pre-upload action
performing the 1200bps touch: opening the CDC port at 1200 baud and dropping DTR
makes the Arduino core restart the chip into the ROM downloader. This is the
same mechanism the Arduino ecosystem uses for every native-USB board, and it is
implemented in the core we already build against. The script waits for the
device to re-enumerate and hands the new port to esptool as UPLOAD_PORT. It is
best effort — a failure is reported and the upload proceeds — so a board already
in download mode still flashes.

Leaving download mode — two parts:

• esptool 4.5.1, which espressif32@6.3.2 pins, does not drive the
  USB-Serial-JTAG reset. 4.11.0 does. PlatformIO was already passing
  --before usb_reset --after hard_reset; only the implementation was at fault.
• board_upload.after_reset = watchdog_reset, which is what Espressif documents
  for this peripheral. The USB-Serial-JTAG can only raise a core reset, and a
  core reset does not re-sample the boot strapping pin — so a board put into
  download mode with the BOOT button stays there even after the pin is released.
  A watchdog reset is a full system reset and re-samples it. Upstream does not
  enable this automatically, so it is set per-board here.

A RESET serial command, for restarting the board while the firmware is
running rather than as part of flashing.

A note on esptool's dependencies

esptool 4.11.0 imports intelhex. PlatformIO's tool manager normally installs
that along with the package — the CI run here does exactly that — but it skipped
them on an existing ~/.platformio during development, and the build then fails
with ModuleNotFoundError: No module named 'intelhex'. If you hit that:

~/.platformio/penv/bin/pip install intelhex

The workflows install it explicitly for the same reason. Both are fallbacks, not
a standing requirement.

Testing

• Repeated pio run -t upload cycles complete with no button presses: the port
  goes firmware CDC → download mode → firmware CDC, and the uptime counter
  restarts from zero each time. Verified with both hard_reset and
  watchdog_reset.
• RESET verified against the uptime counter: the USB port drops and
  re-enumerates, and Time since boot restarts. Note that the Restarting...
  acknowledgement is not observable in practice — USB drops faster than the host
  reads it — so watch for the port disappearing instead.
• CI green on this branch, building with the new esptool.

Not covered: entering download mode by hand with BOOT+RESET and then flashing.
watchdog_reset is precisely the documented fix for that case, but it was not
exercised here.

🤖 Generated with Claude Code

https://claude.ai/code/session_014qWMQSRRkLjQs3fudZAWXh