hkkb-layout-web/README.md

hkkb

A keymap editor for the HHKB Professional on Linux — what PFU's Windows/Mac-only tool does, in a browser. It reads and rewrites the keyboard over the keyboard's own USB-HID protocol; no firmware patching.

Requires

• Go 1.20+ to build — standard library only (no cgo, no Node).
• A browser.
• doas (or sudo) once, to let your user open /dev/hidraw*.

Run

./run.sh

Builds, grants device access the first time (one doas prompt), serves http://127.0.0.1:8080, and opens it. Later runs need no password.

Change the port with -port (e.g. ./run.sh -port 9000).

By hand, if you prefer: go build -o hhkb-web ./cmd/hhkb-web && ./hhkb-web.

Device access

The vendor interface is root-only by default; run.sh installs this rule for you (use sudo if you have no doas):

doas mkdir -p /etc/udev/rules.d
echo 'KERNEL=="hidraw*", ATTRS{idVendor}=="04fe", MODE="0660", GROUP="input"' | doas tee /etc/udev/rules.d/70-hhkb.rules
doas udevadm control --reload-rules && doas udevadm trigger

You must be in the input group. Then ls -l /dev/hidraw3 reads root input.

Use

It auto-detects the model and reads your keymap on connect. Click a key, pick a keycode, then Write. The Fn tab edits the Fn layer (Fn + [ → Up). Read reloads, Reset restores defaults, Save/Load are JSON, Key test highlights presses while the page is focused. Bottom-row Alt/GUI follow the keyboard's HHK/Mac mode and come from the live read.

Layout

internal/hhkb/   protocol + data, no UI, no cgo
cmd/hhkb-web/    web server + embedded UI
doc/protocol.md  the wire protocol

Protocol reverse-engineered by happy-hacking-gnu (https://gitlab.com/dom/happy-hacking-gnu).