Run code and use the REPL
The REPL
mcuctl: Open REPL opens a terminal on the same session as File Transfer,
with ANSI colors, in the editor’s Terminal panel. Interrupt, soft reset, soft
reboot and hard reset are commands too. After a hung exec or run, mcuctl
releases the dead port handle (transport_dead in the activity log) so
Connect or Resume can take the port back.
Run something once
mcuctl eval '1+1'
mcuctl exec 'print(1)' # waits for the program to end
mcuctl run ./app.py # starts it and returns
mcuctl run ./short.py --follow # waits for it to finish
mcuctl run ./encode.py --follow --timeout 0 # waits however long it's quiet
exec waits for the program’s output to end, so use --no-follow for a
loop. run returns immediately by default, so an editor session stays usable.
If a command says timeout waiting for first EOF, the board is still running
your program: use run without --follow, then interrupt or soft-reset.
When a run --follow times out, the error carries partialOutput, everything
printed up to that point.
run --follow gives up when the script prints nothing for 10 s. A script that
works quietly for longer, a long encode or a stream, needs --timeout SECONDS,
or --timeout 0 to wait until it ends.
Interrupt and reset
Command |
MicroPython |
CircuitPython |
|---|---|---|
|
Ctrl-C, no reset |
the same |
|
Raw soft reset: skips |
Toggles between the friendly and raw REPL: does not run |
|
Ctrl-D: runs |
Ctrl-D: runs |
|
The board boots normally |
the same |
After a deploy, a board that looks dead after soft-reset is expected: it
skipped main.py. Use soft-reboot or hard-reset to run startup. Debug
with exec, eval or run before rewriting main.py.
Watch a program without stopping it
get, put and exec all enter the raw REPL, which interrupts whatever is
running. To follow a long script without killing it:
mcuctl run --no-follow script.pystarts it and returns.mcuctl watch-replsubscribes to the board’s output and never sends Ctrl-C. Ctrl-C on the host stops watching; the board keeps running.
Have the script print() its own progress. To talk to the program as well as
watch it, hold its REPL.
If you need a file’s final contents, have the script write it and get it
when the script is done. probe bundles that cycle:
mcuctl probe -d /dev/ttyACM0 probe.py --reboot-first --capture /result.txt --wait 20
--reboot-first hard-resets and reconnects before the run, since stale module
state from a previous try can make a working board look broken. It needs
--device. --wait is a flat delay before the capture read, and --capture
is optional. The result is JSON either way, and a failed capture sets
"ok": false and capture_error instead of losing the fact that the run
itself worked.
Plot what a board prints
In the browser interface, the Plotter button graphs lines that are only numbers.