Multi-board systems

A system joins several KiCad projects (a main board, a sensor board, a display) into one product: which connectors mate, which cables run between them, where each board sits in the enclosure. It is a system.kicad_sys.json file (any *.kicad_sys.json, validated by schemas/kicad-sys.schema.json) next to the projects or a folder or two above them. The sample is examples/system-sample (a main board and a sensor board joined by a six-wire cable).

The System panel (right side, in both editors) lists the boards with their layers, placement and variant, and the connector mates with their status (“6/6 pins · ok”, “7 vs 6 pins”). Its buttons: Add board (a .kicad_pro), Mate connectors (two connectors, directly board to board or through a cable), New cable, System schematic, System ERC and Open 3D assembly. The Project view shows a System node under each project that belongs to a system, with its boards and the system schematic.

System schematic. system.kicad_sch draws each board as a hierarchical sheet whose sheet pins are its connector pins (J4.1, J4.2, …); wires between sheet pins are cable wires. Edit it in either editor or in KiCad: when it is saved the wiring updates the system file. A connector’s pin map comes from its symbol: Sys.Pin<n> fields (SDA, bidi, 3.3V), else the pin names and nets; Sys.Voltage sets a connector’s voltage domain and Sys.Mandatory marks pins that must be connected.

Each board’s sheet file is a generated proxy (system-boards/<board>.kicad_sch, do not edit): one pin-only symbol per connector (reference #SYS_J4, out of the BOM, the board and simulation) with its hierarchical labels on the symbol’s pins, and a no-connect flag on pins that no wire reaches. Next to the system sheet the Electronics Designer writes the symbol library of these symbols and the cable symbol (system-boards/SoftForge_System.kicad_sym), adds its row to the folder’s sym-lib-table (an existing table keeps its other rows) and writes a minimal system.kicad_pro when there is none. kicad-cli sch erc system.kicad_sch then reports only what is really open: on the sample, the spare pin J4.7 of the 7-pin header that the 6-wire cable leaves unconnected (no label_dangling, no lib_symbol_issues).

System ERC (the System group in the Checks tab, markers on the system schematic, Problems on the system file) checks the connections between boards: pin counts per mate (an error when direct, a warning through a cable), output against output, power against ground, unconnected power, ground and mandatory pins, voltage domains that differ, and duplicated or missing connectors.

3D assembly. Open 3D assembly places every board’s 3D model (exported by kicad-cli and cached in .edsnx/system-glb/) at its placement. Drag the gizmo to move or rotate a board, Snap on connector seats a board on its mate, Clash check reports overlapping parts (red markers), and Export writes the assembly as one glb or as STEP. A board with a variant in the system file is exported with that variant’s DNP parts left out.

The clash check works on volumes: after the surface test (triangles that cross) it reports a part that lies entirely inside another body, such as a board sunk in an enclosure wall or a part inside another part (“inside” in the message, contained: true on the pair from edsnx system assembly clash). Containment is decided by ray parity, so it needs a closed mesh around the volume (every edge shared by two triangles; the kicad-cli board and footprint meshes are). A board in the cavity of a hollow enclosure is outside the enclosure’s volume and is not a clash.

STEP. With the OCCT add-on installed, Export STEP (and edsnx system export --format step) writes a B-rep STEP: each board’s STEP from kicad-cli placed by its placement, plus the enclosure (a STEP enclosure as it is, a mesh enclosure as a faceted STEP). Without the add-on it writes a faceted STEP from the meshes instead: AP214, one assembly product with one product per board and one for the enclosure, each part (the PCB with its copper, each footprint) a FACETED_BREP solid of planar triangles when its mesh is closed, else a surface model; the placements are applied. It opens in FreeCAD and other OCCT-based tools; it has no curved surfaces and no colours, and a board without a glb (no kicad-cli) is written as its outline box. --faceted forces it even with the add-on.

Enclosure (assembly.enclosure in the system file, --enclosure on the clash check and the STEP export): a .glb (metres, y up, like a kicad-cli export), an .stl, or a STEP. A faceted STEP (faces bounded by POLY_LOOPs, such as the faceted STEP above or a mesh export from a CAD tool) is read without the add-on, in millimetres, z up, assembly transforms of the file not applied; assembly.enclosurePlacement places it. A B-rep STEP (curved faces) needs the OCCT add-on to tessellate it; without it the check names the add-on and tests the boards only, so export the enclosure from the CAD tool as glTF (.glb), STL or a faceted STEP instead.

Harness. The Harness panel shows the from-to table (cable, from board.J.pin, to board.J.pin, signal, colour, gauge, length); Harness sheet writes a documentation sheet with the table and the cable BOM, CSV the table for a spreadsheet.

edsnx system new --boards main/blinky.kicad_pro,sensor/sensor.kicad_pro
edsnx system erc examples/system-sample/system.kicad_sys.json
edsnx system harness examples/system-sample/system.kicad_sys.json --out doc/harness.pdf
edsnx system assembly clash examples/system-sample
edsnx system export examples/system-sample --format glb --out out/assembly.glb
edsnx system export examples/system-sample --format step --out out/assembly.step --enclosure case.stl

Limits: without the OCCT add-on the assembly STEP is faceted (planar triangles, no colours), and a B-rep STEP enclosure cannot be read (export it as glb, STL or a faceted STEP); containment in the clash check needs closed meshes; the 3D view’s clash check covers the boards only (the enclosure is checked by edsnx system assembly clash).