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.

Hardware bugs rarely respect tool boundaries. A current spike happens because of a firmware code path. An I²C NACK looks fine on the protocol decoder until you scope the rise time. In debug mode, Embedder can mix GDB, the logic analyzer, the scope, and the power analyzer in a single script — and you can ask for it in plain language. This page shows three example multi-tool prompts and what the agent does for each.

​
Scenario 1: Sleep-current regression on a BLE board

Symptom: sleep current rose from 8 µA to 380 µA after a recent commit. Prompt:
embedder
> sleep current jumped from 8 µA to ~380 µA after my last commit. firmware drives GPIO0 high during sleep and logs "enter_sleep"/"wake" over the UART that's wired to the Joulescope's GPI1. trigger a capture on the GPI0 sleep window, decode the UART in parallel, and read NRF_RTC0 and the wakeup-source variable mid-capture without resetting the chip.
What the agent does:
  1. Triggers a Joulescope capture only during the sleep window using the firmware’s GPI0 marker.
  2. Uses the JS220’s hardware UART decoder on GPI1 to decode the DUT’s log lines in parallel — enter_sleep / wake markers will line up with the current trace.
  3. Connects GDB non-intrusively mid-capture so it can read the RTC peripheral and g_last_wakeup_source without disturbing the sleep state.
  4. Reports avg sleep current, the decoded UART bytes, and the register values.
What to look for: if the UART line shows enter_sleep during the high-current window, a peripheral didn’t power down. If g_last_wakeup_source is unexpected, an interrupt is firing repeatedly.

​
Scenario 2: Intermittent I²C NACK during sensor bring-up

Symptom: the sensor returns valid data 95% of the time, NACKs the rest. Pure software state inspection didn’t reveal anything. Prompt:
embedder
> the BME280 NACKs about 5% of the time. start a manual I²C capture on SDA=ch0, SCL=ch1. set a GDB breakpoint on HAL_I2C_ErrorCallback. when the breakpoint hits, dump the I²C error register and the last few I²C frames so I can see which transaction failed.
What the agent does:
  1. Connects GDB and arms the breakpoint.
  2. Starts a manual logic-analyzer capture with an I²C decoder.
  3. Continues execution and waits.
  4. When the error fires, reads the error register, exports the analyzer table, and saves the capture file.
  5. Reports the failing transaction byte and links to the saved capture.
What to look for: the I²C frame just before the breakpoint hit. Address NACK at the start → wrong slave address. NACK mid-write → likely clock-stretch timeout; escalate to the oscilloscope to check rise time.

​
Scenario 3: Brown-out under motor load

Symptom: the MCU resets when the motor PWM kicks in. You suspect a rail droop, but it could also be a software fault. Prompt:
embedder
> the chip resets when I enable the motor PWM. probe VDD on the SDS812X channel 1, trigger on a falling edge below 2.8V, capture for 500ms. capture PWM and Hall on Saleae channels 0–2 at the same time. after the reset, attach without halting and read SCB->CFSR and SCB->HFSR so I can tell if it was brown-out or a software fault.
What the agent does:
  1. Arms a single-shot droop trigger on the Siglent and captures the rail.
  2. Captures PWM and Hall sensor lines on the Saleae in parallel.
  3. After the fault, connects GDB non-intrusively and reads SCB->CFSR (0xE000ED28) and SCB->HFSR (0xE000ED2C).
  4. Reports the rail trace, the digital capture path, and the decoded fault registers.
What to look for: if VDD drops below the MCU’s BOR threshold during the PWM transition, it’s a hardware brown-out — bigger bulk cap or stiffer rail. If VDD stays clean and CFSR shows a UsageFault (UNDEFINSTR, UNALIGNED), it’s software — set a breakpoint on the fault handler and read the stacked PC.

​
Tips for multi-tool prompts

  • Mention every observable you want. “Capture I²C and read the error register” is much clearer than “debug the I²C bus” — the agent doesn’t have to guess what counts as success.
  • Mention the trigger. If you want the capture to start on a GPIO edge, a GDB breakpoint, or a timed window, say so. Otherwise the agent picks a default.
  • Say “without resetting” if you don’t want the agent to flash or reset mid-investigation. The non-intrusive attach pattern keeps the chip running.
  • Order matters when describing tools. “Set a breakpoint, then start the capture” is sequential; “start the capture, then continue execution” sets up monitoring before the action.

​
What makes multi-tool workflows possible

Behind the scenes, debug mode wires a few primitives together that make it natural to chain instruments:
  • One Python prelude per script — every connected instrument’s helpers are available without imports.
  • Shared capture timeline — Logic and Power tabs publish from one coordinator, so simultaneous captures share a timebase in the Console panel (VS Code extension and standalone app).
  • Joulescope GPI triggers (gpi0–gpi3) — capture only the window of interest by firmware-driven GPIO edges.
  • JS220 hardware UART decoder — DUT log lines decoded in parallel with current sampling.
  • Digilent external triggers (external1–external4, t1, t2) — slave a Digilent logic capture to an external GPIO edge.
  • Non-intrusive GDB attach — register snapshots without resetting a live target.
You don’t need to know which primitive applies — describing the symptom and the observables you want is enough. The agent picks the combination.

​
When to ask for a combined workflow

Reach for multi-tool prompts when:
  • You need temporal correlation across instruments (current event ↔ log line ↔ register value).
  • The bug is intermittent and you want one trigger to freeze every observable at once.
  • The hypothesis spans the hardware / software boundary — e.g. “is this a brown-out or a software fault?”.
Stay with a single tool when you only need one observable, or when the probe is fast enough that running tools serially is fine.

​
Next steps

Debug mode overview

Back to the OHPV loop.

Best practices

General tips for keeping sessions focused.
Last modified on May 12, 2026