Initial commit

.gitignore

@@ -0,0 +1 @@
+todo.md

README.md

@@ -0,0 +1,35 @@
+# Tern
+
+Terns are small white seabirds that can hover, but it's also a 30-key keyboard based on the [Hummingbird](https://github.com/PJE66/hummingbird)! Differences from the Hummigbird:
+
+* Hot swappable
+* Spaced for Chosfox CFX keycaps (tighter than normal choc spacing)
+* Pinky keys are dropped down
+* Thumbs are more reachy
+
+![tern_top](images/tern_top.jpeg)
+
+I much prefer reachy thumbs vs tucky thumbs. Years of wiping out on skateboards means my right thumb doesn’t really make that tucking motion anymore.
+
+The other deviation from the hummingbird is that I’m using the upper pinky key as my homerow. I’m using my pinky column as home and bottom rows, not top and home rows like the hummingbird does. Cognitively I like the hummingbird’s solution better, but after cutting a stack of cardboard prototypes, I just had to admit to myself that my pinky does not enjoy extending upwards.
+
+## Case
+
+![tern_quarter](images/tern_quarter.jpeg)
+
+![tern_back](images/tern_back.jpeg)
+
+There are laser cutting files for a case in `case`. The switch plate is made from 1/16" acrylic, and there is a 0.6mm silicone gasket sitting between it and the PCB. I don't actually think the switchplate does anything functional but it looks more finished. There is a file for cutting a sheet of self-adhesive foam for the back which really helps to dampen the sound. I used 1mm sticky backed EVA. 
+
+## Firmware
+
+This uses an identical matrix to the Hummingbird, so you can just lie to your firmware and tell it that it's a Hummingbird. As I mentioned, though, since I dropped the pinkies and use them as home-bottom, using the stock Hummingbird config will make your keymap look a bit strange. I've included a config for ZMK in `firmware/zmk` that tweaks the matrix mapping to allow your keymap to reflect the actual position of the keys.
+
+## Build Guide
+
+[Build guided and bill of materials are here](docs/build_guide.md)
+
+## Thanks
+
+* [Hummingbird](https://github.com/PJE66/hummingbird) for the original idea and matrix
+* [Rufous](https://github.com/jcmkk3/trochilidae) for the basis of the Ergogen config and routing

docs/build_guide.md

@@ -0,0 +1,80 @@
+# Tern Build Guide
+
+This is a very standard build, the only gotcha is that the key spacing is only for ChosFox CFX keycaps. MBK keycaps will not work, they're too wide.
+
+## Parts List
+
+### Required Parts
+
+| Description          | Quantity | Notes                                                    |
+| -------------------- | -------- | -------------------------------------------------------- |
+| Tern PCB             | 1        | See gerbers.zip                                          |
+| Seeed XIAO           | 1        | You can use either the BLE version or the RP2040 version |
+| Choc hotswap sockets | 30       |                                                          |
+| 1N4148W Diodes       | 30       | SOD-123 surface mount package                            |
+| Choc v1 switches     | 30       |                                                          |
+| Chosfox CFX keycaps  | 30       |                                                          |
+
+### Optional Parts
+
+| Description        | Quantity | Notes                                                        |
+| ------------------ | -------- | ------------------------------------------------------------ |
+| Controller sockets | 2        | Supports Mill Max sockets such as 315-43-114-41-001000 and also supports Peel-A-Way super duper low profile sockets |
+
+### Case Parts
+
+| Description           | Quantity | Notes                                                        |
+| --------------------- | -------- | ------------------------------------------------------------ |
+| Top plate             | 1        | 1/16" acrylic, see `case/switch_plate.pdf`                   |
+| Top gasket            | 1        | 0.6mm silicone sheet, such as silicone placemats from [Amazon](https://www.amazon.com/dp/B088LKLSTG), see `case/top_gasket.pdf` |
+| Controller cover      | 1        | 1/8" acrylic, see `case/mcu_cover.pdf`                       |
+| Bottom foam           | 1        | 1mm self-adhesive EVA foam                                   |
+| M2 6mm screws         | 6        | Four for the controller cover, two for the top plate         |
+| M2 thin nuts          | 2        | For the top plate                                            |
+| M2 8mm standoffs      | 2        | For the controller cover                                     |
+| 6mm x 2mm bumper feet | 10       |                                                              |
+
+## PCB Assembly
+
+I assembled it in this order:
+
+- Hotswap sockets
+- Controller sockets
+- Diodes
+
+## Firmware
+
+Electrically-speaking, this keyboard is a Hummingbird, so you can treat it just like the Hummingbird to compile your keymap. I know ZMK has Hummingbird support baked in, not sure about QMK (presumably it does too).
+
+However, I use my pinky columns as "home-bottom" rather than the Hummingbird's "top-home." If you are like me, then your keymap will look a bit strange using the hummingbird's config because the pinky column will have to be shifted up one row in the keymap file. If this bothers you, then you can use the tern shield definition in this repo to correct that, so the location of the keys in your keymap will match their location in physical space. This config is literally identical to the Hummingbird config in the ZMK repo, except that I changed the mapping of the matrix in the overlay.
+
+```shell
+# Copy the contents of firmware/zmk to your zmk-config/config/boards/shields/tern
+cp -R ./firmware/zmk /path-to/zmk-config/config/boards/shields/tern
+# Copy the default keymap into your config directory to get started
+cd /path-to/zmk-config/config
+cp boards/shields/tern/tern.keymap .
+touch tern.conf
+```
+
+## Case
+
+### Laser Cutting
+
+The case is optional and intended to be laser cut. The order of assembly should be as follows
+
+- The switchplate is purely cosmetic but looks nice, and should be laser cut from 1/16" acrylic.
+- Silicone gasket should be cut from 0.6mm silicone sheet, I use placemats from Amazon
+- Controller cover can be cut from whatever you like, I use 1/8" acrylic
+- Bottom foam should be cut from 1mm self-adhesive EVA foam. You can also use 2mm if you prefer but it will extend slightly below the hotswap sockets. When laser cutting, the adhesive side should be facing down.
+
+## Assembly
+
+1. Remove the switch holes from the silicone gasket. These are held in place by tiny little tabs to keep them from blowing around and getting into mischief during laser cutting. Just gently pop them off with your fingers.
+2. Lay the gasket on the PCB
+3. Place the switchplate on
+4. Gently attach the switchplate to the PCB with a 6mm M2 screw and a low profile nut on the underside. If you are using the `v0.1` PCB, I forgot to metal plate these mounting holes on the PCB, so be gentle when you tighten this nut. (I'll fix this in `v1`.) It doesn't need to be super tight, it's really there just to register everything in the right place.
+5. Install the switches. Sometimes the switch plate fitment can be a bit tight. Just go easy and they will all click in.
+6. Install the controller cover
+7. Flip it over, and carefully install the bottom foam. Use the hotswap sockets as a guide to register it in place.
+8. Finally, install the 6mm x 2mm clear bumpon feet, using the bottom foam's circular cutouts to locate them.

ergogen/bin/ergogen

@@ -0,0 +1,21 @@
+#!/bin/sh
+
+# Usage: exposes a Docker container as if it was the ergogen command itself.
+# Any arguments passed to this script will be passed through to ergogen.
+#
+# If the image isn't built, it will build one.
+
+PATH_TO_DOCKERFILE=../container # Relative to this script
+IMAGE_NAME=ergogen-v4
+
+SCRIPT_DIR="$( cd -- "$( dirname -- "${BASH_SOURCE[0]:-$0}"; )" &> /dev/null && pwd 2> /dev/null; )";
+
+# Check if image exsists and build one if it doesn't
+docker image inspect $IMAGE_NAME >/dev/null 2>&1 && true || \
+  docker build -t $IMAGE_NAME $SCRIPT_DIR/$PATH_TO_DOCKERFILE
+
+docker run \
+  --rm \
+  --mount "type=bind,src=$(pwd),dst=/workdir" \
+  --workdir '/workdir' \
+  $IMAGE_NAME "$@"

ergogen/bin/rebuild

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+SCRIPT_DIR="$( cd -- "$( dirname -- "${BASH_SOURCE[0]:-$0}"; )" &> /dev/null && pwd 2> /dev/null; )";
+
+$SCRIPT_DIR/ergogen . && open output/pcbs/tern.kicad_pcb