How mcuctl works

mcuctl is a board tool for MicroPython and CircuitPython: a VS Code-compatible extension, a Python command line, and a local browser app for file transfer and REPL work. Those three are different faces on the same parts. This page is the model; the guides say how to use it.

One owner for the serial port

VS Code extension UI ──┐
CLI / agent RPC ───────┼──> one extension sidecar ──> mpremote / board serial session
                       │
firmware build/flash ──┴──> separate firmware engine

python -m mcuctl ──────────> separate loopback browser app and private board session

A long-lived Python sidecar owns the serial link, built on mpremote, and speaks JSON lines to the extension. File Transfer, the REPL and the terminal commands all go through it, which is why they don’t fight over the port. When an editor session is active, the CLI finds its session (through ~/.mcuctl/workspace-rpc.json, or an explicit MCUCTL_RPC address) and shares it instead of opening a second connection. Without one, the CLI starts a private sidecar and needs -d DEVICE for board operations. The extension’s loopback server binds an ephemeral port, so there is no fixed port to remember.

python -m mcuctl is a separate thing: a loopback web server with its own private board session. That is why you connect a board in the editor or in the browser interface, not both.

Firmware work runs apart

Builds and flashes run in a separate engine process, so a long compile never holds the interactive serial session. A build is one run of omnipython-builds’ build_mp.py; the engine reports its log and its error. On WSL, serial and ESP32 flashing use the Windows Python, because only it can open COM ports, while builds use a native Linux Python.

Two interpreters, one interface

mcuctl detects the interpreter on connect (sys.implementation.name) and adjusts. Resets, package installs and file routing differ between MicroPython and CircuitPython: see Run code and use the REPL, Install packages and Work with CircuitPython.