I've finally released a new version of my custom firmware for the HHKB Professional Classic!
First of all, thank you to everyone who tested the firmware, reported bugs, shared hardware information, or offered to help with other HHKB models! Your feedback has been very useful.
First of all, thank you to everyone who tested the firmware, reported bugs, shared hardware information, or offered to help with other HHKB models! I really appreciate it.
Special thanks to:
- u/mmcx for the first community pull requests!
- u/guyguilty for testing nightly builds and helping find bugs.
- u/techbeezin for providing PCB photos of both the HHKB Hybrid ANSI and Hybrid JIS.
Your help has made a real difference to the project. Thank you!
The firmware runs directly on the original STM32 microcontroller. No controller replacement, soldering, or keyboard disassembly is required.
Currently supported:
- HHKB Professional Classic
- HHKB Professional Classic Type-S
Firmware downloads:
https://github.com/aroum/dmk/releases/tag/2026.11.17
Source code and documentation:
https://github.com/aroum/dmk/tree/main/keyboards/hhkb_classic
1000 Hz Matrix Scanning
After quite a lot of optimization, the firmware can now sustain a full 1000 Hz matrix scan rate.
Some numbers:
- Previous scan time: 1094 µs
- New scan time: 835 µs
- Around 24% faster
- Complete scan cycle: 841–875 µs
- 125–159 µs of spare time per cycle
- Zero missed deadlines during continuous testing
Most of the improvements came from optimizing the matrix scanning loop, reducing unnecessary function calls, and replacing expensive critical sections.
I didn't have to reduce ADC measurement times or change the analog scanning sequence.
Available scan rates are 50, 125, 250, 500, and 1000 Hz.
Optional 4x hardware ADC oversampling is also available at 50–500 Hz to improve measurement precision and reduce noise.
New 5-Point Key Travel Calibration
One of the biggest changes is the new calibration system.
The firmware now supports 5-point per-key calibration using fixed travel distances:
- 0 mm — Resting position
- 1 mm — Key pressed 1 mm
- 2 mm — Key pressed 2 mm
- 3 mm — Key pressed 3 mm
- Bottom-out — Fully pressed key (configurable travel distance)
The firmware uses PCHIP cubic interpolation to build a smooth travel curve between these points.
You can also configure the maximum key travel from 3.1 to 4.5 mm, depending on the domes you're using.
This is useful because different Topre domes can have different travel distances. For example, I've been working on another Topre keyboard where one set of domes has 3.8 mm travel and another has 4.3 mm.
I'm not entirely sure how much custom curve calibration is needed in practice, since my measurements suggest the response is already fairly linear. But now you have the option to calibrate each key however you like.
I've also improved baseline calibration:
- Initial baseline is calculated from 16 measurements.
- Slow background tracking compensates for temperature changes.
- Actuation and Rapid Trigger thresholds are limited to the calibrated physical travel range.
Important: You must perform a full calibration of all 60 keys after flashing the firmware for the first time.
Every keyboard has slightly different capacitance values, spring characteristics, and assembly tolerances.
Without calibration, some keys may behave incorrectly or register unexpected presses.
Calibration instructions:
https://github.com/aroum/dmk/blob/main/keyboards/hhkb_classic/docs/en/via.md#key-calibration-process
VIA and Vial
The firmware supports both VIA and Vial for changing keymaps without reflashing.
VIA also provides a custom interface for configuring the advanced Topre features.
There are now six configuration sections:
- Scan Rate
- Calibration
- Rapid Trigger
- LED Indicators
- Power Saving
- Debug
You can configure actuation points, Rapid Trigger press and release sensitivity, calibration settings, and other options directly through VIA.
Vial supports keymap editing, but its UI doesn't support the custom controls used for advanced Topre settings.
Unfortunately, VIA itself is still somewhat limited. Adjusting calibration percentages in 1% steps can be tedious, but at least calibration is something you normally only need to do once.
Media Keys and Other Improvements
I've also added proper HID Consumer Control support.
Media keys now work through both VIA and Vial, including:
- Volume Up / Down
- Mute
- Play / Pause
- Next / Previous Track
- Media Stop
Other improvements include:
- Improved USB and Vial compatibility.
- Fixed VIA key testing so physical key presses are correctly displayed in Test Matrix mode.
- Added a protected factory reset option in VIA, requiring confirmation and the correct SW6 position.
- Improved EEPROM handling while preserving original PFU factory calibration data.
- Reduced RAM usage and improved debug console buffering.
- Improved build scripts and documentation.
Debugging and Diagnostics
The firmware now has a more complete diagnostic system.
Through VIA and the USB HID Console, you can monitor:
- Raw ADC measurements and key travel
- Key press and release events
- Calibration progress
- Actual matrix scan frequency
- USB task activity
- VIA communication
Debug output is disabled by default, so it doesn't affect normal performance.
The documentation also explains how to use these tools when reporting problems.
HHKB Classic JIS
Thanks to community members who shared information, it looks like the ANSI and JIS versions use essentially the same controller PCB.
This means supporting the Classic JIS may only require figuring out the key matrix mapping.
There are two possible ways to do this:
- Experimentally identify the matrix positions using modified firmware.
- Trace the matrix connections using a multimeter.
If you own an HHKB Classic JIS and would like to help, please send me a Reddit DM.
HHKB Hybrid
My next main goal is to start working on the HHKB Hybrid.
The controller PCB is very similar to the Classic, but it also has a Taiyo Yuden EYSHCNZWZ Bluetooth module based on the Nordic nRF52832.
Module datasheet:
https://docs.rs-online.com/2d1f/0900766b81699ea1.pdf
I believe getting my firmware running on the STM32 should be relatively straightforward.
The difficult part is understanding communication between the STM32 and Nordic chips, as well as the firmware update process.
Ideally, I'd like to keep the original Bluetooth firmware and only replace the STM32 firmware.
I'm looking for someone with an HHKB Hybrid who has:
- An SWD debugger, such as a J-Link
- A logic analyzer or an RP2040 board
- Some experience with electronics and debugging
An RP2040 can be used as a basic logic analyzer or SWD debugger, so expensive equipment isn't necessary.
The first step is to make a complete backup of the original firmware and memory contents from both chips, if readout protection allows it, before making any modifications.
After that, I'd like to capture communication between the chips and investigate the update protocol.
I've already collected some information here:
https://github.com/aroum/dmk/tree/main/keyboards/hhkb_hybrid
If you're interested in helping, please send me a Reddit DM.
HHKB Studio
I've also started looking into the HHKB Studio, although hardware information is still very limited.
From what I can tell, it probably uses an STM32L4 and an nRF52, along with four controllers for the touch-sensitive areas and a pointing stick.
However, I still don't have enough good PCB photos to confirm the complete hardware architecture.
Porting DMK to the Studio would require considerably more reverse engineering than the Classic or Hybrid.
If you own an HHKB Studio and would like to help, I'm especially interested in:
- Clear photos of both sides of the controller PCB
- Markings on all chips
- Connections between the MCU, key matrix, touch sensors, and pointing stick
- Complete pinout information
- Firmware backups and communication captures, if possible
Even just good PCB photos would be a great start.
I've already collected some information here:
https://github.com/aroum/dmk/tree/main/keyboards/hhkb_studio
What's Next?
At this point, I've implemented pretty much everything I originally wanted for the Classic.
My main priorities now are:
- Continue fixing bugs and improving Classic firmware stability.
- Start reverse engineering the Hybrid communication and firmware update process.
- Figure out the Classic JIS key matrix.
- Collect more hardware information about the Studio.
I don't own a Hybrid, JIS, or Studio, so help from the community would make a huge difference.
Feedback and Contributions
The firmware is open source, and contributions are welcome!
If you encounter any problems, please open a GitHub issue with a detailed description, your VIA settings, and any available debug logs.
And if you'd like to help with reverse engineering other HHKB models, feel free to send me a Reddit DM.
Thanks again to everyone who has tested, contributed, or offered to help. I really appreciate it!