Skip to the content
2 layers373.5 × 124.2 mmTKL PCB, the printed circuit board in 3D

rp2040 based TKL keyboard, with C firmware, rotary encoder and OLED display

Size
373.5 × 124.2 mm
Copper layers
2
Thickness
1.6 mm
Parts
222
Nets
148
Pads
1,173
Tracks, vias
1,428, 69
Pours
1
Routed
Yes
KiCad
KiCad 7 (file 20221018)
Created
5 Feb 2024
Updated
27 Oct 2024

Overview

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.

Main components

3

README

README.md

USB HID Keyboard Project

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.

Table of Contents

Introduction

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:

  • An OLED display that shows a Bongo Cat typing animation whenever the user types, adding a fun and interactive visual element.
  • A fully functional rotary encoder that can be used for multimedia control or fine-tuning in design/editing software.
  • An LED indicator that reflects the device's USB connection state (mounted, not mounted, suspended).

Architecture

The overall architecture of the project is illustrated below:

ArquiteturaGeral_V2

The core of the project is a microcontroller that performs the following functions:

  • Detects key presses from the keyboard matrix.
  • Processes inputs from the rotary encoder.
  • Configures and updates the OLED display to show the typing animation.
  • Manages LED indicators based on USB connection states.

The information from the keyboard and encoder is sent to the connected computer using the USB HID protocol via the microcontroller’s USB interface.

Hardware

The hardware components of the project include the PCB and the following components:

  • RP2040 microcontroller: Chosen for its numerous GPIO pins, USB communication capabilities, and ease of reprogramming via USB as a mass storage device.
  • 128Mb Flash memory, 12MHz quartz oscillator, and a 5V-3.3V voltage regulator to power the microcontroller.
  • Hot-swappable sockets for the mechanical switches, allowing switches to be replaced without soldering.
  • A folded matrix design for the key layout to optimize IO usage, reducing the required pins from 16x6 to 12x8.
  • Rotary Encoder: For multimedia control.
  • OLED Display (SSD1306): For displaying animations and status information.
  • LED Indicator: Blinks at different intervals to reflect USB states, show caps lock state, and blink at 1Hz which was a requirement of the LABSI course but can be disabled.

PCB Design

The PCB design was inspired by various resources, including:

3D Printed Case

(This section will be updated soon.)

Software

The firmware for the keyboard was developed in C using the VSCode IDE and CMake for compilation. The software stack includes:

Software Inspirations and Libraries

The project leverages several open-source libraries and resources:

Source Code

The source code of this project is organized into several files, each responsible for different functionalities:

main.c

The 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.h

Handles 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.h

Manages 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.h

Controls 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.h

Implements the driver for the SSD1306 OLED display. Handles initialization, drawing pixels, rendering images, and managing the display buffer.

encoder.pio and encoder.pio.h

Provides 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.h

Header file for encoder.pio, declaring the initialization functions for the encoder PIO state machines.

Current Functionalities

Key Features

  • 87-Key TKL Layout: Provides all essential keys with a compact form factor without a numpad.
  • Hot-Swappable Switches: Allows users to replace mechanical switches without soldering.
  • OLED Display with Bongo Cat Animation: Displays a playful animation that reacts to typing activity.
  • Rotary Encoder: Enables multimedia controls such as volume adjustment.
  • LED Indicator: Blinks at different intervals to indicate USB connection states:
    • 250 ms: Not mounted.
    • 500 ms: Mounted.
    • 2500 ms: Suspended.
  • USB HID Protocol: Ensures seamless integration with computers as a standard HID device.
  • Debounced Key Scanning: Prevents ghosting and ensures reliable keypress detection.

Software Enhancements

  • HID Task Management: Efficiently handles HID reports and manages keyboard and encoder inputs.
  • Bongo Cat Animation Control: Manages the animation states based on user interactions and elapsed time.
  • Rotary Encoder Acceleration: Implements acceleration for quick rotary turns to enhance user experience.
  • Bootloader Mode Check: Supports entering bootloader mode via key combination for firmware updates.

Results

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:

PCB_BAIXO PCB_CIMA VID_20240911_211501-ezgif com-speed (1)

Conclusions

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:

  • Updating the 3D printed case design (v2).
  • Expanding the software features for additional display capabilities.
  • Enhancing encoder functionalities for more control options.

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.

References

  1. Raspberry Pi RP2040 Hardware Design
  2. Japanese Duplex Matrix
  3. Cherry MX Mechanical Switch GIF
  4. Kailh Hot Swap Sockets
  5. OLED Display Datasheet
  6. Rotary Encoder Details
  7. TinyUSB Documentation
  8. pico-ssd1306
  9. USB HID Usage Table
  10. picokey
  11. OLED-BongoCat-Revision
  12. pico-superkey-board
  13. pi-pico-pio-quadrature-encoder

Acknowledgements

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!


Parts

222
QtyValueFootprintReferences
88D_SmallDiode_SMD:D_SOD-123D1, D2, D10, D11, D12, D13, D14, D15, D16, D17, D18, D19, D20, D21, D22, D23 +72
80SW_SW_HSPCM_marbastlib-mx:SW_MX_HS_1uSW1, SW2, SW10, SW11, SW12, SW13, SW14, SW15, SW16, SW17, SW18, SW19, SW20, SW21, SW22, SW23 +64
8100nCapacitor_SMD:C_0402_1005MetricC7, C8, C11, C12, C13, C14, C15, C16
75.1kResistor_SMD:R_0402_1005MetricR1, R2, R3, R4, R5, R6, R7
7SW_SW_HSPCM_marbastlib-mx:SW_MX_HS_1.25uSW77, SW78, SW79, SW81, SW82, SW83, SW84
51uCapacitor_SMD:C_0402_1005MetricC1, C2, C5, C6, C10
21kResistor_SMD:R_0402_1005MetricR8, R9
222pCapacitor_SMD:C_0402_1005MetricC3, C4
227Resistor_SMD:R_0603_1608MetricR10, R11
2SW_PushButton_Switch_SMD:SW_SPST_TL3342BOOT1, RST1
110uCapacitor_SMD:C_0603_1608MetricC9
11kResistor_SMD:R_1206_3216Metric_Pad1.30x1.75mm_HandSolderR12
1Conn_01x04Connector_PinSocket_2.54mm:PinSocket_1x04_P2.54mm_VerticalJ3
1Conn_01x04Connector_JST:JST_SH_SM04B-SRSS-TB_1x04-1MP_P1.00mm_HorizontalJ2
1Conn_01x05Connector_PinHeader_2.54mm:PinHeader_1x05_P2.54mm_VerticalJ4
1Crystal_GND24Crystal:Crystal_SMD_3225-4Pin_3.2x2.5mmY1
1Fuse_SmallFuse:Fuse_1206_3216MetricF1
1LEDLED_SMD:LED_1206_3216Metric_Pad1.42x1.75mm_HandSolderD89
1MX_stabPCM_marbastlib-mx:STAB_MX_P_2.25uS1
1MX_stabPCM_marbastlib-mx:STAB_MX_P_2uS5
1MX_stabPCM_marbastlib-mx:STAB_MX_P_2.75uS3
1MX_stabPCM_marbastlib-mx:STAB_MX_P_6.25uS2
1MX_stabPCM_marbastlib-mx:STAB_MX_P_ISO-ROTS4
1RP2040Package_DFN_QFN:QFN-56-1EP_7x7mm_P0.4mm_EP3.2x3.2mmU3
1RotaryEncoder_SwitchTKL_1:RotaryEncoder_Alps_EC12E-Switch_Vertical_H20mmRotary Encoder
1SRV05-4PCM_marbastlib-various:SOT-23-6-routableU2
1USB_C_Receptacle_USB2.0Connector_USB:USB_C_Receptacle_HRO_TYPE-C-31-M-12J1
1W25Q128JVSPackage_SO:SOIC-8_5.23x5.23mm_P1.27mmFlash
1XC6206PxxxMRPackage_TO_SOT_SMD:SOT-23-3Regulator

Similar boards

  • 2 layers63.5 × 58 mmLatest, the printed circuit board in 3D

    Latest

    minipadKB/minipad

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

    39 parts52GPL-3.0
  • 2 layers224.4 × 97.8 mmKnobdeavour, the printed circuit board in 3D

    Knobdeavour

    ScatteredDrifter/Buran-Ortho

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

    105 parts46
  • 2 layers253.3 × 113.3 mmCut slope, the printed circuit board in 3D

    Cut slope

    hazels-garage/cut-slope

    119 parts29
  • 2 layers344.7 × 123.6 mmSlime88, the printed circuit board in 3D

    Slime88

    zykrah/slime88

    A F13 TKL Multi-Layout Hotswap H88-Compat Type-C PCB

    243 parts29
  • 2 layers346.1 × 118.3 mmTKL VIDEO, the printed circuit board in 3D

    TKL VIDEO

    NCKiser/TKL_VIDEO

    233 parts17
  • 2 layers236.9 × 86.8 mmRaii020, the printed circuit board in 3D

    Raii020

    unspecworks/raii

    splay sweep with ferris

    233 parts17
  • 2 layers346.1 × 93.7 mmSifrl main pcb, the printed circuit board in 3D

    Sifrl main pcb

    ramonimbao/SpaceInvadersFRL

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

    177 parts15
  • 2 layers309.6 × 76.2 mmQ9-Chimera, the printed circuit board in 3D

    Q9-Chimera

    xommmmmmmm/QueueNineChimera

    A drop-in, multi-layout (ortho/row/alpha stagger) PCB with numpad for Keychron Q9

    201 parts15

Questions

How big is the TKL PCB PCB?

It measures 373.5 × 124.2 mm and has 2 copper layers, 1.6 mm thick.

What parts does the TKL PCB use?

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.

Where can I download the TKL PCB KiCad files?

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.

Can I use the TKL PCB design in my own project?

Its repository states no licence, so its author keeps all rights: ask Guilhermesscastro before reusing the design.