Session
Open and inspect a debug session against the resolved board.
connectdisconnectget_board_infoget_stateNever hard fault again
The HAL for AI Agents
Hard Fault is a local embedded-debug agent HAL built on pyOCD. Bring your own model — Codex, Claude, or an OpenAI / Anthropic API key — and it flashes images, reads UART, and drives SWD on your board, behind safety guardrails.
Latest native release: v0.1.8 unsigned preview
01 — install the v0.1.8 preview
$ (set -e; installer=$(curl -fsSL https://github.com/JasonPeng2019/BYO-Installer/releases/download/0.1.8/install.sh); printf '%s\n' "$installer" | sh -s -- --version 0.1.8 --base-url https://github.com/JasonPeng2019/BYO-Installer/releases/download/0.1.8 --sha256 66c8a648cfba41d1de478afc3ec1f6ece8d24b754ede4dfc7c19027569630177 --allow-unsigned)$ (set -e; installer=$(curl -fsSL https://github.com/JasonPeng2019/BYO-Installer/releases/download/0.1.8/install.sh); printf '%s\n' "$installer" | sh -s -- --version 0.1.8 --base-url https://github.com/JasonPeng2019/BYO-Installer/releases/download/0.1.8 --sha256 bc40953e558676d43565af2de147f1665ba7ee9a779d84d58cc5d74ee70d192d --allow-unsigned)$ & ([scriptblock]::Create((New-Object System.Net.WebClient).DownloadString('https://github.com/JasonPeng2019/BYO-Installer/releases/download/0.1.8/install.ps1'))) -Version 0.1.8 -BaseUrl 'https://github.com/JasonPeng2019/BYO-Installer/releases/download/0.1.8' -Sha256 cf2ead609b533d531d77f4bac8393e2ef5125daa168d9f2106d17e85ee7aaa6e -AllowUnsigned$ (set -e; installer=$(curl -fsSL https://github.com/JasonPeng2019/BYO-Installer/releases/download/0.1.8/install.sh); printf '%s\n' "$installer" | sh -s -- --version 0.1.8 --base-url https://github.com/JasonPeng2019/BYO-Installer/releases/download/0.1.8 --sha256 d5b2c624f58caa13e9a31c8a6b54fdd0407957a282a460841eec5a97a8f95b85 --allow-unsigned)02 — initialize this project
$ cd /path/to/your/firmware-project$ byo init$ byo codex firmware # or: byo claude firmwareSee the setup guide and uninstall commands.
// the difference
Without hardware, an agent guesses.
Hard Fault hands it the probe.
One firmware task, run twice — once against a bare model, once through Hard Fault’s MCP server.
Safe enough to hand a model a debug probe. Every mutating action passes a gate, and watchers stop a runaway before it can brick a board.
Board safety →// the loop
A closed loop, not a script.
Every run cycles Connect → Decide → Act → Verify until the board meets its green criteria — or a guardrail stops it.
01
Connect
Resolve the board from its YAML — target, probe, baud, recover policy — and open an SWD session with a tracked run id.
02
Decide
The model plans the next action from compact run memory: structured decisions in, one governed action out.
03
Act
Flash an image, run a build, write to UART, or step the core — every action routed through the brain gate.
04
Verify
Check UART boot text and green criteria, then persist evidence and events to the run log.
↻ the loop repeats until green criteria pass
// capabilities
A firmware engineer's bench, driven by a model.
Execution control
Drive the core exactly as you would by hand at the bench.
haltresumestepresetRegisters & memory
Read and write core registers and memory, including block reads.
read_core_registerwrite_core_registerread_memorywrite_memoryFirmware & UART
Flash validated images and capture serial output for verification.
flash_firmwareread_serialRecovery
Board-policy-aware unlock for supported recover modes.
unlock_recoverGoverned by MCP
Every operation is an MCP tool — wire the same governed actions into your own client or agent.
set_breakpointremove_breakpointread_memory_block// guardrails
Safe to hand a model direct control.
A model can iterate on a fix, but it cannot silently loop on a destructive action or brick a board without an explicit, validated request.
Flash gate
Flashing validates its input before touching the board — a tracked baseline or a valid .elf/.hex succeeds; a missing path or bad suffix refuses.
$flash_firmware notes.txt→refused · invalid suffix
Recover gate
Recovery is board-policy aware: it needs explicit confirmation where a recover_mode exists, and refuses outright where none is tracked.
$unlock_recover (no recover_mode)→refused · unsupported
Mutation watchers
Scoped watchers stop a run thrashing on a broken op — and only that op. Disconnecting and reconnecting clears the block.
$flash_firmware ×3 failed→flash blocked
// benchmark
Proven on a frozen suite, not a demo.
Our internal frozen suite now spans 289 benchmark cases, 30 boards, and four model backends. The average turnkey score was 100, with 90% average development-time acceleration.
- 289
- frozen benchmark cases
- 100
- average turnkey score
- 30
- boards in the frozen suite
- 4
- model backends
- 90%
- average development-time acceleration
// hardware
Every Environment.
Use built-in target support or a compatible CMSIS Device Family Pack. The families shown are examples; pack support extends to many more vendors and MCUs. Each board is checked during setup.
500+board designs listed in Arm's CMSIS-Pack catalogHow board support works →
Infineon
XMC · PSoC
Texas Instruments
MSPM0 · TM4C
NXP
Kinetis · LPC · MCX
Analog Devices / Maxim
ADuCM · MAX32
Nordic
nRF52 · nRF53
ST
STM32
Catalog breadth is an estimate of compatible targets, not a count of boards validated in the frozen suite.
// get started