Ratchet – BIOS flashing toolkit with a built-in MCP server for AI agents

Notifications You must be signed in to change notification settings

Fork 0

Star 3

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

94 Commits

94 Commits

.github/workflows

.github/workflows

docs

docs

packaging

packaging

rust

rust

tasks

tasks

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

install.sh

install.sh

Repository files navigation

A hardware debug and flash-programming toolkit for CH341A and CH347 USB programmers.

Its core is SPI flash programming and BIOS analysis, the path that drives live silicon end to end. Around it sits a unit-tested protocol layer (I2C, UART, 1-Wire, passive SPI sniff, JTAG, SWD, CAN), target-MCU programmers (AVR ISP, STK500 / Arduino bootloader, 24Cxx and 93xxx EEPROM, ESP32 / ESP8266, STM32 over SWD and AN3155 UART), an ARM debug surface (ADIv5, Cortex-M halt/resume/step, ELF-aware memory peek), JTAG IDCODE and BSDL boundary scan, a logic-analyzer model with Saleae / sigrok export, and Bus Pirate / slcan CAN bridges.

Not all of that is wired to live hardware yet. Status marks every command [live], [offline], or [n/w] (not wired). The rule throughout: a command with no live transport exits non-zero with a clear message; it never fakes success.

Written in Rust: a single self-contained binary with custom libusb FFI and a hand-rolled JSON-RPC MCP server, no Node or Python runtime. It replaces AsProgrammer and NeoProgrammer on the SPI-flash path, and covers ground otherwise split across flashrom, avrdude, esptool, stm32flash, and OpenOCD: native USB, image analysis, a knowledge base of diagnostics, and a built-in MCP server for AI agents.

Status

Pre-release. No GitHub Releases are published yet, so the only install route today is from source (see Install).

What drives live hardware today (CLI + MCP):

SPI flash + BIOS, end to end. status, detect, identify, read, write, verify, erase, region-erase, blank-check, sfdp, wp-status, full-repair, and full-backup run against a live CH341A or CH347. write erases the affected sectors first (SPI program can only clear bits 1→0), programs page by page, polls the write-in-progress (WIP) bit after every erase and program so it never races a busy chip, takes an automatic pre-write backup, and reads back to verify. Chips larger than 16 MB switch to 4-byte addressing automatically. full-repair runs the guided pipeline; full-backup is a full-chip read to a named file.

I2C, over CH341A bit-bang or CH347 native. i2c scan, i2c read, i2c write, and eeprom-i2c read/write (24Cxx) use the real Ch341aI2c / Ch347I2c master over the live bus.

JTAG IDCODE scan, over the CH347 JTAG engine (CH341A has none). jtag idcode-scan drives the real Ch347Jtag adapter.

Backend auto-select. open_default() probes CH347 (1a86:55db), then CH341A (1a86:5512), then falls back to mock with a stderr warning; RATCHET_FORCE_MOCK=1 forces mock. Protocol verbs use open_raw_bus(), which returns an honest error rather than a silent mock fallback when no device is present. ratchet status reports the active backend in its backend JSON field.

Offline tools that need no hardware:

i2c sniff decodes a captured (t_us, scl, sda) trace; jtag bsdl-scan parses a BSDL file and reports its boundary register; la export --format csv|jsonl converts a capture; serial-list enumerates serial ports (POSIX); repl is a stdin REPL over the SPI backend; plus the analysis verbs analyze, diff, checksum, chip-info, search, post-decode, and voltage-reference.

Not wired to live hardware yet: uart, onewire, swd, avr, eeprom-microwire, esp, stm32, la capture, buspirate, can, plus monitor, serial connect, and failure-search. Each one's protocol logic is implemented and unit-tested against a mock, but no live CH341A/CH347 transport adapter is wired for it yet (SWD / 1-Wire / AVR-ISP / Microwire bit-bang, native UART RX, external serial/CAN devices). They exit non-zero (or return a JSON-RPC error), never a fake success.

The destructive paths are hardened: a short USB read is a hard error instead of silent zero-padding; erase and write refuse write-protected silicon, unknown-capacity chips, and a silently-selected mock backend; 4-byte mode is always exited after use; whole-range reads stream inside a single chip-select assertion. The SPI write path is proven without hardware by a LoopbackFlash test bus that emulates an SPI NOR chip behind the CH341A USB framing (full-duplex reads, erase/program with AND-into-flash semantics), so a write → read-back → verify round-trip runs end to end. The mock backend keeps the SPI-flash surface exercisable in CI when no device is attached. 472 unit and integration tests pass.

Install

From source via cargo (the path that works today)

Requires Rust 1.82+ and libusb-1.0 installed (see Requirements).

git clone https://github.com/jackulau/ratchet cd ratchet/rust cargo install --path ratchet-cli cargo install --path ratchet-mcp

This installs ratchet and ratchet-mcp into ~/.cargo/bin/ (or the value of CARGO_INSTALL_ROOT if set). Both binaries are self-contained Rust executables; no Node, no Python.

If you prefer not to mix global state, install to a sandbox directory:

cargo install --path ratchet-cli --root /opt/ratchet cargo install --path ratchet-mcp --root /opt/ratchet export PATH="/opt/ratchet/bin:$PATH"

From a checkout (no install)

git clone https://github.com/jackulau/ratchet cd ratchet/rust cargo build --release

Binaries land at target/release/ratchet and target/release/ratchet-mcp

Uninstall

If you used cargo install

cargo uninstall ratchet-cli cargo uninstall ratchet-mcp

If you used --root /opt/ratchet during install, pass the same root:

cargo uninstall ratchet-cli --root /opt/ratchet cargo uninstall ratchet-mcp --root /opt/ratchet

If you built from a checkout

Nothing to uninstall; delete the cloned directory. Optionally:

cd ratchet/rust && cargo clean # remove build artifacts cd .. && rm -rf ratchet # remove the checkout

Removing the Claude Desktop MCP registration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the platform equivalent and remove the "ratchet" entry under mcpServers. Restart Claude Desktop.

Fix your motherboard's BIOS

This is the end-to-end path for reflashing a corrupt or bricked motherboard BIOS with a CH341A (the common ~$3 programmer) or a CH347.

What you need

A CH341A or CH347 USB programmer and a SOIC-8 / SOIC-16 test clip (or a ZIF adapter if you desolder the chip). The BIOS flash is the 8-pin SPI chip near the chipset, usually a Winbond W25Q…, Macronix MX25L…, or GigaDevice GD25Q….

A known-good BIOS image for your exact board revision - download it from the motherboard vendor's support page, or keep the backup ratchet makes in step 2.

Voltage check: most BIOS chips are 3.3 V (what a stock CH341A drives). Some are 1.8 V and need a level-shifter adapter - ratchet chip-info reports the chip's voltage so you can check before connecting.

Steps (clip onto the chip with the board powered off and unplugged):

1. Confirm the programmer + chip are talking.

ratchet status # programmer detected? which backend? ratchet identify # reads the JEDEC ID and looks the chip up in the 806-chip DB

2. Back up the current contents FIRST - always, even if the BIOS looks dead.

ratchet read backup.bin # full-chip dump → file ratchet analyze backup.bin # optional: UEFI volumes, ME region, integrity

3. Flash the known-good image. This automatically:

• saves a timestamped backup of the current chip,

• erases the affected sectors, then programs page-by-page,

• polls the write-in-progress bit after every operation, and

• reads the chip back and verifies it matches the file.

ratchet write new_bios.bin

4. Re-verify independently (optional - write already verified).

ratchet verify new_bios.bin

write refuses an all-0xFF or all-0x00 image (a blank/failed dump that would wipe the chip) and refuses an image larger than the chip. If anything goes wrong mid-write, your original is in the timestamped backup printed by step 3. To recover a board after a bad flash, just ratchet write backup.bin from that file.

One-shot pipeline. ratchet full-repair --reference new_bios.bin runs the whole thing - connection-quality check → double-verify read → health analysis → repair → write → post-write verify - as a single guided workflow.

Verifying on real hardware

CI (.github/workflows/ci.yml: fmt, clippy -D warnings, full test suite, strict doc build, and both smoke suites under RATCHET_FORCE_MOCK=1) and the test suite prove the protocol byte-for-byte without a programmer (see Status), but to confirm against your own board:

ratchet detect # programmer enumerates on USB ratchet identify --json | jq .data # JEDEC id matches the chip silk-screen / DB ratchet read a.bin && ratchet read b.bin && diff a.bin b.bin # two reads are identical (stable clip) ratchet write new_bios.bin # success=true verified=true in the output

Quick Start - multi-protocol

These drive live hardware today (or run offline where noted). Each returns a non-zero exit and an honest message if no device is present.

I2C bus scan + register read (live CH341A / CH347)

ratchet i2c scan ratchet i2c read --addr 0x50 --reg 0x00 --len 256

24Cxx I2C EEPROM dump / restore (live)

ratchet eeprom-i2c read --addr 0x50 --part 24c256 dump.bin ratchet eeprom-i2c write --addr 0x50 --part 24c256 dump.bin

JTAG IDCODE chain (live, CH347 only)

ratchet jtag idcode-scan

Offline: decode a captured I2C trace / parse a BSDL file / convert a capture

ratchet i2c sniff trace.json ratchet jtag bsdl-scan part.bsdl ratchet la export capture.json out.csv --format csv

Enumerate serial ports (POSIX)

ratchet serial-list

Verbs whose live transport isn't wired yet (uart, onewire, swd, avr, eeprom-microwire, esp, stm32, la capture, buspirate, can) exit non-zero with an explanation (see Status).

Commands

ratchet --help exposes 39 top-level subcommands plus help. Status legend: [live] drives hardware (honest error if no device), [offline] needs no hardware, [n/w] not wired to a live transport yet (exits non-zero, never fakes success).

Group Commands

Hardware status [live], detect [live], identify [live], monitor [n/w]

Chip ops read write verify erase region-erase blank-check sfdp wp-status [live]

Analysis analyze diff checksum [offline]

Knowledge base search chip-info post-decode voltage-reference [offline]; failure-search [n/w]

Serial serial-list [offline]; serial connect [n/w]

Repair full-repair [live], full-backup [live], repl [live]

Self-test self-test (also --self-test flag) [offline, mock]

I2C i2c scan/read/write [live], i2c sniff [offline], eeprom-i2c read/write [live]

JTAG jtag idcode-scan [live, CH347], jtag bsdl-scan [offline]

Instruments la export [offline]; la capture [n/w]

Not wired yet uart open/sniff, onewire scan/temp, swd connect/halt/resume/step/dump, avr signature/program/fuses/erase, eeprom-microwire read/write, esp detect/flash, stm32 swd-flash/uart-flash, buspirate bridge/probe, can sniff/send [n/w]

Every inspection command supports --json for AgentEnvelope output: {ok, command, data?|error, nextAction?}.

ratchet status --json ratchet chip-info ef4017 --json ratchet analyze backup.bin --json | jq '.data.regions'

Agent Interface (MCP)

ratchet ships a built-in MCP server (ratchet-mcp) that exposes the tool surface to AI agents (Claude Desktop, mcp-cli, custom SDK clients) over stdio, using hand-rolled JSON-RPC 2.0. It serves 30 tools: 18 for SPI-flash / BIOS analysis and 12 for hardware protocols. The SPI-flash/BIOS tools plus i2c_scan, i2c_read, i2c_write, and jtag_idcode_scan run against the live backend; the remaining hardware tools return a JSON-RPC error until their transport is wired. The JSON-RPC dispatch, schema descriptors, and argument shapes are real.

ratchet-mcp # start the server (stdio

[truncated for AI cost control]