Keyboard

ergogen-keyboard

Ergogen keyboard project, migrated to KiCad 8 with a local preview/edit app.

This repo contains the full keyboard definition: a split ergo board with a matrix, thumb cluster, rotary encoder and its own nice!nano controller per half. It is a wireless split (independent MCU on each half, e.g. ZMK). The numpad that used to live in the old heyjva/ergogen fork is not part of this repo.

Split layout: left + right

One config.yaml generates both halves as separate PCBs via ergogen's mirror:

• The points.zones.main / thumb zones carry a mirror: block, so ergogen emits mirror_* points for the right half.
• pcbs.main_left selects source points (where: -/mirror_/); pcbs.main_right selects mirror points (where: /mirror_/) and anchors positioned footprints to mirror_main_* refs.
• The right half's side-actuated power/reset switches get +180° rotation so their actuators face the mirrored board edge.
• Both halves share the same net names (P11..P21, P2, etc.). That is safe because they are separate PCBs / separate MCUs — the nets never physically connect across boards.

Ergogen writes output/pcbs/main_left.kicad_pcb and output/pcbs/main_right.kicad_pcb. The KiCad projects live in:

Build/regenerate a half's KiCad project from ergogen output:

node <ergogen> . -o output           # regenerate both PCBs
./kicad/build_kicad_project.sh right  # (re)build the right-half project
# ./kicad/build_kicad_project.sh left   # WARNING: wipes the routed left PCB

Contents

Footprints (KiCad 8)

The board uses these footprints from ceoloide/ergogen-footprints, vendored under footprints/ceoloide/:

• switch_choc_v1_v2 — Kailh Choc hotswap switches
• diode_tht_sod123 — per-key diodes
• mcu_nice_nano — nice!nano controller
• encoder_evqwgd001 — Panasonic EVQWGD001 rotary encoder
• battery_connector_jst_ph_2, power_switch_smd_side, reset_switch_smd_side, mounting_hole_plated

Keys/diodes/MCU/encoder are on the Back (B) side; the side-actuated power/reset switches are on the Front (F). Each half is non-reversible on its own; the split mirror is what produces the right half.

Wiring notes (important for firmware)

The matrix uses 7 columns and 4 rows:

• Columns: P21 P20 P19 P18 P17 P16 P15
• Rows: P14 P13 P12 P11

The nice!nano does not break out physical pins named P11, P12, P13, or P17. In config.yaml those logical nets are therefore routed onto spare physical nice!nano pins, and the nice!view SPI signals are assigned as follows:

The remaining matrix nets (P21 P20 P19 P18 P16 P15 P14) map 1:1 to the same-named physical pins. Update your firmware pin map to match the physical pins above. (In the original fork these four nets were never connected to the MCU — this project fixes that.)

3D models

The footprints are wired to reference 3D models but the model asset files are not included here. To see 3D renders in KiCad, drop the appropriate .step / .wrl files into models/ and point the footprints' *_3dmodel_filename params at them. 3D models do not render in the browser preview — only in KiCad.

Previewing & editing locally

The preview/edit app is a patched fork of ceoloide/ergogen-gui at heyjva/ergogen-gui. It runs a local web server and, unlike the stock GUI, includes a "Save to File" button that writes changes straight back to this repo's config.yaml — and it works in Firefox / Zen.

One-time setup

# clone both repos as siblings
git clone https://github.com/heyjva/ergogen-keyboard.git
git clone https://github.com/heyjva/ergogen-gui.git

cd ergogen-gui
npm install -g pnpm   # if you don't have pnpm
PNPM_CONFIG_BLOCK_EXOTIC_SUBDEPS=false \
  ERGOGEN_VERSION=github:ceoloide/ergogen#v4.3.0 \
  pnpm install --no-frozen-lockfile

Run it

cd ergogen-gui
./start.sh

This launches:

1. a tiny save-helper on http://localhost:3001 (writes config.yaml), and
2. the GUI on http://localhost:3000.

Open http://localhost:3000 in Firefox / Zen. The editor auto-loads this repo's config.yaml. Edit it, then click Save to File (or press Ctrl/Cmd+S) to write your changes back to config.yaml on disk. Commit with git as usual.

The save-helper is required because Firefox cannot write local files directly from a web page. It binds to 127.0.0.1 only and only ever writes this repo's config.yaml.

If you keep the repos somewhere other than as siblings, point the helper at the file explicitly:

CONFIG_PATH=/absolute/path/to/ergogen-keyboard/config.yaml ./start.sh

Regenerating outputs from the command line

The GUI is for previewing/editing. To regenerate the DXF/KiCad files on disk from config.yaml, run Ergogen v4.3.0 against this folder:

# from a checkout of ceoloide/ergogen at branch v4.3.0
node /path/to/ergogen/src/cli.js . -o output

This reads config.yaml + footprints/ and writes output/.

Complete KiCad project (schematic + PCB)

Ergogen only produces a .kicad_pcb (footprints + net connectivity, no schematic). The kicad/ folder contains a complete, openable KiCad project generated from that PCB:

Open kicad/keyboard.kicad_pro in KiCad.

About the schematic

The schematic is generated from the PCB's netlist (KiCad has no built-in PCB→schematic reverse). Each component is a real symbol laid out on a grid, and connectivity is expressed with global net labels on each pin (the standard approach for auto-generated keyboard schematics). It's electrically correct and ERC-readable, but laid out on a grid rather than hand-drawn — useful for verification, BOM, and reference, not a pretty hand-routed diagram.

Regenerating the KiCad project

Requires KiCad installed (pcbnew python module + kicad-cli):

# after regenerating output/ with ergogen:
./kicad/build_kicad_project.sh

Notes / expected DRC warnings

• Unconnected items: the PCB has nets but no routed traces (ergogen doesn't route) — route in KiCad. Not an error.
• invalid_outline from ENC1: the EVQWGD001 encoder footprint adds an Edge.Cuts roller cutout that reads as a secondary open contour. Harmless for the design; clean it up in KiCad's Edge.Cuts if desired.
• lib_footprint / lib_symbol warnings: footprints are embedded in the PCB and standard KiCad symbol libs are used; these "library not in config" warnings are cosmetic.

JLCPCB design rules

The project is pre-configured for JLCPCB's standard 2-layer, 1oz FR-4 process (their cheapest tier), so DRC catches anything they can't make:

• Numeric constraints live in kicad/keyboard.kicad_pro (board.design_settings.rules): min track/clearance 0.1 mm, min via 0.45 mm / 0.3 mm drill, min PTH drill 0.3 mm, min hole-to-hole 0.5 mm, min copper-to-edge 0.2 mm, min silk text 1.0 mm. These are JLCPCB's true standard-process minimums for 1oz 2-layer.
• The auto-router routes down to these limits (0.1 mm track/space, 0.1 mm hole-to-copper). That is manufacturable at JLCPCB but leaves little margin; the default net class uses a more comfortable 0.25 mm track / 0.1 mm space.
• JLC-specific checks (annular ring, edge clearance, hole-to-hole, silk width/height, silk-to-pad, SMD pad clearance) are in kicad/keyboard.kicad_dru. Note the via annular-ring rule is 0.05 mm: 0.45 mm-via/0.3 mm-hole is a standard no-extra-cost JLC via; the 0.13 mm annular guideline applies to component PTH pads, not tented vias.
• These files are not overwritten by build_kicad_project.sh (which only regenerates the .kicad_pcb/.kicad_sch), so the rules persist across rebuilds. The router's "Fix DRC settings after routing" option WILL rewrite the .kicad_pro constraints, so re-check them after routing.
• Source: https://jlcpcb.com/capabilities/pcb-capabilities

Run a rules check any time with:

kicad-cli pcb drc kicad/keyboard.kicad_pcb --severity-error