MCUscope

MCUscope is a hardware debug bridge for embedded targets. It lets both humans and AI agents (such as Claude Code) talk to an STM32 (or any) microcontroller over a serial link. They can send CAN/I2C/SPI/GPIO/ADC commands, stream and query timestamped debug output, and plot realtime data in the browser.

A single daemon (mcuscoped) owns the serial port, timestamps every line into SQLite, and serves a local REST + WebSocket API and a web UI on 127.0.0.1:8558. The mcu CLI is a thin client over that API and is the primary interface for both the human and the agent.

What you get, with any line-based firmware and no changes to it: a timestamped capture of every line, a live terminal with per-pane filters, regex search over the whole capture, !p realtime plots and !m markers from plain printf. On top of that:

• Agent primitives: mcu wait (send, then block until a matching line or timeout) and mcu assert (every --expect seen, no --forbid seen, exit 0 or 1); --json on every command; exit codes 0/1/2/3.
• Sessions: name a span of the capture, query, export or purge just that run; the daemon records one per run of its own.
• Exports: lines as text/JSONL/CSV, plot CSV with decoded enum labels and bit lanes, CAN CSV, or a whole session as a zip bundle, from the CLI or the web UI, over any clock-time window.
• Commands and buses, with the C monitor module in your firmware: can (up to nine controllers, --bus N), i2c, spi, gpio, adc, plus decoded CAN table, typed plot streams and digital/enum lanes.
• PlotJuggler: mirror plot points to PlotJuggler's UDP Server source live (mcu pj on).
• LAN access with a runtime token, rate-limited; loopback clients never need it.
• Linux and Windows 10/11, COMx, /dev/tty* and socket://host:port device strings.

This package (mcuscope) is the host side. The portable C firmware "monitor" module that runs on the target, a hardware-free simulator, and the full specification live in the project repository.

Install

Requires Python 3.10 or newer.

uv tool install mcuscope        # or: pipx install mcuscope

This exposes three console scripts on your PATH: mcuscoped (the daemon), mcu (the CLI), and mcu-sim (the hardware-free simulator).

To reach a real serial port, one OS-specific step:

• Linux: your user must be in the dialout group: sudo usermod -aG dialout $USER, then log out and back in. Without it, opening /dev/ttyACM0 fails with permission denied.
• Windows 10/11: most USB-serial adapters and ST-Link VCPs work with the in-box driver; some need the vendor driver (CP210x, CH340, FTDI).

Neither is needed for the quickstart below, which runs with no hardware attached.

Quickstart

No hardware needed to try it:

mcuscoped --sim --open            # daemon + built-in simulator; opens the web UI

The web UI at http://127.0.0.1:8558/ui/ shows the live terminal, CAN table, and realtime plots. The Plots panel also renders a Digital/Enum view (logic-analyser bit traces and labelled enum/state bands) sharing the same time base and cursor as the analog charts.

With real hardware, start the daemon first (it owns the port and captures everything), then attach the port - from the UI's + Attach dialog, or the CLI:

mcuscoped                                              # serves the API + web UI on :8558
# in another terminal (or use `mcu daemon start` to background the daemon):
mcu devices                                            # find the port name
mcu attach /dev/ttyACM0 --baud 115200 --alias board    # Linux
mcu attach COM7 --baud 115200 --alias board            # Windows

mcu status                        # daemon + port health
mcu cmd ping                      # -> monitor 1 <project>  (port-layer name, not the alias)
mcu cmd 'i2c scan'                # -> 48 50
mcu tail -f                       # follow live capture

Every command takes --json for a single machine-readable object and returns meaningful exit codes (0 success/match, 1 error or bad usage, 2 timeout, 3 daemon unreachable). Run mcu ai-guide for a compact, agent-oriented cheat sheet.

The simulator also runs standalone (mcu-sim, prints e.g. socket://127.0.0.1:9900); attach it like any device: mcu attach socket://127.0.0.1:9900 --alias sim.

What your firmware has to send

Nothing, to start with. Any line-based printf output is captured, timestamped, filtered and searchable as-is, so MCUscope is useful as a better serial terminal with no firmware changes at all. The only rule is that debug lines must not begin with < or !, which are reserved for the monitor protocol.

Two extra line formats get you realtime plots and timeline markers, with no library and no float printf:

printf("!p %lu temp=%d.%02d rpm=%d\n", tick_ms, whole, frac, rpm);
printf("!m @%lu calibration start\n", tick_ms);   // marker; the @tick is optional

!p <tick> <name>=<value> ..., values integer, fixed-point or scientific notation. Each name becomes a plot channel. Adding the portable C monitor module is only needed when you want the host to send commands to the firmware, or want decoded CAN and typed digital/enum streams. See What your firmware has to send.

Documentation

Full quickstart, configuration reference, protocol/API specification, and firmware integration guide are in the project repository.

License

MIT