Your first session

You don’t need a board to try mcuctl. It can hold a desktop MicroPython interpreter open the same way it holds a board, so this page uses one. Every command works on a board once you name it with -d.

You need a micropython executable. If you don’t have one, build the unix port or download one from the MicroPython releases.

Start a session and ask it something

mcuctl hold start --spawn micropython
mcuctl hold ask -d micropython "import sys; print(sys.implementation.name, sys.implementation.version[:2])" --text
mcuctl hold ask -d micropython "print(sum(range(10)))" --text
mcuctl hold stop -d micropython

It prints:

micropython (1, 30)
45

The version is whatever your interpreter reports. hold start opened the interpreter and kept it running between commands. Each hold ask typed a line at its prompt, waited for the next prompt and returned what came back, and --text printed just that. hold stop let go.

Leave out --text and you get JSON with an output field and a next offset you can pass to hold read --since.

The same thing on a board

Boards are reached over USB serial, Wi-Fi or Bluetooth. List what is attached, then name one:

mcuctl ports
mcuctl exec -d /dev/ttyACM0 "print(1 + 1)"
mcuctl ls -d /dev/ttyACM0 /

On Windows a port is COM3 and the like. -d ws://HOST reaches a board over Wi-Fi and -d ble://NAME over Bluetooth.

Where to go next: