Repository navigation
Circuit Boards
A circuit board marks out the keys sharing one physical board; a split keyboard needs two.
A board is its keys. It has no rectangle of its own and is always drawn
around whatever is on it, standing offset clear. It can't be resized;
dragging its outline moves every key on it; and a board that loses its last
key is gone. Boards stay visible in every mode, dimmed outside Circuits, but
are only editable there. In the code and the save file a board is a pcb.
P, or Add to new board, builds a board around the current selection —
the only way to make one. After that, the key panel's Circuit board
picker does everything: it lists every board plus — none —, so setting,
clearing and moving keys across are one edit. A rotation group always goes as
one piece.
Two boards never overlap: an edit that would overlap them is refused outright, and dragging a board into another stops it dead. Touching is fine. Creating one is the exception — a new board drawn over an existing one slides clear along whichever axis needs the least travel, keys and all, and only rolls back if nothing within about twenty units fits. Key drags in Keycaps mode are deliberately never blocked, so a layout change can push two boards together, and it's on you to pull them apart.
A board is never in two pieces. Drag a key well away and the board grows a neck to reach it rather than splitting — at least 1u wide, matching the board's offset where that is wider. A hole fully enclosed by keys is a real feature and survives untouched.
Click a board's outline to select it — it doubles in weight under the pointer
and turns solid and accented once selected. Selecting opens a second
properties panel above the key panel; boards and keys select separately and
can both be selected at once. Clicking gathers several, the same additive rule
keys follow; ⇧‑click narrows to one. Space, Esc, the panel's close button,
or leaving Circuits mode drops the selection.
Dragging the outline moves the board and everything on it; a press that releases without moving selects instead. A move that would collide simply doesn't advance. Hovering reveals two handles: close at the top‑left and options at the top‑right, which opens the board's four exports.
⌫ removes every selected board as one undo step, releasing its keys rather than deleting them. Clicking the panel's title — with exactly one board selected — renames the board; a colliding name gets " 02", " 03", … appended. New boards are named "Circuit board 01", "02", …
| Rectangular | The bounding box of the board's keys |
| Cutout | An outline that follows the keys themselves |
Offset is how far the outline stands off the keys, in whole 0.25u steps (up to eight); a new board starts at one, and zero hugs the keys. It applies to both shapes.
A cutout follows the 0.25u grid rather than a keycap's own edge, punches out enclosed gaps as holes, and can carry diagonal edges: each rotated group is traced square‑on in its own frame and turned back onto the main grid, then all the pieces are boolean‑joined into one shape.
A board also carries these sidebar properties, shared across the selection or Mixed where it disagrees:
| Controller | Pro Micro, Elite-C, RP2040, nice!nano, or Other… for free text — independent per board, even when two are linked |
| Hotswap | Sockets rather than soldered switches |
| One diode per switch | Off zeroes the BOM's diode count rather than assuming it silently |
| Backlight / underglow | Whether the board carries that footprint |
| Stabilizers | Screw-in, snap-in, or plate-mounted — unset by default |
A row or column is a set of keys wired to the same matrix line — nothing else. Like a board it carries no geometry, and it belongs to exactly one board, since two switches on different boards can't share a net.
Add to new row / Add to new column wire the selection together, replacing whichever row or column each key was already on. Both need the selection to sit on exactly one board. The Row/Column dropdowns then move keys onto, off (— none —), or across to another, listing only lines on the selection's own board; the × beside each is a one‑click — none —, which works even across boards. A row or column with no members left dissolves.
Assigning a row or column touches only the selected keys, never the rest of a rotation group — a cluster turned 15° can easily cover two real columns.
The demo keyboard (D) arrives already wired, which is the quickest way to see
this: one matrix row per keyboard row, one column per 1u position, 6 × 22. That
is the same matrix the export would have guessed from the geometry — wiring it
changes no nets, it changes the export from reporting a matrix it inferred to
one a person confirmed. Folding it narrower was tried and dropped: a full‑size
board is 22.5u wide, so the tightest matrix that keeps the rows physical is
6 × 21, and buying those six positions costs every column its straight line.
Rows draw in one colour and columns in another, on top of the keys, through each member's true centre in reading order, stopping a little short of each so crossing lines never merge. A small number past each line's start names it. Circuits mode only.
This is what KiCad export reads first.
The USB connector has a physical location, so it's a marker on the board's perimeter rather than a sidebar field. Place USB connector drops one halfway round the perimeter; drag it anywhere along the outline afterwards, around corners and onto different edges. It follows the real outline, including a cutout's diagonal edges, and lies at each edge's own angle. Its position is stored as a 0–1 fraction of the perimeter, so it survives the board reflowing. Once placed, a USB-C / Micro-USB picker appears beside it. Remove clears it; no marker is a valid state, since a board with no controller has no port of its own.
Select two or more boards and Link boards appears in the board panel. Linking draws a line between them — a chain, for more than two — clipped to each board's edge, with a badge at its midpoint naming the connector: a wifi glyph for Wireless, "TRS"/"TRRS" for the wired options. Linking boards already linked reuses that link rather than duplicating it.
The line is clickable, and selecting one opens its own panel with the two board names, the Connector picker, and Unlink. Unlike the key and board selections, a link selection replaces both. The same Link section appears on a linked board's panel, reading and writing the same data, so changing the connector anywhere updates everywhere.
A board linked over Wireless also gains a Battery section — a presence toggle and a free‑text capacity. An unlinked board's power question isn't modelled yet.
A board's options handle opens a menu of four exports. None of them tries to be the tool it feeds: the DXFs are shapes for a vector editor or laser cutter, and the KiCad file is placement and a netlist, not routing.
| Item | File | What it is |
|---|---|---|
| PCB DXF | control-function-pcb-<id>.dxf |
The perimeter alone, one closed polyline per loop |
| Plate DXF | control-function-plate-<id>.dxf |
The same perimeter plus a cutout at every key, on a second layer |
| KiCad | control-function-<id>.kicad_pcb |
The outline on Edge.Cuts, a switch and diode footprint per key, every pad on its net |
| BOM | control-function-bom-<id>.csv |
A parts list |
Geometry is written in millimetres at 19.05 mm per unit — the only place the editor's abstract unit becomes a real dimension.
The BOM lists switches, rotary encoders, diodes (one per switch, unless that's turned off), keycaps grouped by size and shape, and stabilizers grouped by width for every key 2u or wider or shaped like an Enter.
Both DXFs are R12. They measure y upward where the editor measures it downward, so a board comes out mirrored about its own height, bottom‑left corner on the origin. A switch cutout is a plain 14 mm square, turned to match a rotated group and independent of the keycap on top of it; a knob gets a 7 mm circle for an EC11's bushing.
The KiCad file carries a plain Cherry MX footprint and a through‑hole diode on the classic 7.62 mm pitch below its switch. Nets run column → switch → diode → row, QMK's default COL2ROW direction. Knobs, the controller and the connectors are skipped rather than guessed at.
A switch's nets come from what you assigned, ahead of any guessing. Anything unassigned falls back to binning switches onto the layout's own 1u pitch — exact for an ortholinear board, close for a row‑staggered one, and unreliable for a column‑staggered split, which is the reason to assign by hand. An unassigned switch never joins an assigned net just for sharing a coordinate. A board mixing the two exports with a toast saying so — some rows/columns still guessed, check nets.