Q60_HHKB

Q60 HHKB

Happy Hacking layout on a Keychron Q60 (wired, QMK / VIA)
Interactive guide

hhkb_q60.py remaps a regular wired Keychron Q60 (USB 3434:01C0) to the HHKB Professional layout. It writes the keymap over the VIA raw-HID protocol, the same way usevia.app does. That means:

no firmware flashing
the layout is stored on the keyboard and works on any computer
you can still open and edit the result in VIA

Python 3 on Linux. No extra packages.

What changes

The Q60 is already physically an HHKB layout. The script changes three things:

Backspace. The key above Enter types Backspace. Keychron ships it as Delete. Fn + that key types Delete.
Fn layer. Fn now works like an HHKB Pro 2: arrows, Home/End, PgUp/PgDn, volume, PrtSc and numpad keys.
Lighting. Keychron’s RGB lighting and NKRO controls move to Fn + Right Shift. A real HHKB has no backlight, so this pair is otherwise unused.

Hold Fn

$Fn layer: Esc=Power, 1-= = F1-F12, \=Ins, `=Del, Tab=Caps, I/O/P=PrtSc/ScrLk/Pause, [=Up, BS=Del, A/S/D/F=Vol-/Vol+/Mute/Eject, H/J=*,/, K/L=Home/PgUp, ;/'=Left/Right, Enter=Numpad Enter, N/M=+/-, ,/.=End/PgDn, /=Down$

Group	Keys
Arrows and paging	`Fn` + `[` ↑ · `/` ↓ · `;` ← · `'` → · `K` Home · `,` End · `L` PgUp · `.` PgDn
Editing	`BS` Backspace · `Fn` + `BS` Delete · `Fn` + ` Delete · `Fn` + `\\` Insert · `Fn` + `Tab` Caps Lock
Function row	`Fn` + `1`…`0` F1–F10 · `-` F11 · `=` F12
Media	`Fn` + `A` Vol − · `S` Vol + · `D` Mute · `F` Eject (macOS)
Numpad	`Fn` + `H` * · `J` / · `N` + · `M` − · `Enter` Numpad Enter
System	`Fn` + `I` PrtSc · `O` ScrLk · `P` Pause · `Esc` Power

Hold Fn + Right Shift

Lighting layer: Tab=RGB on/off, Q/A=next/previous effect, W/S=brighter/dimmer, E/D=hue, R/F=saturation, T/G=effect speed, N=NKRO toggle

Key	Up	Key	Down
`Tab`	Backlight on / off
`Q`	Next effect	`A`	Previous effect
`W`	Brighter	`S`	Dimmer
`E`	Hue forward	`D`	Hue back
`R`	More saturation	`F`	Less saturation
`T`	Faster effect	`G`	Slower effect
`N`	NKRO on / off

Mac / Windows switch

The slide switch on the side picks the base layer. Only the bottom row differs.

Position	Bottom row
Mac (layer 0)	`Option` `Cmd` `Space` `Cmd` `Option`
Windows (layer 1)	`Win` `Alt` `Space` `Alt` `Win`

Usage

1. Allow access to the keyboard. On Linux, only root can write to the keyboard’s VIA interface by default. To allow it until you unplug the keyboard (the hidraw number can vary; the script prints the right one if access fails):

sudo chmod a+rw /dev/hidraw9

To allow it permanently, which also lets usevia.app connect in Chrome:

echo 'KERNEL=="hidraw*", ATTRS{idVendor}=="3434", ATTRS{idProduct}=="01c0", MODE="0660", TAG+="uaccess"' \
  | sudo tee /etc/udev/rules.d/99-keychron-q60.rules
sudo udevadm control --reload && sudo udevadm trigger

2. Run the script.

python3 hhkb_q60.py backup             # save every layer to q60_backup_<timestamp>.json
python3 hhkb_q60.py apply              # back up, write the HHKB layout, read it back to verify
python3 hhkb_q60.py restore FILE.json  # write a backup back to the keyboard

apply always saves a backup first. To undo the change, restore the backup it made.

3. Fine-tune in VIA (optional). Open usevia.app in Chrome or Chromium and authorize the Q60. VIA’s layers line up with this layout:

VIA layer	Use
0	Mac
1	Windows
2	Fn
3	Fn + Right Shift
4, 5	Empty, free for your own keys

Files

File	What it is
`hhkb_q60.py`	The remapping script
`q60-hhkb-guide.html`	Interactive version of this guide, also served on GitHub Pages
`assets/`	Images used in this README