KiCad - the KiCad Bridge

@@ -1,87 +0,0 @@-# KiCad on Linux--The KiCad Bridge runs on Linux from the same release as Windows: one zip carries `kicad-bridge.exe` and-`kicad-bridge` (x86_64, glibc 2.39 or newer: Ubuntu 24.04, Debian 13, Fedora 40 and later), and Adom-Bridge starts the one for its OS. Every verb answers on Linux. Verbs that have no Linux path yet say so-with `errorCode: not_supported_on_platform` and a hint; none of them pretends.--## What you need--- **Adom Bridge for Linux** (the AppImage), signed in, running in your desktop session.-- **KiCad 10** from any of:-  - your distribution or the official PPA (Ubuntu): `sudo add-apt-repository ppa:kicad/kicad-10.0-releases && sudo apt install kicad`;-  - Flathub: `flatpak install --user flathub org.kicad.KiCad` (no root needed; `kicad_upgrade` does this for you);-  - snap, or a build of your own under `/usr/local`.-- A desktop session: GNOME, KDE, Cinnamon, Xfce and others, on **Wayland or X11**.--`kicad_readiness` tells you what it found: `installs[]` (one row per KiCad, with its source: distro-package, Flatpak, snap, PATH) and `platform`:--```json-"platform": {"os": "linux", "session": "wayland", "windowControl": true, "uiAutomation": true,-             "dialogSweep": true, "ipcApi": true, "kicadCli": true, "silentInstall": false}-```--## How it works--| What | How, on Linux |-|---|---|-| KiCad's windows | KiCad 10 is an X11 application everywhere: on a Wayland desktop it runs under XWayland. The bridge reads its windows from the X server (title, kind, process, owner, size, minimized and maximized state, stacking, focus), and closes, places and screenshots them there. Pure Rust, no X libraries needed. |-| Screenshots | The bridge reads a window's own pixels, so a KiCad window behind other windows still captures, nothing moves and nothing takes focus. Images land in the bridge's data folder (`screenshots/`) with the same fields as on Windows (`fullPath`, `safePath`, `coordMap`, `capturedBy: "local:x11"`). |-| Menus, dialog text and buttons | The desktop accessibility bus (AT-SPI), Linux's counterpart of Windows UI Automation. The bridge walks KiCad's menu bar and invokes items, reads a dialog's message, presses its buttons and ticks its check boxes, all without raising a window. `kicad_send_key` with a chord such as `alt+3` runs the menu item that carries it. The symbol and footprint editors load a part by typing its name into the library tree's search field and activating the row it selects. |-| Simulation | `kicad_simulate` runs ngspice through the distribution's `libngspice` (the library KiCad's own simulator uses); install it with `sudo apt install libngspice0` (Debian, Ubuntu) or `sudo dnf install libngspice` (Fedora) if it is missing. |-| KiCad's own processes | Each KiCad the bridge starts runs in its own systemd scope (`systemd-run --user --scope`), so it outlives a bridge restart, and a KiCad that crashes or runs out of memory never takes Adom Bridge down with it. |-| Live board edits | KiCad's IPC API, the same as on Windows. The bridge turns the API server on in KiCad's settings before the first launch. A Flatpak KiCad shares `/tmp` with the host through the launchers the bridge writes, so its API socket is the host's `/tmp/kicad/api.sock`. |-| Headless verbs | `kicad-cli` (DRC, ERC, exports, renders, netlists, lint) and file edits work the same on every OS. |-| Opening in the background | KiCad opens without taking keyboard focus from what you are typing in. Ask for the foreground with `foreground: true` and a `foregroundReason`, as on Windows. |-| First launch | Before KiCad starts for the first time the bridge writes any missing global library table (`sym-lib-table`, `fp-lib-table`, and KiCad 10's `design-block-lib-table`) from KiCad's own template, and marks the setup wizard done, so no "KiCad Setup" wizard covers the board. Files that exist are never touched. |--## What differs from Windows--- **Keys.** KiCad ignores synthetic key events on Linux, so `kicad_send_key` with a single key reaches-  a KiCad window only when that window already has the keyboard focus (the bridge never moves focus to-  type). Otherwise it answers `not_focused`. Use a chord or the `menu` argument (both run the menu item-  in the background), or the verb built for the job.-- **Clicks** at coordinates (`kicad_click`) are not available; use the menu, dialog-button and-  editing verbs instead.-- **Modal dialogs opened by the bridge itself.** A dialog that opens because the bridge pressed a menu-  item or a button (for example *Edit Teardrops*, or the "Are you sure?" box behind a Cancel) holds-  KiCad's accessibility bus until it closes, so the bridge cannot read or press it. It still screenshots-  it for you and closes it with Escape (Cancel). Dialogs KiCad opens on its own (warnings, the setup-  wizard) read and press normally. This is why `kicad_teardrops` is not Linux-ready yet.-- **Taskbar shortcuts** (`kicad_taskbar_repair`) are a Windows feature; `kicad_prewarm` skips that-  step on Linux.-- **Installing KiCad.** `kicad_upgrade` installs the Flathub build per user. A distribution package needs-  `sudo`, which the bridge never runs; it tells you the command instead.-- **On a Wayland desktop** X cannot see native Wayland windows (a browser, a terminal). KiCad's own-  windows are always visible to the bridge; `foreground` reads 0 while a Wayland window has focus.--## Which verbs are Linux-ready--Measured with the bridge's own verb battery (`skills/kicad-bridge-test/run_verb_tests.py`, every catalog verb)-through Adom Bridge on Ubuntu 24.04, GNOME on Wayland, KiCad 10.0.8 from the official PPA: **349 of 357 verbs-pass**, with no foreground grabs.--| Verbs | On Linux |-|---|---|-| Headless: DRC, ERC, every export and render, netlists, lint, libraries, footprint and symbol files, project and schematic edits, board file edits, rules, checks, fab, PCM | Ready, the same as Windows. |-| Live board through the IPC API: routing, zones, pours, silkscreen batches, selection, placement, 3D view control | Ready. |-| Windows: `kicad_launch`, `kicad_open_board`, `kicad_open_schematic`, `kicad_open_project`, `kicad_open_3d_viewer`, `kicad_state`, `kicad_window_info`, `kicad_open_editors`, `kicad_document_info`, `kicad_screenshot_all`, the close verbs, `kicad_foreground` | Ready (X11 and XWayland). |-| Menus and dialogs: `kicad_menu_items`, menu chords through `kicad_send_key`, `kicad_dismiss_dialogs`, the automatic dialog sweep | Ready (accessibility bus). |-| Library editors: `kicad_open_symbol_editor`, `kicad_show_symbol`, `kicad_open_footprint_editor`, `kicad_show_footprint` | Ready (accessibility bus). |-| `kicad_simulate` | Ready with the distribution's libngspice installed. |-| `kicad_height_check`, the 3D view of `kicad_library_views` | Ready; they need KiCad's 3D models (`kicad-packages3d` on Debian and Ubuntu, or the Flatpak, which includes them). |-| `kicad_send_key` with a single key | Only when the KiCad window already has focus; otherwise `not_focused`. |-| `kicad_click` | Not available on Linux (`not_supported_on_platform`). |-| `kicad_teardrops` | Not yet: it drives a modal dialog that it opens itself (see above). |-| `kicad_taskbar_repair` | Windows only (`not_supported_on_platform`). |-| `kicad_enable_software_opengl` | Windows only: Linux uses the system's Mesa, which already renders without a GPU. |--## Troubleshooting--| Symptom | Fix |-|---|---|-| `windowControl: false` in readiness | The bridge has no `DISPLAY`. Adom Bridge must run inside your desktop session (its autostart does this). |-| Menu or dialog verbs answer "no D-Bus session bus" or "accessibility bus did not answer" | Install `at-spi2-core` (every GNOME, KDE and Cinnamon desktop has it) and run Adom Bridge from the desktop session. |-| A Flatpak KiCad never answers the IPC API | Open KiCad through the bridge (`kicad_open_board`), which uses its own launchers that share `/tmp`; a KiCad started from the app menu keeps its socket inside the sandbox. |-| No KiCad found | `kicad_readiness` lists where it looked. Install from the list above, or `kicad_upgrade` for the Flatpak. |