
Latest
minipadKB/minipad
The PCB and case files for the minipad, an RP2040-based 2-3-key keypad for the rhythm game osu!.

rp2040 based TKL keyboard, with C firmware, rotary encoder and OLED display
TKL PCB is an open-source printed circuit board by Guilhermesscastro, from the Guilhermesscastro/TKL-KEYBOARD repository on GitHub. It is a 2-layer board of 373.5 × 124.2 mm with 222 parts on 148 nets, routed with 1,428 tracks and 69 vias.
It is built around the RP2040, W25Q128JVSIQ and SRV05-4. Its parts include 92 switches, 89 diodes, 16 capacitors, 12 resistors and 4 connectors. It belongs with the lEDs and displays and keyboards and input boards and the RP2040 boards of this library.
This repository contains the source code and documentation for the USB HID Keyboard Project, developed as part of the LABSI course. The project implements a custom mechanical keyboard with a PT-PT TKL (Tenkeyless) layout featuring 87 keys, an OLED display with a Bongo Cat typing animation, a rotary encoder for multimedia control, and an LED indicator to reflect device states.
This project is a prototype of a mechanical keyboard with a TKL format with a PCB board design based on the RP2040 microcontroller. This project was made in the LABSI course at Porto Higher Institute of Engineering (ISEP). In addition to the basic keyboard features, the project integrates:
The overall architecture of the project is illustrated below:
The core of the project is a microcontroller that performs the following functions:
The information from the keyboard and encoder is sent to the connected computer using the USB HID protocol via the microcontroller’s USB interface.
The hardware components of the project include the PCB and the following components:
The PCB design was inspired by various resources, including:
(This section will be updated soon.)
The firmware for the keyboard was developed in C using the VSCode IDE and CMake for compilation. The software stack includes:
The project leverages several open-source libraries and resources:
The source code of this project is organized into several files, each responsible for different functionalities:
main.cThe entry point of the firmware. It initializes all hardware components, sets up USB HID, and enters the main loop where it continuously handles USB tasks, HID reports, and updates the Bongo Cat animation.
keyboard.c and keyboard.hHandles the keyboard matrix scanning, key debouncing, HID report generation, and management of key states and buffers. Implements the logic for detecting key presses and sending appropriate HID reports to the host.
bongocat.c and bongocat.hManages the Bongo Cat animation displayed on the OLED screen. Handles different animation states based on user interactions and timing to provide a dynamic visual feedback mechanism.
led.c and led.hControls the LED indicator that reflects the USB connection state. Manages different blink patterns corresponding to various USB states such as mounted, not mounted, and suspended.
pico-ssd1306/ssd1306.c and pico-ssd1306/ssd1306.hImplements the driver for the SSD1306 OLED display. Handles initialization, drawing pixels, rendering images, and managing the display buffer.
encoder.pio and encoder.pio.hProvides the Programmable I/O (PIO) programs for handling the rotary encoder's quadrature signals. Manages the decoding of rotary inputs to enable smooth multimedia control.
encoder.pio.hHeader file for encoder.pio, declaring the initialization functions for the encoder PIO state machines.
The final prototype works well, especially with the new addition of the Bongo Cat animation and the fully functional rotary encoder. The LED indicator effectively communicates the device's USB connection state to the user. Here are images of the assembled Keyboard:
Overall, the project has achieved most of its objectives, delivering a functional and interactive mechanical keyboard with unique features like the Bongo Cat animation and rotary encoder. Future improvements include:
Being given more time and downsizing the keyboard to a macropad could have allowed for more in-depth software development and additional customization when realizing the project during my semester, however, the current state of the project already includes the basic functionalities that were required by the LABSI course, and i continued to work on it as a personal project.
A heartfelt thank you to all the developers and communities that provided invaluable resources and inspiration for this project:
Your open-source contributions have been instrumental in the development of this keyboard project. Thank you for sharing your knowledge and tools with the community!
| Qty | Value | Footprint | References |
|---|---|---|---|
| 88 | D_Small | Diode_SMD:D_SOD-123 | D1, D2, D10, D11, D12, D13, D14, D15, D16, D17, D18, D19, D20, D21, D22, D23 +72 |
| 80 | SW_SW_HS | PCM_marbastlib-mx:SW_MX_HS_1u | SW1, SW2, SW10, SW11, SW12, SW13, SW14, SW15, SW16, SW17, SW18, SW19, SW20, SW21, SW22, SW23 +64 |
| 8 | 100n | Capacitor_SMD:C_0402_1005Metric | C7, C8, C11, C12, C13, C14, C15, C16 |
| 7 | 5.1k | Resistor_SMD:R_0402_1005Metric | R1, R2, R3, R4, R5, R6, R7 |
| 7 | SW_SW_HS | PCM_marbastlib-mx:SW_MX_HS_1.25u | SW77, SW78, SW79, SW81, SW82, SW83, SW84 |
| 5 | 1u | Capacitor_SMD:C_0402_1005Metric | C1, C2, C5, C6, C10 |
| 2 | 1k | Resistor_SMD:R_0402_1005Metric | R8, R9 |
| 2 | 22p | Capacitor_SMD:C_0402_1005Metric | C3, C4 |
| 2 | 27 | Resistor_SMD:R_0603_1608Metric | R10, R11 |
| 2 | SW_Push | Button_Switch_SMD:SW_SPST_TL3342 | BOOT1, RST1 |
| 1 | 10u | Capacitor_SMD:C_0603_1608Metric | C9 |
| 1 | 1k | Resistor_SMD:R_1206_3216Metric_Pad1.30x1.75mm_HandSolder | R12 |
| 1 | Conn_01x04 | Connector_PinSocket_2.54mm:PinSocket_1x04_P2.54mm_Vertical | J3 |
| 1 | Conn_01x04 | Connector_JST:JST_SH_SM04B-SRSS-TB_1x04-1MP_P1.00mm_Horizontal | J2 |
| 1 | Conn_01x05 | Connector_PinHeader_2.54mm:PinHeader_1x05_P2.54mm_Vertical | J4 |
| 1 | Crystal_GND24 | Crystal:Crystal_SMD_3225-4Pin_3.2x2.5mm | Y1 |
| 1 | Fuse_Small | Fuse:Fuse_1206_3216Metric | F1 |
| 1 | LED | LED_SMD:LED_1206_3216Metric_Pad1.42x1.75mm_HandSolder | D89 |
| 1 | MX_stab | PCM_marbastlib-mx:STAB_MX_P_2.25u | S1 |
| 1 | MX_stab | PCM_marbastlib-mx:STAB_MX_P_2u | S5 |
| 1 | MX_stab | PCM_marbastlib-mx:STAB_MX_P_2.75u | S3 |
| 1 | MX_stab | PCM_marbastlib-mx:STAB_MX_P_6.25u | S2 |
| 1 | MX_stab | PCM_marbastlib-mx:STAB_MX_P_ISO-ROT | S4 |
| 1 | RP2040 | Package_DFN_QFN:QFN-56-1EP_7x7mm_P0.4mm_EP3.2x3.2mm | U3 |
| 1 | RotaryEncoder_Switch | TKL_1:RotaryEncoder_Alps_EC12E-Switch_Vertical_H20mm | Rotary Encoder |
| 1 | SRV05-4 | PCM_marbastlib-various:SOT-23-6-routable | U2 |
| 1 | USB_C_Receptacle_USB2.0 | Connector_USB:USB_C_Receptacle_HRO_TYPE-C-31-M-12 | J1 |
| 1 | W25Q128JVS | Package_SO:SOIC-8_5.23x5.23mm_P1.27mm | Flash |
| 1 | XC6206PxxxMR | Package_TO_SOT_SMD:SOT-23-3 | Regulator |

minipadKB/minipad
The PCB and case files for the minipad, an RP2040-based 2-3-key keypad for the rhythm game osu!.

ScatteredDrifter/Buran-Ortho
A 39-key orthogonal keyboard with support for two knobs, based on a rp2040





ramonimbao/SpaceInvadersFRL
An F-rowless TKL keyboard case, plate, and PCB that uses the HiTek Series 725 switches.

xommmmmmmm/QueueNineChimera
A drop-in, multi-layout (ortho/row/alpha stagger) PCB with numpad for Keychron Q9
It measures 373.5 × 124.2 mm and has 2 copper layers, 1.6 mm thick.
222 parts, built around the RP2040, W25Q128JVSIQ and SRV05-4. 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.
From the Guilhermesscastro/TKL-KEYBOARD repository on GitHub, at the commit this page was made from: the board is PCB/TKL_PCB.kicad_pcb and its schematic PCB/TKL_PCB.kicad_sch. PCBKit opens the board in the browser, with nothing to install.
Its repository states no licence, so its author keeps all rights: ask Guilhermesscastro before reusing the design.