/pcb

name: pcb
description: Create, edit, lay out and review native KiCad circuit boards (.kicad_pcb) and their schematics (.kicad_sch) - parts and nets, ERC, placement and routing, DRC, and a review before ordering (fab limits, decoupling, track width for current, assembly and BOM sourcing for JLCPCB, PCBWay or another fab); exports fabrication files, the netlist and BOM, or STEP for enclosure design. Shows boards and schematics in the CAD Viewer.
license: MIT
metadata:
  repository: earthtojake/text-to-cad

PCB design

Setup

Run the `cad` command (`~/.local/bin/cad` where it is not on your PATH; `cad.exe` on Windows). If it is missing, install text-to-cad, outside a sandbox or with its permission:

curl -fsSL https://texttocad.dev/install.sh | sh

On Windows, in PowerShell: `irm https://www.texttocad.dev/install.ps1 | iex`. If the CAD app was only just added, its server may still be starting: try again for up to a minute first. `cad doctor --check` explains any other failure, changing nothing; `cad doctor` repairs what it reports. Tell the person any next step `cad setup` prints.

text-to-cad reads a board or schematic itself, so inspecting either, and viewing a schematic or taking its snapshot, need no KiCad. DRC (`cad kicad_pcb drc`), ERC (`cad kicad_sch erc`), every export (`cad kicad_pcb export`, `cad kicad_sch export`) and an edit (`kicad_pcb.edit`, `kicad_sch.edit`) run KiCad's command line, `kicad-cli`, and its IPC API from kicode, the `kicad` extra (`cad[kicad]`): the `cad` command installs it the first time a board command needs it (about 100 MB to download and 340 MB on disk, once; nothing for you to install), and `cad run` gives a script that edits a board its environment. Showing a board or taking its snapshot needs it too: KiCad refills the board's copper pours on a copy before they are drawn, so the first board shown starts that download. `CAD_KICAD_REFILL=0` in the server's environment turns the refill off (no download; set it as `CAD_KICAD_3DMODELS` below), and the pours are drawn as the file saved them, as they are when the download or the refill fails. A KiCad you installed yourself is never run. `CAD_KICAD_CLI` can name another `kicad-cli` (the command line itself, named `kicad-cli`; KiCad 9 or newer, a nightly's for an edit). It runs headless, with private settings, and never opens KiCad's app; never open a board in KiCad's app to check it. Its library variables name KiCad's own libraries, never your variables or KiCad settings: a project's `sym-lib-table` or `fp-lib-table` row that names a stock library as KiCad's own tables do (`${KICAD10_SYMBOL_DIR}/Device.kicad_sym`, `${KICAD10_FOOTPRINT_DIR}/Resistor_SMD.pretty`, any major's spelling) reads it in the libraries of the KiCad you installed (the newest, if several; or the installation whose `3dmodels` folder `CAD_KICAD_3DMODELS` names): nothing to set. With no KiCad installed, ERC warns `lib_symbol_issues` that each such library was not found and DRC `lib_footprint_issues` that it is not enabled; a project that carries its libraries (`${KIPRJMOD}`) needs no KiCad.

kicode's KiCad is a nightly (10.99), so a board or schematic it saves is in the nightly's format, which a stable KiCad app refuses; viewing and snapshots still work, and the CAD Viewer's Open in says which KiCad on this computer can open the file.

Native files are the source

Edit the `.kicad_pcb` itself, preserving its companion `.kicad_pro`, `.kicad_dru`, libraries and schematic when present. Reading or displaying a board never writes it. There is no text-to-cad PCB model, build step, or generated-board ownership marker. A helper script may make a requested edit, but reread the current file before editing and preserve unknown records and UUIDs. Do not regenerate an existing project from an incomplete description.

Change a board through KiCad's IPC API in an edit, a `with` block: `kicad_pcb.edit` hands the block the open board (KiPy's `Board`, as kicode names it: `kicode.board.Board`) and saves it at the block's end when the block changed it; a block that changes nothing leaves the file byte for byte, one that raises saves nothing (its exception goes on), and a save KiCad cannot finish leaves every file as it was, saying why. A board not there yet is made by KiCad, with its project, and saved. `kicad_sch.edit` does the same for a schematic ([schematic](references/schematic.md#edit-it)); the two of one project, one inside the other, share one KiCad. Run the script with `cad run board.py`, which gives it the `kicad` extra (kicode: KiPy and a `kicad-cli` with its headless `api-server`); a `kicad-cli` that `CAD_KICAD_CLI` names without one is refused up front, before any server starts. That server listens on a local socket, which a shell sandbox that refuses sockets (an agent app's default, Codex's among them) does not allow: the edit then stops at once, saying so, and the script must run outside the sandbox (ask for the unsandboxed or escalated run); inspecting, DRC, exports and snapshots run inside it. KiCad's first start from a new environment can take a minute, which the edit says while it waits. Import KiPy's names from `kicode` (`from kicode.proto.common.types import KIID`, `from kicode.util.units import from_mm`), never from `kipy`: the two cannot share a process. Saving writes the file in the nightly's format: one from an older KiCad is upgraded, which the run says, and that older KiCad can no longer open it. Checks and exports of the saved board are calls after the block (`kicad_pcb.drc`, `kicad_pcb.export`); a STEP or GLB export holds each part's 3D model where the board's 3D view finds it ([board views](#board-views)), and leaves out, naming them, the parts whose model is missing (or, in a STEP, only in VRML); `--to dxf` writes the outline and drilled holes, for an enclosure:

from cad import kicad_pcb
from kicode.util.units import from_mm

BOARD = "board.kicad_pcb"

with kicad_pcb.edit(BOARD) as b:       # the