Connect to a board
mcuctl reaches a board over USB serial, Wi-Fi (Connect over Wi-Fi) or Bluetooth (Connect over Bluetooth). Connecting works the same way in the editor, the browser interface and the terminal.
In an editor
Click the mcuctl status bar item or run mcuctl: Connect to Board, then
pick a port (COM3, /dev/ttyACM0 and so on). mcuctl: Resume Last Device
reconnects to the previous one. For a CircuitPython board, prefer its REPL
serial interface: the data interface of a second CDC port is filtered out.
From the terminal
mcuctl ports # what is attached
mcuctl connect /dev/ttyACM0
mcuctl status # connected? which interpreter?
mcuctl resume # reconnect to the last device
Connect interrupts any running program and enters the raw REPL. It reads
sys.implementation.name and reports interpreter as micropython or
circuitpython, and every later command adjusts to that. The two differ in
what a reset does and in how packages install; see
Work with CircuitPython.
You can also skip connect and pass -d PORT to any command. With no
editor session running, the command opens a private session for itself.
The clock
Connect sets the board’s clock to the host’s UTC only when the board’s clock
is unset (a year before 2024). A clock that NTP or anything else has set is
left alone. mcuctl rtc --set always sets it, in UTC on both interpreters, and
mcuctl rtc reads it back in machine.RTC().datetime() order. mpremote’s
own rtc --set writes local time, so the two tools disagree by your UTC
offset.
One program owns the port
A serial port can have one owner. If another tool holds it (a serial monitor, Thonny, another mcuctl window), connect fails with a busy error; close the other tool or disconnect there. While an editor is connected, the terminal commands share its session instead of opening a second connection, which is why they find it first: Drive a board from an agent has the details.
On a board whose program never returns control, Windows can report the port as busy or locked. Troubleshooting covers what to try.