ws-ESP32-S3-CAM: Command for Claude Code

Read serial output from the board

idf.py monitor does not work in non-TTY contexts (Claude Code, piped shells, subshells) — it exits immediately and looks like success. Use pyserial directly, and respect the macOS DTR trap below.

Usage: /monitor [seconds] (default 15)

---

⚠ The macOS DTR trap — read this before "why is serial silent?"

On macOS, opening /dev/cu.usbmodem* raises DTR and RTS by default. For the ESP32-S3's native USB-Serial-JTAG, DTR=asserted drives GPIO0 low and RTS=asserted drives EN low — i.e. every time pyserial opens the port, the chip is forced back into download-mode / held in reset. The device never boots the app, so serial stays silent, so you keep re-opening the port, so it stays stuck. Spent ~20 min of cry-detect-01 bring-up debugging this on 2026-04-17.

Symptoms:

• First serial read shows rst:0x15 (USB_UART_CHIP_RESET), boot:0x0 (DOWNLOAD(USB/UART0)) → waiting for download.
• Subsequent reads return 0 bytes.
• esptool ... chip_id succeeds (proves USB is fine; device is in download mode).
• Red LED (CH32V003 P6) stays off or dim; power-LED (green) stays solid.

Fix 1 — stty -hupcl + dd (works reliably)

stty -f /dev/cu.usbmodem3101 -hupcl 2>/dev/null
dd if=/dev/cu.usbmodem3101 of=/tmp/boot.log bs=1 count=50000 &
DD_PID=$!; sleep 15; kill $DD_PID 2>/dev/null; wait 2>/dev/null
head -200 /tmp/boot.log

stty -hupcl tells the driver not to drop DTR on close. dd opens the device at a lower level than pyserial and doesn't assert modem control lines. This is what actually grabbed the backtrace that unblocked us.

Fix 2 — pyserial but set dtr/rts before open

~/.espressif/python_env/idf5.5_py3.14_env/bin/python -u -c "
import serial, time, sys
ser = serial.Serial()
ser.port = '/dev/cu.usbmodem3101'
ser.baudrate = 115200
ser.timeout = 0.2
ser.dtr = False   # must be set BEFORE open
ser.rts = False   # must be set BEFORE open
ser.open()
# Optional: pulse RTS only to reset without touching DTR
ser.rts = True; time.sleep(0.2); ser.rts = False; time.sleep(0.4)
start = time.time()
while time.time()-start < 20:
    n = ser.in_waiting
    if n: sys.stdout.buffer.write(ser.read(n)); sys.stdout.buffer.flush()
    else: time.sleep(0.05)
ser.close()
"