app
KiCad - the KiCad Bridge
Public Made by Adomby adom
Reference implementation of the KiCad bridge: multi-instance Python server, forward path via kicad-cli, reverse path via in-process plugin. Most complex of the three bundled bridges.
← Commit history
README.md+37−37@@ -1,31 +1,31 @@-# Adom Bridge — KiCad Bridge+# Adom Bridge: KiCad Bridge -A **reverse bridge** that lets Adom Bridge (ab) — and the AI driving it — control the user's own+A **reverse bridge** that lets Adom Bridge (ab), and the AI driving it, control the user's own KiCad on Windows: open and drive every editor, install symbol/footprint libraries, place parts, run DRC/ERC, export manufacturing files, and screenshot any window back to the AI. -> ### Two artifacts on this page — which one do you want?+> ### Two artifacts on this page, which one do you want? > > | | **Release ZIP** (`adom-bridge-kicad-v*.zip`) | **Package** (`adom-wiki pkg install adom/kicad-bridge`) | > |---|---|---|-> | What it is | The **bridge runtime** — the actual Python server that drives KiCad | **Skills + docs only**, for a container/agent |+> | What it is | The **bridge runtime**: the actual Python server that drives KiCad | **Skills + docs only**, for a container/agent | > | Who loads it | **Adom Bridge** downloads it automatically via `adom-bridge-kicad-manifest.json` | You, into a container, to teach an agent the `kicad_*` verbs | > | Contains | code, certs, UIA scripts, board template | `SKILL.md` files (no binaries, no images) |-> | You install it manually? | **No** — Bridge handles it | Yes |+> | You install it manually? | **No**: Bridge handles it | Yes | > > **The package is not the bridge.** Installing the package does not give you a working-> bridge; Adom Bridge loading the release zip does. Both are kept deliberately small — the zip is+> bridge; Adom Bridge loading the release zip does. Both are kept deliberately small, the zip is > auto-bundled into Adom Bridge, so it ships only what the runtime needs. KiCad is the user's **host app**. The bridge *detects* an existing KiCad and, if none is present,-*installs* one for them — it never asks the user to download or click through anything by hand.+*installs* one for them, it never asks the user to download or click through anything by hand. - **Page / docs:** https://wiki.adom.inc/adom/kicad-bridge - **Bridge SDK:** https://wiki.adom.inc/adom/adom-bridge-sdk - **Verb namespace:** `kicad_*` · **Status verb:** `kicad_bridge_status` · **Health:** `GET /status` > Every screenshot in this README was captured on **ADOMBASELINE**, a stock Hyper-V VM with **no-> GPU**, driven end-to-end through the bridge — install → libraries → editors → 2D → 3D. If it+> GPU**, driven end-to-end through the bridge, install → libraries → editors → 2D → 3D. If it > renders there, it renders on a real laptop. ---@@ -61,7 +61,7 @@ carries a revision guard, and is DRC-checked against a snapshot before it commit autorouter and not an electrical sign-off. Details and the regression demo: [SKILL.md](SKILL.md#live-routing-from-09340) and [demo/routing/README.md](demo/routing/README.md). -## The demo verb — `kicad_demo`+## The demo verb: `kicad_demo` One verb that shows the whole bridge off, built for the AI that demos Adom Bridge during Hydrogen's install. Six beats, in the order a hardware person thinks:@@ -89,7 +89,7 @@ then move on. **It ships nothing.** The two demo parts, the schematic and the board are all generated in code, and the 3D bodies come from KiCad's *own* bundled-`3dmodels/*.3dshapes` — so the runtime zip stays small and the 3D views are real.+`3dmodels/*.3dshapes`: so the runtime zip stays small and the 3D views are real. Parts install into the user's real `Adom` library; the project lands in `Documents/adom-kicad-demo`. @@ -106,7 +106,7 @@ window-targeted (UIA / `PostMessage`), so you can keep working while it runs. ## How it fits together The bridge is a `spawn.kind: python` process Bridge launches on the user's machine (`entrypoint:-server.py`, `port: 0` — Bridge picks the port and passes `ADOM_BIND_HOST`). It speaks HTTP+server.py`, `port: 0`: Bridge picks the port and passes `ADOM_BIND_HOST`). It speaks HTTP (`POST /command`, `GET /status`) and reaches KiCad through **four control surfaces**, picking the lightest one that can do the job. @@ -126,41 +126,41 @@ lightest one that can do the job. Everything below was opened and captured on the GPU-less VM. Sample data is the **RP2040 breakout** generated by `tour-pack-rp2040/` (an `AdomRP2040` symbol + `QFN-56_AdomRP2040` footprint + a board). -### Schematic editor — `kicad_open_schematic`+### Schematic editor: `kicad_open_schematic` The RP2040 breakout: the MCU (U1), USB-C, a 12 MHz crystal, decoupling, and mounting pins.  -### Symbol editor — `kicad_open_symbol_editor`+### Symbol editor: `kicad_open_symbol_editor` Opens straight to a symbol (`kicad_install_symbol` puts it in a user library first).  -### Footprint editor — `kicad_open_footprint_editor`+### Footprint editor: `kicad_open_footprint_editor` -`{"footprintName":"QFN-56_AdomRP2040","library":"AdomRP2040"}` loads the part directly — 56 pins ++`{"footprintName":"QFN-56_AdomRP2040","library":"AdomRP2040"}` loads the part directly, 56 pins + thermal pad, 7×7 mm, 0.4 mm pitch, courtyard and silkscreen.  -### PCB editor (2D) — `kicad_open_board`+### PCB editor (2D): `kicad_open_board` -The routed breakout — copper, silkscreen, the QFN-56 land pattern, mounting holes.+The routed breakout, copper, silkscreen, the QFN-56 land pattern, mounting holes.  -### 3D viewer — `kicad_open_3d_viewer {"editor":"pcb"}`+### 3D viewer: `kicad_open_3d_viewer {"editor":"pcb"}` -The full board in 3D — board body, the USB-C connector's 3D model, the QFN chip body, SMD parts,+The full board in 3D, board body, the USB-C connector's 3D model, the QFN chip body, SMD parts, plated through-holes. **Rendered on the CPU via the software-OpenGL fallback (below); reload 1.7 s.**  --- -## Install & upgrade — zero manual steps+## Install & upgrade: zero manual steps The bridge never tells the user to go download KiCad. `kicad_upgrade` fetches the official installer and runs it silently, picking the scope automatically:@@ -171,36 +171,36 @@ and runs it silently, picking the scope automatically: `kicad_readiness` reports whether KiCad is installed and ready without side effects; the AI routes on it before offering to install. Hard-won install details (all handled for you): -- KiCad 10's NsisMultiUser installer **requires** a scope flag — bare `/S` errors `rc=666660`.+- KiCad 10's NsisMultiUser installer **requires** a scope flag, bare `/S` errors `rc=666660`. - Bridge's portable Python has **no CA bundle**; the bridge ships `certs/cacert.pem` and uses it for TLS. - Downloads are size-checked against `Content-Length` (a truncated installer otherwise fails at NSIS).-- `%APPDATA%/kicad/<ver>/` lib tables don't exist until first launch — the bridge **bootstraps** them+- `%APPDATA%/kicad/<ver>/` lib tables don't exist until first launch, the bridge **bootstraps** them so `install_library`/`install_footprint` work on a never-opened KiCad. - `kicad_upgrade {"diagnoseOnly":true}` reports token-elevation type + `EnableLUA` without installing. --- -## Dialogs & error handling — the bridge clears the pointless ones+## Dialogs & error handling: the bridge clears the pointless ones KiCad throws modal dialogs that stall automation. The bridge **scans every window owned by a running-KiCad process** (by PID — reliable, unlike title matching), auto-expires the benign ones, screenshots+KiCad process** (by PID, reliable, unlike title matching), auto-expires the benign ones, screenshots what it dismissed, and returns a hint so the AI can decide what (if anything) to tell the user. Auto-expired benign dialogs include: - **"Could not use OpenGL / falling back to software rendering"** (GPU-less hosts).-- **"Welcome to KiCad — starting for the first time"** first-run wizard (dismissing accepts defaults).+- **"Welcome to KiCad, starting for the first time"** first-run wizard (dismissing accepts defaults). - **"This file was created by an older version of KiCad"** conversion notice.  Verbs: -- `kicad_window_info` — lists windows and **self-heals** (auto-expires benign dialogs) by default.-- `kicad_dismiss_dialogs {"all":true}` — clear everything blocking; `{"screenshot":true}` returns+- `kicad_window_info`: lists windows and **self-heals** (auto-expires benign dialogs) by default.+- `kicad_dismiss_dialogs {"all":true}`: clear everything blocking; `{"screenshot":true}` returns images of each; `{"forceSoftwareCanvas":true}` persists Cairo canvas; `{"debug":true}` dumps the raw PID-based scan.-- `kicad_screenshot_all` — one call returns **every** open KiCad window, so the AI can spot an error+- `kicad_screenshot_all`: one call returns **every** open KiCad window, so the AI can spot an error dialog it didn't expect and read the message. ---@@ -208,10 +208,10 @@ Verbs: ## Software-OpenGL fallback (last resort) `kicad_enable_software_opengl` deploys Mesa's `llvmpipe` (a CPU OpenGL rasterizer) into KiCad's `bin`-so a box with **no usable GPU** — Hyper-V, RDP, headless CI — can still render the editors and the 3D+so a box with **no usable GPU**: Hyper-V, RDP, headless CI, can still render the editors and the 3D viewer. This is how every 3D shot above exists. -> ⚠️ It renders on the CPU and is **slow**. It is a worst-case fallback only — a real GPU (or GPU-P /+> ⚠️ It renders on the CPU and is **slow**. It is a worst-case fallback only, a real GPU (or GPU-P / > DDA passthrough) is vastly better. The bridge keeps it so a GPU-less box isn't a dead end; it is > never suggested proactively. @@ -222,18 +222,18 @@ viewer. This is how every 3D shot above exists. All 47 verbs (prefix `kicad_`). Call `kicad_describe` for the live catalog with per-verb hints, related verbs, and pitfalls. -**Windows & UI** — `launch`, `open_board`, `open_schematic`, `open_symbol_editor`, `open_footprint_editor`,+**Windows & UI**: `launch`, `open_board`, `open_schematic`, `open_symbol_editor`, `open_footprint_editor`, `open_3d_viewer`, `open_editors`, `close_symbol_editor`, `close_footprint_editor`, `close_3d_viewer`, `close`, `window_info`, `dismiss_dialogs`, `screenshot_all`, `send_key`, `click`, `fix_keyboard`, `demo` -**Libraries & parts** — `install_library`, `install_symbol`, `install_footprint`, `install_plugin`,+**Libraries & parts**: `install_library`, `install_symbol`, `install_footprint`, `install_plugin`, `place_footprint`, `adom_library_status` -**Checks & export** — `run_drc`, `run_erc`, `lint_board`, `lint_schematic`, `lint_library`,+**Checks & export**: `run_drc`, `run_erc`, `lint_board`, `lint_schematic`, `lint_library`, `format_upgrade`, `export_gerber`, `export_pdf`, `export_svg`, `export_step`, `export_bom_csv`, `export_molecule` -**Detect, install & meta** — `list_versions`, `readiness`, `describe`, `diagnostics`, `status`,+**Detect, install & meta**: `list_versions`, `readiness`, `describe`, `diagnostics`, `status`, `enable_software_opengl`, `check_for_updates`, `upgrade`, `uninstall`, `bridge_status`, `bridge_call` ---@@ -242,16 +242,16 @@ related verbs, and pitfalls. Bridge provisions everything; there is nothing to install by hand. -- **Python** ≥ 3.11 (Bridge provisions it) — stdlib only, plus the bundled `certs/cacert.pem`.+- **Python** ≥ 3.11 (Bridge provisions it), stdlib only, plus the bundled `certs/cacert.pem`. - **KiCad** ≥ 7.0 (host app; `kicad_upgrade` installs it if absent). - **OS:** Windows (macOS/Linux detection stubs exist; the GUI surfaces are Windows-first). -The bridge binds `ADOM_BIND_HOST` on a Bridge-assigned port — never `0.0.0.0`. Auto-updates via+The bridge binds `ADOM_BIND_HOST` on a Bridge-assigned port, never `0.0.0.0`. Auto-updates via `updateManifestUrl` in `bridge.json`. --- -*Developer docs ship as `user-invocable:false` skills in the package itself — `kicad-bridge-dev`+*Developer docs ship as `user-invocable:false` skills in the package itself, `kicad-bridge-dev` (architecture + hard-won findings), `kicad-bridge-publish` (release recipe), and `kicad-bridge-hero` (page hero recipe). Maintainers get them with the normal `pkg install`; everyday users are never offered them.*