Skip to the content
2 layers48 × 68 mmT9kb, the printed circuit board in 3D

Tiny I2C T9 phone keypad module for ESP32 and other microcontrollers

Size
48 × 68 mm
Copper layers
2
Thickness
1.6 mm
Parts
38
Nets
18
Pads
156
Tracks, vias
385, 32
Pours
25
Routed
Yes
KiCad
KiCad 9.0 (file 20241229)
Created
7 Oct 2026
Updated
1 Nov 2026

Overview

T9kb is an open-source printed circuit board by acidvegas, from the acidvegas/t9kb repository on GitHub, published under the ISC licence. It is a 2-layer board of 48 × 68 mm with 38 parts on 18 nets, routed with 385 tracks and 32 vias.

Its parts include 24 switches, 4 resistors, 2 capacitors, 2 connectors and 1 IC. It belongs with the keyboards and input boards of this library.

README

README.md

T9KB

A tiny phone-style keypad for DIY projects that talks I2C. Plug it into an ESP32 (or anything with Qwiic / I2C) and you get the full key layout of an old desk phone handset: 3 soft keys, a 5-way d-pad, call / end / speaker / mute, and the 3x4 number pad.

There are virtually no good small modules on the market for basic I2C text input. The M5Stack CardKB is about the only one, and it is a tiny QWERTY board. Nothing like it exists for T9, so I made this one for T9 phone-style input on my own projects, starting with a DIY VoIP phone.

The layout follows the Grandstream WP826 handset. Keys are metal snap domes on gold pads, the same way real phones do it, and 3D printed PLA keycaps go on top. A single TI TCA8418 scans the keys, so the board has no firmware to flash. The text side (multi-tap, T9, key repeat) lives in an Arduino library on the host.

Status: v0.3 hardware is designed and ready to order, not built or tested yet. The Arduino library compiles and its logic is tested on a PC, not yet on real hardware. The keycaps and case are printed and fit.

Key face   Parts side

Key face, angled   Parts side, angled

The 3D model for case and keycap design is hardware/t9kb.step.

Arduino library

The library is in library/ (Arduino, compiles for the ESP32 core). Install it by copying or symlinking library/ into your Arduino libraries folder as T9KB.

cpp
#include <Wire.h>
#include <T9KB.h>

T9KB keypad;

void setup() {
	Wire.begin();
	keypad.begin(); // or keypad.begin(Wire, INT_GPIO, RST_GPIO) with the INT / RST pads wired
}

void loop() {
	keypad.update();
	while (keypad.available()) {
		T9Event ev = keypad.read(); // ev.key, ev.type (press / release / long / repeat), ev.code (raw key number)
	}
	uint8_t c;
	while ((c = keypad.getChar())) {
		// typed text, CardKB style
	}
}

Text entry through getChar():

KeyTap in Abc / abc / ABCLong press123 mode
2 to 9Letters, then the digit (abc2, def3, ... wxyz9)The digitDigit
11 . , ' ? ! " -11
0Space00, long press +
*Symbols (below)*
##Next mode#, long press mode
Right soft keyBackspace (auto-repeats)Backspace
ArrowsCardKB arrow codes (auto-repeat)Arrow codes

The * symbols, in order: . , ' ? ! " - ( ) @ / : _ ; + % * = < > $ [ ] { } \ ~ ^ # | ` &

  • Live preview: each tap sends the letter right away, and the next tap on the same key sends a backspace plus the next letter. Show the text as it comes in and the screen previews every letter as you cycle. pending() is true while the last letter can still change, so you can underline it, and tapSet() returns the characters on that key ("abc2" on 2) so you can show the choices. It returns nullptr when nothing is pending. The letter is final after 800 ms or when another key is pressed.
  • Modes: long press # cycles Abc, abc, ABC, 123. It starts in Abc, which capitalizes the first letter and any letter after . , ! or ? . setMode() changes the mode from code.
  • Codes: backspace 0x08, left 0xB4, up 0xB5, down 0xB6, right 0xB7, the same values the M5Stack CardKB sends. getChar() returns 0 when nothing is waiting.
  • Events only: OK, call, end, the left and middle soft keys, speaker and mute type nothing. Handle them from key events.
  • Events: read them from the queue with available() / read(), or set a callback with onKey(). isPressed() works for every key, so combos like a soft key plus a digit work.
  • Timing: setTapTimeout() (800 ms), setLongPress() (600 ms) and setRepeat() (500 ms delay, 80 ms rate).
  • Reading the keypad: without INT the library polls every 10 ms over I2C. With INT wired it only reads when a key event is waiting.
ExampleWhat it shows
TextLine editor on the serial monitor with live preview and mode display
EventsPrints every key event with its raw key number
Dialer123 mode phone dialer using the onKey() callback, Call and End
DeepSleepESP32 deep sleep, woken by a keypress on the INT wire

T9 word prediction is planned for later.

Keys

One rigid PLA keycap per key, with no web or membrane. Each cap has a 0.75 mm flange underneath that the case plate holds in, and a small rigid plunger that rests on its dome. Only the dome pushes back, so every key takes the dome's own force and keeps its click. Caps are green with black digits, letters and icons in the top 0.2 mm. Each cap leaves 0.10 mm around it in its plate hole (GROW), and the 2.56 mm plate makes deep holes that guide the caps, so pressing a wide key near one end barely tips it.

Keycaps   Keycap undersides

FileWhat
keys/t9kb_keys_caps.stlAll 24 caps, face down for printing
keys/t9kb_keys_legends.stlBlack legends, lined up with the caps
keys/t9kb_keys.scadOpenSCAD source with all dimensions as parameters

Legends: digits and letters on the number keys, an envelope (voicemail) on 1, speaker, muted microphone, call and hang up icons on the side keys, a line on each soft key, and arrows on the d-pad. The center select key is blank. Every stroke and every gap is at least 0.36 mm, so a 0.4 mm nozzle prints them all.

Printing (Bambu A1 mini, PLA, textured plate): build/slice.py slices every part with OrcaSlicer into ready-to-print .gcode.3mf files in build/out/:

FileWhat
keys_2color_MANUAL.gcode.3mfGreen caps, black legends: load black first, the printer pauses once in the first layer for green
case_top.gcode.3mfCase top only
case.gcode.3mfCase top and lid

The caps print face down at 0.12 mm layers after a 0.2 mm first layer, so the legends are exactly the first layer. No supports.

PartSize
CapsKey sizes from the layout, 4.36 mm tall, stick out of the plate 1.0 mm
Flange0.75 mm wide, 0.8 mm thick, stops under the plate
Plungers1.2 mm on 5 mm domes, 1.0 mm on 4 mm domes (Snaptron: at most 25% of the dome)
Tip0.40 mm above the board, resting on the dome
D-pad8 mm center key and 4 arrows, each with its own stop on the plate

TIP in t9kb_keys.scad is where the plunger meets the dome. ButtonWorx publishes no dome height; 5 mm round domes run 0.24 to 0.38 mm and the peel-and-stick film adds about 0.05 mm, so 0.40 leaves at most about 0.1 mm of free play. If the keys feel pre-pressed or don't click, raise it to 0.52. Keep TOP - TIP a multiple of the 0.12 mm layers after the 0.2 mm first one, then re-export and re-slice:

text
build/export.sh          # keycap and case STLs
python3 build/slice.py   # every .gcode.3mf

slice.py runs the OrcaSlicer 2.4.2 AppImage extracted to ~/.local/share/orca (--appimage-extract, needs libwebkit2gtk-4.1-0 and xvfb) with its stock Bambu A1 mini, Bambu PLA Basic and 0.12 mm Fine / 0.20 mm Standard profiles.

The keycap and case images in preview/ are rendered from build/preview.scad (-D 'VIEW="keys"', under, case, exploded or section).

Case

A 3D printed two-part case: a top shell with a hole for every key and a back lid. The keycaps and board drop into the top shell face down, then 4 M1.4 self-tapping screws go through the lid and the board's corner holes (H1-H4) into the face plate and clamp the stack together.

Case with the keycaps   Case top, keycaps, board and lid

Cross-section

FileWhat
case/t9kb_case_top.stlTop shell, already flipped plate down for printing
case/t9kb_case_lid.stlBack lid, floor down
case/t9kb_case.scadOpenSCAD source with all dimensions as parameters
PartSize
Outside52.6 x 72.6 x 8.8 mm
Walls2.0 mm
Top plate2.56 mm, deep key holes that keep the keys from tipping; keys stick out 1.0 mm
Spacer1.6 mm under the plate, a pocket for every keycap flange; rests on a 1.0 mm rim at the board edge, the rest stays 0.3 mm off the board clear of the dome adhesive
Key holes0.25 mm around the key outline, 0.10 mm around each cap; a 1.4 mm ring and spokes split the d-pad
Lid1.2 mm floor, 1.2 mm skirt that holds the board against the spacer, a 3.4 mm boss under each board corner
Screws4 x M1.4 x 8 mm self-tapping pan head (PH00): 1.7 mm holes in the lid, 1.5 mm holes in the board, 1.2 mm pilots that stop 0.56 mm under the face
OpeningsQwiic slot on the top edge and a window in the lid for the jack, wire hole on the bottom edge for the J2 pads
Inside1.8 mm under the board for the parts (tallest is U1, 0.8 mm; the 2.96 mm Qwiic jack sits in the lid window, flush with the back)

Print both parts in PLA or PETG. 0.2 mm layers, 3 walls, no supports needed. The top shell prints plate down, so the face comes out flat.

Assembly:

  1. Lay the top shell face down and drop every keycap into its hole from the inside, flange down.
  2. Stick the domes on the board, then lay the board key face down onto the spacer.
  3. Feed any J2 wires out through the bottom hole.
  4. Set the lid in from the back and drive the 4 screws until snug. The first time they cut their own thread in the pilots, so don't overtighten.

Specs

ItemValue
Board size48 x 68 mm, 1.6 mm thick, 2 layers, 2 mm corner radius
Keys24 metal dome pads (Snaptron patterns: 17 for 5 / 5.3 mm domes, 7 for 4 mm domes)
ControllerTI TCA8418 keypad scanner, no firmware
I2C address0x34 (fixed)
Power3.3 V only (1.65 to 3.6 V)
ConnectorQwiic / STEMMA QT (JST SH 4-pin), top edge, parts side
Key faceFlat: gold dome pads and legends only (KiCad bottom layer)
Parts sideAll parts (8 total, KiCad top layer)

Key layout

All sizes in mm, measured on the key face. The key area is 43 x 63, centered on the board with a 2.5 border on every side.

KeysCountSizeDome
Soft keys313 x 54 mm
D-pad ring18 circle
D-pad center110.5 circle5 mm
D-pad arrows4In the ring around the center4 mm
Side keys410.5 x 7, two on each side5 mm
Number keys1213 x 75 mm
GapSize
Between soft keys, between number keys2
Soft keys to d-pad3
Soft keys to side keys3.5
Between the 2 stacked side keys3
D-pad to number keys3
Side keys to number keys3.5

The outer edges of the soft keys, side keys and number keys all line up.

Connections

Qwiic connector (J1):

PinSignal
1GND
23.3V
3SDA
4SCL

Breakout pads on the bottom edge of the parts side (J2, 2.54 mm pitch, solder wires or an SMD header):

PadSignalNotes
1GND
23V3
3SDA
4SCL
5INTGoes low when a key event is waiting (10k pull-up on board)
6RSTPull low to reset the TCA8418 (10k pull-up on board)

Qwiic has no spare wire for INT. Over Qwiic alone the host polls the keypad; solder a wire from J2's INT pad to a GPIO for interrupt-driven reads and wake-on-keypress.

The board has 4.7k I2C pull-ups through the 3-pad solder jumper JP1. It comes bridged. If you chain it with other boards that already have pull-ups, cut both copper bars on JP1.

Key map

The TCA8418 reports a key number from 1 to 80 (row * 10 + column + 1). Bit 7 of the event byte is 1 for press, 0 for release.

KeyRowColKey number
1001
2012
3023
Soft left034
Soft middle045
Soft right056
41011
51112
61213
Speaker1314
Up1415
Mute1516
72021
82122
92223
Left2324
OK2425
Right2526
*3031
03132
#3233
Call3334
Down3435
End3536

Minimum setup over I2C:

RegisterNameWriteWhy
0x1DKP_GPIO10x0FRows 0 to 3 are keypad rows
0x1EKP_GPIO20x3FColumns 0 to 5 are keypad columns
0x01CFG0x01Interrupt on key events

Then read KEY_LCK_EC (0x03) for the event count, read KEY_EVENT_A (0x04) once per event, and write 0x01 to INT_STAT (0x02) to clear the interrupt.

The board has no diodes, so single keys and 2-key combos are reliable. Pressing 3 keys that form an L in the matrix can show a fake 4th key.

Parts

Assembled by JLCPCB (all on the parts side):

RefPartPackageLCSCJLC type
U1TCA8418RTWRWQFN-24 4x4 mmC138713Extended
J1JST SM04B-SRSS-TB (Qwiic)SMD right angleC160404Extended
C1100 nF0603C14663Basic
C210 uF0603C19702Basic
R1, R24.7k (I2C pull-ups)0603C23162Basic
R3, R410k (RST, INT pull-ups)0603C25804Basic

Bought separately and added by hand:

QtyPartWhereNotes
205 to 5.3 mm metal domes (see Dome sources)Varies17 needed, rest are spares
104 mm metal domes (see Dome sources)Varies7 needed, rest are spares
1Kapton (polyimide) tapeAnywhereOnly for loose domes

Dome sources

The pads follow Snaptron's published single-sided contact patterns: 17 pads for 5 / 5.3 mm domes and 7 pads for 4 mm domes (soft keys and d-pad arrows). Prices and stock were checked on 2026-10-07.

From ButtonWorx (Maine, US, $4 minimum order, no force listed):

PadsPartPriceMounting
5 mmSnap Dome Chopped Circle 5.2mm Peel & Stick$0.50 eachBuilt-in 7 mm square sticker
4 mmSnap Dome Round 4mm Dimple, loose$0.40 eachLoose: tape it down

The adhesive squares around neighboring d-pad domes may overlap; trim them if they do. A 4.5 mm dome does not fit the 4 mm pads.

Ordering from JLCPCB

Upload hardware/fab/t9kb_gerbers.zip and use these settings:

SettingValue
Layers2
Dimensions48 x 68 mm (auto-detected)
MaterialFR-4
PCB thickness1.6 mm (Economic PCBA only offers ENIG at 1.6 mm)
Surface finishENIG (required, the dome contacts need gold)
Gold thickness2U" (1U" also works)
PCB assemblyYes, Economic
Assembly sideTop side
BOM / CPLhardware/fab/BOM.csv and hardware/fab/CPL.csv

On the placement preview page, check these before paying:

  • U1: the dot on the chip lines up with the pin 1 triangle printed on the board.
  • J1: the connector opening faces the top edge of the board.

If either is turned wrong, rotate it right there in the preview. Resistors and capacitors do not care.

Assembly

  1. Clean the key face with isopropyl alcohol.
  2. Place a dome on each gold pad, centered on the round contact (not on the small hole, which is off-center on purpose). The small pads (soft keys and d-pad arrows) take 4 mm domes, the rest take 5 mm domes. Four-leg domes go with a leg on each of the 4 cut corners of the gold frame.
  3. Tape over the domes with Kapton tape, or use peel-and-stick domes. Air vents through the small hole in each center pad, so the tape can cover the domes fully.
  4. Test by pressing each dome with a finger while reading key events.

A dome that sits crooked can be peeled off and placed again. Nothing on the key face is soldered.

Rebuilding the board

The board is generated by script (KiCad 9). There is no schematic; the netlist lives in gen_pcb.py.

text
cd hardware
./autoroute.sh    # place parts, autoroute with freerouting, pour ground, run DRC
python3 fab.py    # gerbers, drill files, BOM, CPL

autoroute.sh expects freerouting.jar in tools/. Download it from the freerouting v2.0.1 release (needs Java 21).

References

  • ref/tca8418.pdf: TI TCA8418 datasheet
  • ref/snaptron_guide.pdf: Snaptron metal dome design guide (contact pad patterns, plating, venting)

Notes

  • The TCA8418 exposed pad is tied to ground, as TI recommends (ground or floating, never power).
  • Dome pads follow Snaptron's single-sided contact patterns for 5 / 5.3 mm and 4 mm domes, with the off-center via-in-pad option for 2-layer boards. There is no solder mask inside the pad area, per Snaptron.
  • U1 uses TI's own land pattern and stencil for the RTW0024B package (TCA8418 datasheet).
  • The key face is the KiCad bottom layer so JLC assembles the top side.
  • LEDs and backlight were removed for this revision. They may come back later.

Mirrors: SuperNETs • GitHub • GitLab • Codeberg

Parts

38
QtyValueFootprintReferences
4M1.4MountingHole_1.5mm_M1.4H1, H2, H3, H4
210kR_0603_1608MetricR3, R4
24.7kR_0603_1608MetricR1, R2
1100nFC_0603_1608MetricC1
110uFC_0603_1608MetricC2
1BreakoutPads_1x06_P2.54mm_SMDJ2
1CALLMetalDome_5mmSW10
1CONTACTMetalDome_5mmSW6
1DOWNMetalDome_4mmSW11
1ENDMetalDome_5mmSW12
1I2C_PUSolderJumper-3_P1.3mm_Bridged2Bar123_RoundedPad1.0x1.5mmJP1
1K0MetalDome_5mmSW23
1K1MetalDome_5mmSW13
1K2MetalDome_5mmSW14
1K3MetalDome_5mmSW15
1K4MetalDome_5mmSW16
1K5MetalDome_5mmSW17
1K6MetalDome_5mmSW18
1K7MetalDome_5mmSW19
1K8MetalDome_5mmSW20
1K9MetalDome_5mmSW21
1KHASHMetalDome_5mmSW24
1KSTARMetalDome_5mmSW22
1LEFTMetalDome_4mmSW7
1OKMetalDome_5mmSW8
1QwiicJST_SH_SM04B-SRSS-TB_1x04-1MP_P1.00mm_HorizontalJ1
1RIGHTMetalDome_4mmSW9
1SOFT_LMetalDome_4mmSW1
1SOFT_MMetalDome_4mmSW2
1SOFT_RMetalDome_4mmSW3
1SPKMetalDome_5mmSW4
1TCA8418RTWRWQFN-24-1EP_4x4mm_P0.5mm_EP2.45mm_TI_RTW0024BU1
1UPMetalDome_4mmSW5

Similar boards

  • 2 layers85 × 115 mmOSO BOOK C1, the printed circuit board in 3D

    OSO BOOK C1

    joeycastillo/The-Open-Book

    For details on how to build, test and use Open Book, I've made documentation available here.

    38 parts8.1kCC-BY-SA-4.0
  • 2 layers38.1 × 12.7 mmVrs io 1, the printed circuit board in 3D

    Vrs io 1

    rusefi/rusefi

    rusefi - GPL internal combustion engine control unit

    38 parts1.2k
  • 2 layers136 × 84 mmMacropad, the printed circuit board in 3D

    Macropad

    hackclub/OnBoard

    💡 Join 1,000 teenagers and make your first PCB with a $100 grant!

    38 parts915
  • 2 layers126.4 × 15.2 mmV5ProbeTop, the printed circuit board in 3D

    V5ProbeTop

    Architeuthis-Flux/JumperlessV5

    The next generation jumperless breadboard

    38 parts332
  • 2 layers66 × 25.4 mmArdmover Empfangsspule Yann, the printed circuit board in 3D

    Ardmover Empfangsspule Yann

    Ardumower/ardumower

    Develop an open source robotic lawn mower (HW+SW reference platform)

    38 parts282
  • 2 layers17.8 × 17.8 mmAltmode friend, the printed circuit board in 3D

    Altmode friend

    CRImier/MyKiCad

    My KiCad boards. Can't be bothered uploading individually anymore, so here you go.

    38 parts253GPL-3.0
  • 2 layers51.4 × 61 mmWifi gb cart, the printed circuit board in 3D

    Wifi gb cart

    Staacks/wifi-game-boy-cartridge

    A WiFi cartridge for the original Game Boy.

    38 parts242
  • 2 layers125 × 97.2 mmBattoota, the printed circuit board in 3D

    Battoota

    AlaaSaadAbdo/battoota

    Keyboards

    38 parts188

Questions

How big is the T9kb PCB?

It measures 48 × 68 mm and has 2 copper layers, 1.6 mm thick.

What parts does the T9kb use?

38 parts. 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 T9kb KiCad files?

From the acidvegas/t9kb repository on GitHub, at the commit this page was made from: the board is hardware/t9kb.kicad_pcb. PCBKit opens the board in the browser, with nothing to install.

Can I use the T9kb design in my own project?

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