USB REPL unavailable when GUI is running (VCP+MSC vs GUI event loop conflict)

[Amperstrand]

Summary

When the Specter-DIY GUI is running on the touchscreen, the USB VCP REPL becomes inaccessible. mpremote cannot enter raw REPL mode, and even raw serial Ctrl-C interrupts are silently consumed. The REPL only works during a brief ~1-2 second boot window before the GUI's asyncio event loop takes over.

This blocks automated GUI testing and developer REPL access during normal operation.

Environment

• Board: STM32F469DISC (Specter-DIY Disco)
• Firmware: make disco (GUI-enabled, no HIL)
• Boot: boot/main/boot.py sets pyb.usb_mode("VCP+MSC")
• USB: Device enumerates as 16c0:27dd (CDC-ACM), creates /dev/ttyACM1
• MicroPython fork: f469-disco (custom)

Expected behavior

Per the MicroPython documentation and STM32 USB design, pyb.usb_mode("VCP+MSC") should provide:

• USB VCP (virtual COM port) for REPL — always available
• USB MSC (mass storage) for PYBFLASH — always available

These should coexist with the GUI (LVGL on LTDC/DSI touchscreen) since they use independent hardware peripherals.

Actual behavior

Boot sequence

1. Device resets, boot/main/boot.py runs pyb.usb_mode("VCP+MSC")
2. USB enumerates as CDC-ACM (/dev/ttyACM1 on Linux)
3. Brief REPL window (~1-2s): mpremote connect works, print('ok') succeeds
4. GUI starts (display.init() → SpecterGUI() → specter.start())
5. REPL becomes permanently blocked: mpremote fails with TransportError: could not enter raw repl
6. Raw serial Ctrl-C (\x03) is silently consumed — no response
7. Raw serial Ctrl-D (\x04) causes USB re-enumeration, device disappears

After GUI starts

$ mpremote connect /dev/ttyACM1 exec "print('ok')"
mpremote.transport.TransportError: could not enter raw repl

$ python3 -c "
import serial
s = serial.Serial('/dev/ttyACM1', 115200)
s.write(b'\x03')  # Ctrl-C
" 
# No response, no error — silently consumed

What works

• make hil (HIL mode, no GUI): REPL works indefinitely
• make disco during boot window: REPL works for ~1-2s before GUI starts
• make disco with main.py patched to skip GUI: REPL works indefinitely

Root cause analysis

The GUI's asyncio event loop (asyncio.run()) monopolizes the MicroPython VM. When mpremote tries to enter raw REPL mode, it sends a soft reset (Ctrl-B) which requires the VM to be in the REPL idle state. But the VM is running the asyncio event loop and never returns to the REPL prompt.

Specifically:

1. boot/main/boot.py:53 — pyb.usb_mode("VCP+MSC") sets up USB VCP with dupterm slot 1 (REPL)
2. src/main.py:69 — specter.start() calls asyncio.run(self.setup()) which never returns
3. The asyncio loop polls USB VCP for Specter host protocol data but doesn't service REPL dupterm

The USBHost.enable() call (in platform.set_usb_mode()) explicitly kills REPL:

# src/platform.py:337-338
os.dupterm(None, 0)
os.dupterm(None, 1)

But this only happens when the user enables USB communication in settings — the REPL should survive until then.

What we tried

1. make hil + HIL commands over ST-Link UART

Approach: Build with HIL_ENABLED=1, use TEST_UI: commands over pyb.UART("YB", 9600) via ST-Link VCP.
Result: ST-Link V2.1 on this board doesn't bridge the UART "YB" signal to its USB VCP. The ST-Link VCP only provides SWD debug, not UART passthrough. platform.stlk is a physical UART pin that would need a separate USB-serial adapter.
Verdict: Requires hardware change (external USB-serial adapter wired to UART YB pins).

2. make hil with GUI enabled (patched main.py)

Approach: Removed if platform.hil_test_mode: pass guard so GUI runs in HIL mode.
Result: HIL mode auto-enables USBHost early (specter.py:564-567), which calls platform.enable_usb() and kills REPL via dupterm(None, 0) and dupterm(None, 1). REPL is gone before GUI even starts.
Verdict: USBHost + REPL are mutually exclusive on the same USB VCP.

3. make disco (no HIL, standard boot)

Approach: Standard production build with GUI. USB set to VCP+MSC.
Result: REPL works during ~1-2s boot window, then blocked by GUI event loop. Ctrl-C silently consumed.
Verdict: asyncio event loop prevents REPL from regaining control.

4. Raw serial interrupt during GUI

Approach: Send Ctrl-C (\x03), Ctrl-D (\x04), Ctrl-B (\x02) via pyserial to /dev/ttyACM1.
Result: All commands silently consumed. Ctrl-D causes USB re-enumeration and device disappears. No way to break into REPL.
Verdict: No interrupt mechanism works once GUI is running.

5. Boot window race condition

Approach: Script to detect REPL during boot, upload DGP files before GUI starts.
Result: Boot window is ~1-2s and unreliable. Script timed out.
Verdict: Too fragile for automation.

Potential workarounds

A. LVGL timer-based REPL yield (recommended)

Add a mechanism where the LVGL update timer periodically yields to the REPL. MicroPython's dupterm can coexist with asyncio if the event loop checks for REPL input. This could be:

• A dupterm callback that queues REPL input for processing
• A dedicated asyncio task that services dupterm alongside the GUI loop
• LVGL v6 lv_task_handler() is already called from a timer — add dupterm servicing there

B. GPIO-based GUI suspend

Add a physical button or GPIO pin that, when pressed, suspends the GUI event loop and returns to the REPL. Similar to how some MicroPython boards use a BOOT button to enter safe mode.

C. USB serial adapter for UART YB

Connect an external USB-serial adapter (e.g., FT232H) to the STM32's UART "YB" pins. This gives a dedicated REPL port that's independent of USB VCP. The ST-Link SWD connector has UART TX/RX pins that could be used.
Pros: Guaranteed REPL access regardless of GUI state
Cons: Requires hardware modification or additional cable

D. Separate USB configurations

Use pyb.usb_mode("VCP") without MSC, or configure USB descriptors to expose two separate interfaces (VCP for REPL + another VCP for Specter protocol). This would require custom USB descriptor changes in the MicroPython port.
Pros: Clean separation
Cons: Significant MicroPython port changes

E. UART-based REPL only, no USB REPL

Keep USB exclusively for Specter host protocol and MSC. Use the physical UART (wired to ST-Link or external adapter) for REPL. This is closest to the existing HIL design intent (see the commented-out code in platform.py:339-351).
Pros: No conflict, clean separation of concerns
Cons: Requires physical serial connection for development

Related code

File	Line(s)	Relevance
boot/main/boot.py	53	pyb.usb_mode("VCP+MSC")
src/main.py	17-69	GUI setup and specter.start()
src/platform.py	320-356	set_usb_mode(), stlk UART, dupterm management
src/specter.py	555-621	HIL listener, USBHost auto-enable
src/hil.py	49-106	HIL command handler over UART
f469-disco/micropython/ports/stm32/usb.c	624-627	VCP dupterm slot assignment

Impact

• Developer experience: Cannot use REPL while GUI is running. Must flash HIL firmware (no GUI) for any REPL-based development or testing.
• Automated testing: Cannot automate GUI tests via USB. HIL UART requires physical serial adapter.
• Debugging: Cannot inspect live GUI state via REPL. Must use debug traces or HIL commands.

[Amperstrand]

Root cause: ST-Link UART bridge is blocked by USB pin conflict

Investigated whether the ST-Link V2.1's UART bridge can carry REPL. It can — but the current firmware config blocks it.

Hardware wiring

The ST-Link V2.1 on STM32F469DISCO bridges its VCP to PA9 (TX) / PA10 (RX). However, the MicroPython board config uses those pins for USB:

Pin	Current config	ST-Link bridge use
PA9	MICROPY_HW_USB_VBUS_DETECT_PIN	USART1 TX → ST-LINK RX
PA10	MICROPY_HW_USB_OTG_ID_PIN	USART1 RX → ST-LINK TX
PA11	USB DM (OTG FS device mode)	—
PA12	USB DP (OTG FS device mode)	—

Additionally, the "YB" UART in the current firmware maps to USART3 on PB10/PB11 (Arduino header pins), NOT to the ST-Link bridge. This is a different UART entirely — platform.stlk = pyb.UART("YB", 9600) goes to PB10/PB11, which has no connection to the ST-Link.

What would need to change (in f469-disco submodule)

1. In mpconfigboard.h: remove USB_VBUS_DETECT_PIN and USB_OTG_ID_PIN
2. Add USART1 on PA9/PA10, define MICROPY_HW_UART_REPL = PYB_UART_1 at 115200 baud
3. Rebuild MicroPython cross-compiler and firmware

Trade-off: USB OTG host mode detection lost (VBUS detect + OTG ID). USB device mode (VCP+MSC on PA11/PA12) still works without those pins — and that's all Specter uses.

Why we're not doing this now: Requires changes to the f469-disco MicroPython submodule, which we want to avoid modifying for portability.

---

Workarounds for automated testing

Workaround 1: Two-phase flash (current approach, proven)

How: Flash make hil → upload DGP → run test suite → flash make disco → manual GUI test.

Steps:

# Phase 1: Automated GP testing
make hil
openocd ... flash ...
mpremote cp seedkeeper.dgp :/flash/gp/
mpremote exec "from keystore.javacard.gp.test_gp_flow import main; main()"

# Phase 2: Visual GUI testing (SeedKeeper already installed)
make disco
openocd ... flash ...
# User tests GUI on touchscreen

Pros: Simple, no code changes, fully proven (19/19 tests passing).
Cons: Can't test GUI "Install from SD Card" menu (no DGP on filesystem after disco flash). Two flash cycles per test round.

Workaround 2: Two-phase with pre-loaded DGP (better GUI coverage)

How: Same as above, but write DGP to flash via openocd's write_memory command before flashing disco firmware.

Steps:

# Phase 1: Automated GP testing (installs SeedKeeper on card)
make hil && openocd ... flash ...
mpremote cp seedkeeper.dgp :/flash/gp/
mpremote exec "from keystore.javacard.gp.test_gp_flow import main; main()"

# Phase 2: Find DGP flash address, write it via openocd, flash disco
# (Need to determine /flash/gp/ flash address from linker script)
# Then flash disco firmware which preserves /flash/ filesystem

# Phase 3: GUI test with all features (including Install menu)

Pros: GUI "Install from SD Card" menu would work. Full feature coverage.
Cons: Requires knowing the flash address of the /flash/ filesystem region. Complex.

Workaround 3: Boot-window race (fragile)

How: Flash disco firmware, then immediately send commands during the ~1-2s REPL window before GUI starts.

Steps:

# Python script that races to upload DGP during boot
# 1. Detect ttyACM1 appearing
# 2. Connect at 115200
# 3. Send base64-encoded DGP as Python one-liner
# 4. GUI starts, DGP is on filesystem

Pros: No firmware changes.
Cons: Extremely fragile. Boot window is 1-2 seconds. Race condition with USB enumeration.

Workaround 4: Application-level dupterm on PB10/PB11 (requires hardware)

How: Add os.dupterm(pyb.UART("YB", 115200), 0) in boot.py to route REPL to USART3 (PB10/PB11). Connect a $5 USB-serial adapter (FT232H, CP2102) to PB10/PB11 on the Arduino header.

Steps:

1. Wire USB-serial adapter to CN7: PB10 (TX) → RX, PB11 (RX) → TX
2. Add one line to boot.py: os.dupterm(pyb.UART("YB", 115200), 0)
3. GUI runs on touchscreen, REPL available on USB-serial adapter

Pros: Guaranteed REPL access regardless of USB state. No C changes needed.
Cons: Requires external hardware. Needs UART wiring to CN7 connector.

Workaround 5: Future C fix (proper solution, documented for reference)

If/when we decide to modify f469-disco submodule:

1. In mpconfigboard.h: free PA9/PA10 from USB, define USART1 with MICROPY_HW_UART_REPL
2. Update platform.py: change stlk = pyb.UART("YB", 9600) to pyb.UART(1, 115200)
3. REPL goes through ST-Link VCP at 115200 baud, USB VCP remains for Specter host protocol
4. GUI + REPL coexist natively

Pros: Clean solution, no external hardware.
Cons: Requires f469-disco submodule change. Loses USB OTG host detection (acceptable for our use case).

[Amperstrand]

Two-phase flash testing — verified working

Successfully tested the two-phase approach from the issue description (Workaround 1):

Phase 1: Automated GP testing (HIL firmware)

1. make hil → flash via openocd
2. Upload SeedKeeper DGP via base64 exec (mpremote cp times out, but base64 works)
3. Run test_gp_flow.py → 38/38 passed, 0 failed
4. SeedKeeper installed on card (persists across flash)

Phase 2: Visual GUI testing (disco firmware)

1. make disco → flash via openocd
2. GUI runs on touchscreen, SeedKeeper already installed on card
3. User can test JavaCard Manager menu items

Lessons learned

DGP upload: mpremote cp hangs when the GUI's asyncio loop is running (even in HIL mode). Workaround: upload via mpremote exec with base64 encoding:

mpremote exec "import ubinascii; f=open('/flash/gp/X.dgp','wb'); f.write(ubinascii.a2b_base64('...')); f.close()"

MemoryError on first DGP load: The GUI's asyncio event loop fragments the heap. Running gc.collect() before loading fixes it. The test suite now calls gc.collect() before loading DGP files.

Card reader pin conflict: When disco firmware runs, the GUI's provisioning flow reconfigures the card reader pins, causing isCardInserted() to return False. The presPin (C2) reads 0 even though the card is physically seated. This only affects REPL-initiated card operations — the GUI's own card probing works because it runs during setup before the pin state changes. This is a separate issue from the REPL conflict and needs investigation.

Command sequence for repeatable testing

# Phase 1: HIL + test
source /etc/profile.d/arm-toolchain.sh
make hil
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "init" -c "reset halt" \
  -c "flash write_image erase bin/specter-diy.bin 0x08000000" -c "reset run" -c "shutdown"
sleep 10
mpremote connect /dev/ttyACM1 exec "import os; os.mkdir('/flash/gp')"
mpremote connect /dev/ttyACM1 exec "import ubinascii; f=open('/flash/gp/SeedKeeper.dgp','wb'); f.write(ubinascii.a2b_base64('$(base64 -w0 bin/applets/seedkeeper.dgp)')); f.close()"
mpremote connect /dev/ttyACM1 exec "import gc; gc.collect(); from keystore.javacard.gp.test_gp_flow import main; main()"

# Phase 2: GUI test (SeedKeeper already on card)
make disco
openocd ... flash ...
# Test GUI on touchscreen