KiCad - the KiCad Bridge

@@ -0,0 +1,69 @@+{+  "schema_version": 1,+  "type": "app",+  "slug": "adom-desktop-kicad-bridge",+  "title": "Reference bridge: KiCad",+  "brief": "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.",+  "version": "1.0.0",+  "tags": [],+  "license": "MIT",+  "discovery_triggers": [+    "kicad bridge",+    "kicad bridge source",+    "kicad_bridge_call",+    "reverse bridge",+    "in-process kicad plugin",+    "kicad bridge architecture",+    "pcbnew bridge",+    "eeschema bridge",+    "kicad plugin payload",+    "adom_bridge.py",+    "usercustomize.py kicad",+    "multi-instance bridge",+    "kicad bridge reference",+    "fork the kicad bridge"+  ],+  "discovery_pitch": "Reference implementation of the KiCad bridge — multi-instance Python server, forward path via kicad-cli, reverse path via in-process plugin (kicad_bridge_call). The most complex of the three bundled bridges; use as a deep-dive reference when authoring your own.",+  "sample_prompts": [+    {+      "label": "Read kicad bridge source",+      "prompt": "Download the kicad-bridge zip from the wiki and walk me through its server.py"+    },+    {+      "label": "Add a new kicad verb",+      "prompt": "Help me add a new kicad_get_layer_image verb to the in-process bridge plugin"+    },+    {+      "label": "Understand reverse bridge",+      "prompt": "Explain how kicad_bridge_call routes from cloud Docker into the running pcbnew.exe"+    },+    {+      "label": "List kicad verbs",+      "prompt": "adom-desktop bridge_list and show me the kicad verbs"+    },+    {+      "label": "Try the watcher pip",+      "prompt": "Enable project watch in Adom Desktop settings for a kicad project"+    }+  ],+  "install": {+    "binary_name": "adom-desktop-kicad-bridge",+    "install_dir": "",+    "install_hint": "",+    "version_cmd": ""+  },+  "readme": "# Reference bridge: KiCad\r\n\r\n## Source code + contributing (2026-05)\r\n\r\nThe KiCad bridge moved out of `adom-inc/adom-desktop`'s monorepo into its own dedicated repo so the community can extend it without coordinating with Adom Desktop's release cycle.\r\n\r\n### Where the source lives\r\n\r\nThe canonical repo is **[`adom-inc/adom-bridge-kicad`](https://github.com/adom-inc/adom-bridge-kicad)** on GitHub. It's private today and will go public after a review pass.\r\n\r\nIn the meantime, the full source — code, history, contributing guide, license — is **mirrored on this wiki page**:\r\n\r\n| Download | What it is | How to use |\r\n|---|---|---|\r\n| [`adom-bridge-kicad-source.tar.gz`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop-kicad-bridge/adom-bridge-kicad-source.tar.gz) | Clean source tree, no `.git` directory. ~165 KB. | `tar xzf adom-bridge-kicad-source.tar.gz && cd adom-bridge-kicad/` |\r\n| [`adom-bridge-kicad.bundle`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop-kicad-bridge/adom-bridge-kicad.bundle) | Git bundle with full commit history. ~240 KB. | `git clone https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop-kicad-bridge/adom-bridge-kicad.bundle adom-bridge-kicad && cd adom-bridge-kicad && git log` |\r\n\r\nNo GitHub account needed to download either — both URLs are public.\r\n\r\n### How to contribute\r\n\r\nWe accept community improvements. Most useful targets right now:\r\n\r\n- **KiCad 11 support** — when KiCad 11 ships, the `kicad_detect.py` discovery + the in-process bridge plugin both need updates. Fork-friendly.\r\n- **macOS / Linux ports** — bridge currently Windows-only; cross-platform PRs welcome.\r\n- **New verbs** — anything KiCad exposes via `pcbnew.*` / `kicad-cli` that you'd find useful.\r\n\r\nTwo contribution paths, depending on your access:\r\n\r\n**With a GitHub account (preferred):** wait until we make the repo public, then fork on GitHub and open a PR. We're aiming to flip the repo public in the next maintenance pass.\r\n\r\n**Without GitHub access (patch-by-email-style, available right now):** Clone the bundle, make your changes, generate a patch with `git format-patch origin/main..HEAD --stdout > my-changes.patch`, and email it to **`[email protected]`**. Adom maintainers will review and apply.\r\n\r\nSee `CONTRIBUTING.md` inside the tarball/bundle for the full PR + ship workflow.\r\n\r\n### How shipping works after merge\r\n\r\n1. Maintainer merges your PR into `main`\r\n2. Maintainer tags `v<X.Y.Z>` + runs `bash scripts/release-bridge.sh kicad` on their box\r\n3. New zip + manifest published to this wiki page (replaces current version)\r\n4. Every Adom Desktop install running v1.7.19+ auto-picks up your change within 4 hours OR immediately via `adom-desktop refresh_bridges`\r\n\r\nNo NSIS installer rebuild required. Your code reaches real users in ~30s after merge.\r\n\r\n### License\r\n\r\nMIT — see the `LICENSE` file in the tarball.\r\n\r\n---\r\n\r\n\r\nThe KiCad bridge is one of three reference implementations bundled with Adom Desktop. It's the most complex of the three — a multi-instance Python server that runs alongside KiCad GUI processes and provides both a forward path (CLI → bridge → kicad-cli) and a reverse path (CLI → bridge → in-process Python plugin inside KiCad).\r\n\r\nIf you're authoring a new third-party bridge, see the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges) first. Use this page for architectural reference once you've grasped the basics.\r\n\r\n## Quick facts\r\n\r\n| | |\r\n|---|---|\r\n| Name | `kicad` |\r\n| Display | KiCad EDA |\r\n| Spawn kind | Python (`server.py`) |\r\n| Port | 8772 |\r\n| Verb prefix | `kicad_*` (23 verbs) |\r\n| Watcher | yes (`*.kicad_pcb`, `*.kicad_sch`, `*.kicad_pro`) |\r\n| Source zip | [`kicad-bridge-v0.8.2.zip`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-v0.8.2.zip) |\r\n| Manifest | [`kicad-bridge-manifest.json`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-manifest.json) |\r\n| User-facing skill | [`kicad-SKILL.md`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-SKILL.md) |\r\n\r\n## What it does\r\n\r\n- **Forward path** (CLI → bridge → kicad-cli): board/schematic linting (`kicad_lint_board`, `kicad_lint_schematic`, `kicad_lint_library`), DRC/ERC (`kicad_run_drc`, `kicad_run_erc`), format upgrades, exports.\r\n- **Window automation** (CLI → bridge → Win32): launch editors (`kicad_open_board`, `kicad_open_schematic`, …), list open editors, capture screenshots of all KiCad windows, send keystrokes, click at coords.\r\n- **Reverse path** (CLI → bridge → in-process plugin inside KiCad): `kicad_bridge_call` invokes a Python handler running INSIDE the running KiCad GUI exe, with access to `pcbnew.*` / future `kipy`. This gives Docker-side Claude live introspection of the actually-open board without a round-trip through file exports.\r\n\r\n## `bridge.json`\r\n\r\n```json\r\n{\r\n  \"manifest_version\": 1,\r\n  \"name\": \"kicad\",\r\n  \"displayName\": \"KiCad EDA\",\r\n  \"version\": \"0.8.2\",\r\n  \"description\": \"Reverse bridge for KiCad — board/schematic introspection, lint via kicad-cli, plugin install, multi-instance probe, in-process DRC.\",\r\n  \"homepage\": \"https://github.com/adom-inc/adom-desktop\",\r\n  \"author\": \"Adom Inc.\",\r\n  \"license\": \"MIT\",\r\n  \"spawn\": {\r\n    \"kind\": \"python\",\r\n    \"entrypoint\": \"server.py\",\r\n    \"port\": 8772,\r\n    \"healthEndpoint\": \"http://127.0.0.1:8772/status\",\r\n    \"stopMethod\": \"kill\",\r\n    \"killImageName\": \"python.exe\"\r\n  },\r\n  \"verbPrefixes\": [\"kicad_\"],\r\n  \"verbs\": [\r\n    \"kicad_open_board\", \"kicad_open_schematic\", \"kicad_open_symbol_editor\",\r\n    \"kicad_open_footprint_editor\", \"kicad_open_3d_viewer\",\r\n    \"kicad_list_versions\",\r\n    \"kicad_run_drc\", \"kicad_run_erc\",\r\n    \"kicad_lint_board\", \"kicad_lint_schematic\", \"kicad_lint_library\",\r\n    \"kicad_format_upgrade\",\r\n    \"kicad_install_plugin\", \"kicad_install_symbol\", \"kicad_install_footprint\",\r\n    \"kicad_bridge_status\", \"kicad_bridge_call\",\r\n    \"kicad_open_editors\", \"kicad_window_info\", \"kicad_screenshot_all\",\r\n    \"kicad_send_key\", \"kicad_click\", \"kicad_close\"\r\n  ],\r\n  \"dependencies\": { \"python\": \">=3.11\", \"kicad\": \">=10.0\" },\r\n  \"category\": \"EDA\",\r\n  \"tags\": [\"pcb\", \"schematic\", \"open-source\", \"kicad-10\", \"kicad-11-ready\"],\r\n  \"watcher\": {\r\n    \"supports\": true,\r\n    \"displayName\": \"Project Watch\",\r\n    \"description\": \"Monitors a KiCad project folder for file changes and syncs them to Docker.\",\r\n    \"defaultGlobs\": [\"*.kicad_pcb\", \"*.kicad_sch\", \"*.kicad_pro\"],\r\n    \"configKey\": \"project_watch\"\r\n  }\r\n}\r\n```\r\n\r\nThe `watcher` field declares that this bridge supports project-watching — the GUI renders a 👁 pip on the chip when watching is active. See the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges#bridgejson-schema) for the full schema.\r\n\r\n## Architecture highlights\r\n\r\n```\r\nkicad/\r\n├── server.py              ← HTTP entry point; routes /command to handlers/\r\n├── handlers/              ← One module per logical verb group\r\n│   ├── board_ops.py       ← kicad_run_drc, kicad_lint_board, kicad_open_board, …\r\n│   ├── schematic_ops.py\r\n│   ├── library_ops.py\r\n│   ├── window_automation.py  ← Win32 SendInput, PrintWindow, EnumWindows\r\n│   ├── bridge_call.py     ← Reverse bridge dispatch into the in-process plugin\r\n│   └── …\r\n├── kicad_detect.py        ← Find installed KiCad versions, exe paths, USER_SITE\r\n├── adom_library.py        ← Symbol/footprint discovery in sym-lib-table.txt\r\n├── lib_table.py           ← Add/remove rows in *-lib-table files\r\n├── plugin_install.py      ← Copy adom_bridge.py into USER_SITE/usercustomize.py\r\n├── plugin_payload/\r\n│   └── adom_bridge.py     ← Reverse-bridge plugin loaded INSIDE every KiCad GUI exe\r\n├── parsers/               ← .kicad_sym, .kicad_mod, .kicad_pcb tokenizers\r\n└── start.bat              ← Windows launcher for local dev\r\n```\r\n\r\nThe reverse-bridge plugin (`plugin_payload/adom_bridge.py`) is what makes the kicad bridge special. KiCad's bundled Python interpreter overrides `site.USER_SITE` to `%USERPROFILE%\\Documents\\KiCad\\10.0\\3rdparty\\Python311\\site-packages\\`, and the `usercustomize.py` import hook fires on every KiCad GUI exe start (`kicad.exe`, `pcbnew.exe`, `eeschema.exe`, `kicad-cli.exe`). Our plugin uses this hook to launch a tiny websocket client that connects to the bridge — turning every running KiCad into a remote-controllable instance.\r\n\r\n## Reverse-bridge example\r\n\r\n```bash\r\n# From cloud Docker: list every open KiCad GUI exe + which board it has loaded\r\nadom-desktop kicad_open_editors\r\n\r\n# Direct in-process call: ask the running pcbnew.exe what board it has open\r\nadom-desktop kicad_bridge_call '{\"method\":\"get_board_info\"}'\r\n\r\n# Run a DRC IN-PROCESS — no file write, no kicad-cli detour\r\nadom-desktop kicad_bridge_call '{\"method\":\"run_drc\",\"args\":{\"severity\":\"error\"}}'\r\n```\r\n\r\nThe bridge dispatches these to `adom_bridge.py` running inside pcbnew. The handler executes against the live `pcbnew.GetBoard()` and returns JSON over the websocket.\r\n\r\n## Reference: install the source locally to read\r\n\r\n```bash\r\n# Pull the zip (no auth needed — wiki static URL)\r\ncurl -L https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-v0.8.2.zip -o /tmp/kicad-bridge.zip\r\n\r\n# Extract\r\nmkdir -p /tmp/kicad-bridge && cd /tmp/kicad-bridge && python3 -c \"import zipfile; zipfile.ZipFile('/tmp/kicad-bridge.zip').extractall()\"\r\nls -la\r\n```\r\n\r\nYou'll see `server.py`, `bridge.json`, `handlers/`, `plugin_payload/`, etc. — fork the layout for your own bridge.\r\n\r\n## Related\r\n\r\n- **[Bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges)** — `bridge.json` schema, packaging recipe, lifecycle\r\n- **[Puppeteer bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-puppeteer-bridge)** — simpler architecture, single-instance, Node + Chrome for Testing\r\n- **[Fusion 360 bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-fusion-bridge)** — passthrough-to-add-in pattern\r\n- **[adom-desktop main page](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop)** — install the parent app first\r\n\r\n",+  "author": {+    "id": "695820315b5f1e4db2fcf602",+    "name": "Kyle Bergstedt",+    "email": "[email protected]"+  },+  "visibility": {+    "public": true+  },+  "hero": null,+  "metadata": {},+  "created_at": "2026-05-28T05:28:43.294Z",+  "updated_at": "2026-05-28T05:28:43.294Z",+  "skills": []+}\ No newline at end of file