# adwuard/trackerkb architecture

> Architecture diagram of the GitHub repository adwuard/trackerkb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adwuard/trackerkb
- Repository: https://github.com/adwuard/trackerkb

## Overview

This repository provides a tracker-keyboard product: a physical keyboard/PCB and enclosure designs, plus RP2040 firmware that reads keys and emits USB HID input. The main runtime path is key switches → firmware debounce and key mapping → TinyUSB keyboard handling → host. The README also documents a USB hub linking the keyboard and a Teensy 4.1 tracker, separate tracker firmware, and three enclosure options. Edges reflect the shown firmware calls or documented product relationships; unsampled hardware details are represented only at the documented subsystem level.

Main entry points: [`hardware/Tracker-Keyboard-PCB`](https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB) (Keyboard PCB), [`software/src/pico-m8-keyboard.cpp`](https://github.com/adwuard/trackerkb/blob/master/software/src/pico-m8-keyboard.cpp) (Key scanning and mapping), [`software/src/includes/Print.h`](https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Print.h) (Print API), [`hardware/Tracker-Keyboard-PCB/datasheets_and_footprints/DEV-16771`](https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB/datasheets_and_footprints/DEV-16771) (Teensy tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Hardware"]
  node_keys["Key switches"]
  node_pcb["Keyboard PCB"]
  node_rp2040["RP2040 MCU"]
  node_hub["USB hub"]
  node_teensy["Teensy tracker"]
  node_cnc["CNC enclosure"]
  node_acrylic["Acrylic enclosure"]
  node_printed["3D-printed enclosure"]
end

subgraph group_firmware["Keyboard firmware"]
  node_firmware_main["Key scanning and mapping"]
  node_hid["TinyUSB keyboard HID"]
  node_usb_callbacks["USB state callbacks<br/>[usb.h]"]
  node_usb_config["TinyUSB device config<br/>[tusb_config.h]"]
end

subgraph group_support["Firmware support"]
  node_cdc_stub["CDC compatibility stub"]
  node_arduino["Arduino compatibility<br/>[Arduino.h]"]
  node_print["Print implementation<br/>[Print.cpp]"]
  node_print_api["Print API<br/>[Print.h]"]
  node_printable["Printable interface<br/>[Printable.h]"]
  node_wstring["String compatibility<br/>[WString.h]"]
  node_stream["Stream compatibility<br/>[Stream.h]"]
end

node_user(("Keyboard user"))
node_host(("USB host"))
node_tracker_fw["Headless tracker firmware"]

node_user -->|"presses"| node_keys
node_keys -->|"GPIO input"| node_firmware_main
node_firmware_main -->|"presses/releases"| node_hid
node_hid -->|"sends HID"| node_host
node_pcb -->|"hosts MCU"| node_rp2040
node_pcb -->|"connects switches"| node_keys
node_hub -->|"connects USB"| node_teensy
node_hub -->|"connects USB"| node_rp2040
node_teensy -->|"runs firmware"| node_tracker_fw
node_firmware_main -->|"includes callbacks"| node_usb_callbacks
node_firmware_main -->|"includes stub"| node_cdc_stub
node_arduino -->|"includes API"| node_print_api
node_print -->|"uses compatibility"| node_arduino
node_print_api -->|"uses strings"| node_wstring
node_print_api -->|"uses interface"| node_printable
node_stream -->|"aliases to"| node_print_api
node_cnc -->|"encloses assembly"| node_pcb
node_acrylic -->|"encloses assembly"| node_pcb
node_printed -->|"encloses assembly"| node_pcb

click node_keys "https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB"
click node_pcb "https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB"
click node_rp2040 "https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB/datasheets_and_footprints/RP2040"
click node_hub "https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB"
click node_teensy "https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB/datasheets_and_footprints/DEV-16771"
click node_firmware_main "https://github.com/adwuard/trackerkb/blob/master/software/src/pico-m8-keyboard.cpp"
click node_hid "https://github.com/adwuard/trackerkb/tree/master/software/src/TinyUSB_Mouse_and_Keyboard"
click node_usb_callbacks "https://github.com/adwuard/trackerkb/blob/master/software/src/includes/usb.h"
click node_usb_config "https://github.com/adwuard/trackerkb/blob/master/software/src/includes/tusb_config.h"
click node_cdc_stub "https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Adafruit_USBD_CDC-stub.h"
click node_arduino "https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Arduino.h"
click node_print "https://github.com/adwuard/trackerkb/blob/master/software/src/Print.cpp"
click node_print_api "https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Print.h"
click node_printable "https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Printable.h"
click node_wstring "https://github.com/adwuard/trackerkb/blob/master/software/src/includes/WString.h"
click node_stream "https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Stream.h"
click node_cnc "https://github.com/adwuard/trackerkb/tree/master/hardware/Enclosure/1_CNC-Case"
click node_acrylic "https://github.com/adwuard/trackerkb/tree/master/hardware/Enclosure/2_Acylic-Case"
click node_printed "https://github.com/adwuard/trackerkb/tree/master/hardware/Enclosure/3_3D-Printed-Case"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_keys,node_pcb,node_rp2040,node_hub,node_teensy,node_cnc,node_acrylic,node_printed,node_user toneBlue
class node_firmware_main,node_hid,node_usb_callbacks,node_usb_config toneAmber
class node_cdc_stub,node_arduino,node_print,node_print_api,node_printable,node_wstring,node_stream toneMint
class node_host,node_tracker_fw toneIndigo
```

## Components

### Hardware

- [Key switches](https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB): `hardware/Tracker-Keyboard-PCB`
- [Keyboard PCB](https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB): `hardware/Tracker-Keyboard-PCB`
- [RP2040 MCU](https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB/datasheets_and_footprints/RP2040): `hardware/Tracker-Keyboard-PCB/datasheets_and_footprints/RP2040`
- [USB hub](https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB): `hardware/Tracker-Keyboard-PCB`
- [Teensy tracker](https://github.com/adwuard/trackerkb/tree/master/hardware/Tracker-Keyboard-PCB/datasheets_and_footprints/DEV-16771): `hardware/Tracker-Keyboard-PCB/datasheets_and_footprints/DEV-16771`
- [CNC enclosure](https://github.com/adwuard/trackerkb/tree/master/hardware/Enclosure/1_CNC-Case): `hardware/Enclosure/1_CNC-Case`
- [Acrylic enclosure](https://github.com/adwuard/trackerkb/tree/master/hardware/Enclosure/2_Acylic-Case): `hardware/Enclosure/2_Acylic-Case`
- [3D-printed enclosure](https://github.com/adwuard/trackerkb/tree/master/hardware/Enclosure/3_3D-Printed-Case): `hardware/Enclosure/3_3D-Printed-Case`

### Keyboard firmware

- [Key scanning and mapping](https://github.com/adwuard/trackerkb/blob/master/software/src/pico-m8-keyboard.cpp): `software/src/pico-m8-keyboard.cpp`
- [TinyUSB keyboard HID](https://github.com/adwuard/trackerkb/tree/master/software/src/TinyUSB_Mouse_and_Keyboard): `software/src/TinyUSB_Mouse_and_Keyboard`
- [USB state callbacks](https://github.com/adwuard/trackerkb/blob/master/software/src/includes/usb.h): `software/src/includes/usb.h`
- [TinyUSB device config](https://github.com/adwuard/trackerkb/blob/master/software/src/includes/tusb_config.h): `software/src/includes/tusb_config.h`

### Firmware support

- [CDC compatibility stub](https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Adafruit_USBD_CDC-stub.h): `software/src/includes/Adafruit_USBD_CDC-stub.h`
- [Arduino compatibility](https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Arduino.h): `software/src/includes/Arduino.h`
- [Print implementation](https://github.com/adwuard/trackerkb/blob/master/software/src/Print.cpp): `software/src/Print.cpp`
- [Print API](https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Print.h): `software/src/includes/Print.h`
- [Printable interface](https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Printable.h): `software/src/includes/Printable.h`
- [String compatibility](https://github.com/adwuard/trackerkb/blob/master/software/src/includes/WString.h): `software/src/includes/WString.h`
- [Stream compatibility](https://github.com/adwuard/trackerkb/blob/master/software/src/includes/Stream.h): `software/src/includes/Stream.h`

### Other components

- **Keyboard user**
- **USB host**
- **Headless tracker firmware**

## Connections

- Keyboard user → Key switches: presses (evidence: `README.md`)
- Key switches → Key scanning and mapping: GPIO input (evidence: `software/src/pico-m8-keyboard.cpp`)
- Key scanning and mapping → TinyUSB keyboard HID: presses/releases (evidence: `software/src/pico-m8-keyboard.cpp`)
- TinyUSB keyboard HID → USB host: sends HID (evidence: `README.md`)
- Keyboard PCB → RP2040 MCU: hosts MCU (evidence: `README.md`)
- Keyboard PCB → Key switches: connects switches (evidence: `README.md`)
- USB hub → Teensy tracker: connects USB (evidence: `README.md`)
- USB hub → RP2040 MCU: connects USB (evidence: `README.md`)
- Teensy tracker → Headless tracker firmware: runs firmware (evidence: `README.md`)
- Key scanning and mapping → USB state callbacks: includes callbacks (evidence: `software/src/pico-m8-keyboard.cpp`)
- Key scanning and mapping → CDC compatibility stub: includes stub (evidence: `software/src/pico-m8-keyboard.cpp`)
- Arduino compatibility → Print API: includes API (evidence: `software/src/includes/Arduino.h`)
- Print implementation → Arduino compatibility: uses compatibility (evidence: `software/src/Print.cpp`)
- Print API → String compatibility: uses strings (evidence: `software/src/includes/Print.h`)
- Print API → Printable interface: uses interface (evidence: `software/src/includes/Print.h`)
- Stream compatibility → Print API: aliases to (evidence: `software/src/includes/Stream.h`)
- CNC enclosure → Keyboard PCB: encloses assembly (evidence: `README.md`)
- Acrylic enclosure → Keyboard PCB: encloses assembly (evidence: `README.md`)
- 3D-printed enclosure → Keyboard PCB: encloses assembly (evidence: `README.md`)