The eepyBoard

Custom ergonomic mechanical keyboard with low-profile (Choc) switches.

Versions

• eepyBoard v1.0: Hardware revision 1
  • Mostly ortholinear layout with 13 columns
  • Bottom row: two regular keys + four thumb keys (per side, symmetrical)
  • Partial F-key row (Esc, F1-F8) and rotary encoder
  • RP2040 controller board in upper right corner

Repository structure

• /layouts: Keyboard layouts created with the Keyboard Layout Editor
• /ergogen: Ergogen files to generate outlines, cases and PCBs
• /kicad: KiCad PCBs and generated files
• /3d_prints: 3D models for the enclosure
• /qmk_keyboards: QMK keyboard files to compile and flash the QMK firmware

How-to

Generating the PCB

The KiCad PCB files are generated using Ergogen. Then they need to be manually routed and finalized in KiCad before they can be exported as Gerber files and send to a PCB manufacturer.

Generating KiCad files with Ergogen

To generate the KiCad PCB file with Ergogen, first install Ergogen using npm: npm install.

Then, run npm run ergogen. You can find the KiCad file in ergogen/output/pcbs/eepyboard.kicad_pcb. Copy the file to kicad/eepyboard.kicad_pcb.

Routing and finalizing the KiCad files

Open the file in KiCad (create a project if non exists yet). Finalize the PCB in KiCad.

1. Run the Design Rules Checker. Check the errors. Most of them can be ignored/excluded.
   • All "Footprint not found in libraries" can be ignored completely. This is due to how Ergogen generates the PCB.
2. Add VCC and GND planes.
   • Menu: File -> Board Setup
   • On "Physical Stackup", change the copper layer number to 4.
   • On "Board Editor Layers", change the type of In1.Cu and In2.Cu to "power plane".
   • NOTE: In1.Cu will be the VCC plane, In2.Cu will be a GND plane.
3. Add filled zones to the VCC and GND planes.
   • Select the In1.Cu layer.
   • Use the "Add a filled zone" tool and draw a rectangle that contains the entire board. Assign the zone to VCC.
   • Repeat the same process for the In2.Cu layer and assign the zone to GND.
   • The zones don't need to be filled just yet.
4. Add another filled zone on the B.Cu layer and assign it to GND.
5. Route all signal traces (no VCC or GND yet). Recommended order:
   • Matrix rows (on B.Cu)
   • Matrix columns (with vias on F.Cu)
   • NeoPixel data pins
   • Connect everything to the MCU.
6. Route VCC traces.
   • Connect the VCC traces between the NeoPixel chips and the capacitors with a 0.750 mm track.
   • Place free-standing vias (Ctrl+Shift+V) in the middle of the just created VCC traces.
7. Route GND traces.
   • Draw short GND traces with a 0.750 mm track and a via at the end next to the GND pads of the NeoPixel chips.
8. Fill all zones by pressing B. Make sure that all nets are routed.
9. Run the Design Rules Checker and make sure there are no (relevant) violations.

Export Gerber files

Now you can generate the gerber, drill and map files.

1. Generate Gerber files.
   • Menu: File -> Fabrication Output -> Gerbers
   • Select plot format Gerber.
   • Set output directory to gerber/rev1/ (adjust for current revision).
   • Set coordinate format to 4.6, unit mm.
   • Click Plot to generate files.
2. Generate drill and map files.
   • In the previous dialog, click Generate Drill Files....
   • Set drill file format to Excellon.
   • Set drill units to millimeters.
   • Set same output directory as above.
   • Click Generate Drill File, then Generate Map File
3. Create zip file with all generated files from kicad/gerber/{REVISION}.
   • No subdirectories, only files.
   • Ideally name the file kicad/gerber/eepyboard_{REVISION}.zip.
4. Upload zip file to manufacturer and make sure everything is correct.
5. Add all generated files to version control.

Compile and flash QMK firmware

To compile the QMK firmware, you first need the qmk CLI and a local copy of the QMK firmware.

1. Install the qmk CLI using your favorite package manager.
2. Run qmk setup to clone a local copy of the QMK firmware. (By default in ~/qmk_firmware, feel free to adjust.)

The firmware for this keyboard is compiled using the local copy of QMK and the keyboard definitions in qmk_keyboards which are automatically symlinked to your installed QMK firmware directory (defaults to ~/qmk_firmware, can be overridden by setting QMK_HOME in your environment). A Makefile is provided to simplify compiling and flashing.

To compile and flash the firmware, run make qmk-flash.

After compiling the firmware, you will be asked to put your keyboard into bootloader mode. This can be done in multiple ways:

• Hold the BOOTSEL button on the controller board while pressing the reset button (or while plugging in the cable).
• Hold the Escape key while pressing the reset button / plugging in the cable.
• Press the key combination that is mapped to the QK_BOOTLOADER keycode (currently Fn + Right Ctrl).

The RP2040 uses UF2 as the default bootloader. This bootloader works by emulating a USB storage device that the firmware file can be copied on. After putting the RP2040 into bootloader mode, you need to mount the USB storage device (doesn't matter where). For convenience, it is recommended to enable auto-mounting in your system, e.g. using udiskie.

You can also run make qmk-activate which will run qmk config to set user.keyboard and user.keymap to this keyboard. This allows you to use the qmk CLI directly without specifying the keyboard and keymap everytime.

Used software

• Keyboard Layout Editor
• Ergogen, unofficial Ergogen web UI
• KiCad
• Onshape
• UltiMaker Cura
• QMK

Resources

• FlatFootFox's Ergogen tutorial
• QMK documentation