first commit

README.md

@@ -0,0 +1,52 @@
+# 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>).