KicadGen: a small language for scripting KiCad schematics
v0.72.103.244

kicad_gen.py is a small Python library — really a tiny domain- specific language — for describing a KiCad schematic in code: place a component, connect two pins, write the file. Any real circuit written using this language (this project's own two example circuits, ppexample_circuit1~/~ppexample_circuit2, or a downstream consumer's own real, physically-designed circuit) is written using exactly what's documented below.

This document is a practical reference for the language itself, written so that a change to a circuit — add a part, rewire a connection, move something — can be made directly. It does not repeat the history of how each rule below was discovered; that narrative, including every bug found along the way and exactly how it was confirmed, lives in ResearchJournal.org's own entries and in kicad_gen.py's own module docstring. Read this document to use the language; read those if you want to know why a rule exists.

EXCISED 2026-08-17 from dudhya (old-smartphone revival), the project kicad_gen.py was originally developed inside, along with the rest of this project's own generic engine (a separate extraction, 2026-08-14 – see ResearchJournal.org's own entries for both dates). What was genuinely dudhya-specific in the original version of this document (a concrete description of THAT project's own real pipeline, its own real file paths and Makefile targets) was updated and dispatched to dudhya's own DevelopmentStandard.org rather than carried forward stale into this project; what remains here is the language reference itself, generalized where an example had named a specific downstream project's own file.

Everything here was true as of v0.72.103.244. Treat kicad_gen.py's own docstring as the final authority if the two ever disagree — code and comment can drift, and the code is what actually runs.

kicad_gen.py is only ONE piece of this project's own larger toolchain – worth understanding the whole shape before diving into the language itself, since it explains WHY things are organized the way they are. See Concept.org's own "Goal" section for the full picture; briefly:

1. A real netlist (loaded from an existing KiCad schematic via netlist.py's own load_from_schematic(), or built directly for a circuit that doesn't have a schematic yet, as this project's own two example circuits do) is the one, shared ground truth.
2. kicad_layout.py consumes that netlist to produce a placed, wired, KiCad-valid schematic – entirely algorithmically, using THIS document's own language (Schematic~/~place()~/~label()~/ ~wire()) under the hood, but with every component's own position decided from the netlist rather than typed by hand.
3. A hand-written script (this document's own real subject) can ALSO consume that same language directly, choosing every coordinate deliberately – this is how this project's own two example circuits are built, and how any downstream consumer's own real, physically-designed circuit would typically be authored.

Learning this language well enough to hand-write or hand-edit a circuit script is exactly the skill needed to read or extend kicad_layout.py's own generator code too, since both ultimately call the same place()~/~label()~/~wire() primitives – one calling them with hand-chosen coordinates, the other with computed ones.

A KiCad schematic is, underneath, a text file (S-expressions, similar in spirit to Lisp) listing every symbol placed on the sheet, every wire drawn between two points, and every text label. Hand-writing that text file is exactly as tedious and error-prone as it sounds — this project tried it and found several real bugs the hard way (see ResearchJournal.org). kicad_gen.py exists so you never write that text directly: you call Python functions, and the library emits correct, verified S-expressions on your behalf.

Three ideas carry almost the whole language:

1. Every component is a symbol you "place" at an (x, y) position on the sheet, in millimetres, optionally rotated. Placing it gives you back a small dictionary mapping each of its pin names to that pin's own absolute (x, y) position — already correctly computed, accounting for the component's rotation.
2. Two things on the same electrical net are connected either by a real, drawn wire, or by two matching net labels. A drawn wire is for two things sitting close together, physically. A label is for a net with many members spread across the sheet (like ground), or for two things too far apart to sensibly draw a direct line between.
3. A label is never placed exactly on a pin. It sits at the far end of a short stub wire leading away from the pin, so the schematic stays readable rather than looking like every pin has text glued onto it.

Listing 1 is how every script starts: the imports, then the schematic.

import sys, os
sys.path.insert(0, os.path.dirname(__file__))   # so "import kicad_gen" finds
                                                  # the library, from any directory
                                                  # you happen to run the script from
from kicad_gen import Schematic, write_project_file

sch = Schematic(
    title="My circuit",
    date="2026-08-17",
    rev="1.0",             # see "Versioning the schematic" below
    company="my project",
    comments=["One line per title-block comment slot (up to 4)."],
    paper="A4",             # "A4" or "A3"; see "Fitting the page" below
)

sch is the one object every other call in this language works through. At the end of the script (see Listing 2):

root_uuid = sch.write("my-circuit.kicad_sch")
write_project_file("my-circuit.kicad_pro", root_uuid, "my-circuit.kicad_pro")

write_project_file makes the schematic open as a proper KiCad project rather than a bare file — always call it alongside sch.write(), passing the root_uuid that write() itself returns (the project file needs to reference the schematic's own internal identifier to associate the two correctly).

Confirmed by direct measurement (rendering to SVG and checking where the drawn geometry actually ends up relative to the label's own anchor point, not just visual impression): "right", "left", and "down" all place their label's text correctly, extending away from the pin as intended. "up" does not — no combination of settings tried gave a clean result; the text ends up leaning back toward the pin rather than clearly above it. It still works electrically (ERC has no complaint), it just doesn't look as clean.

Practical guidance: use "up" when you must (a pin genuinely on a component's own north/top edge, with no sensible alternative), but if a different direction is equally natural for a given pin, prefer it. This is an open problem, not a solved one — if you find a fix, it belongs in kicad_gen.py's own label() docstring and in DevelopmentStandard.org's Electronics section, not just in your own circuit's script.

A recurring, specific goal across this project's own schematic reviews: place a component so the pin it connects to is genuinely close by, ideally aligned in at least one axis so the wire between them is a single straight line, not a diagonal one that might cross something else.

The technique: before deciding where to put a new component, place the other end of its connection first, and look at that pin's own computed absolute coordinates (the dictionary place() already gave you). Then choose your new component's own placement so that, after accounting for its own rotation, its relevant pin lines up in X (for a vertical wire) or Y (for a horizontal one) with the target. Concretely, for a multi-pin IC with several real pins sitting on its own north/top edge: passives wired to those pins were each placed north of the IC, at the same X as the specific pin each one wires to — not south of it, which would have required each wire to travel down and back up, crossing the IC's own body on the way.

Two closely-related things to check afterward, since getting the wire straight doesn't guarantee everything else is fine:

• Two components can end up nearly on top of each other if you align both with two pins that are themselves very close together (a real, confirmed case: two capacitors wired to two pins only 2.54mm apart on the same IC ended up only 2.5mm apart themselves). Fix by staggering along the other axis — keep the alignment that gives the short, clean wire, but give the two components real separation in the perpendicular direction. See "Checking your own work" below for the specific check that catches this.
• A straight wire toward a neighbour can pass through unrelated pins if those pins happen to share the same coordinate on the axis your wire runs along — common on a multi-pin IC, where several pins along one edge share an X or Y value. If this happens, route with two wire segments instead of one straight line (see next section).

For a connection that can't safely be a single straight line — because something else sits between the two points — draw it as two (or more) separate wire() calls forming an L-shape (or a longer path), moving through an intermediate point that avoids whatever's in the way (see Listing 11):

reset_x, reset_y = u1["RESET"]
r1_x, r1_y = r1["2"]
sch.wire((reset_x, reset_y), (r1_x, reset_y))   # sideways first
sch.wire((r1_x, reset_y), (r1_x, r1_y))          # then straight down

There is no automatic obstacle avoidance in this language — you choose the intermediate point yourself, based on where you know the obstacle to be.

paper="A4" (297mm x 210mm) or "A3" (420mm x 297mm) in the Schematic(...) constructor. A4 is preferred for anything that reasonably fits — A3 was used briefly for an earlier, much more loosely-spaced layout and found unnecessarily large once spacing was tightened up. There is no automatic scaling or overflow warning — if a component or a label ends up past the page edge, KiCad will still happily export it (onto a second, mostly-empty page, or simply clipped depending on the export), so check this yourself (see "Checking your own work" below).

Never trust that a script ran without a Python error as evidence the result is correct — none of the checks below are optional, and each one has caught a real, previously-unnoticed bug at least once in this project's own history.

• Electrical correctness: make kicad-erc (or directly, kicad-cli sch erc --severity-all -o report.rpt file.kicad_sch) — read the actual violation count and each specific message, not just whether the command exits successfully.
• Wire-path collisions: two unrelated wires geometrically overlapping (not just sharing an intended endpoint) silently merges their nets, and ERC alone does not always make this obvious at a glance. A short script comparing every pair of drawn wire segments for this is worth keeping and re-running after any layout change — see ResearchJournal.org, 2026-08-03 entries, for a working example.
• Label coordinate collisions: two differently-named labels landing on the exact same point is a related, separate check.
• Component-body overlap: ERC has no concept of this at all — it is purely visual. Compare every pair of placed components' own coordinates directly; anything closer than roughly 12mm is worth a second look (found a real case at 2.5mm apart this way).
• Page bounds: sum up every placed coordinate (symbols, wires, labels, text — but skip the lib_symbols block itself, which is full of unrelated internal symbol-definition coordinates that have nothing to do with where things actually ended up on the sheet) and confirm the range fits inside the paper size with a reasonable margin.

None of these are built into this language automatically — they are separate, small scripts written and refined over this project's own history of finding bugs the hard way. Treat them as a checklist to run after any change, not a one-time thing done once and never repeated.

Stated directly, since it would be easy to assume otherwise after reading this far: this is a tool for describing what connects to what, plus enough manual control over position and routing to produce something reasonably clean. It does not automatically:

• lay out a whole circuit well on its own when hand-written — every position in a hand-written circuit script is exactly whatever was typed, chosen deliberately by a real, iterative review process, not computed by an algorithm (that's kicad_layout.py's own, separate job – see "The role this language plays in the larger toolchain" above);
• avoid every possible wire crossing or component overlap on its own — the checks above catch problems, they do not prevent them from being possible in the first place;
• check your circuit's own electrical design is correct (only that it's wired the way you told it to be) — that's still on you, the datasheet, and ERC's own rule set.

General-purpose, always-correct automatic schematic layout remains, as far as this project's own research has found, an unsolved problem in EDA tooling generally — not a gap specific to this small language. Expect to keep using the checklist above, and expect a genuinely new circuit's first layout attempt to need at least one further round of review.