$ show UltimateHackingKeyboard/firmware
This repository contains the production firmware for the Ultimate Hacking Keyboard (UHK) family, including the UHK60, UHK80, and companion modules (trackball, trackpoint, keycluster) plus a USB dongle. It implements the complete embedded software stack for a highly configurable split ergonomic keyboard: USB HID and Bluetooth LE HID transport, a rich macro engine with layers, chording, autoshift, sticky modifiers, and secondary roles, per-key RGB backlighting, OLED display with LVGL-based UI, battery management, and inter-device communication (UART, I2C, SPI). The firmware supports two hardware generations via conditional compilation (legacy NXP MCUXpresso SDK on the right half, Zephyr RTOS on the device half and dongle). Architecturally, the codebase is organized into distinct compilation targets: the right-hand keyboard half (right/), the left-hand half and dongle (device/), shared libraries (shared/), and peripheral modules (trackball/, trackpoint/, keycluster/). Central design patterns include an event-driven main loop with an event scheduler, a postponer system for delayed key actions, a versioned binary configuration parser, a lock-free messenger queue for inter-device messaging, and a double-buffered HID report pipeline. The firmware exposes a large USB vendor command set for reconfiguration, debugging, and firmware updates, and includes an embedded test suite that simulates key inputs and validates USB reports. The code demonstrates strong engineering craftsmanship with clean abstractions, extensive use of state machines, and careful resource management in a constrained embedded environment. While the dual-platform support introduces some conditional compilation complexity, the core modules are well-isolated and many patterns (event scheduler, postponer, UART parser, config parser, double buffer) are directly reusable in other embedded projects. The repository is actively maintained with a comprehensive test suite and CI pipeline, though the Zephyr migration is ongoing and some legacy code paths remain.
The LLM identified 5 files worth highlighting for reuse:
Implements a generic postponer (event queue) that delays key events for chording, autoshift, and oneshot handling. Events are added with a time delay and played back by the main loop. The design is isolated (only depends on timer and a simple linked list) and could be extracted for any embedded system requiring delayed or ordered event processing.
A versioned binary configuration parser with dry-run mode and detailed error codes. It reads a buffer, validates the data model version, and extracts fields for keymaps, macros, host connections, mouse settings, and module configurations. The pattern of conditional field extraction based on version is cleanly separated and reusable for any embedded device with upgradeable binary configuration.
A lock-free, fixed-size FIFO queue using a memory pool for inter-device message passing (left half, right half, dongle). It supports multiple producer/consumer contexts without mutexes by using atomic head/tail pointers. This is a textbook implementation of a lock-free queue that can be reused in any embedded project requiring safe interrupt-driven communication.
A generic C++ template for double buffering used for HID reports. Provides a clean interface with swap_sides() and access to active/background buffers. The template is self-contained, header-only, and can be applied to any data structure that needs atomic swapping between producer and consumer contexts in embedded firmware.
Implements a bitmask-based event scheduler that drives the main loop. Events are set via SetEvent() and cleared after processing. The scheduler supports rescheduling and unscheduling. This is a minimal, efficient pattern for event-driven firmware that could be reused in any bare-metal or RTOS project needing a lightweight event loop.