# Embedded Agent Bridge (EAB)

> Daemon and CLI bridging AI agents to embedded hardware (ESP32, STM32, nRF, NXP MCX). ALWAYS use eabctl for ALL hardware operations.

## CRITICAL: DO NOT USE THESE DIRECTLY
- esptool
- pio device monitor
- Serial port access (/dev/cu.* or /dev/tty.*)

## USE THESE INSTEAD

Check status:
    eabctl status
    eabctl status --json

View serial output:
    eabctl tail 50
    eabctl tail 50 --json

View daemon events (non-blocking JSONL):
    eabctl events 50
    eabctl events 50 --json

Flash firmware:
    eabctl flash /path/to/project

Reset device:
    eabctl reset

Fault analysis (Cortex-M crash decode):
    eabctl fault-analyze --device NRF5340_XXAA_APP --json
    eabctl fault-analyze --device MCXN947 --probe openocd --chip mcxn947 --json

Send command:
    eabctl send "text"
    eabctl wait-event --type command_sent --timeout 10

High-speed data stream:
    eabctl stream start --mode raw --chunk 16384 --marker "===DATA_START===" --no-patterns --truncate
    eabctl recv-latest --bytes 65536 --out latest.bin
    eabctl stream stop

Run diagnostics:
    eabctl diagnose
    eabctl diagnose --json

Extract base64 payload between markers:
    eabctl capture-between "===WAV_START===" "===WAV_END===" out.b64
    eabctl capture-between "===WAV_START===" "===WAV_END===" out.wav --decode-base64

Pre-flight check (run before flashing):
    eabctl preflight

## WHY

The EAB daemon manages the serial port. If you access it directly, you get "port busy" errors.
eabctl automatically pauses the daemon, does the operation, and resumes.

## TROUBLESHOOTING

Port busy error     -> Use eabctl flash instead of esptool
No output           -> eabctl status && eabctl reset
Boot loop           -> eabctl flash /path/to/working/project
Flash failed        -> eabctl preflight (diagnose issues)

## STATUS FILE

Check /tmp/eab-devices/<device>/status.json for:
- connection.status: connected/reconnecting/disconnected
- health.status: healthy/idle/stuck/disconnected
- health.idle_seconds: seconds since last activity

## EVENT STREAM

Check /tmp/eab-devices/<device>/events.jsonl for JSONL event records (pause/resume, flash, alerts, commands).

## DATA STREAM

When enabled, raw bytes are written to /tmp/eab-devices/<device>/data.bin.
Binary framing is **optional** and only applies when custom firmware is allowed (see PROTOCOL.md).

## SUPPORTED HARDWARE

ESP32 (serial/esptool), STM32 (ST-Link/st-flash), nRF5340 (J-Link/west flash), MCXN947 (OpenOCD/west flash), any Zephyr target with J-Link or OpenOCD.
