Repository navigation
Consolidated release for HHKB Professional Classic (PD-KB401*, AHHX01) and Classic Type-S (PD-KB401*SC, AHHS01) running on the stock STM32L072 microcontroller. No hardware modifications or controller replacements are required.
Important: Mandatory Key Calibration After Flashing
Although the firmware includes robust default capacitive threshold baselines, it is mandatory to perform a full custom calibration of all 60 keys immediately after flashing.
Individual PCB stray capacitance, spring tolerances, and housing assembly tensions vary across units. Running the calibration procedure guarantees precise actuation depth, reliable Rapid Trigger tracking, and eliminates ghost presses or dead zones.
Step-by-step instructions, visual matrix tracking via Key Tester, and HID console live monitoring are detailed in the official documentation:
https://github.com/aroum/dmk/blob/main/keyboards/hhkb_classic/docs/en/via.md#key-calibration-process
Headline Highlights
- Native 1000 Hz Matrix Polling: Fully optimized monolithic scan loop executing in ~835 µs, leaving over 12% timing headroom per millisecond without starving lower-priority FreeRTOS tasks.
- 5-Point Monotonic Travel Curve (PCHIP): Models physical key travel from 0.0 mm baseline up to the user-configured bottom-out depth (3.1–4.5 mm) using monotonic cubic spline interpolation with zero overshoot.
- Full Consumer & Media Keycode Support: Comprehensive HID Consumer Control mapping in Vial/VIA v3, enabling native volume, mute, playback, and transport controls across all OS platforms.
- Guarded Factory Reset in VIA: Two-step confirmation toggle with hardware DIP SW6 interlock preventing accidental wipes of custom EEPROM settings and keymaps.
- Unified Diagnostic HID Console: Standardized matrix streaming, live ASCII calibration progress bars, and execution rate monitors.
- Build System Enhancements: Includes PR contributions for automated local toolchain discovery and robust header parsing.
What's Changed
Topre Matrix Engine & 1000 Hz Polling
- Monolithic 1000 Hz Polling:
- Reduced matrix scan pass duration from 1094 µs down to 835 µs (-24%), unlocking sustained 1000 Hz matrix polling with 125–159 µs of idle headroom per millisecond.
- Zero Missed Deadlines: Matrix scanner maintains continuous 1000 Hz operation without frame slips.
- Hot-Path Optimization:
- Eliminated 120 getter calls (
hhkb_get_cal_peak()andhhkb_get_rt_key()) per scan pass by caching column pointers at the outer matrix loop. - Hoisted debug evaluation flags completely out of the inner 60-key loop.
- Replaced FreeRTOS critical sections in RAM-resident functions (
.RamFunc) with atomicPRIMASKinstructions (__get_PRIMASK(),__disable_irq(),__set_PRIMASK()), cutting 120 Flash-veneer jumps per pass.
- Eliminated 120 getter calls (
- Task Starvation Protection:
- Maintained non-blocking overdue timer notification handling (
ulTaskNotifyTake(pdTRUE, 0)) ensuring the lower-priority FreeRTOS USB task is never starved.
- Maintained non-blocking overdue timer notification handling (
Calibration & Travel Modeling
- 5-Point Calibration Curve:
- Evaluates travel across 5 reference points: 0% (0.0 mm baseline), 25%, 50%, 75%, and 100% of the user-configured bottom-out depth (3.1–4.5 mm, default 4.0 mm).
- Generates a 126-entry lookup table in RAM using Piecewise Cubic Hermite Interpolating Polynomial (PCHIP) spline math to ensure strict monotonic response without overshoot.
- Standalone Curve Visualizer: Provided
tools/ec_curve_visualizer.py(run viauv run tools/ec_curve_visualizer.py) for inspecting individual dome curves.
- Dynamic Baseline & Temperature Compensation:
- 16-Sample Averaging: Initial calibration baseline captures 16 consecutive matrix scan passes (16 ms at 1000 Hz) to calculate rock-solid resting capacitance references.
- Slow background baseline tracking continuously adapts to ambient temperature drift during non-actuated states.
- Hardware Actuation Clamping:
- Actuation points and Rapid Trigger press/release thresholds are automatically clamped to
curve[125](maximum physical bottom-out travel), preventing unreachable key states.
- Actuation points and Rapid Trigger press/release thresholds are automatically clamped to
Keycodes, VIA Controls & Media Keys
- Consumer & Media Keycodes:
- Added comprehensive translation and report handling for HID Consumer usage pages: Volume Up/Down, Mute, Play/Pause, Next/Previous Track, Media Stop, and system control keys.
- Full interoperability across VIA and Vial keymap configurations.
- VIA v3 Submenus & Dynamic Status:
- 6 dedicated submenus: Scan Rate, Calibration, Rapid Trigger, LED/RGB Indicators, Power Saving, and Debug.
- Documented WebHID polling characteristics: dynamic status labels (calibration progress, EEPROM health) refresh upon tab reload or submenu switching.
- Key Tester Matrix Mode: Switch matrix state protocol handler (
VIA_SUB_SWITCH_MATRIX_STATE) correctly mirrors physical key depressions in VIA's Test Matrix mode.
- Guarded Factory Reset:
- Dedicated reset action protected by an
Arm settings resetsafety toggle. - Hardware DIP switch interlock: reset requires DIP SW6 to be set to OFF. If SW6 is ON, firmware aborts the erase with
Set SW6 to OFF. - Clears user EEPROM sectors (starting at
0x08081500), resetting calibrations and dynamic keymaps while preserving factory PFU calibration data and firmware banks. Automatically reboots into factory defaults.
- Dedicated reset action protected by an
HID Console Diagnostics
- Standardized EC Matrix Stream:
- Real-time capacitance reporting:
[EC] R<row> C<col> : raw=<raw> base=<base> peak=<peak> travel=<norm/10>% <DN|UP> - Threshold filtering (±40 ADC units or state changes) eliminates USB buffer congestion.
- Real-time capacitance reporting:
- Calibration Monitor:
- Live ASCII progress bar and percentage tracker:
[CAL] [====> ] 45% (27/60) | Key R1 C3 peak: 2840 (base: 1120)
- Live ASCII progress bar and percentage tracker:
- Polling Rate Telemetry:
- Reports actual matrix frequency and USB task loop:
[RATE] matrix=1000 Hz (target: 1000 Hz), usb_loop=500 Hz - Idle Scheduling: Documents that
usb_loop=500 Hzduring idle is expected behavior caused by the 2 ms FreeRTOS wait timeout (ulTaskNotifyTake(..., pdMS_TO_TICKS(2))), instantly ramping to 1000 Hz on active input.
- Reports actual matrix frequency and USB task loop:
Community Pull Requests & Build Tooling
- PR #2 (@mmcx): Ignore commented-out
#definedirectives inKEYBOARD_DIR/config.hduring Vial header preprocessing. - PR #3 (@mmcx): Automatically prefer locally built
picotoolfrom CMake_depswith automatic fallback to system binaries inbuild_all.sh. - BSS & Buffer Hygiene: Expanded debug console buffer to 128 bytes and ring buffer to 256 bytes, preventing diagnostic message truncation and log interleaving.
Included Assets
dmk-hhkb-classic-classic-via.hfb: Firmware for HHKB Professional Classic (Model AHHX01, HFB version A4.50).dmk-hhkb-classic-type-s-via.hfb: Firmware for HHKB Professional Classic Type-S (Model AHHS01, HFB version A8.50).via.json: Complete VIA v3 draft definition containing layout definitions, custom Topre/EC controls, and diagnostic toggles.
Documentation Links
- Installation & Flashing Guide: https://github.com/aroum/dmk/blob/main/keyboards/hhkb_classic/docs/en/install.md
- VIA Configuration & Key Calibration: https://github.com/aroum/dmk/blob/main/keyboards/hhkb_classic/docs/en/via.md
- Diagnostics & HID Console: https://github.com/aroum/dmk/blob/main/keyboards/hhkb_classic/docs/en/debug.md
- Russian Documentation: https://github.com/aroum/dmk/blob/main/keyboards/hhkb_classic/docs/ru/via.md