driverge-mcp 0.0.0 → 0.0.1

package/README.md

@@ -4,14 +4,16 @@
 <p align="center"><em>Datasheet PDF → embedded C/C++ driver, from any MCP client.</em></p>
 
 <p align="center">
-  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue">
+  <a href="https://www.npmjs.com/package/driverge-mcp"><img alt="npm" src="https://img.shields.io/npm/v/driverge-mcp"></a>
+  <a href="https://github.com/MehmetTopuz/driverge-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/MehmetTopuz/driverge-mcp/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue"></a>
   <img alt="status" src="https://img.shields.io/badge/status-pre--release-orange">
   <img alt="mcp" src="https://img.shields.io/badge/MCP-server-black">
 </p>
 
-> 🚧 **Pre-release** — under active development; not yet published to npm. The
-> `npx driverge-mcp` command below is the intended install; until it's published,
-> [run from source](#run-from-source-pre-release).
+> 🚧 **Early pre-release** — [`driverge-mcp`](https://www.npmjs.com/package/driverge-mcp)
+> is on npm, so the `npx driverge-mcp` install below works today. APIs and the
+> JSON schema may still change before v0.1.0; expect rough edges.
 
 ---
 
@@ -27,15 +29,68 @@ TypeScript pipeline extracts a *validated, structured JSON* model of the chip, a
 the host AI you're already talking to fills in the reasoning-heavy parts (init
 sequence, vendor quirks, docs). Your datasheet never leaves your machine.
 
+## Quick start
+
+Add one entry to your MCP client's config (Claude Desktop, Claude Code, Cursor —
+paths per client in [Installation](#installation)):
+
+```json
+{
+  "mcpServers": {
+    "driverge": { "command": "npx", "args": ["-y", "driverge-mcp"] }
+  }
+}
+```
+
+Restart the client, then ask:
+
+> "Analyze the datasheet at `C:/ds/bme280.pdf` with driverge, then generate a
+> portable driver."
+
+That's it — no clone, no build, no API key. Details in
+[Installation](#installation) and [Usage](#usage).
+
+## Why Driverge?
+
+Bringing up a new sensor or IC means hand-transcribing dozens of register
+addresses, bit-field masks, and command codes out of a 40-page PDF — slow work,
+and a classic source of silent bugs (one wrong mask or transposed address and the
+driver "works" but reads garbage). Driverge does that mechanical part
+deterministically and leaves the reasoning to the AI you already use.
+
+- **No hallucinated register maps.** Addresses, bit-field masks, and command codes
+  are *extracted from the datasheet and validated* — not guessed. That's the
+  failure mode of "just ask an LLM to write the whole driver"; here, invalid or
+  incomplete data is rejected before it ever reaches code generation.
+- **Bring your own client — no API keys, no lock-in.** Driverge is a plain MCP
+  server with no embedded LLM. It runs inside whatever MCP client you already use
+  (Claude Desktop, Claude Code, Cursor, …) and reasons with the model you're
+  already paying for — no separate subscription or service.
+- **Private & offline.** The datasheet is parsed locally and never uploaded — safe
+  for NDA'd or unreleased parts.
+- **Deterministic & reproducible.** The same PDF always yields the same JSON and
+  the same driver skeleton — reviewable, diff-able, and testable, not a one-shot
+  black box.
+- **Portable by construction.** One driver core targets any platform through a
+  tiny per-bus thin-HAL seam (2–3 functions); the native targets (STM32, ESP32)
+  pre-fill that seam for you — switch platforms without touching driver logic.
+- **The AI does only what it's good at.** Register geometry is deterministic;
+  init-sequence ordering, timing quirks, and compensation math need judgment.
+  Driverge marks exactly those spots with `TODO(driverge)` and a `fill_in_brief`,
+  the host AI completes them, then `validate_driver` checks the result.
+
+**Good for:** quickly evaluating a new sensor, prototyping, porting an existing
+driver to a different MCU, or just learning an unfamiliar chip's register map.
+
 ## What it does
 
 1. **Analyze** a datasheet PDF → detect format, manufacturer, and interface kind
    (register-map vs. command-set), then extract registers / bit-fields (or
    commands + CRC) and the bus protocol into a **frozen JSON contract**, gated by
    a validator.
-2. **Generate** a driver for a target platform: a deterministic **thin-HAL
-   skeleton** — register/bit-field constants, the 5-function HAL seam, function
-   stubs — with every reasoning gap marked `TODO(driverge)` plus a `fill_in_brief`
+2. **Generate** a driver for a target platform, in C or C++: a deterministic
+   **thin-HAL skeleton** — register/bit-field constants, the per-bus thin-HAL
+   seam, function stubs — with every reasoning gap marked `TODO(driverge)` plus a `fill_in_brief`
    telling the host AI exactly what to complete.
 3. **Validate** the completed driver: thin-HAL purity, no leftover TODOs, register
    references exist, bit-field masks match the JSON.
@@ -46,26 +101,132 @@ Every target specializes the same portable **[thin-HAL](https://en.wikipedia.org
 seam — the driver core is identical across platforms; only the seam implementation
 changes.
 
-| Target | Bus binding | Language | Status |
-|---|---|---|---|
-| **Portable (thin-HAL)** | user-implemented `hal_i2c_*` / `hal_spi_*` / `hal_delay_ms` | C | ✅ |
-| **ESP32** | ESP-IDF `i2c_master_*` | C | ✅ |
-| **STM32** | CubeHAL `HAL_I2C_Mem_Read/Write` | C | ✅ |
-| **Arduino** | `Wire` / `SPI` | C++ | planned |
+| Target | Bus binding | Buses | Language | Status |
+|---|---|---|---|---|
+| **Portable (thin-HAL)** | user-implemented `hal_*` seam | I²C, SPI, UART, CAN | C / C++ | ✅ |
+| **ESP32** | ESP-IDF (`i2c_master_*`, `spi_master`, `uart`, TWAI) | I²C, SPI, UART, CAN | C / C++ | ✅ |
+| **STM32** | CubeHAL (`HAL_I2C_*`, `HAL_SPI_*` + GPIO CS, `HAL_UART_*`) | I²C, SPI, UART | C / C++ | ✅ |
+| **Arduino** | `Wire` / `SPI` | — | C++ | planned |
 
-- **Offline & private** — the datasheet is parsed locally; nothing is uploaded.
-- **Deterministic** — the same PDF yields the same JSON and the same skeleton.
-- **Cross-platform** — one parsed model, many target bindings.
+STM32 CAN is planned (the bxCAN/FDCAN family split needs its own pass); asking
+a target for a bus it doesn't support fails fast with a clear
+`UnsupportedBusError` rather than emitting a wrong seam. Pass
+`language: "cpp"` to `generate_driver` for a class-based C++ driver
+(`.hpp`/`.cpp`) instead of the default C output — same registers, same seam,
+same validation.
 
 > ⚠️ **Generated code is a strong draft, not a certified driver.** Init sequences,
 > compensation formulas, and timing quirks are completed by the host AI and
 > **must be reviewed** before use on hardware. Not safety-certified.
 
+### Verified parts
+
+The extraction pipeline is regression-tested against real datasheets from
+**12 manufacturers**. Parts with fully automatic extraction (registers *and*
+bit-fields, or a clean command set):
+
+| Part | Manufacturer | Kind | Extracted |
+|---|---|---|---|
+| BME280 | Bosch Sensortec | register map | 16 regs, 19 bit-fields |
+| MCP23017 | Microchip | register map | 12 regs, 96 bit-fields |
+| SHT3x | Sensirion | command set | 6 commands + CRC |
+| TMAG5170 | Texas Instruments | register map (SPI) | 21 regs, 79 bit-fields |
+| DHT20 | Aosong | command set | 2 commands |
+| LSM6DSRX | STMicroelectronics | register map | 31 regs, 91 bit-fields |
+| MAX30102 | Maxim Integrated | register map | 20 regs, 33 bit-fields |
+
+Other tested parts (ADXL345, MLX90614, AEAT-8811, PCA9685, VL53L3CX, TLE5014)
+extract **partially** or **defer** to the host AI — the pipeline says so
+explicitly instead of guessing, and the generated skeleton tells the host AI
+what to complete. The full, always-current matrix lives in the
+[coverage scorecard](tests/scorecard/scorecard.snap.md).
+
+## Concepts behind Driverge
+
+Driverge splits driver-writing into two kinds of work: the **mechanical part**
+(register addresses, masks, command tables — extracted and checked by
+deterministic code) and the **judgment part** (init ordering, timing quirks,
+compensation math — completed by the host AI). Everything below exists to keep
+that boundary sharp.
+
+```mermaid
+flowchart LR
+  PDF["Datasheet PDF"]
+  subgraph D["Driverge — deterministic, no LLM"]
+    A["analyze_datasheet<br>L1–L5 parse + validate"]
+    J[("frozen JSON<br>cached under a ref")]
+    G["generate_driver<br>thin-HAL skeleton +<br>TODO(driverge) markers"]
+    V["validate_driver<br>static lint"]
+  end
+  subgraph H["Host AI — reasoning"]
+    F["fill the TODOs: init sequence,<br>quirks, compensation docs"]
+  end
+  OUT["driver.c / driver.h"]
+  PDF --> A --> J --> G --> F --> V
+  V -->|pass| OUT
+  V -->|fail| F
+```
+
+### Deterministic core, reasoning at the edge
+
+Register geometry is mechanical: an address is right or wrong, a mask either
+matches the datasheet or it doesn't. Driverge handles that part with plain
+TypeScript — no internal LLM, no API keys, no sampling — so the output is the
+same on every run. What genuinely needs judgment (in what order to poke the
+registers, which timing quirk applies, how to document a compensation formula)
+is left to the host AI you're already talking to.
+
+### The frozen JSON contract
+
+`analyze_datasheet` runs a five-stage pipeline (L1–L5): detect the PDF type,
+map keyword pages, identify the manufacturer and interface kind, extract the
+register table (or command set + CRC), and validate the result against a frozen
+draft-07 [JSON-Schema contract](schemas/datasheet.schema.json) — also exposed
+as the `driverge://schema` resource. Anything that fails validation is rejected
+*before* code generation, so a bad extraction can never silently become a bad
+driver.
+
+### The `ref` handle
+
+Parsing a datasheet yields a large JSON document; shuttling it through the chat
+context on every call would be slow and lossy. Instead, the parsed model is
+cached server-side under a content-stable `ref`, and the tools pass that handle
+around. The same `ref` with a different `target` re-renders instantly with no
+re-parse, and the full JSON stays readable at `driverge://datasheet/<ref>`.
+
+### The thin-HAL seam
+
+Generated drivers touch hardware through a tiny per-bus seam — and nothing
+else:
+
+| Bus | Seam functions (plus `hal_delay_ms`) |
+|---|---|
+| I²C | `hal_i2c_read`, `hal_i2c_write` |
+| SPI | `hal_spi_transfer` (one call = one CS-framed transaction) |
+| UART | `hal_uart_write`, `hal_uart_read` |
+| CAN | `hal_can_transfer` (one call = one frame exchange) |
+
+The driver core is therefore identical across platforms; a native target
+(ESP32, STM32) just pre-fills the seam with the vendor calls.
+`validate_driver` enforces this purity: a driver that calls a vendor peripheral
+API outside the seam fails the lint. Buses with no universal register-access
+primitive (UART, CAN) keep the same discipline — the device-specific framing is
+a marked `TODO(driverge)` reasoning gap (`framing_todo`), completed by the host
+AI and then linted.
+
+### The fill-in loop
+
+The skeleton marks every reasoning gap with a `TODO(driverge)` comment and
+ships a `fill_in_brief` describing what belongs there. The host AI completes
+the markers using the datasheet resource, then `validate_driver` statically
+checks the result — no leftover TODOs, every register reference real, masks
+matching the JSON — and the loop repeats until it passes.
+
 ## Installation
 
-**Prerequisites:** Node.js LTS (≥ 18).
+**Prerequisites:** Node.js LTS (≥ 18; CI-tested on Node 20 & 22).
 
-Once published, add Driverge to your MCP client (no build step —
+Add Driverge to your MCP client (no build step —
 [npx](https://docs.npmjs.com/cli/commands/npx) fetches and runs it):
 
 **Claude Desktop** — `claude_desktop_config.json`:
@@ -98,9 +259,39 @@ Once published, add Driverge to your MCP client (no build step —
 Other clients (Codex, Gemini CLI, …) take the same `command` + `args` pair in
 their own MCP config.
 
-### Run from source (pre-release)
+**No clone, no global install.** The config above tells your MCP client to
+launch `npx -y driverge-mcp`; npx downloads Driverge from the npm registry on
+first run, caches it, and starts it automatically each time the client does
+(`-y` skips npx's install prompt). You never run it by hand — to confirm it's
+wired up, ask your client to run the `ping` tool, which replies `pong`. Cloning
+the repo (below) is only for development.
 
-Until the npm package is published:
+### Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `DRIVERGE_OUT_ROOT` | server's working directory | Root that `generate_driver`'s `out_dir` writes are confined to. Any `out_dir` that resolves outside this root is rejected (`out_dir "…" escapes the allowed root`). Set it to the directory you want drivers written into. |
+
+Set it in the MCP config's `env` block, e.g.:
+
+```json
+{
+  "mcpServers": {
+    "driverge": {
+      "command": "npx",
+      "args": ["-y", "driverge-mcp"],
+      "env": { "DRIVERGE_OUT_ROOT": "C:/work/drivers" }
+    }
+  }
+}
+```
+
+Without `out_dir` the generated files are returned in the tool result only —
+no disk writes, no configuration needed.
+
+### Run from source (development)
+
+To contribute, or to run the latest unreleased changes:
 
 ```bash
 git clone https://github.com/MehmetTopuz/driverge-mcp.git
@@ -124,8 +315,13 @@ Give your MCP client a datasheet and ask it to build a driver. The typical flow:
 
 1. **`analyze_datasheet`** — `{ "pdf_path": "/abs/path/bme280.pdf" }` → returns a
    compact summary and a `ref` handle; the full JSON is available as a resource.
+   If auto-detection picks the wrong vendor or interface style, the optional
+   `manufacturer_hint` (free text) and `interface_kind_hint`
+   (`"register_map"` | `"command_set"`) parameters steer it.
 2. **`generate_driver`** — `{ "ref": "…", "target": "portable" }` → returns the
-   driver files + a `fill_in_brief`. (`out_dir` also writes them to disk.)
+   driver files + a `fill_in_brief`. (`out_dir` also writes them to disk;
+   `language: "cpp"` renders a class-based `.hpp`/`.cpp` driver instead of the
+   default C.)
 3. The host AI completes the `TODO(driverge)` markers using the brief and the
    `driverge://datasheet/<ref>` resource.
 4. **`validate_driver`** — `{ "ref": "…", "files": [...] }` → static checks; loop
@@ -138,11 +334,35 @@ Reusing the same `ref` with a different `target` re-renders with **no re-parse**
 > "Analyze the datasheet at `C:/ds/bme280.pdf` with driverge, then generate a
 > portable driver."
 
-Driverge parses the BME280 memory map (14 registers, bit-fields, I²C address),
-validates it, and emits `bme280.h` / `bme280.c` — register `#define`s, bit-field
-`MASK`/`SHIFT` macros, the thin-HAL seam, and `bme280_init/read_register/
-write_register` stubs. The host AI then fills the init sequence and compensation
-docs from the datasheet prose.
+Driverge parses the BME280 memory map (16 registers, 19 bit-fields, I²C
+address), validates it, and emits `bme280.h` / `bme280.c` — register
+`#define`s, bit-field `MASK`/`SHIFT` macros, the thin-HAL seam, and the
+`bme280_init/read_register/write_register` stubs:
+
+```c
+/* bme280.h — generated by Driverge (excerpt) */
+#define BME280_I2C_ADDR 0x76
+
+#define BME280_REG_CTRL_MEAS 0xF4
+#define BME280_REG_STATUS    0xF3
+/* … */
+#define BME280_TEMP_XLSB_TEMP_XLSB_MASK  0xF0
+#define BME280_TEMP_XLSB_TEMP_XLSB_SHIFT 4
+```
+
+```c
+/* bme280.c — every reasoning gap is a marked TODO (excerpt) */
+int bme280_init(bme280_t *dev) {
+    /* … */
+    /* TODO(driverge): implement the power-on / reset init sequence — the
+     * correct register write order and values, plus any required startup
+     * delay. See fill_in_brief.init_sequence_todo. */
+    return 0;
+}
+```
+
+The host AI then fills the init sequence and compensation docs from the
+datasheet prose, and `validate_driver` checks the result.
 
 ### MCP surface
 
@@ -152,16 +372,42 @@ docs from the datasheet prose.
 | Tool | `generate_driver` | `ref` + `target` → driver skeleton + `fill_in_brief` |
 | Tool | `validate_driver` | static-lint a completed driver against its `ref` |
 | Tool | `validate_datasheet` | re-run the L5 validator over a `ref` or JSON |
+| Tool | `ping` | health check — confirms the server is running |
 | Resource | `driverge://datasheet/<ref>` | full parsed JSON for an analyzed datasheet |
 | Resource | `driverge://schema` | the frozen datasheet JSON-Schema contract |
 | Prompt | `generate-driver` | guided analyze → generate → fill → validate flow |
 
+## Troubleshooting
+
+- **Is the server even running?** Ask your client to run the `ping` tool — it
+  replies `pong`. If npx fails to start, check `node --version` (≥ 18 required).
+- **Scanned / image-only PDFs.** Driverge parses text-based PDFs; scanned or
+  mixed PDFs are detected and reported with an explicit warning, and parsing
+  will be incomplete (OCR is deferred to a future release).
+- **`extraction: partial` or `deferred` is not a failure.** `partial` means the
+  registers were found but detail (e.g. bit-fields) is incomplete; `deferred`
+  means the register/command section was detected but not auto-extracted. In
+  both cases the generated skeleton tells the host AI exactly what to complete
+  from the datasheet resource. Only `none` is a genuine parse failure.
+- **`out_dir "…" escapes the allowed root`.** Disk writes are confined under
+  `DRIVERGE_OUT_ROOT` (default: the server's working directory) — see
+  [Configuration](#configuration).
+- **`UnsupportedBusError` on a native target.** The target doesn't support that
+  part's bus yet (today that means CAN on STM32, or a bus the parser couldn't
+  identify). Generate the **portable** target instead and implement its seam.
+
 ## Roadmap
 
 - **v0.x** — one reference sensor (BME280), portable thin-HAL core, MCP surface,
-  multiple clients. *(current)*
-- **v0.y** — native targets: ESP32 ✅, STM32 ✅, Arduino (next).
-- **v1.0** — multi-manufacturer coverage and a stable, versioned JSON schema.
+  multiple clients. ✅
+- **v0.y** — native targets: ESP32 ✅, STM32 ✅, Arduino (next);
+  multi-manufacturer extraction ✅ (12 vendors tested — see
+  [Verified parts](#verified-parts)); multi-bus seam families (I²C, SPI, UART,
+  CAN) ✅; C or C++ output ✅. *(current)*
+- **v1.0** — broader vendor/part coverage, STM32 CAN (bxCAN/FDCAN), and a
+  stable, versioned JSON schema.
+
+Day-to-day progress is tracked in the [CHANGELOG](CHANGELOG.md).
 
 ## Contributing
 

package/dist/codegen/esp32.d.ts

@@ -1,4 +1,12 @@
 import type { DatasheetJson } from "../schema/types.js";
-import type { DriverArtifact } from "./types.js";
-/** Portable core + an ESP-IDF seam implementation for the same part. */
-export declare function generateEsp32Driver(json: DatasheetJson): DriverArtifact;
+import type { CodegenLanguage, DriverArtifact } from "./types.js";
+/**
+ * Portable core + an ESP-IDF seam implementation for the same part. With
+ * language "c" (default) the seam is `<slug>_hal_esp32.c`, unchanged from
+ * before. With language "cpp" the seam becomes `<slug>_hal_esp32.cpp` and its
+ * core include is `#include "<slug>.hpp"` (see coreInclude/seamPath above) —
+ * everything else in the seam content is identical either way.
+ */
+export declare function generateEsp32Driver(json: DatasheetJson, opts?: {
+    language?: CodegenLanguage;
+}): DriverArtifact;

package/dist/codegen/esp32.js

@@ -1,12 +1,39 @@
 // ESP32 (ESP-IDF) target. Per platform-code-generation-targets, a native target
 // does NOT replace the thin HAL — it *pre-fills* the seam. So the ESP32 driver is
 // the exact portable core (unchanged, still platform-agnostic) PLUS a
-// <part>_hal_esp32.c that implements hal_i2c_*/hal_delay_ms with the ESP-IDF v5
-// i2c_master driver. The user drops all three files into an ESP-IDF component;
+// <part>_hal_esp32.c that implements the bus's thin-HAL seam + hal_delay_ms with
+// ESP-IDF v5 drivers. The user drops all three files into an ESP-IDF component;
 // only the board's bus/pin bring-up stays a TODO(driverge).
+//
+// I2C/SPI/UART/CAN only: the I2C seam references `${PREFIX}_I2C_ADDR`, a macro
+// the portable core only defines for I2C parts; the SPI seam needs the portable
+// core's hal_spi_transfer declaration; the UART seam (Session B) wraps ESP-IDF's
+// uart driver around hal_uart_write/hal_uart_read; the CAN seam (Session C)
+// wraps ESP-IDF's TWAI (Two-Wire Automotive Interface, ESP-IDF's CAN 2.0
+// controller) driver around hal_can_transfer — any other bus (unknown) has no
+// ESP-IDF seam here, so this target refuses (UnsupportedBusError) rather than
+// emit an uncompilable seam.
 import { prefixOf, slug } from "./ident.js";
+import { generatePortableCppDriver } from "./portable-cpp.js";
 import { generatePortableDriver } from "./portable.js";
-function halImpl(name, prefix) {
+import { UnsupportedBusError } from "./types.js";
+// Contract amendment (post-GREEN 4b3da14/d576ba6): a language:"cpp" seam
+// cannot stay byte-identical to the "c" seam, because that file
+// #include's "<slug>.h" — which doesn't exist in a cpp bundle (only
+// <slug>.hpp/.cpp). So with language "cpp" the seam file itself becomes
+// `<slug>_hal_<target>.cpp` and its core include becomes `#include
+// "<slug>.hpp"`; everything else in the seam is unchanged. This costs
+// nothing: the .hpp declares the hal_* seam inside `extern "C"`, so compiling
+// this seam as C++ still emits plain C-linkage definitions the class methods
+// can call, and both ESP-IDF and a C++-enabled CubeMX project compile .cpp
+// sources natively.
+function coreInclude(name, language) {
+    return `#include "${name}.${language === "cpp" ? "hpp" : "h"}"`;
+}
+function seamPath(name, language) {
+    return `${name}_hal_esp32.${language === "cpp" ? "cpp" : "c"}`;
+}
+function halImplI2c(name, prefix, language) {
     const content = [
         "/*",
         ` * ${prefix} — ESP-IDF (i2c_master) HAL seam implementation (generated by Driverge).`,
@@ -16,7 +43,7 @@ function halImpl(name, prefix) {
         ` * i2c_new_master_bus() for your SDA/SCL pins, then call ${name}_esp32_bind()`,
         " * once before using the driver. The driver core stays byte-for-byte portable.",
         " */",
-        `#include "${name}.h"`,
+        coreInclude(name, language),
         "#include <string.h>",
         '#include "driver/i2c_master.h"',
         '#include "freertos/FreeRTOS.h"',
@@ -60,18 +87,202 @@ function halImpl(name, prefix) {
         "}",
         "",
     ].join("\n");
-    return { path: `${name}_hal_esp32.c`, content };
+    return { path: seamPath(name, language), content };
+}
+function halImplSpi(name, prefix, language) {
+    const content = [
+        "/*",
+        ` * ${prefix} — ESP-IDF (spi_master) HAL seam implementation (generated by Driverge).`,
+        " *",
+        " * Drop this beside the portable core; it fills the thin-HAL seam with the",
+        " * ESP-IDF v5 spi_master driver: one half-duplex, polling transaction per",
+        ` * hal_spi_transfer() call. In your app: bring up the SPI bus with`,
+        " * spi_bus_initialize() for your MOSI/MISO/SCLK pins, then call",
+        ` * ${name}_esp32_bind() once before using the driver. The driver core stays`,
+        " * byte-for-byte portable.",
+        " */",
+        coreInclude(name, language),
+        "#include <string.h>",
+        '#include "driver/spi_master.h"',
+        '#include "freertos/FreeRTOS.h"',
+        '#include "freertos/task.h"',
+        "",
+        `static spi_device_handle_t s_${name}_dev;`,
+        "",
+        "/* Add the device to an already-initialized SPI bus (spi_bus_initialize'd",
+        " * `host`) and keep the handle for the hal_* calls. Call once at startup;",
+        " * see fill_in_brief.hal_setup_todo for the SPI mode this part expects. */",
+        `esp_err_t ${name}_esp32_bind(spi_host_device_t host, int cs_gpio, int clock_hz) {`,
+        "    spi_device_interface_config_t cfg = {",
+        "        .flags = SPI_DEVICE_HALFDUPLEX,",
+        "        .spics_io_num = cs_gpio,",
+        "        .clock_speed_hz = clock_hz,",
+        "        .mode = 0, /* see fill_in_brief.hal_setup_todo for this part's SPI mode */",
+        "        .queue_size = 1,",
+        "    };",
+        `    return spi_bus_add_device(host, &cfg, &s_${name}_dev);`,
+        "}",
+        "",
+        "void hal_spi_transfer(const uint8_t *tx, uint16_t tx_len, uint8_t *rx, uint16_t rx_len) {",
+        "    spi_transaction_t t;",
+        "    memset(&t, 0, sizeof t);",
+        "    t.length = 8 * tx_len;",
+        "    t.rxlength = 8 * rx_len;",
+        "    t.tx_buffer = tx;",
+        "    t.rx_buffer = rx;",
+        `    spi_device_polling_transmit(s_${name}_dev, &t);`,
+        "}",
+        "",
+        "void hal_delay_ms(uint32_t ms) {",
+        "    vTaskDelay(pdMS_TO_TICKS(ms));",
+        "}",
+        "",
+    ].join("\n");
+    return { path: seamPath(name, language), content };
+}
+function halImplUart(name, prefix, language) {
+    const content = [
+        "/*",
+        ` * ${prefix} — ESP-IDF (uart) HAL seam implementation (generated by Driverge).`,
+        " *",
+        " * Drop this beside the portable core; it fills the thin-HAL seam with the",
+        " * ESP-IDF v5 UART driver. In your app: configure and install the UART driver",
+        " * (uart_param_config + uart_driver_install) for your TX/RX pins, port, and",
+        ` * this part's baud rate, then call ${name}_esp32_bind() once before using the`,
+        " * driver. The driver core stays byte-for-byte portable. See",
+        " * fill_in_brief.hal_setup_todo for the baud rate/config to use.",
+        " */",
+        coreInclude(name, language),
+        '#include "driver/uart.h"',
+        '#include "freertos/FreeRTOS.h"',
+        '#include "freertos/task.h"',
+        "",
+        `static uart_port_t s_${name}_port;`,
+        "",
+        "/* Point the seam at an already-installed UART port (uart_driver_install'd).",
+        " * Call once at startup — see fill_in_brief.hal_setup_todo. */",
+        `void ${name}_esp32_bind(uart_port_t port) {`,
+        `    s_${name}_port = port;`,
+        "}",
+        "",
+        "void hal_uart_write(const uint8_t *data, uint16_t len) {",
+        `    uart_write_bytes(s_${name}_port, (const char *)data, len);`,
+        "}",
+        "",
+        "uint16_t hal_uart_read(uint8_t *data, uint16_t len, uint32_t timeout_ms) {",
+        `    int n = uart_read_bytes(s_${name}_port, data, len, pdMS_TO_TICKS(timeout_ms));`,
+        "    if (n < 0) {",
+        "        return 0;",
+        "    }",
+        "    return (uint16_t)n;",
+        "}",
+        "",
+        "void hal_delay_ms(uint32_t ms) {",
+        "    vTaskDelay(pdMS_TO_TICKS(ms));",
+        "}",
+        "",
+    ].join("\n");
+    return { path: seamPath(name, language), content };
+}
+function halImplCan(name, prefix, language) {
+    const content = [
+        "/*",
+        ` * ${prefix} — ESP-IDF (TWAI) HAL seam implementation (generated by Driverge).`,
+        " *",
+        " * Drop this beside the portable core; it fills the thin-HAL seam with the",
+        " * ESP-IDF v5 TWAI (Two-Wire Automotive Interface — ESP-IDF's CAN 2.0",
+        " * controller) driver. In your app: install and start the TWAI driver",
+        " * (twai_driver_install + twai_start) for your TX/RX GPIOs and this part's",
+        ` * bitrate, then call ${name}_esp32_bind() once before using the driver.`,
+        " * The driver core stays byte-for-byte portable. See",
+        " * fill_in_brief.hal_setup_todo for the bitrate/acceptance-filter config.",
+        " *",
+        ` * ${name}_esp32_bind() deliberately takes NO arguments: unlike I2C/SPI/UART`,
+        " * (which bind a specific bus/port handle), ESP-IDF exposes exactly one",
+        " * TWAI peripheral per chip, installed once for the whole application — so",
+        " * there is nothing instance-specific to store yet. The hook is kept for",
+        " * signature parity with the other targets' bind().",
+        " */",
+        coreInclude(name, language),
+        "#include <string.h>",
+        '#include "driver/twai.h"',
+        '#include "freertos/FreeRTOS.h"',
+        '#include "freertos/task.h"',
+        "",
+        "/* Reserved bind hook (see the file comment above). Call once after",
+        " * twai_driver_install()/twai_start(). */",
+        `void ${name}_esp32_bind(void) {`,
+        "}",
+        "",
+        "int hal_can_transfer(uint32_t id, const uint8_t *tx, uint8_t tx_len, uint8_t *rx, uint8_t *rx_len, uint32_t timeout_ms) {",
+        "    twai_message_t tx_msg;",
+        "    memset(&tx_msg, 0, sizeof tx_msg);",
+        "    tx_msg.identifier = id;",
+        "    tx_msg.data_length_code = tx_len;",
+        "    if (tx != NULL && tx_len > 0) {",
+        "        memcpy(tx_msg.data, tx, tx_len);",
+        "    }",
+        "    if (twai_transmit(&tx_msg, pdMS_TO_TICKS(timeout_ms)) != ESP_OK) {",
+        "        return -1;",
+        "    }",
+        "    if (rx == NULL || rx_len == NULL || *rx_len == 0) {",
+        "        return 0;",
+        "    }",
+        "    twai_message_t rx_msg;",
+        "    if (twai_receive(&rx_msg, pdMS_TO_TICKS(timeout_ms)) != ESP_OK) {",
+        "        return -1;",
+        "    }",
+        "    uint8_t n = rx_msg.data_length_code;",
+        "    if (n > *rx_len) {",
+        "        n = *rx_len;",
+        "    }",
+        "    memcpy(rx, rx_msg.data, n);",
+        "    *rx_len = n;",
+        "    return 0;",
+        "}",
+        "",
+        "void hal_delay_ms(uint32_t ms) {",
+        "    vTaskDelay(pdMS_TO_TICKS(ms));",
+        "}",
+        "",
+    ].join("\n");
+    return { path: seamPath(name, language), content };
 }
-/** Portable core + an ESP-IDF seam implementation for the same part. */
-export function generateEsp32Driver(json) {
+/**
+ * Portable core + an ESP-IDF seam implementation for the same part. With
+ * language "c" (default) the seam is `<slug>_hal_esp32.c`, unchanged from
+ * before. With language "cpp" the seam becomes `<slug>_hal_esp32.cpp` and its
+ * core include is `#include "<slug>.hpp"` (see coreInclude/seamPath above) —
+ * everything else in the seam content is identical either way.
+ */
+export function generateEsp32Driver(json, opts = {}) {
+    const bus = json.protocol.bus;
+    if (bus !== "I2C" && bus !== "SPI" && bus !== "UART" && bus !== "CAN") {
+        throw new UnsupportedBusError("esp32", bus);
+    }
     const name = slug(json.metadata.part);
     const prefix = prefixOf(json.metadata.part);
-    const base = generatePortableDriver(json);
+    const language = opts.language ?? "c";
+    const base = language === "cpp" ? generatePortableCppDriver(json) : generatePortableDriver(json);
+    const hal = bus === "SPI"
+        ? halImplSpi(name, prefix, language)
+        : bus === "UART"
+            ? halImplUart(name, prefix, language)
+            : bus === "CAN"
+                ? halImplCan(name, prefix, language)
+                : halImplI2c(name, prefix, language);
+    const hal_setup_todo = bus === "SPI"
+        ? `Bring up the ESP-IDF SPI bus (spi_bus_initialize with your MOSI/MISO/SCLK pins and host), then call ${name}_esp32_bind(host, cs_gpio, clock_hz) before the first driver call. Confirm this part's SPI mode (0-3) and maximum clock speed from the datasheet's SPI timing section.`
+        : bus === "UART"
+            ? `Install the ESP-IDF UART driver (uart_param_config + uart_driver_install) on your chosen port with this part's baud rate/parity/stop-bits (see the datasheet's serial interface section), then call ${name}_esp32_bind(port) before the first driver call.`
+            : bus === "CAN"
+                ? `Install and start the ESP-IDF TWAI driver (twai_driver_install + twai_start) on your chosen TX/RX GPIOs with this part's bitrate and an acceptance filter covering its message IDs (see the datasheet's CAN bus timing/message-ID section), then call ${name}_esp32_bind() before the first driver call.`
+                : `Bring up the ESP-IDF I2C master bus (i2c_new_master_bus with your SDA/SCL GPIOs and port), then call ${name}_esp32_bind(bus, 400000) before the first driver call. Tune ${prefix}_I2C_TIMEOUT_MS if needed.`;
     return {
-        files: [...base.files, halImpl(name, prefix)],
+        files: [...base.files, hal],
         fill_in_brief: {
             ...base.fill_in_brief,
-            hal_setup_todo: `Bring up the ESP-IDF I2C master bus (i2c_new_master_bus with your SDA/SCL GPIOs and port), then call ${name}_esp32_bind(bus, 400000) before the first driver call. Tune ${prefix}_I2C_TIMEOUT_MS if needed.`,
+            hal_setup_todo,
         },
     };
 }