A custom mechanical keyboard built from scratch for Hack Club Keeb YSWS.
qbMX is a fully custom mechanical keyboard designed in KiCad and Fusion. It features:
- 85-key (79+6) layout with a rotary encoder, modelled after Apple's Magic Keyboard.
- Cherry MX Low-Profile Red switches, and on-plate stabalisers (instead of on-pcb)
- Uses the RP2040 microcontroller (Orpheus Pico)
- A 0.91" 128x32 OLED display
- 15 mini-LEDs at the top of the keyboard
- Custom PCB, ordered and assembled by me
I wanted to learn about and build a keyboard myself, since I'd never done it before. Designing the matrix and optimising GPIO lanes with functionality was a cool challenge. Oh, and I just wanted a keyboard; and Keeb gave me an excuse to make it.
| Path | Description |
|---|---|
keeb.kicad_sch |
Schematic |
keeb.kicad_pcb / keeb.kicad_pro |
KiCad PCB layout & project |
pcb/ + pcb.zip |
Gerbers & drill files (F.Cu, B.Cu, silkscreen, mask, Edge.Cuts) |
*.step |
3D models (board, OLED, rotary encoder, plate) |
key-switches.pretty/, extra_key.pretty/ |
Footprint libraries |
readme-library/ |
Photos & renders |
bom.csv |
Bill of materials |
After building all physical hardware, download the firmware folder then:
export PICO_SDK_PATH=/path/to/pico-sdk
cd firmware && mkdir build && cd build
cmake .. && makehold BOOTSEL on the Pico, plug in the USB and drag qbmx.uf2 to the mass storage device.
OLED Shows 5 pages: 0. Current keyboard layer
- Custom text/bitmap
- LED mode + brightness
- WPM counter with bar graph
- Host temps (CPU avg, GPU avg, Pico internal temp)
For temperature tracking to work properly,
- Install pyserial
pip3 install pyserial- Run host script which auto-detects the Pico port
python3 firmware/host_temp.pyNote: osx-cpu-temp will return 0.0°C on Apple Silicon Macs without SMC entitlements; where the OLED will show N/A in this case. You may instead compile
osx-cpu-tempfrom source or usesudo powermetrics.
By default they are mapped to F13-F18 (USB HID keycodes 0x68 -> 0x6D), which is recognised by every major OS. It can be remapped in system settings.
Other functions include: Short press rotary encoder to pause, Long press rotary encoder to toggle between volume and brightness (backlight) mode
See JOURNAL.md.
See bom.csv.
- Hack Club Keeb for the program
- siderakb/key-switches.pretty and eblaster/marbastlib libraries
- GrabCAD models switch, encoder, OLED
- Github models keycaps