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.