eepyBoard/README.md

# The eepyBoard

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

## Versions

- **eepyBoard v1.0: Hardware revision 1**
    - Mostly ortholinear layout with 13 columns (73 keys + rotary encoder)
    - 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

- **eepyBoard v1.1: Hardware revision 2**
    - Column staggered split layout (single board) with a total of 15 columns and 6 rows (88 keys + 2 rotary encoders)
    - Each side has 7 columns by 5 rows (not counting function keys and arrow keys)
    - Bottom row: three regular keys + four thumb keys on each side, and an additional centered thumb key
    - Full F-key row (Esc, F1-F12)
    - 4 arrow keys in the center
    - 2 pressable rotary encoders (one in the center of the keyboard, one in the upper right)
    - Compact RP2040 "Pico Mini" controller board in the center

- **eepyBoard v1.2: Hardware revision 3**
    - Mostly ortholinear layout with 14 columns (81 keys + rotary encoder)
    - Bottom row with regular keys, thumb keys and a 1.5u space key
    - Full F-key row (Esc, F1-F12) and rotary encoder
    - Compact RP2040 "Pico Mini" controller controller board in upper right corner

## Repository structure

- `/layouts`: Keyboard layouts created with the [Keyboard Layout Editor](http://www.keyboard-layout-editor.com)
- `/ergogen`: [Ergogen](https://docs.ergogen.xyz/) files to generate outlines, cases and PCBs
- `/kicad`: KiCad PCBs and generated files
- `/3d_prints`: 3D models for the enclosure
- `/qmk_keyboards`: [QMK](https://qmk.fm/) 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/revN/eepyboard_revN.kicad_pcb` (replace `revN` with the current revision).

#### Routing and finalizing the KiCad files

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

1. Round off the bottom corners of the board outline:
    - Remove the bottom center line and the two small fillet arcs next to it.
    - Select the two remaining bottom lines. Right click them and use "Shape Modification -> Extend Lines to Meet".
    - Right click the two angled lines again. Use "Shape Modification -> Fillet Lines..." with a 200mm radius.
2. 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.
3. 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.
4. 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.
5. Add another filled zone on the `B.Cu` layer and assign it to GND.
6. 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.
7. 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.
8. 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.
9. Fill all zones by pressing B. Make sure that all nets are routed.
10. 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/`.
    - 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/revN/gerber/`.
    - No subdirectories, only files.
    - Ideally name the file `kicad/revN/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](https://docs.qmk.fm/#/cli) 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](http://www.keyboard-layout-editor.com)
- [Ergogen](https://docs.ergogen.xyz/), [unofficial Ergogen web UI](https://ergogen.ceoloide.com/)
- [KiCad](https://www.kicad.org/)
- [Onshape](https://www.onshape.com/)
- [UltiMaker Cura](https://ultimaker.com/software/ultimaker-cura/)
- [QMK](https://qmk.fm/)

## Resources

- [FlatFootFox's Ergogen tutorial](https://flatfootfox.com/ergogen-introduction/)
- [QMK documentation](https://docs.qmk.fm/)