# eepyBoard Prototype

Prototype for the [eepyBoard](https://git.0xbd.space/binaryDiv/eepyBoard), which is going to be a custom ergonomic
mechanical keyboard with low-profile (Kailh Choc) switches.

This prototype is a simplified split keyboard to find out the optimal distance and rotation for the actual eepyBoard,
which is going to be a singular/non-split keyboard with a split layout.

## 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/protoeepyboard.kicad_pcb`.
Copy the file to `kicad/protoeepyboard.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. (Optional) 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. Route all signal traces.
3. Run the Design Rules Checker and make sure there are no (relevant) violations.
4. Add some fancy text on the `F.Silkscreen` layer.

#### 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 `protoeepyboard_{REVISION}.zip`.
4. Upload zip file to manufacturer and make sure everything is correct.
5. Add all generated files to version control (the zip should be on gitignore).

### 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 either by
pressing the reset button on the backside of the keyboard, or by using the `QK_BOOTLOADER` keycode (TODO: where is the
keycode mapped to on the protoEepyBoard?).

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.cache.works/)
- [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/)