bakesheep/emberprobe-mcu-flash-debug/mcu-debug-control

MCU Debug Control

Use scripts/debug.js from this skill directory. It uses VS Code's debugger APIs and never reads or edits launch.json.

For paused C/C++ threads, stacks, scopes and object expansion, use scripts/inspect.js and read references/paused-inspection.md. For RTOS task states, priorities and stack fill estimates, use mcu-rtos. Inspection requires the native EmberProbe adapter.

C++ breakpoints accept .cpp source lines or a quoted, fully qualified function signature (for example --function "app::Worker::run(int)"). Prefer source lines when overloads or inlining make a function breakpoint ambiguous. A listed breakpoint is not proof that it has been verified at a firmware address; report adapter verification when available.

Before you run

• MCP first: if this session provides EmberProbe MCP tools (such as debug_control), use them; the scripts here are the fallback. The authorization and hardware rules on this page apply to both.
• Applies to: controlling the workspace debugger session (start/stop/pause/continue/step/restart) and managing source-line or function breakpoints.
• Requires: the EmberProbe Agent Bridge and VS Code's debugger APIs; --start also needs a complete EmberProbe debug configuration (ELF, probe, target, OpenOCD, SVD).
• Preconditions: one control action in flight (else DEBUG_CONTROL_BUSY — read status instead); pause needs a running target, continue/step need a paused target; breakpoints can be created before a session starts.
• Side effects: --start launches a session, resets the target and programs the ELF when Flash differs; --start --attach halts the running target without reset or download; control actions change execution state; --stop ends the session and returns once the managed OpenOCD server has released the probe (an unconfirmed server exit fails with DEBUG_SERVER_STOP_FAILED and the probe stays owned); breakpoint mutations change VS Code breakpoints.
• Success evidence: state-changing commands complete from the corresponding DAP state event. A --status/--breakpoints read does not prove --start works. On timeout, read status; never auto-resend.

For failure handling, retry limits, cross-skill routing, and result scoping, read ../_emberprobe/agent-workflow.md.

node <skill-dir>/scripts/debug.js --workspace <workspace> --status
node <skill-dir>/scripts/debug.js --workspace <workspace> --select --session <session-id>
node <skill-dir>/scripts/debug.js --workspace <workspace> --select --group <server-group> --core <zero-based-core>
node <skill-dir>/scripts/debug.js --workspace <workspace> --start
node <skill-dir>/scripts/debug.js --workspace <workspace> --start --attach
node <skill-dir>/scripts/debug.js --workspace <workspace> --pause
node <skill-dir>/scripts/debug.js --workspace <workspace> --continue
node <skill-dir>/scripts/debug.js --workspace <workspace> --step-over
node <skill-dir>/scripts/debug.js --workspace <workspace> --step-in
node <skill-dir>/scripts/debug.js --workspace <workspace> --step-out
node <skill-dir>/scripts/debug.js --workspace <workspace> --restart
node <skill-dir>/scripts/debug.js --workspace <workspace> --stop

--start resets the target and programs the ELF when Flash differs. --start --attach keeps the running firmware instead: it halts the core where it is, without reset or download, so a hung or misbehaving target keeps its state for --status, inspect.js stacks and mcu-rtos. Prefer it when the user wants to know where a running target is stuck, and resume with --continue afterwards unless they want it to stay paused. Attach programs nothing, so its result reports firmwareConsistency; on ELF_TARGET_MISMATCH, warn that source lines and symbols may not match the running firmware.

Use one action per call. --start reuses EmberProbe's configured ELF, probe, target, OpenOCD, and SVD. State-changing commands complete from the corresponding DAP state event even if debugger's request promise responds late, and they do not retry after a timeout. Only one control action may be in flight; on DEBUG_CONTROL_BUSY, read status instead of issuing concurrent commands. Pause requires a running target; continue and stepping require a paused target. Restart is available only when debugger advertises it.

Use optional --thread <positive-id> only with debug control actions (--pause, --continue, stepping, --restart, or --stop). Status, start, breakpoint listing, and breakpoint mutation commands do not accept a thread ID.

If status lists multiple sessions, select one explicitly before control or memory access. --select accepts a session ID or an unambiguous group/core in the requested workspace; it performs no hardware operation. Selection is rejected during writes or control actions. --stop closes the selected member only; shared OpenOCD groups stop their server after the last member exits. Group members do not advertise restart: stop every core before starting a new launch that resets the device. Grouped scalar reads/writes require the sidebar ELF to match the selected core. Do not guess a core or reuse another session's write confirmation.

If a control action returns DEBUG_CONTROL_TIMEOUT, run --status and do not automatically repeat the original command. If the target is still running and an explicit --pause or --restart also times out, explain that debugger may be stuck and ask before running --stop, followed by --start, to rebuild the session.

Breakpoints

node <skill-dir>/scripts/debug.js --workspace <workspace> --breakpoints
node <skill-dir>/scripts/debug.js --workspace <workspace> --add-breakpoint --source src/main.c --line 42
node <skill-dir>/scripts/debug.js --workspace <workspace> --disable-breakpoint --source src/main.c --line 42
node <skill-dir>/scripts/debug.js --workspace <workspace> --remove-breakpoint --function main

Breakpoint mutation actions are --add-breakpoint, --remove-breakpoint, --enable-breakpoint, and --disable-breakpoint. Select either --source <workspace-file> --line <1-based-line> [--column <1-based-column>] or --function <name>. Optional --condition, --hit-condition, and --log-message are accepted when adding. Breakpoints are managed by VS Code, remain visible in its Breakpoints view, and can be created before a session starts.

If EmberProbe reports DEBUG_SESSION_CONFLICT, do not guess which session to control. Base all failure explanations on the structured stderr diagnostic.