嵌入式调试AI助手

Embedded Agent Bridge

Background daemons that manage serial ports, GDB, and OpenOCD so LLM agents (Claude Code, Cursor, Copilot, etc.) can interact with embedded hardware without hanging or wasting context tokens. The agent pings the daemon for data through a simple CLI and file interface instead of trying to hold open interactive sessions directly.

Agent ──eabctl──► Serial Daemon ──UART──► ESP32 / STM32
  │
  ├──Python API──► JLinkBridge ──SWD/RTT──► nRF5340 / Zephyr targets
  │
  ├──eabctl──► fault-analyze ──GDB──► Cortex-M registers (any probe)
  │
  └──eabctl──► DSS Transport ──JTAG/XDS110──► TI C2000

Features

Serial Monitor Daemon - Auto-detect USB serial ports - Timestamped logging to latest.log - Pattern detection (crashes, errors, disconnects) → alerts.log - Bidirectional communication via cmd.txt queue - Auto-reconnection on disconnect - Pause/resume for flashing (port sharing) - JSON event stream (events.jsonl) for structured agent consumption

GDB + OpenOCD Bridge - Start/stop OpenOCD from CLI (eabctl openocd start --chip esp32s3) - One-shot GDB commands (eabctl gdb --cmd "bt" --cmd "info registers") - Chip-agnostic flash, erase, reset, chip-info commands - Automatic ELF-to-binary conversion for STM32 (st-flash requires .bin) - ESP32 and STM32 (ST-Link) support built-in

ESP-IDF Integration - eab-flash wrapper: auto-pauses daemon, flashes, daemon resumes - Works with idf.py flash and esptool directly

RTT (Real-Time Transfer) - J-Link transport: JLinkRTTLogger subprocess with background logging, multi-format output (rtt.log, rtt.jsonl, rtt.csv) - probe-rs transport: Native Rust extension (PyO3) for probe-agnostic RTT (ST-Link, CMSIS-DAP, J-Link, ESP USB-JTAG) - Log rotation, boot/reset detection - Real-time plotter (browser-based uPlot + WebSocket, parses DATA: key=value from RTT stream)

Cortex-M Fault Analysis - eabctl fault-analyze reads fault registers (CFSR, HFSR, BFAR, MMFAR, SFSR, SFAR) via GDB - Decodes fault bits to human-readable descriptions - Stacked PC extraction for crash location - Works with any debug probe (J-Link or OpenOCD/CMSIS-DAP)

Debug Probe Abstraction - Pluggable probe backends: J-Link (via JLinkGDBServer), OpenOCD (CMSIS-DAP, ST-Link) - Probe registry with auto-detection - Backward-compatible with legacy JLinkBridge API

C2000 DSS Transport - Persistent JTAG session via TI CCS scripting (Python API) - Fast memory read/write (~1-5ms per read vs ~50ms with DSLite) - ERAD profiler, DLOG buffer capture, register decode - Trace export to Perfetto JSON (ERAD spans, DLOG tracks, log events) - Variable streaming from live C2000 targets

ML Inference Benchmarking - INT8 TFLite Micro with CMSIS-NN backend on Cortex-M33 and Cortex-M55 - DWT hardware cycle counter profiling (zero-overhead, exact cycle counts) - Automated bench_capture regression step parses [ML_BENCH] output lines - Cross-board comparison: sine, person_detect, micro_speech, exoboot_gait models - STM32N6 SRAM boot automation (GDB load for boards without on-chip flash) - Example firmware: mcxn947-ml-bench/, stm32n6-ml-bench/, stm32n6-npu-bench/, stm32n6-gait-bench/

Zephyr RTOS Support - west flash integration for Zephyr targets - Chip profiles for nRF5340, MCXN947, RP2040, STM32N6 - Board detection from CMakeCache.txt - STM32N6 SRAM boot via sram_boot regression step

Hardware-in-the-Loop Regression Testing - Define tests in YAML — flash, reset, send commands, assert log output, check variables - eabctl regression --suite tests/hw/ --json runs a full suite with pass/fail JSON output - Setup/teardown phases, variable assertions (expect_eq/gt/lt), fault checking - ML benchmark steps: bench_capture (parse inference metrics), sram_boot (STM32N6 SRAM load) - CI-friendly: exit code 0 = all pass, 1 = any fail - Steps shell out to eabctl --json for full isolation

HIL pytest Plugin - Write hardware-in-the-loop tests as normal pytest functions with fixtures and assert - hil_device fixture manages device lifecycle (flash, reset, teardown) - RTT output captured per-test, attached to pytest report on failure - --hil-device, --hil-chip, --hil-probe CLI options; tests auto-skip without hardware - hil_central fixture for second BLE central device

BLE Hardware-in-the-Loop - Second nRF5340 DK as BLE central controlled via RTT shell (BleCentral) - Multi-device YAML regression: devices: {peripheral: ..., central: ...} - New YAML steps: ble_scan, ble_connect, ble_subscribe, ble_write, expect_notify - Full BLE end-to-end test: peripheral advertises → central connects → notifications flow → writes

DWT Non-Halting Watchpoints - Program Cortex-M DWT comparators to watch memory addresses without halting the CPU - Stream JSONL events when watched variables change (at ~100Hz polling via J-Link) - ELF symbol resolution — watch conn_interval by name, not address - Conditional halting watchpoints via GDB Python (e.g. halt only when value changes >20%) - eabctl dwt watch/halt/list/clear subcommands; all 4 comparators on Cortex-M33

Debug Monitor Mode - Non-halting breakpoints for BLE firmware — debug handler runs as Cortex-M exception - BLE Link Layer keeps running at high priority; GATT callbacks debuggable without disconnect - eabctl debug-monitor enable --device NRF5340_XXAA_APP [--priority 3] - DEMCR register control (MON_EN bit 16); integrates with regression YAML flash step - eabctl preflight --ble-safe warns when BLE build + halt-mode debugging detected

MCP Server - Exposes all eabctl commands as MCP tools for Claude Desktop, Cursor, and any MCP-aware agent - 8 tools: get_status, read_rtt, send_command, fault_analyze, flash_firmware, reset_device, run_regression, get_alerts - stdio transport; install with pip install embedded-agent-bridge[mcp] - Add to Claude Desktop: {"mcpServers": {"eab": {"command": "eabmcp"}}}

Anomaly Detection - Baseline recording: capture RTT metric distributions from a known-good firmware run - Z-score comparison: detect deviations from baseline (message rates, event intervals, error counts) - EWMA streaming: real-time sigma alerting on a rolling mean — pure Python, no numpy required - Regression step: anomaly_watch with configurable sigma threshold and fail_on_anomaly - Metrics extracted: BT notify count, connection interval, MTU, heap free, TX backpressure

Fault Analysis + RTT Context - --rtt-context N on fault-analyze: captures last N RTT log lines before crash timestamp - JSON output adds context_window and ai_prompt fields for LLM root cause analysis - Auto-trigger: crash pattern detection → automatic fault-analyze → fault_report event

Agent-Friendly Design - All output in files — agents read with cat, tail, or their native file tools - --json flag on every command for structured output - No interactive sessions, no stdin, no TTY requirements - Session directory (/tmp/eab-devices/<device>/) is the single source of truth