Porcupine is an autogenerated, ergonomic, split, 36-42 key, wired/wireless, columnar-staggered keyboard. It is designed to fit my needs and my hand, but it can be easily updated thanks to declarative design. It uses a ProMicro-compatible MCU board and supports both QMK and ZMK firmwares.
It is inspired by:
- [Ferris] Sweep keyboard
- rae-dux keyboard
- samoklava and its workflow
- all the work done by Ben Vallack on his Youtube channel
It is fully Open-Source: the KiCad files are released under the solderpad license, version 2.1. The software (scripts/config files) in this repository is released under the GPL.
- Autogenerated - PCB layout is declared using YAML config files and generated into PCB files using Ergogen tool (migrated to V4). Use my fork of it for added footprints.
- 3 variants:
- regular 5x3 column-staggered ortholiner layout with 3 thumb keys (36 keys total)
- regular 5x3 column-staggered ortholiner layout with 4 thumb keys (38 keys total)
- regular 6x3 column-staggered ortholiner layout with 4 thumb keys (42 keys total)
- Wired or wireless
- Low-profile (using Kailh Choc switches)
- Reversible PCB (save cost in production)
- Pro-micro/Elite C/Proton C/nice!nano support
- Hot-Swap support
- SplitKB Tenting puck support.
- uses KiKit to render PCB previews (see below)
- uses KiBot to run DRC, create Gerber and Drill files for production (and Interactive BOM and 3d renders just for fun)
| Front/Left | Back/Right |
|---|---|
| Porcupine | |
 |
 |
| Porcupine 4 thumb keys | |
 |
 |
| Porcupine 3x6 | |
 |
 |
| Prototype boards (generated using Ergogen v3 still): | |
 |
 |
| Porcupine working final prototype | |
 |
To build and use a Porcupine you will need:
- 1x PCB Kit
- 2x promicro compatible boards or 2 nice!nanos.
- 34-42 Choc V1 Low profile switches
- 34-42 Kailh Choc hot-swap sockets
- 34-42 diodes (SMD or THT)
- 34-42 keycaps
- 2x reset switches (optional; B3U-1000P(M))
- 4x 12x low profile female headers (optional; only if you want the microcontroller socketed)
- 48x Mill Max low profile socket pins (optional; socketed microcontroller; if you are using tht diodes you can use the legs of those diodes)
- Some little rubber feet/bumpers
- 2x power (On/Off) switches (optional; MSK 12C02)
- JST PH battery connector (wireless build; S2B-PH-K)
- Li-Po 110mAh battery (wireless build; 301230)
- 1x TRRS (not TRS!) cable (wired build only)
- 2x TRRS Jack [PJ-320A] (wired build only)
- 1 USB Cable (wired build; depends on your micro-controller choice)
Manually-routed PCBs for each variant are included in the output folder, so if they are fine for you, you can just take them directly, have them produced and then build.
For step-by-step instructions on assembling the keyboard, see the Porcupine build guide.
QMK firmware and keymaps - confirmed working with the prototype boards! 🎉
ZMK firmware and keymaps - confirmed working now as well! 🎉
If you would like to modify this:
- fork it
- (optionally, to see the 3d view of generated PCB in KiCad)
- copy 3d models from
3dmodels/ergogenfolder into your KiCad's installation${KICAD6_3RD_PARTY}/3dmodels/ergogen/folder1.
- copy 3d models from
- change
input/porcupine*.yamlto your liking - commit to Github
The associated Github Workflow action will then generate the PCB, 2D Images of the board and a whole KiBot package with Gerber/Drill files, Interactive Bom, images and renders. The files will be available as Workflow Action artifacts.
output/[board_name]/pcbs/ folder, the Workflow will pick it up and generate everything for it as well.
If you would rather do all that locally, then:
- install Ergogen:
npm install - install Docker
- generate PCBs:
npm run gen_pcb - generate images:
npm run gen_images - generate Kibot package:
npm run gen_kibot
Further:
- route the board manually in KiCad
- produce (for eample in JLCPCB or PCBWay)
- build
- load firmware
- use it!
- Kicad files are 6.0, so unfortunately not backwards compatible.
- If you're going for wired version or just want to skip out on the power switch, you need to solder the Jumper.
- Manually-routed boards are included, but there is no autorouting for generated boards.
- You need to have Docker installed to use
npm run gen_imagesornpm run gen_kibotto generate pcb images and Kibot bundle.
- a variant with MX switches
- automation of DRC/BOM/Gerber creation/validation with Github workflow
- proper 3d-printable cases
- LED support
The author(s) waive(s) responsibility for any damage or regulatory violations caused by using this hardware and software (see license). Please consult your local regulations around radio frequencies and what's allowed for DIY projects in your country.
Porcupine logo by @migorzka
Footnotes
-
The models are bundled here in the repository, but they are taken from KiCad directly, from keyswitch-kicad-library or are created by me. ↩