Troubleshooting
Symptom |
What to do |
|---|---|
Listing ports shows nothing, or connect fails |
Another tool may hold the port: close Thonny and serial monitors. After a bad flash the filesystem may be corrupt: erase and reflash |
Port busy or exclusive lock |
Another mcuctl window owns that port. Disconnect there, or pick the other board. Two windows can’t share one port |
WSL can’t see |
Install a Windows Python with |
Two windows, two boards |
Use distinct ports and run the command from each workspace folder. |
The terminal reaches an unexpected session |
Two windows on one folder: the last connect wins. |
|
The session releases the port handle on its own. |
|
The board’s program is stuck in a callback that never returns, so its USB stops answering. A killed mcuctl command lets go of the port after a few seconds. If it stays busy, reset the board through its UART port ( |
|
An older mcuctl. The board’s native USB sent extra bytes after a chunk, sometimes holding a |
|
The board is still running your program. If it’s working quietly, give |
Board is dead after deploy and |
Expected: soft-reset skips |
Two USB ports (UART and native CDC) |
|
A crash or reboot with no Python traceback |
The panic backtrace goes to the console UART only: Capture the console |
|
|
|
Run |
Wrong board, or no Wi-Fi on a P4 |
|
Build can’t find omnipython-builds |
Run from the folder holding it, or pass |
Build can’t find a cross-compiler |
Install the one the error names, or use Locate… for its |
App partition too small |
|
A module is missing from the firmware |
|
CircuitPython: every command hangs and serial writes time out |
The board is wedged with the receive ring full and Ctrl-C can’t reach it. 1200-baud touch, then copy firmware |
CircuitPython: wrote to the drive and the board didn’t restart |
|
Connect is slow and you want to see where the time goes |
Set |
CircuitPython: the display blanks when the script ends |
Expected. The app has to hold the VM |
More on a specific area: Recover a board, Work with CircuitPython, Connect over Wi-Fi.