{"slug": "show-hn-ratchet-let-an-ai-agent-reflash-your-bios-over-a-ch341a-mcp-server", "title": "Show HN: Ratchet – let an AI agent reflash your BIOS over a CH341A (MCP server)", "summary": "Ratchet, a new hardware debug and flash-programming toolkit for CH341A and CH347 USB programmers, was released as a pre-release on GitHub. Written in Rust, it replaces multiple existing tools like AsProgrammer and flashrom by providing a single binary with an MCP server for AI agents. The toolkit supports SPI flash programming, I2C, JTAG, and various MCU programmers, with live hardware support for BIOS reflashing and diagnostics.", "body_md": "A hardware debug and flash-programming toolkit for CH341A and CH347 USB programmers.\n\nIts 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.\n\nNot all of that is wired to live hardware yet. [Status](#status) marks every command `[live]`\n\n, `[offline]`\n\n, or `[n/w]`\n\n(not wired). The rule throughout: a command with no live transport exits non-zero with a clear message; it never fakes success.\n\nWritten 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.\n\nPre-release. No GitHub Releases are published yet, so the only install route today is from source (see [Install](#install)).\n\nWhat drives live hardware today (CLI + MCP):\n\n**SPI flash + BIOS, end to end.**`status`\n\n,`detect`\n\n,`identify`\n\n,`read`\n\n,`write`\n\n,`verify`\n\n,`erase`\n\n,`region-erase`\n\n,`blank-check`\n\n,`sfdp`\n\n,`wp-status`\n\n,`full-repair`\n\n, and`full-backup`\n\nrun against a live CH341A or CH347.`write`\n\nerases 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`\n\nruns the guided pipeline;`full-backup`\n\nis a full-chip read to a named file.**I2C**, over CH341A bit-bang or CH347 native.`i2c scan`\n\n,`i2c read`\n\n,`i2c write`\n\n, and`eeprom-i2c read/write`\n\n(24Cxx) use the real`Ch341aI2c`\n\n/`Ch347I2c`\n\nmaster over the live bus.**JTAG IDCODE scan**, over the CH347 JTAG engine (CH341A has none).`jtag idcode-scan`\n\ndrives the real`Ch347Jtag`\n\nadapter.**Backend auto-select.**`open_default()`\n\nprobes CH347 (`1a86:55db`\n\n), then CH341A (`1a86:5512`\n\n), then falls back to mock with a stderr warning;`RATCHET_FORCE_MOCK=1`\n\nforces mock. Protocol verbs use`open_raw_bus()`\n\n, which returns an honest error rather than a silent mock fallback when no device is present.`ratchet status`\n\nreports the active backend in its`backend`\n\nJSON field.\n\nOffline tools that need no hardware:\n\n`i2c sniff <trace.json>`\n\ndecodes a captured (t_us, scl, sda) trace;`jtag bsdl-scan <file.bsdl>`\n\nparses a BSDL file and reports its boundary register;`la export <capture.json> <out> --format csv|jsonl`\n\nconverts a capture;`serial-list`\n\nenumerates serial ports (POSIX);`repl`\n\nis a stdin REPL over the SPI backend; plus the analysis verbs`analyze`\n\n,`diff`\n\n,`checksum`\n\n,`chip-info`\n\n,`search`\n\n,`post-decode`\n\n, and`voltage-reference`\n\n.\n\nNot wired to live hardware yet: `uart`\n\n, `onewire`\n\n, `swd`\n\n, `avr`\n\n, `eeprom-microwire`\n\n, `esp`\n\n, `stm32`\n\n, `la capture`\n\n, `buspirate`\n\n, `can`\n\n, plus `monitor`\n\n, `serial`\n\nconnect, and `failure-search`\n\n. 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.\n\nThe 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`\n\ntest 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.\n\nRequires Rust 1.82+ and libusb-1.0 installed (see [Requirements](#requirements)).\n\n```\ngit clone https://github.com/jackulau/ratchet\ncd ratchet/rust\ncargo install --path ratchet-cli\ncargo install --path ratchet-mcp\n```\n\nThis installs `ratchet`\n\nand `ratchet-mcp`\n\ninto `~/.cargo/bin/`\n\n(or the value of `CARGO_INSTALL_ROOT`\n\nif set). Both binaries are self-contained Rust executables; no Node, no Python.\n\nIf you prefer not to mix global state, install to a sandbox directory:\n\n```\ncargo install --path ratchet-cli --root /opt/ratchet\ncargo install --path ratchet-mcp --root /opt/ratchet\nexport PATH=\"/opt/ratchet/bin:$PATH\"\ngit clone https://github.com/jackulau/ratchet\ncd ratchet/rust\ncargo build --release\n# Binaries land at target/release/ratchet and target/release/ratchet-mcp\ncargo uninstall ratchet-cli\ncargo uninstall ratchet-mcp\n```\n\nIf you used `--root /opt/ratchet`\n\nduring install, pass the same root:\n\n```\ncargo uninstall ratchet-cli --root /opt/ratchet\ncargo uninstall ratchet-mcp --root /opt/ratchet\n```\n\nNothing to uninstall; delete the cloned directory. Optionally:\n\n```\ncd ratchet/rust && cargo clean    # remove build artifacts\ncd .. && rm -rf ratchet           # remove the checkout\n```\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n(macOS) or the platform equivalent and remove the `\"ratchet\"`\n\nentry under `mcpServers`\n\n. Restart Claude Desktop.\n\nThis is the end-to-end path for reflashing a corrupt or bricked motherboard BIOS with a CH341A (the common ~$3 programmer) or a CH347.\n\n**What you need**\n\n- A CH341A or CH347 USB programmer and a SOIC-8 / SOIC-16 test clip (or a ZIF adapter if you\ndesolder the chip). The BIOS flash is the 8-pin SPI chip near the chipset, usually a Winbond\n`W25Q…`\n\n, Macronix`MX25L…`\n\n, or GigaDevice`GD25Q…`\n\n. - A known-good BIOS image for your exact board revision - download it from the motherboard\nvendor's support page, or keep the backup\n`ratchet`\n\nmakes 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 <chip>`\n\nreports the chip's voltage so you can check before connecting.\n\n**Steps** (clip onto the chip with the board powered off and unplugged):\n\n```\n# 1. Confirm the programmer + chip are talking.\nratchet status                # programmer detected? which backend?\nratchet identify              # reads the JEDEC ID and looks the chip up in the 806-chip DB\n\n# 2. Back up the current contents FIRST - always, even if the BIOS looks dead.\nratchet read backup.bin       # full-chip dump → file\nratchet analyze backup.bin    # optional: UEFI volumes, ME region, integrity\n\n# 3. Flash the known-good image. This automatically:\n#      • saves a timestamped backup of the current chip,\n#      • erases the affected sectors, then programs page-by-page,\n#      • polls the write-in-progress bit after every operation, and\n#      • reads the chip back and verifies it matches the file.\nratchet write new_bios.bin\n\n# 4. Re-verify independently (optional - `write` already verified).\nratchet verify new_bios.bin\n```\n\n`write`\n\nrefuses an all-0xFF or all-0x00 image (a blank/failed dump that would wipe the chip) and\nrefuses an image larger than the chip. If anything goes wrong mid-write, your original is in the\ntimestamped backup printed by step 3. To recover a board after a bad flash, just\n`ratchet write backup.bin`\n\nfrom that file.\n\n**One-shot pipeline.** `ratchet full-repair --reference new_bios.bin`\n\nruns the whole thing -\nconnection-quality check → double-verify read → health analysis → repair → write → post-write\nverify - as a single guided workflow.\n\nCI (`.github/workflows/ci.yml`\n\n: fmt, clippy `-D warnings`\n\n, full test suite, strict doc\nbuild, and both smoke suites under `RATCHET_FORCE_MOCK=1`\n\n) and the test suite prove the\nprotocol byte-for-byte without a programmer (see [Status](#status)), but to confirm\nagainst your own board:\n\n```\nratchet detect                       # programmer enumerates on USB\nratchet identify --json | jq .data   # JEDEC id matches the chip silk-screen / DB\nratchet read a.bin && ratchet read b.bin && diff a.bin b.bin   # two reads are identical (stable clip)\nratchet write new_bios.bin           # success=true verified=true in the output\n```\n\nThese drive live hardware today (or run offline where noted). Each returns a non-zero exit and an honest message if no device is present.\n\n```\n# I2C bus scan + register read (live CH341A / CH347)\nratchet i2c scan\nratchet i2c read --addr 0x50 --reg 0x00 --len 256\n\n# 24Cxx I2C EEPROM dump / restore (live)\nratchet eeprom-i2c read --addr 0x50 --part 24c256 dump.bin\nratchet eeprom-i2c write --addr 0x50 --part 24c256 dump.bin\n\n# JTAG IDCODE chain (live, CH347 only)\nratchet jtag idcode-scan\n\n# Offline: decode a captured I2C trace / parse a BSDL file / convert a capture\nratchet i2c sniff trace.json\nratchet jtag bsdl-scan part.bsdl\nratchet la export capture.json out.csv --format csv\n\n# Enumerate serial ports (POSIX)\nratchet serial-list\n```\n\nVerbs whose live transport isn't wired yet (`uart`\n\n, `onewire`\n\n, `swd`\n\n, `avr`\n\n,\n`eeprom-microwire`\n\n, `esp`\n\n, `stm32`\n\n, `la capture`\n\n, `buspirate`\n\n, `can`\n\n) exit\nnon-zero with an explanation (see [Status](#status)).\n\n`ratchet --help`\n\nexposes 39 top-level subcommands plus `help`\n\n. Status legend:\n`[live]`\n\ndrives hardware (honest error if no device), `[offline]`\n\nneeds no\nhardware, `[n/w]`\n\nnot wired to a live transport yet (exits non-zero, never\nfakes success).\n\n| Group | Commands |\n|---|---|\n| Hardware | `status` [live], `detect` [live], `identify` [live], `monitor` [n/w] |\n| Chip ops | `read` `write` `verify` `erase` `region-erase` `blank-check` `sfdp` `wp-status` [live] |\n| Analysis | `analyze` `diff` `checksum` [offline] |\n| Knowledge base | `search` `chip-info` `post-decode` `voltage-reference` [offline]; `failure-search` [n/w] |\n| Serial | `serial-list` [offline]; `serial` connect [n/w] |\n| Repair | `full-repair` [live], `full-backup` [live], `repl` [live] |\n| Self-test | `self-test` (also `--self-test` flag) [offline, mock] |\n| I2C | `i2c scan/read/write` [live], `i2c sniff` [offline], `eeprom-i2c read/write` [live] |\n| JTAG | `jtag idcode-scan` [live, CH347], `jtag bsdl-scan` [offline] |\n| Instruments | `la export` [offline]; `la capture` [n/w] |\n| 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] |\n\nEvery inspection command supports `--json`\n\nfor AgentEnvelope output:\n`{ok, command, data?|error, nextAction?}`\n\n.\n\n```\nratchet status --json\nratchet chip-info ef4017 --json\nratchet analyze backup.bin --json | jq '.data.regions'\n```\n\nratchet ships a built-in MCP server (`ratchet-mcp`\n\n) that exposes the tool surface to AI agents\n(Claude Desktop, mcp-cli, custom SDK clients) over stdio, using hand-rolled JSON-RPC 2.0. It\nserves 30 tools: 18 for SPI-flash / BIOS analysis and 12 for hardware protocols. The\nSPI-flash/BIOS tools plus `i2c_scan`\n\n, `i2c_read`\n\n, `i2c_write`\n\n, and `jtag_idcode_scan`\n\nrun against\nthe live backend; the remaining hardware tools return a JSON-RPC error until their transport is\nwired. The JSON-RPC dispatch, schema descriptors, and argument shapes are real.\n\n```\nratchet-mcp                              # start the server (stdio; live backend, mock fallback)\nratchet-mcp --list-tools                 # dump tool surface (one name per line)\n```\n\nRegister with Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`\n\n):\n\n```\n{\n  \"mcpServers\": {\n    \"ratchet\": {\n      \"command\": \"ratchet-mcp\"\n    }\n  }\n}\n```\n\n| Tool | Purpose |\n|---|---|\n`detect` |\nScan USB for CH34x programmers |\n`identify` |\nRead JEDEC ID + SFDP + DB lookup |\n`read_chip` / `write_chip` / `verify_chip` / `erase_chip` |\nSPI flash ops |\n`analyze_image` / `bios_regions` / `nvram_vars` |\nBIOS image inspection |\n`search_chips` / `chip_info` |\n806-chip database |\n`post_decode` / `failure_search` / `voltage_reference` |\nDiagnostics knowledge base |\n`i2c_scan` / `i2c_read` / `i2c_write` |\nI2C bus ops (live) |\n`jtag_idcode_scan` |\nJTAG chain forensics (live, CH347) |\n`uart_capture` |\nTwo-channel UART sniff (not wired; honest error) |\n`swd_dump_ram` |\nARM RAM dump over SWD (not wired; honest error) |\n`avr_program` / `esp_flash` / `stm32_swd_flash` |\nTarget-MCU programmers (not wired; honest error) |\n`la_capture` |\nMulti-channel logic analyzer (not wired; honest error) |\n`bus_pirate_proxy` / `can_sniff` |\nExternal-device bridges (not wired; honest error) |\n\nratchet is built to not brick your board. Every item below is enforced in code (see\n`backends/`\n\nand `tasks/cli-smoke.sh`\n\n):\n\n**Auto-backup before every write.** The current chip is dumped to a timestamped file before programming. Opt out with`--skip-backup`\n\n.**Read-back verify after every write.**`write`\n\nreads the chip back and compares it to the file; the result is reported as`verified`\n\n. Opt out with`--skip-verify`\n\n.**Erase-before-program + WIP polling.** Sectors are erased before programming (SPI program can only clear bits 1→0), and the write-in-progress status bit is polled after every erase and page program, so the next command never races a still-busy chip (chip-erase can take tens of seconds).**Blank-image guard.**`write`\n\nrefuses an all-0xFF or all-0x00 image - a blank or failed dump that would wipe a working BIOS. Use`erase`\n\nto intentionally blank a chip.**Capacity check.** Writes larger than the chip are rejected, not silently truncated; chips the database cannot size (`unknown chip capacity`\n\n) are refused outright instead of written blind.**Write-protect guard.** Erase and write refuse a chip whose block-protect bits are set (`write protected`\n\n) - protected silicon silently ignores program commands, which would otherwise read as a fake success.**No silent mock writes.** The CLI`write`\n\n/`erase`\n\n/`region-erase`\n\n/`full-repair`\n\nverbs and the MCP`write_chip`\n\n/`erase_chip`\n\n/`region_erase`\n\ntools refuse to run when the factory silently fell back to the mock backend (no programmer attached); only an explicit`RATCHET_FORCE_MOCK=1`\n\nallows it. Destructive-op JSON carries a`backend`\n\nfield so agents can tell silicon from mock.**MCP confirm gate.** The destructive MCP tools require`\"confirm\": true`\n\nin their arguments; calls without it get a JSON-RPC error, so an agent can never write or erase by accident.**Short-read detection.** A USB transfer that delivers fewer bytes than requested is a hard`short transfer`\n\nerror, never zero-padded data - protecting reads, verifies, and backups.**Automatic 4-byte addressing** on chips over 16 MB, so large BIOS images aren't half-addressed- and 4-byte mode is always exited when the operation completes, so the chip is never left misaddressing for the next tool (or the board itself).\n\n**Backup no-clobber.**`full-backup`\n\nrefuses to overwrite an existing`ratchet-backup-<chip>.bin`\n\nwithout`--force`\n\n- it may be your only copy of a working BIOS.**Post-read flags.**`read`\n\nreports`all_ff`\n\n/`all_zero`\n\nso a blank (0xFF) or dead (0x00) read is obvious in the output.\n\nAdvisory (not an automatic block): `identify`\n\n/ `chip-info`\n\nreport the chip's rated voltage so you\ncan confirm a 1.8 V part isn't being driven by a stock 3.3 V CH341A before you connect. The CLI\n`erase`\n\nverb has no interactive prompt (it's meant for scripting; the MCP surface has the confirm\ngate instead) - but `write`\n\n's automatic pre-write backup means a normal reflash is always\nrecoverable.\n\n```\nrust/\n├── ratchet-usb-sys   ← custom libusb FFI via bindgen (no rusb / nusb)\n├── ratchet-usb       ← safe RAII wrapper, error mapping, bulk/control transfers\n├── ratchet-core      ← chip db (806 chips), backends (mock/CH341A/CH347),\n│                       BIOS analyzer, repair, NVRAM, UEFI, knowledge-base,\n│                       protocols (I2C/UART/1-Wire/SPI-sniff/JTAG/SWD),\n│                       programmers (AVR/STK500/24Cxx/93xxx/ESP/STM32),\n│                       debug (ADIv5/Cortex-M/ELF/boundary-scan),\n│                       instruments (logic-analyzer/export/Bus-Pirate/slcan),\n│                       workflow pipeline, REPL state, agent envelope\n├── ratchet-cli       ← clap-based CLI, 39 top-level subcommands + --self-test flag\n├── ratchet-mcp       ← MCP JSON-RPC 2.0 server (30 tools, stdio)\n└── ratchet-node      ← optional napi-rs bridge for Node consumers\n```\n\nFully native: direct SPI / I2C / UART / JTAG / SWD over libusb, with nothing shelled out at runtime. ratchet is an alternative to flashrom / avrdude / esptool / stm32flash / OpenOCD, not a wrapper around them.\n\n**CH341A**(`1a86:5512`\n\n): most common, SPI + UIO bit-bang for I2C / JTAG / SWD / 1-Wire, ~$3 on AliExpress.**CH347**(`1a86:55db`\n\n): newer, up to 60 MHz SPI, native I2C + UART, JTAG.**CH343**(`1a86:55d3`\n\n): UART serial-debug only.\n\nWinbond, Macronix, GigaDevice, SST / Microchip, EON, Spansion / Cypress / Infineon, Micron / Numonyx, ISSI, AMIC, XMC, PUYA, ESMT, Intel, Atmel / Adesto, and more. Both 3.3 V and 1.8 V variants.\n\n**AVR**: ATmega328P (Arduino UNO), ATmega2560, ATtiny85, ATmega32U4 via ISP or STK500 bootloader.** STM32**: F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H7 / L0 / L4 / L5 via SWD or AN3155 UART bootloader.** ESP**: ESP8266, ESP32, ESP32-S2 / S3 / C3 / C6 via ROM bootloader + optional stub.** ARM Cortex-M**: generic debug surface (halt / resume / step / RAM dump) via SWD on any ADIv5-compliant target.\n\n**End user (cargo-install path)**: Rust 1.82+ and libusb-1.0 (system package).** macOS**:`brew install libusb`\n\n. The CH341A / CH347 are vendor-specific USB devices, so macOS loads no kernel driver for them and libusb (via IOKit) opens them directly - no kext, no Zadig, no extra entitlements when you run`ratchet`\n\nfrom a terminal. If the build can't find libusb, make sure Homebrew's`lib`\n\n/`include`\n\nare on the pkg-config path (`export PKG_CONFIG_PATH=\"$(brew --prefix libusb)/lib/pkgconfig\"`\n\n). If a programmer doesn't enumerate, replug it and re-run`ratchet detect`\n\n.**Linux (Debian / Ubuntu)**:`sudo apt install libusb-1.0-0-dev`\n\n. For non-root access add a udev rule for`1a86:5512`\n\n(CH341A) /`1a86:55db`\n\n(CH347), or run with`sudo`\n\n.**Windows**: vcpkg-installed libusb for build; WinUSB driver via[Zadig](https://zadig.akeo.ie/)for runtime.\n\nratchet began as **biosMCP**, a CH341A-focused BIOS programmer built to replace AsProgrammer and\nNeoProgrammer. The original TypeScript prototype was rewritten as a native Rust workspace (the\nprior state is preserved at the `ts-final`\n\ngit tag), then grew from a SPI-flash-only tool into the\nbroader multi-protocol toolkit and was renamed ratchet to match its wider scope.\n\nMIT. See [LICENSE](/jackulau/ratchet/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-ratchet-let-an-ai-agent-reflash-your-bios-over-a-ch341a-mcp-server", "canonical_source": "https://github.com/jackulau/ratchet", "published_at": "2026-06-19 23:13:26+00:00", "updated_at": "2026-06-19 23:37:32.941020+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "ai-infrastructure", "ai-products"], "entities": ["CH341A", "CH347", "Rust", "GitHub", "MCP", "SPI", "JTAG", "I2C"], "alternates": {"html": "https://wpnews.pro/news/show-hn-ratchet-let-an-ai-agent-reflash-your-bios-over-a-ch341a-mcp-server", "markdown": "https://wpnews.pro/news/show-hn-ratchet-let-an-ai-agent-reflash-your-bios-over-a-ch341a-mcp-server.md", "text": "https://wpnews.pro/news/show-hn-ratchet-let-an-ai-agent-reflash-your-bios-over-a-ch341a-mcp-server.txt", "jsonld": "https://wpnews.pro/news/show-hn-ratchet-let-an-ai-agent-reflash-your-bios-over-a-ch341a-mcp-server.jsonld"}}