Overview Files Versions Dependencies Discussions Activity

Raw

Gallia KiCad Feature Tour

An AI-guided interactive tour of Gallia's KiCad bridge commands. You orchestrate KiCad in real time — opening editors, parsing designs, searching libraries — while narrating to the user in a dark-themed side panel AND in chat.

HARD RULES — Follow Every Time

These rules come from direct user feedback. They are non-negotiable.

1. Be Very Talkative

The user complained about "dead air time" — there must be NO silent gaps
Every panel update should have a DETAILED description explaining what's happening, why it matters, and what the data means
Talk to the user in chat too between tool calls — explain your thinking
Descriptions should be 4-8 lines minimum, not 1-2 sentence stubs

2. Take a Screenshot at EVERY Step

After every bridge command, window operation, or panel update — take a screenshot
Read the screenshot with the Read tool to verify what's on screen
If something looks wrong, fix it before moving on

3. Verify Window Positions at Every Step

After taking a screenshot, CHECK that the expected KiCad window is visible and in the foreground
If it's not visible, re-issue window front and window position commands
Tell the user in the panel that you're verifying/fixing window positions
For steps that don't need a KiCad window (library searches), say so explicitly in the panel: "No KiCad window needed for this step — library search is pure file parsing"

4. Newlines in Panel Text

When passing --data or --description to tour_cli.py panel update, use \n for newlines
The CLI converts \\n → \n automatically — just use \n in your bash strings
NEVER show literal \n to the user — always verify newlines render correctly

5. Panel Must Not Clip

The narration panel uses screen_height - 80 px to account for taskbar + titlebar
The "Quit Tour" button must ALWAYS be visible at the bottom
If you see it clipped in a screenshot, stop and fix it

6. Shut Down Panel at End of Tour

When the tour completes (final summary step), ALWAYS run:
```
tour_cli.py panel stop
```
Also close any open KiCad editor windows
Do not leave the panel running after the tour ends

7. Handle Errors Gracefully

If a KiCad window shows an error dialog, dismiss it (PostMessageW VK_RETURN) and explain what happened
If a bridge command fails, show the error in the panel and move to the next step
Never crash the tour — skip problematic steps and continue

8. Kill Everything Before Starting

At the start of every tour, force-kill ALL KiCad processes and the old panel
Verify clean slate with tasklist | grep before proceeding
Check bridge server health before starting

Architecture

Claude Code (you — narrator + orchestrator)
  │
  ├── tour_cli.py panel start     → launch dark-themed narration panel (port 8799)
  ├── tour_cli.py panel update    → push step/title/description/status/data to panel
  ├── tour_cli.py panel stop      → shut down panel
  ├── tour_cli.py screenshot      → capture desktop PNG → Read tool → you analyze it
  ├── tour_cli.py highlight       → draw teal border overlay on screen (auto-dismiss)
  ├── tour_cli.py bridge          → HTTP POST to KiCad bridge server (port 8772)
  ├── tour_cli.py ipc-test        → run Rust IPC test binary
  ├── tour_cli.py ipc-layer       → set KiCad active layer via IPC (live!)
  ├── tour_cli.py window          → Win32 window find / position / close / front / wait
  └── tour_cli.py preflight       → check all prerequisites

Zero pip dependencies. Only Python stdlib (tkinter, urllib, ctypes, subprocess).

Setup & Preflight

# Discover paths
TOUR_DIR="$(cd ~/Github/adom-desktop/plugins/kicad/tour && pwd)"

# Check everything is ready
python "$TOUR_DIR/tour_cli.py" preflight

Preflight prints SCH_PATH and PCB_PATH — save those for bridge commands.

Screen size is 2560x1600 physical. Panel goes on the right (width=480). KiCad editors get positioned at 0 0 1840 1528.

Tour Startup Sequence

# 1. Kill everything
taskkill //F //IM kicad.exe; taskkill //F //IM eeschema.exe; taskkill //F //IM pcbnew.exe
tour_cli.py panel stop

# 2. Check bridge
tour_cli.py bridge health

# 3. Get screen size
tour_cli.py window screen-size

# 4. Launch narration panel
tour_cli.py panel start --port 8799

# 5. Screenshot to verify panel position and Quit button visibility
tour_cli.py screenshot
# READ the screenshot — verify panel is on right, Quit button visible at bottom

Panel Update Reference

tour_cli.py panel update \
  --step N --total 12 \
  --title "Step Title" \
  --act "ACT_NAME" \
  --description "Multi-line description\nwith newlines" \
  --status "Status text" \
  --status-color "#3fb950" \
  --data "Monospace data area\nfor tables and results" \
  --data-color "#3fb950"

Colors: green=#3fb950, yellow=#d29922, blue=#58a6ff, red=#f85149, teal=#00b8b1

Workflow Per Step — FOLLOW THIS EXACTLY

For EVERY tour step:

Update panel — set step number, title, act, description (4-8 lines explaining what you're about to do and why it matters)
Set status — "Running command..." with yellow color (#d29922)
Execute — run the bridge/window/IPC command
Update status — change to green (#3fb950) with results summary
Update data area — format the results as a clean monospace table
Verify window — if a KiCad editor should be visible:
- Run window front "Editor Name" to ensure it's in foreground
- Run window position "Editor Name" 0 0 1840 1528 if needed
Screenshot — capture desktop, Read the PNG
Analyze — verify the expected window is visible, panel looks right, button not clipped
Fix issues — if window not visible, re-issue front/position commands; if panel text wrong, re-send update
Narrate in chat — tell the user what you see, what's interesting, transition to next step

Tour Steps (12 Steps, 3 Acts)

Act 1: "DESIGN" — Analyze the Demo Schematic (Steps 1-6)

Step 1: Welcome

Panel: overview of what the tour will demonstrate (3 acts, 12 steps)
Data area: show the act breakdown
No KiCad window needed yet

Step 2: Open Demo Schematic

Bridge: open_schematic filePath=<SCH_PATH>
Window: wait → position (0,0,1840,1528) → front
Panel: explain that the bridge launches eeschema.exe via HTTP
Highlight the schematic area
Verify editor is in foreground via screenshot

Step 3: Schematic Statistics

Bridge: get_schematic_stats filePath=<SCH_PATH>
Panel: show component count, wire count, power symbols, etc.
Explain: "AI agents can instantly understand any design's scope"

Step 4: List All Components

Bridge: list_schematic_components filePath=<SCH_PATH>
Panel: format as Ref / Value / Footprint table
Explain: what each component does in the circuit

Step 5: Component Deep Dive (U1 — LM358)

Bridge: get_component_details filePath=<SCH_PATH> reference=U1
Panel: show all properties, footprint, datasheet, position
Explain: dual op-amp, SOIC-8 package, TI datasheet

Step 6: Generate BOM

Bridge: generate_bom filePath=<SCH_PATH>
Panel: format as Qty / Value / Package / Refs table
Explain: identical parts grouped (R1+R2 = qty 2), ready for procurement
Close schematic editor after this step

Act 2: "LIBRARIES" — Browse Component Libraries (Steps 7-9)

Step 7: Search Symbol Libraries

Bridge: search_symbols query=opamp limit=10
Panel: format results as Library / Symbol / Pins table
Explain: 224 symbol libraries, thousands of components, regex search
Note in panel: "No KiCad window needed — pure file parsing"

Step 8: Symbol Detail — LM358 Pin Map

Bridge: get_symbol_info library=Amplifier_Operational symbol=LM358
Panel: show full pin map — Pin# / Name / Type / Unit
Explain: AI can use pin data to auto-wire circuits correctly

Step 9: Search Footprint Libraries

Bridge: search_footprints query=QFP limit=10 (or 0805, SOIC, etc.)
Panel: format as Library / Name / Pads / Type table
Explain: 155+ footprint libraries, 15,000+ footprints, fast filename matching
Note: this command was added recently, searches system + user libraries

Act 3: "PCB" — PCB Board Analysis (Steps 10-11)

Step 10: Open PCB Layout

Close any lingering KiCad windows first
Bridge: open_board filePath=<PCB_PATH>
Window: wait → position → front
If error dialog appears, dismiss it (PostMessageW VK_RETURN)
Panel: explain what the PCB editor shows (copper traces, pads, board outline)
Verify PCB Editor is in foreground via screenshot

Step 11: PCB Statistics

Bridge: get_pcb_statistics filePath=<PCB_PATH>
Panel: format Board/Components/Routing sections
Explain: matches schematic (same component count), board dimensions, layer config
Close PCB editor after this step

Finale

Step 12: Tour Complete

Panel: "Tour Complete!" with full capabilities summary
Data area: list ALL bridge command categories
Status: "All 12 steps complete!" in green
Chat: recap table of all 12 steps
SHUT DOWN: tour_cli.py panel stop and close any remaining KiCad windows

CLI Reference

Subcommand	Purpose	Example
`preflight`	Check bridge, IPC, demo files	`tour_cli.py preflight`
`screenshot [path]`	Capture desktop to PNG	`tour_cli.py screenshot`
`highlight x y w h`	Draw highlight overlay	`tour_cli.py highlight 100 80 800 600 --label "Schematic"`
`bridge <cmd> [k=v]`	Send bridge command	`tour_cli.py bridge get_schematic_stats filePath=...`
`ipc-test [--section N]`	Run IPC test suite	`tour_cli.py ipc-test --section 1`
`ipc-layer <id>`	Set active PCB layer	`tour_cli.py ipc-layer 34`
`window <action> <title>`	Window management	`tour_cli.py window wait "Schematic Editor"`
`panel <action>`	Narration panel control	`tour_cli.py panel start --port 8799`

Highlight options

--color HEX       Border color (default: #00b8b1 teal)
--duration MS     Auto-dismiss time (default: 5000)
--label TEXT      Badge text above the highlight
--thickness N     Border width in px (default: 3)

Window actions

Action	Description
`find <title>`	List windows matching title substring
`close <title>`	Close the first matching window
`front <title>`	Bring matching window to foreground
`position <title> x y w h`	Move and resize window
`wait <title> [--timeout N]`	Block until window appears (default 15s)
`screen-size`	Print screen width and height

Bridge commands available

Editor control: open_schematic, open_board, open_symbol_editor, open_footprint_editor, open_3d_viewer, close_symbol_editor, close_footprint_editor, close_3d_viewer, close_kicad

Schematic analysis: get_schematic_stats, get_schematic_hierarchy, list_schematic_components, get_component_details, list_schematic_nets

PCB analysis: get_pcb_statistics, list_pcb_nets, list_pcb_footprints, find_tracks_by_net

Libraries: list_symbol_libraries, search_symbols, search_footprints, get_symbol_info

BOM & netlist: generate_bom, generate_netlist, trace_connection, get_net_connections

Design checks: run_drc, run_erc

Export: export_gerber, export_pdf, export_svg, export_step, export_bom_csv

IPC layer IDs

Layer	ID
F.Cu (front copper)	3
In1.Cu (inner 1)	4
In2.Cu (inner 2)	5
B.Cu (back copper)	34

DPI / Coordinate Notes

Screen: 2560x1600 physical, 150% DPI scaling
highlight.py is DPI-unaware — pass physical pixel coordinates, it converts internally
win_manager.py IS DPI-aware (SetProcessDPIAware) — coordinates are physical pixels
Panel uses tkinter logical pixels (winfo_screenwidth/height - 80px for taskbar)
KiCad editors: position at 0,0 size 1840x1528 (physical pixels, leaves room for panel)

Troubleshooting

Problem	Fix
Bridge OFFLINE	`python ~/Github/adom-desktop/plugins/kicad/server.py` (run in background)
Panel not starting	Check port 8799 not in use; kill old panel process
Quit button clipped	Panel should use `screen_h - 80` for height
Literal `\n` in panel	CLI auto-converts `\\n`→`\n`; check your escaping
KiCad window not in foreground	Re-issue `window front "Editor Name"`
PCB "Error loading" dialog	Dismiss with PostMessageW VK_RETURN, continue
Unicode error in window titles	tour_cli.py uses `.encode("ascii","replace").decode()`
search_footprints timeout	Already optimized — fast-path filename match only