Skip to content

HHKB Classic Custom Firmware — 2026.11.17

Latest

Choose a tag to compare

@aroum aroum released this 17 Nov 04:33

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() and hhkb_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 atomic PRIMASK instructions (__get_PRIMASK(), __disable_irq(), __set_PRIMASK()), cutting 120 Flash-veneer jumps per pass.
  • Task Starvation Protection:
    • Maintained non-blocking overdue timer notification handling (ulTaskNotifyTake(pdTRUE, 0)) ensuring the lower-priority FreeRTOS USB task is never starved.

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 via uv 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.

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 reset safety 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.

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.
  • Calibration Monitor:
    • Live ASCII progress bar and percentage tracker:
      [CAL] [====> ] 45% (27/60) | Key R1 C3 peak: 2840 (base: 1120)
  • 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 Hz during 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.

Community Pull Requests & Build Tooling

  • PR #2 (@mmcx): Ignore commented-out #define directives in KEYBOARD_DIR/config.h during Vial header preprocessing.
  • PR #3 (@mmcx): Automatically prefer locally built picotool from CMake _deps with automatic fallback to system binaries in build_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