# 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.

![editor](doc/base.png)

## 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>).