Build STM32 firmware using CubeIDE headless builder.

Compiles the project at project_path using the specified build configuration. CubeIDE headless mode automatically detects new/deleted source files - no Makefile maintenance needed.

Args: project_path: Absolute path to the CubeIDE project root (must contain .project and .cproject). configuration: Build configuration - "Debug" or "Release". clean: If true, clean before building (slower but ensures full rebuild).

Returns: Build result with filtered compiler output, errors/warnings, ELF size, and the path to the built .elf file on success.

Build firmware and flash it to the board in one step.

Compiles the project, then flashes the resulting .elf to the connected STM32 via ST-Link. This is the most common workflow - use this instead of calling stm32_build and stm32_flash separately.

Args: project_path: Absolute path to the CubeIDE project root. configuration: Build configuration - "Debug" or "Release". clean: If true, clean before building. reset: If true, reset the board after flashing. verify: If true, verify flash contents after writing. probe: Board nickname, probe nickname, or ST-Link SN to target a specific board.

Returns: Combined build and flash results.

Flash firmware to STM32 board via ST-Link.

Writes the specified .elf (or .bin/.hex) file to the connected STM32's flash memory using OpenOCD over SWD.

Args: elf_path: Absolute path to the firmware file (.elf, .bin, or .hex). reset: If true, hard-reset the board after flashing. verify: If true, verify flash contents match the file. probe: Board nickname, probe nickname, or ST-Link SN to target a specific board.

Returns: Flash result — ST-LINK info, download status, verify result.

Read board information via ST-Link.

Connects to the STM32 via SWD and reads device info: ST-LINK version, voltage, CPU type, and flash size. Useful for verifying the ST-Link connection before building/flashing.

Args: probe: Board nickname, probe nickname, or ST-Link SN to target a specific board.

Returns: Board info — ST-LINK firmware, serial, voltage, CPU, flash size.

Show all connected ST-Link probes and boards with nicknames.

Enumerates all connected ST-Link probes, reads MCU info from each, and enriches the output with board and probe nicknames from the persistent board map (~/.stm32-mcp/board_map.json).

Returns: Formatted list of connected boards and probes with nicknames, MCU device names, UIDs, and ST-Link serial numbers.

Name a board (by MCU UID) or probe (by ST-Link serial number).

Board nicknames follow the physical MCU — they persist across probe swaps. Probe nicknames follow the ST-Link — label your probes physically (colored dots, tape) to match.

Exactly one of mcu_uid or stlink_sn must be provided. If nickname is empty, removes the mapping.

Args: nickname: Human-readable name (e.g., "blinky", "sensor-board"). mcu_uid: MCU unique device ID (for board nicknames). stlink_sn: ST-Link serial number (for probe nicknames).

Returns: Confirmation message.

Resolve C expressions against the firmware ELF — the one-call replacement for grepping headers and hand-running GDB.

Args: elf_path: Path to the firmware .elf. expressions: A single expression or a JSON array of them. Accepts plain symbols ("g_app") and C paths with dots and array indices ("g_app.scheduler.taskCount", "g_app.scheduler.tasks[3].lastRunMs").

Returns: One line per expression: address, size, and type. Type tells float vs int vs enum vs struct — use it to pick the right live_memory/display treatment. Struct-typed entries note that sub-fields resolve as ".".

List available serial ports.

Shows all serial ports on this machine with device path, description, VID:PID, and serial number. ST-Link VCP ports are marked with [ST-Link VCP].

Returns: List of serial ports with details.

Open a serial connection to an STM32 board.

Opens the specified serial port and stores the connection for use with serial_send, serial_read, and serial_disconnect. The connection persists across tool calls until explicitly disconnected.

Args: port: Serial port path (e.g., "/dev/cu.usbmodem1234"). Use serial_list_ports to find available ports. baudrate: Baud rate (default 115200).

Returns: Connection status message. The connection_id for subsequent calls is the port path (e.g., "/dev/cu.usbmodem1234") — the same value you passed as the port argument.

Send data over serial and optionally read the response.

Sends the data string (plus line ending) to the connected board. If read_response is true, waits for and returns the response using a polling loop (50ms inter-byte, 200ms silence break).

Args: connection_id: Connection ID from serial_connect. data: The string to send. read_response: If true, wait for and return response data. read_timeout: Max seconds to wait for response (default 2.0). line_ending: Line ending to append — "lf" (default), "cr", "crlf", or "none".

Returns: What was sent, and the response if read_response is true.

Read data from the serial port buffer.

Reads whatever data is available or arrives within the timeout period. Useful for catching async output like boot messages or periodic prints. Uses polling loop (50ms inter-byte, 200ms silence break).

Args: connection_id: Connection ID from serial_connect. timeout: Max seconds to wait for data (default 2.0). max_bytes: Max bytes to read (default 4096).

Returns: Received data as text, or "(no data received)".

Close a serial connection.

Closes the serial port and removes it from the connection pool.

Args: connection_id: Connection ID from serial_connect.

Returns: Confirmation message.

Run a multi-step hardware sequence (serial + SWD memory) in one tool call.

Executes a list of send, delay, capture, mem_write, and mem_read steps sequentially with real timing (no tool-call overhead between steps). Useful for hardware test sequences that are timing-sensitive — blinking GPIOs over SWD, bit-banging registers with deterministic delays, mixed serial/memory flows.

Timing note: each mem_write/mem_read currently launches a fresh OpenOCD process (~tens of ms overhead per op), so sub-10ms delays between memory ops won't be honored precisely. Delay steps themselves are accurate.

Args: steps: JSON array of step objects. Step types: Send: {"send": "CMD", "to": "/dev/ttyACM0 (Linux) or /dev/cu.usbmodemXXXX (macOS)", "expect": "OK", "read_timeout": 2.0, "line_ending": "lf"} Delay: {"delay_ms": 500} Capture: {"capture": true, "label": "my_label", "device_index": 0} MemWrite: {"mem_write": true, "address": "0x48000418", "value": "0x40", "probe": "yellow", "width": 32} or {"mem_write": true, "symbol": "blink", "elf_path": "/path/to.elf", "value": "1", "probe": "yellow"} MemRead: {"mem_read": true, "address": "0x48000400", "count": 2, "probe": "yellow", "width": 32, "label": "gpio_pre"} or {"mem_read": true, "symbol": "blink", "elf_path": "/path/to.elf", "probe": "yellow"}

    Serial: "to" is the connection_id from serial_connect. "expect",
        "read_timeout", "line_ending" optional on send steps.
    Capture: "label" and "device_index" optional. PNGs saved to /tmp/stm32-captures/.
    Memory: "probe" accepts board nickname, probe nickname, or ST-Link SN.
        "address" is hex ("0x48000418"); or use "symbol" + "elf_path".
        "width" is 8/16/32 bits, defaults to 32 (auto-detected from symbol size).
        "count" (read only) defaults to 1. "label" (read only) prefixes the result line.
on_failure: "continue" (default) to run all steps, or "stop" to abort on first failure.
filter_responses: If true, expect patterns match only >-prefixed VCP response lines.

Returns: Formatted report with per-step results and a summary line.

Read memory by address or variable name (from ELF symbols).

Reads memory from the connected STM32 via OpenOCD. Can specify a raw hex address or a symbol resolved from the ELF — a plain variable name or a C path like "g_app.dosing.cfg.pid_kp".

Args: address: Hex address like "0x20000304". Mutually exclusive with symbol. symbol: Variable name ("blink") or C path ("app.state.rate"). Requires elf_path. elf_path: Path to .elf file for symbol resolution. count: Number of units to read (default 1). width: Access width — 8, 16, or 32 bits. Auto-detected from symbol size. probe: Board nickname, probe nickname, or ST-Link SN. Empty auto-selects the only connected board.

Returns: Memory contents formatted as hex values.

Write memory by address or variable name.

Writes a value to memory on the connected STM32 via OpenOCD. Can specify a raw hex address or a symbol resolved from the ELF — a plain variable name or a C path like "g_app.dosing.cfg.pid_kp".

Args: address: Hex address like "0x20000304". Mutually exclusive with symbol. symbol: Variable name ("blink") or C path ("app.state.rate"). Requires elf_path. elf_path: Path to .elf file for symbol resolution. value: Value to write — hex "0xFF" or decimal "255". width: Access width — 8, 16, or 32 bits. Auto-detected from symbol size. probe: Board nickname, probe nickname, or ST-Link SN. Empty auto-selects the only connected board.

Returns: Confirmation of the write operation.

Start continuous background memory monitoring via SWD.

Launches a persistent OpenOCD connection and polls the specified variables at the given interval. Results are written to a JSONL file and kept in a ring buffer accessible via live_memory_read. Variables can be edited while the session runs via live_memory_write.

IMPORTANT: Only one live_memory session per probe at a time. Stop any existing session before starting a new one. Stop live_memory before flashing or using stm32_read_memory/stm32_write_memory.

Args: variables: JSON array of variables to monitor. Elements can be: - String: plain symbol ("blink") or C path with dots/indices ("g_app.dosing.cfg.pid_kp", "tasks[2].lastRunMs"), resolved from the ELF. Structs (size > 4 bytes) are auto-expanded into individual fields with dotted names; prefer a sub-struct like "g_app.dosing" over a huge root ("g_app") to keep the poll fast. - Dict with "symbol": {"symbol": "temp", "type": "float"} Add "expand": false to disable struct auto-expansion. - Dict with "address": {"address": "0x20000304", "name": "x", "width": 32} elf_path: Path to .elf file for symbol resolution. probe: Board nickname, probe nickname, or ST-Link SN. Empty auto-selects the only connected board. interval_ms: Polling interval in milliseconds (minimum 250). output_path: JSONL output file path. Default: /tmp/live_memory_.jsonl

Returns: Session ID, output path, and resolved variable list.

Stop a live memory monitoring session.

Stops the background polling thread, kills the OpenOCD process, and returns session statistics.

Args: session_id: Session ID from live_memory_start.

Returns: Session statistics: duration, read count, error count, output path.

Read recent entries from a live memory session.

Returns the last N entries from the in-memory ring buffer without touching the JSONL file.

Args: session_id: Session ID from live_memory_start. last_n: Number of recent entries to return (default 10, max 100).

Returns: Recent memory readings formatted as text.

Edit a variable through a RUNNING live memory session (live expression edit).

Writes through the session's OpenOCD connection — the monitoring session keeps running and the next polls show the new value. No need to stop and restart the session. Integers and floats are accepted ("1200", "0x4B0", "0.85" — floats require a 32-bit symbol).

Args: session_id: Session ID from live_memory_start. value: Value to write — hex "0xFF", decimal "255", or float "0.85". symbol: Variable name or C path ("g_app.dosing.cfg.pid_kp") resolved from the session's ELF. Mutually exclusive with address. Width auto-detected from symbol size. address: Hex address like "0x20000304". Mutually exclusive with symbol. width: Access width — 8, 16, or 32 bits (address form only).

Returns: Write confirmation with the target variable.

Start a real-time debug session via a persistent OpenOCD connection.

Enables CPU control (halt/resume/step/reset), hardware breakpoints, watchpoints, register access, and stack inspection through the debug_* tools. One session per probe.

Args: probe: Board nickname, probe nickname, or ST-Link SN. elf_path: Path to the firmware .elf — enables symbol names for breakpoints and source locations in halt reports. Recommended.

Returns: Session ID (pass to all other debug_* tools) and core state.

Stop a debug session and shut down OpenOCD.

Args: session_id: Session ID from debug_session_start. resume_first: If the core is halted, resume it before shutting down so firmware keeps running (default true). Set false to leave the core halted.

Returns: Confirmation with session duration.

Report debug session status: core state, location, breakpoints, watchpoints.

Args: session_id: Session ID from debug_session_start.

Returns: Core state (halted/running), PC/LR/SP with function and source line when halted, and the current breakpoint/watchpoint lists.

Halt the CPU and report where it stopped.

Args: session_id: Session ID from debug_session_start.

Returns: Core state and PC/LR/SP/xPSR with function name and source line.

Resume execution of a halted core.

Args: session_id: Session ID from debug_session_start.

Returns: Confirmation, or notice if the core was already running.

Single-step the halted core by N instructions.

Args: session_id: Session ID from debug_session_start. count: Number of instructions to step (1-100, default 1).

Returns: New PC location after stepping (function name and source line).

Reset the target (system reset).

Args: session_id: Session ID from debug_session_start. halt: false (default) = reset and run firmware; true = reset and halt at the reset vector (startup code inspection).

Returns: New target state.

Block until the core halts (e.g. breakpoint hit), then report where.

Use after debug_resume when a breakpoint is armed. Returns the halt location (PC/LR/SP/xPSR with function and source line) or a timeout note.

Args: session_id: Session ID from debug_session_start. timeout_ms: Give up after this many milliseconds (default 5000).

Returns: Halt report, or timeout message with current state.

Manage hardware breakpoints (Flash Patch & Breakpoint unit).

Args: session_id: Session ID from debug_session_start. action: "set", "clear", "clear_all", or "list" (default). location: Function name or hex address — required for set/clear. Function names resolve via the session's ELF.

Returns: Breakpoint list after the operation.

Manage data watchpoints (DWT comparators — usually only a few per MCU).

Args: session_id: Session ID from debug_session_start. action: "set", "clear", "clear_all", or "list" (default). location: Variable name (ELF) or hex address — required for set/clear. width: Access size in bytes: 1, 2, or 4 (default 4). access: "r", "w", or "rw" (either direction, default). value: If set (e.g. "5"), break only when the watched value matches.

Returns: Watchpoint list after the operation.

Read core registers while the core is halted.

Args: session_id: Session ID from debug_session_start. regs: "core" (default) = PC, LR, SP, xPSR; "all" = full register dump (r0-r12, SP, LR, PC, xPSR, MSP/PSP, CONTROL...); or a single register name like "r5" or "pc".

Returns: Register values in hex. PC and LR are annotated with function and source line when an ELF is loaded.

Read or write RAM/registers through the debug session.

Works while the core is running (real-time) as well as halted — unlike stm32_read_memory this does not launch a second OpenOCD.

Args: session_id: Session ID from debug_session_start. action: "read" (default) or "write". address: Hex address like "0x20000304". Mutually exclusive with symbol. symbol: Variable name resolved from the session ELF. Structs (size > 4 bytes) are auto-expanded into per-field reads. value: Value to write (hex "0xFF" or decimal) — write only. width: Access width — 8, 16, or 32 bits (auto from symbol size). count: Number of units to read (read only).

Returns: Memory contents as hex values, or write confirmation.

Reconstruct an approximate call stack from PC, LR, and a stack scan.

Requires a halted core and an ELF-loaded session. The stack scan is a heuristic: it reports PC, LR, then likely return addresses (thumb addresses into code symbols) found in the stack window, in stack order.

Args: session_id: Session ID from debug_session_start. words: Stack words to scan (default 64, max 256).

Returns: Approximate call frames, innermost first.

Upgrade FUS (Firmware Upgrade Service) on an STM32WB board.

Step 1 of first-time STM32WB bringup. Must run before installing a modern BLE stack on a board shipped with an older FUS. Uses mode=UR and firstinstall=0 per FUS_INSTALL.md.

Args: probe: Board nickname, probe nickname, or ST-Link SN. wireless_dir: Optional path to STM32WB_Copro_Wireless_Binaries. Falls back to $STM32_WIRELESS_BINARIES then ~/stm32cube-wb/Projects/STM32WB_Copro_Wireless_Binaries.

Returns: Status header plus tail of the STM32_Programmer_CLI output.

Install BLE stack on an STM32WB board (requires FUS already upgraded).

Step 2 of first-time bringup. Uses firstinstall=1. If this reports FUS_STATE_IMG_NOT_FOUND, the FUS is too old — run stm32_fus_upgrade first.

Args: probe: Board nickname, probe nickname, or ST-Link SN. variant: BLE stack variant. Only 'full' is currently wired. Other variants (light, hci, lld) live at different addresses. wireless_dir: Optional path to STM32WB_Copro_Wireless_Binaries.

Returns: Status header plus tail of the STM32_Programmer_CLI output.

One-shot STM32WB bringup: FUS upgrade, then BLE stack full install.

Does NOT re-flash user firmware. FUS operations wipe flash sectors [0..3] via a helper binary, so after this call run stm32_build_and_flash with the correct project_path to restore your application.

Args: probe: Board nickname, probe nickname, or ST-Link SN. wireless_dir: Optional path to STM32WB_Copro_Wireless_Binaries.

Returns: Full transcript of both steps and a reminder to re-flash user firmware.