Trkey Macropad

Overview

This is a compact 3×3 macropad built with Raspberry Pi Pico / RP2040, running CircuitPython/Arduino. It connects via USB using the Adafruit HID library, allowing you to assign keyboard shortcuts, media keys, and macros. An OLED display shows layer and status information for easy feedback.

• OLED Display: Amazon Link
• PCB Design: OSH Park Project
• Web Key Mapper: trinibos1/Trkey_mapper

Update

• UF2 file is old but code is up to date
• wireless trkey macropad has started development

---

Changelog / Update Log

• 2026-02-14
  • Added startup boot animation to main Arduino sketch (arduino/Trkey_macro.ino) with 3x3 box reveal, TRKEY splash, and version text.
  • Added dedicated WebSerial + USB connection guide (WEBSERIAL_CONNECTION.md).
  • Improved Arduino firmware compatibility and robustness:
    • HID report ID fixes for keyboard/media reports.
    • Numeric key token support ("1".."0") plus legacy aliases ("ONE".."ZERO").
    • RAM-backed layers.json handling when LittleFS is unavailable.
    • Safer JSON fallback behavior and macro ID parsing improvements.
    • USB descriptor naming updates for Trkey product/manufacturer.

Features

• 3×3 Cherry MX Brown Hyperglide 45g tactile mechanical key matrix
• USB HID support (no Bluetooth)
• OLED display for layer/status feedback
• Tap/Hold functionality for advanced key actions
• Multiple layers for extended shortcut options
• Fast and responsive keypresses
• Simple wiring: switches connect directly to GND
• All-in-one UF2: CircuitPython, libraries, and firmware code included

---

Hardware

Component	Details
Microcontroller	Raspberry Pi Pico / RP2040
Switches	9x Cherry MX Brown Hyperglide 45g tactile
Display	OLED I2C 128x32 (link)
PCB	Custom 3×3 macropad (link)
Power	USB only

PCB

---

Firmware

UF2 Firmware:

• macropad.uf2 — stable, all-in-one with CircuitPython, libraries, and code
• dev_firmware.uf2 — development version for testing new features

Key Features: Tap/Hold, Layers, Media keys

Arduino IDE firmware (C/C++)

If you want to move from CircuitPython to Arduino IDE, use arduino/Trkey_macro.ino.

Startup animation is now included in the main sketch (arduino/Trkey_macro.ino).

For beta experiments, you can still use arduino/Trkey_macro_Beta.ino (also provided as arduino/Trkey_macro Beta.ino).

This sketch keeps the same behavior as code.py:

• 3x3 key scanning with debounce + key repeat
• Layer functions: MO(x), TO(x), TT(x), DF(x)
• Media keys + keyboard combos + text macros (MACRO_n)
• Text macro typing fallback is ASCII-only (A-Z, a-z, 0-9, space, newline)
• OLED layer/key UI (with highlighted key and boxed grid)
• Serial command protocol for LIST, GET, PUT, DEL, RELOAD
• Macros can be defined on any layer; duplicate IDs use the last parsed definition

Required Arduino libraries:

• Adafruit SSD1306
• Adafruit GFX Library
• TinyUSB from the RP2040 board core (Adafruit_TinyUSB_Arduino)
• ArduinoJson
• LittleFS (included with RP2040 core)

Recommended board core: Raspberry Pi Pico/RP2040 (Earle Philhower core).

RP2040 TinyUSB note (important):

• Do not call tusb_init() in your sketch (the RP2040 Arduino core already initializes TinyUSB).
• Prefer the TinyUSB bundled with the RP2040 core (Adafruit_TinyUSB_Arduino).
• If you installed Documents/Arduino/libraries/Adafruit_TinyUSB_Library, remove it to avoid library conflicts.

Documentation:

• WEBSERIAL_CONNECTION.md — USB CDC/WebSerial command flow, upload handshake, persistence behavior, and troubleshooting.
• layers.json in repo root — example keymap/profile format used by firmware and mapper.

---

Usage

1. Flash the UF2 (macropad.uf2 or dev_firmware.uf2) onto your Pico — everything is included, no additional setup needed.

2. Plug in the macropad — ready to use.

3. Use your macropad:

   • Tap switches for primary actions
   • Hold switches for secondary actions or layer switching
   • OLED displays the current layer and status

---

Companion App (Beta)

This beta feature is implemented in Arduino firmware (arduino/Trkey_macro.ino) and an optional PC CLI app (pc_companion/trkey_music_companion.py).

• The macropad still works fully without the companion app.
• Companion mode adds now-playing OLED metadata and app events.
• You can switch to music layer by name with: MODE music.

Quick start:

1. Flash Arduino beta firmware (arduino/Trkey_macro_Beta.ino).
2. Flash Arduino firmware (arduino/Trkey_macro.ino).
3. Run companion app: python pc_companion/trkey_music_companion.py --port <PORT>.
4. In app CLI, type:
   • music to load the music layer by name.
   • np Song|Artist|45|180|Spotify to update metadata.

Supported companion key tokens (in layers.json):

• APP_PLAY_PAUSE
• APP_NEXT
• APP_PREV
• APP_MUTE
• APP_VOL_UP
• APP_VOL_DOWN
• APP_SEEK_FWD_10
• APP_SEEK_BACK_10

APP_* keys emit APP_EVENT <token> on serial and media actions also fallback to HID media controls.

Web-Based Key Mapper

Customize your macropad's key bindings using the web-based key mapper:

• Full key remapping: Assign single keys or complex shortcuts to any of the 9 keys
• Multi-layer support: Configure multiple layers for extended functionality
• Macro support: Create macros for complex sequences
• Web Serial API: Communicate directly with your macropad via the browser

Access the key mapper here: trinibos1/micropad_web

---

Contributions

Contributions are welcome to improve the key library, including:

• Adding new key mappings or shortcuts
• Optimizing tap/hold behavior
• Enhancing multi-layer support
• Improving key response and stability

Submit issues or pull requests to collaborate.

🙌 Thanks

Huge thanks to Adafruit for their amazing hardware and the CircuitPython + library ecosystem.
Without their work, projects like this macropad wouldn’t be possible. 💜

License

MIT License – see LICENSE for details.

contact

Email: [email protected]