Skip to the content
4 layers100 × 142.5 mmKeeb4x4, the printed circuit board in 3D

4x4 macropad: STM32G431, per-key RGB, ScreenKey display keycaps, encoder. KiCad + Rust/Embassy firmware, USB bootloader, host CLI, printable base.

Size
100 × 142.5 mm
Copper layers
4
Thickness
1.6 mm
Parts
127
Nets
98
Pads
585
Tracks, vias
1,797, 302
Pours
4
Routed
Yes
KiCad
KiCad 10.0 (file 20260206)
Created
24 Oct 2026
Updated
24 Oct 2026

Overview

Keeb4x4 is an open-source printed circuit board by TheRealBluesun, from the TheRealBluesun/keeb4x4 repository on GitHub, published under the CERN-OHL-P-2.0 licence. It is a 4-layer board of 100 × 142.5 mm with 127 parts on 98 nets, routed with 1,797 tracks and 302 vias.

It is built around the STM32G431CBT6, 74AHCT1G125SE and W25Q128JVSIQ, with the 74HC154D, AP2112K-3.3 and USBLC6-2SC6 among its other parts. Its parts include 32 diodes, 29 capacitors, 19 switches, 17 resistors and 15 connectors. It belongs with the keyboards and input and lEDs and displays boards and the STM32 boards of this library.

Main components

9

README

README.md

keeb4x4 v2

A 4×4 macropad: STM32G431, 16 MX-style keys with per-key SK6812 RGB, up to 12 Waveshare 0.85" ScreenKey display keycaps, an EC11 rotary encoder, and a USB-C connection that streams key/encoder events to the host as JSON. Firmware is Rust/Embassy, with a resident USB bootloader so you never need a debug probe after the first flash.

Base and illustrative assembled layout

What's here

PathContents
keeb4x4.kicad_{pro,sch,pcb}KiCad project: schematic and 4-layer PCB (100 × 142.5 mm)
fab/Gerbers, BOM and CPL for JLCPCB, plus order settings and hand-solder list
FIRMWARE_NOTES.mdPin map, matrix polarity, encoder, LED chain — the hardware facts firmware relies on
firmware/Rust/Embassy application firmware
bootloader/USB DFU bootloader, recovery, memory layout
host/keeb CLI: list devices, listen to events, build and flash firmware
enclosure/3D-printable base (STL/STEP) and its parametric source
docs/PARTS.mdWhat to buy beyond the assembled board: ScreenKeys, switches, encoder
docs/PROGRAMMER.mdOne-time bootloader flashing with an ST-Link clone
tools/pcb/KiCad Python scripts used while routing the LED chain and GND stitching

Quick start (you have a board)

New board?

  1. Buy the parts that aren't on the assembled board: docs/PARTS.md (ScreenKeys, switches, encoder, ST-Link…)
  2. Flash the pre-built firmware once with an ST-Link: docs/PROGRAMMER.md. Image on the releases page.

Requires rustup. Toolchains and targets are pinned per project and install automatically.

sh
cargo build --manifest-path host/Cargo.toml --release --locked
host/target/release/keeb list      # should show the board
host/target/release/keeb listen    # watch key / encoder events

To rebuild and flash firmware over USB:

sh
host/target/release/keeb build
host/target/release/keeb update firmware/artifacts/update/keeb-v2.kbf

On Linux, install the udev rules first (see bootloader/README.md). If the application ever stops responding, hold the encoder button while plugging in USB to enter recovery, then run keeb update --recovery ....

A newly assembled board is blank. It needs a one-time bootloader install over the SWD header (J3) with a cheap ST-Link V2 clone and probe-rs. Start with docs/PROGRAMMER.md, which covers what to buy, wiring and troubleshooting.

Assembly notes

JLC assembles the SMT parts on both sides. You hand-solder the 16 switches, the EC11 encoder, and the SWD/OLED headers. Check the part rotations in JLC's preview before you order. See fab/README.md.

The USB VID/PID (c0de:cafe, plus STM32 DFU 0483:df11 in recovery) are prototype identities, not allocated ones.

License

  • Hardware (KiCad files, fab/, enclosure/): CERN-OHL-P-2.0
  • Software (firmware/, bootloader/, host/, tools/): MIT

ScreenKey init values are adapted from Waveshare's MIT-licensed example; see firmware/THIRD_PARTY.md.

Parts

127
QtyValueFootprintReferences
24100nFCapacitor_SMD:C_0603_1608MetricC1, C2, C10, C11, C12, C13, C14, C15, C16, C17, C18, C19, C20, C21, C22, C23 +8
161N4148WDiode_SMD:D_SOD-123D1, D2, D3, D4, D5, D6, D7, D8, D9, D10, D11, D12, D13, D14, D15, D16
16SK6812MINI-ELED_SMD:LED_SK6812MINI-E_3.2x2.8mm_P1.5mm_ReverseMountLED1, LED2, LED3, LED4, LED5, LED6, LED7, LED8, LED9, LED10, LED11, LED12, LED13, LED14, LED15, LED16
16SW_PushButton_Switch_Keyboard:SW_Cherry_MX_1.00u_PCBSW1, SW2, SW3, SW4, SW5, SW6, SW7, SW8, SW9, SW10, SW11, SW12, SW13, SW14, SW15, SW16
12100Resistor_SMD:R_0603_1608MetricR6, R7, R8, R9, R10, R11, R12, R13, R14, R15, R16, R17
8MountingHole:MountingHole_3.2mm_M3H1, H2, H3, H4, H5, H6, H7, H8
31uFCapacitor_SMD:C_0603_1608MetricC5, C25, C26
24.7kResistor_SMD:R_0603_1608MetricR4, R5
25.1kResistor_SMD:R_0603_1608MetricR1, R2
110kResistor_SMD:R_0603_1608MetricR3
110uFCapacitor_SMD:C_0805_2012MetricC27
14.7uFCapacitor_SMD:C_0603_1608MetricC4
174AHCT1G125Package_TO_SOT_SMD:SOT-23-5U4
174HC154Package_SO:SOIC-24W_7.5x15.4mm_P1.27mmU5
1AO3400APackage_TO_SOT_SMD:SOT-23Q1
1AP2112K-3.3Package_TO_SOT_SMD:SOT-23-5U3
1BOOTButton_Switch_SMD:SW_SPST_B3U-1000PSW18
1EC11Rotary_Encoder:RotaryEncoder_Alps_EC11E-Switch_Vertical_H20mmSW17
1OLED_SSD1306Connector_PinHeader_2.54mm:PinHeader_1x04_P2.54mm_VerticalJ2
1RESETButton_Switch_SMD:SW_SPST_B3U-1000PSW19
1STM32G431CBT6Package_QFP:LQFP-48_7x7mm_P0.5mmU1
1SWDConnector_PinHeader_2.54mm:PinHeader_1x05_P2.54mm_VerticalJ3
1ScreenKey1Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ4
1ScreenKey10Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ13
1ScreenKey11Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ14
1ScreenKey12Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ15
1ScreenKey2Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ5
1ScreenKey3Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ6
1ScreenKey4Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ7
1ScreenKey5Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ8
1ScreenKey6Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ9
1ScreenKey7Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ10
1ScreenKey8Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ11
1ScreenKey9Connector_FFC-FPC:Hirose_FH12-12S-0.5SH_1x12-1MP_P0.50mm_HorizontalJ12
1USBLC6-2SC6Package_TO_SOT_SMD:SOT-23-6U2
1USB_C_16PConnector_USB:USB_C_Receptacle_HRO_TYPE-C-31-M-12J1
1W25Q128JVSIQSOIC-8_5.3x5.3mm_P1.27mmU6

Similar boards

  • 2 layers308.8 × 99.3 mmHem, the printed circuit board in 3D

    Hem

    marcocampione/Hem-keyboard

    A 65% ANSI keyboard PCB with an RP2040 on the board

    302 partsMIT
  • 2 layers446.9 × 141.7 mmPerson keyboard, the printed circuit board in 3D

    Person keyboard

    jtljac/person-keyboard

    My personal Keyboard Design

    374 parts
  • 4 layers55 × 55 mmDrone PCB FC, the printed circuit board in 3D

    Drone PCB FC

    Ethansuttor/drone_PCB

    An 80×80 mm STM32F405 flight controller for a 4S freestyle quad, running Betaflight off a custom target I wrote.

    90 parts
  • 4 layers76 × 50 mmWigglecam, the printed circuit board in 3D

    Wigglecam

    jadenrhee/wigglecam-controller

    RP2040 co-processor board for a 4-lens wigglegram camera: constant-current flash, controls, battery telemetry, Pi 5 I2C interface. 4-layer, DRC-clean, fab-ready.

    105 parts
  • 4 layers353.7 × 129.8 mmTokenBoard, the printed circuit board in 3D

    TokenBoard

    h3ll5ur7er/TokenBoard

    You wouldn't vibe code a keyboard.. or would you? uses konnect to interact with KiCad and CADence to model the case

    422 parts
  • 2 layers347.9 × 119.3 mmSupport All PCBS, the printed circuit board in 3D

    Support All PCBS

    Jubakuba/Keycult-TKL-Kicad

    Keycult TKL PCB Replacement with per key rgb.

    401 parts
  • 4 layers95 × 95 mmAgentDeck, the printed circuit board in 3D

    AgentDeck

    Brillar0101/agentdeck

    RP2040 macropad for supervising AI coding agents: 13 hot-swap keys with per-key RGB status, encoder, joystick, 4-layer PCB, CircuitPython firmware, printable enclosure

    101 partsMIT
  • 2 layers83 × 127 mmNumpad, the printed circuit board in 3D

    Numpad

    blafr103/pico-numpad

    Hand-wired 17-key USB numpad on Pi Pico W. CircuitPython, diode matrix, event-driven scanning.

    120 partsMIT

Questions

How big is the Keeb4x4 PCB?

It measures 100 × 142.5 mm and has 4 copper layers, 1.6 mm thick.

What parts does the Keeb4x4 use?

127 parts, built around the STM32G431CBT6, 74AHCT1G125SE, W25Q128JVSIQ and 74HC154D. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.

Where can I download the Keeb4x4 KiCad files?

From the TheRealBluesun/keeb4x4 repository on GitHub, at the commit this page was made from: the board is keeb4x4.kicad_pcb and its schematic keeb4x4.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the Keeb4x4 design in my own project?

Its repository publishes it under the CERN-OHL-P-2.0 licence: you may reuse it on that licence's terms (keep the author's notice, and for a copyleft licence share your changes alike).