app

Adom Desktop - KiCad Bridge

Public Made by Adom

by 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.

kicadpcbschematicedabridgeadom-desktop
Overview Files Skills Discover Packages Releases Dependencies Issues4 Breadcrumbs Pull Requests Activity
adom-desktop-kicad-bridge / skills / kicad-tour / SKILL.md
Download

name: kicad-tour description: "Run a guided KiCad tour on the user's laptop via adom-desktop — install a custom symbol library, walk the user through Symbol Editor → Footprint Editor → Schematic Editor → PCB Editor → 3D Viewer, then export gerbers. Two prebuilt packs ship under plugins/kicad/tour-pack/ (single resistor, fast) and plugins/kicad/tour-pack-rp2040/ (RP2040 breakout board, comprehensive). Trigger words — kicad tour, walk me through kicad, kicad demo, show me kicad, rp2040 breakout, resistor demo, kicad showcase, end-to-end kicad, send symbol and footprint, kicad export gerbers, gerbers for jlcpcb, gerbers for instapcb, kicad 3d board, kicad design walkthrough."

kicad-tour

A guided 8-step walkthrough of the KiCad bridge end-to-end. Runs from any cloud Docker session (or HD) — every command dispatches through adom-desktop kicad_* to the bridge on the user's laptop. Each step produces a visible change in KiCad that a viewer can see (and that the tour-runner script can screenshot).

Read kicad-interaction first. It covers the state-check + dialog rules this tour follows.

When to use

  • User asks "show me what KiCad can do" / "walk me through kicad"
  • Demo / onboarding flow when first connecting AD to KiCad
  • Sanity check after a fresh AD install — proves every bridge verb works

The 8-step tour (sequential, ~90s end-to-end)

Each step's CLI invocation is shown verbatim. The tour-runner Python script (plugins/kicad/skills/kicad-tour/tour_runner.py) executes these exact calls

  • collects screenshots into a single output dir.

Pre-step — pick a pack

# Fast demo (single 0805 resistor — proves the verbs work)
PACK=tour-pack
# Comprehensive demo (RP2040 breakout board — proves a real chip works)
PACK=tour-pack-rp2040

The packs are mounted by the bridge at:

  • C:/Github/adom-desktop/plugins/kicad/<PACK>/
  • (When AD is installer-deployed, look under %LOCALAPPDATA%/Adom Desktop/bridges-cache/kicad/<PACK>/ — adjust paths.)

Step 1 — install the custom symbol + footprint libraries

The tour-pack ships a <Lib>.kicad_sym and a <Lib>.pretty/ directory. The kicad_install_library verb copies them to the user's KiCad library tree (%USERPROFILE%/Documents/KiCad/10.0/{symbols,footprints}/) and registers them in sym-lib-table and fp-lib-table.

LIB=AdomTour   # or AdomRP2040 for the RP2040 pack

adom-desktop kicad_install_library "{
  \"libraryPath\":\"C:/Github/adom-desktop/plugins/kicad/${PACK}/${LIB}.kicad_sym\",
  \"libraryType\":\"symbol\",
  \"libraryName\":\"${LIB}\"
}"

adom-desktop kicad_install_library "{
  \"libraryPath\":\"C:/Github/adom-desktop/plugins/kicad/${PACK}/${LIB}.pretty\",
  \"libraryType\":\"footprint\",
  \"libraryName\":\"${LIB}\"
}"

Step 2 — open Symbol Editor on the custom symbol

SYMBOL=R_AdomTour       # tour-pack
# SYMBOL=RP2040_AdomTour   # tour-pack-rp2040

adom-desktop kicad_open_symbol_editor "{
  \"libraryName\":\"${LIB}\",
  \"symbolName\":\"${SYMBOL}\"
}"

Wait ~5s for KiCad's startup. Screenshot via kicad_screenshot_all — should show the new library highlighted in the left-side library tree.

Step 3 — open Footprint Editor on the custom footprint

FOOTPRINT=R_0805_AdomTour       # tour-pack
# FOOTPRINT=QFN-56_AdomRP2040    # tour-pack-rp2040

adom-desktop kicad_open_footprint_editor "{
  \"libraryName\":\"${LIB}\",
  \"footprintName\":\"${FOOTPRINT}\"
}"

Step 4 — show 3D viewer for the footprint

# editor='fp' explicitly targets the Footprint Editor's 3D viewer
# (KiCad 9 worked via WM_COMMAND 20500; KiCad 10 may need adjustment —
# the fallback to PCB editor below covers the common case.)
adom-desktop kicad_open_3d_viewer '{"editor":"fp"}'

If this returns "3D Viewer did not open from Footprint Editor" on KiCad 10, either skip to step 7 (the board's 3D viewer is the more reliable showcase anyway) OR send Alt+3 via AD's chord-aware keypress verb (focus the Footprint Editor first):

# desktop_press_key owns modifier chords; kicad_send_key is only for single keys to an exact hwnd
adom-desktop desktop_press_key '{"keys":"alt+3"}'

Step 5 — open the prebuilt schematic

The tour-pack ships template/tour-demo.kicad_sch (single R) or template/rp2040-breakout.kicad_sch (RP2040 breakout). Each is wired to use the custom library installed in step 1.

SCH=C:/Github/adom-desktop/plugins/kicad/${PACK}/template/tour-demo.kicad_sch
# SCH=C:/Github/adom-desktop/plugins/kicad/tour-pack-rp2040/template/rp2040-breakout.kicad_sch

adom-desktop kicad_open_schematic "{\"filePath\":\"${SCH}\"}"

Step 6 — open the prebuilt board

Same idea — premade .kicad_pcb with the footprint placed and a (model "${KICAD10_3DMODEL_DIR}/...") reference per footprint.

PCB=C:/Github/adom-desktop/plugins/kicad/${PACK}/template/tour-demo.kicad_pcb
adom-desktop kicad_open_board "{\"filePath\":\"${PCB}\"}"

Step 7 — show the 3D view of the board

# editor='pcb' to target the board's 3D viewer (and skip the FP path
# which would otherwise be tried first when both editors are open).
adom-desktop kicad_open_3d_viewer '{"editor":"pcb"}'

This is the visual climax — the green board appears with the actual 3D chip model rendered on top. For the RP2040 pack this is a QFN-56 package; for the resistor pack it's a tiny 0805 chip.

Step 8 — export gerbers

adom-desktop kicad_export_gerbers "{
  \"filePath\":\"${PCB}\",
  \"outputDir\":\"C:/tmp/${PACK}-gerbers\"
}"

Returns the list of generated .gbr / .gtl / .gbl / .gm1 files. These are JLCPCB- and InstaPCB-ready directly.

Failure modes + recovery

Symptom Cause Recovery
Unknown command: export_gerbers Bridge < v0.7.1 Update via bridge_reinstall '{"name":"kicad"}'
3D Viewer did not open from Footprint Editor KiCad 10 WM_COMMAND ID different Pass editor='pcb' (step 7 path) — works on board
Library 'AdomTour' not found after opening editor KiCad cached its old lib-table state Close all KiCad windows + reopen — sym/fp-lib-table is read at startup
Schematic opens with "older format" warning bar Tour-pack files are KiCad 9 sexpr Tolerable; KiCad 10 reads them. They convert on save.
Cannot find footprint AdomTour:R_0805_AdomTour Footprint library install failed Re-run step 1b; verify %USERPROFILE%/Documents/KiCad/10.0/footprints/AdomTour.pretty/ exists

Cleanup

adom-desktop kicad_close '{}'                       # close all KiCad windows
rm -rf "%USERPROFILE%/Documents/KiCad/10.0/symbols/AdomTour.kicad_sym"
rm -rf "%USERPROFILE%/Documents/KiCad/10.0/footprints/AdomTour.pretty"
# (Or leave them — they're harmless even when not actively tour-touring.)

Tour-runner Python

plugins/kicad/skills/kicad-tour/tour_runner.py orchestrates all 8 steps non-interactively + pulls every screenshot to a local output dir. Usage:

python plugins/kicad/skills/kicad-tour/tour_runner.py \
    --pack tour-pack \
    --output /tmp/kicad-tour-shots
# or
python plugins/kicad/skills/kicad-tour/tour_runner.py \
    --pack tour-pack-rp2040 \
    --output /tmp/rp2040-tour-shots

Each step's CLI call is shown above stdout in human-readable form, with the resulting screenshot named 01-symbol-editor.png, 02-footprint-editor.png, etc. Exits 0 on full success.

When run from inside a Docker container (= relay path) vs. on the host (= direct API path) the script's adom-desktop subprocess transparently picks whichever is reachable. No config required.