Gemini panel

keyboards

Schematics, pcbs, layout files for all my keyboard projects

Structure

• design/ — original keyboard designs, one folder per board with layout/ (KLE, keymap, VIA), pcb/ (KiCad), case/ (3DP CAD), and firmware/ (QMK/VIA builds) inside
  • gemini/ — split staggered 40% that docks into a regular 40%
• commissions/ — VIA/layout files for boards built for others
• docs/ — GitHub Pages site with interactive design docs, deployed by .github/workflows/pages.yml on every push to main that touches docs/ (one-time setup: Settings → Pages → Source → GitHub Actions)
• tools/release/ — kb_release.py, the release bundler (see below)

Releases

Every merge to main that touches design/<board>/ publishes a GitHub release for that board: .github/workflows/release.yml. Each release is a manufacturing bundle — a self-contained snapshot of one version, so a fab house or a future me can build the board from a single download without checking out the repo:

• layout/ — KLE, keymap, VIA
• pcb/ — the KiCad projects, footprint library, placement CSVs, generators
• pcb/fab/<project>-gerbers.zip — gerbers + Excellon drill, plotted by kicad-cli at build time; this is the file you upload to JLCPCB/PCBWay
• pcb/fab/<project>-bom-jlc.csv, -cpl-jlc.csv — BOM and placement in JLCPCB's column format; -bom-pcbway.csv carries MPNs for PCBWay
• pcb/fab/<project>-cpl.csv, -drc.json — KiCad's own placement export (everything else is derived from it) and the DRC report as built
• ASSEMBLY.md — what gets machine-placed, what's fitted by hand, and the DFM checks to clear before ordering assembly
• case/stl/, case/step/ — case pieces
• firmware/ — QMK/VIA definitions and any built images
• MANIFEST.json, SHA256SUMS, RELEASE.md

Some of that duplicates the repo, deliberately: a release pins each file to the version it was built with.

Versioning

Semver per keyboard, held as <board>-v<x.y.z> git tags — gemini-v0.2.1 is independent of any other board. First release of a board is 0.1.0.

Building a bundle locally

python3 tools/release/kb_release.py bundle --board gemini --version 0.1.0
# → dist/gemini-v0.1.0/ and dist/gemini-v0.1.0.zip

Needs kicad-cli on PATH (or KICAD_CLI set) for the gerbers; pass --skip-pcb for a source-only bundle. Only files tracked by git go in, so venvs and KiCad backups never leak into a release.

Assembly (PCBA) files

The boards are script-generated and have no schematic, so the BOM can't come out of KiCad. design/<board>/pcb/parts.csv is the source of truth instead: one rule per part, matched against every footprint on the board at release time. A footprint that matches no rule fails the build rather than quietly vanishing from the BOM — which matters here, because the switch footprints carry keycap legends (T, Space) in their Value field and a naive value-based BOM would list 22 one-off parts instead of 43 sockets.

Rules also mark parts hand (the Pico, which sits on headers and can't be machine-placed) so they stay out of the BOM and CPL but still get written up in ASSEMBLY.md, and carry a per-part rotation offset for parts whose orientation in JLCPCB's library differs from the footprint's.