Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.embedder.com/llms.txt

Use this file to discover all available pages before exploring further.

Debug mode is a dedicated agent mode for diagnosing real hardware problems. You stay in plain language — describe what’s wrong, ask for what you want to know — and Embedder uses GDB, logic analyzers, oscilloscopes, and power analyzers to investigate. Use it when you have a board on the bench and a problem you can’t pin down from source alone: an MCU that hangs, an I²C bus that NACKs intermittently, sleep current that’s 10× expected, a clock that won’t lock.

​
Enter debug mode

embedder
/debug
Embedder TUI cycling Act → Plan → Debug with Shift+Tab
On entry, Embedder checks for a connected J-Link probe (and offers to install J-Link software if missing), runs hardware_status to list every connected instrument, and auto-loads the helper docs for each one. Python helpers for power analyzers (ppk2-api, joulescope) and logic analyzers (logic2-automation, dwfpy) are installed on first use, not at mode entry — you’ll get a confirmation prompt the first time the agent tries to run a script for a given device.
Always enter debug mode before asking the agent to probe. Outside of debug mode, the GDB and instrument tools are unavailable and the agent can’t run them.

​
How to prompt in debug mode

Describe the symptom in natural language. Embedder picks the right instrument and writes the script for you.
embedder
> the device isn't logging anything — use gdb to figure out where it's hanging
embedder
> capture 2 seconds of I²C on the BME280 and show me the addresses
embedder
> measure sleep current on this board at 3.3V for 5 seconds
embedder
> the chip resets when the motor PWM kicks in — find out why
You don’t need to name the tool. If you say “is this clock signal clean?” the agent reaches for the scope; “capture UART” reaches for the logic analyzer. Naming the tool (“use gdb”, “use the Joulescope”) narrows the choice when there’s ambiguity.

​
What the agent does behind the scenes

For every problem, Embedder follows a structured Observe → Hypothesize → Probe → Verify loop:
1

Observe

Reads the hardware_status snapshot, recent serial / RTT history, current GDB state, and the source files involved.
2

Hypothesize

Lists candidate root causes and prioritizes them by likelihood and ease of verification.
3

Probe

Writes and runs a Python script under .embedder/hardware/ that drives the chosen instruments.
4

Verify

Checks the probe results against each hypothesis. Either narrows the next probe or reports the root cause.

​
Sub-guides

GDB

Inspect register state, set breakpoints, walk RTOS task lists, snapshot a live target without resetting it.

Logic analyzer

Capture and decode SPI, I²C, UART, CAN, USB, and 18 other digital protocols.

Power analyzer

Profile sleep current, boot energy, and active draw with PPK2 or Joulescope.

Oscilloscope

Probe analog signals — clock, reset, power rails, comm lines.

Combined workflows

Worked scenarios that need multiple instruments — sleep-current regression, intermittent I²C NACK, brown-out under load.

​
Tips

  • Re-prompt with “refresh hardware status” if you plug in a new instrument mid-session — the agent only auto-detects on entry.
  • The agent prefers non-destructive probes by default. If you want it to flash firmware, reset the chip, or erase memory, say so explicitly.
  • Sessions in debug mode block submitWork — you’ll need to leave debug mode (or end the session) to mark the work as done.

​
Availability

Debug mode is enabled in standard Embedder builds. Some enterprise builds (e.g. the infineon distribution) ship with debug mode disabled — in those cases the /debug slash command is hidden and the agent will report “Debug mode unavailable” if asked to switch.
Last modified on May 12, 2026