Drive every key LED of a NuPhy Air V3 keyboard from the browser, on stock firmware. A hidden HID command (0xD8) writes a RAM RGB table and a hidden backlight effect (21) renders it. This repo packages the working recipe as a dependency-free TypeScript library, a probe and demo page, and a written protocol reference.
Verified on an Air75 V3 ANSI (firmware 1.0.16.6, 84 key LEDs) and an Air100 V3 ISO (firmware 1.0.6.6, 100 key LEDs), with about 30 fps streaming. Other boards of the same protocol family are expected to work: the LED count is read from the device, and the survey builds the index map for your layout.
pnpm install
pnpm devOpen the served page in a Chromium browser. Close the official NuPhy IO app first (it holds exclusive HID access), plug the keyboard in wired mode, then: Connect, Arm, Static rainbow. If arming fails, update the firmware through NuPhy IO: effect 21 appeared in 1.0.16.6 (Air75 V3) and 1.0.6.6 (Air100 V3), the July 2026 "execution logic of the lighting" update. A future firmware could change or remove it: the versions above are the tested ones.
import { pickDevice, AIR75_V3_ANSI } from "./src/protocol";
const air = await pickDevice(); // user gesture required
await air.arm(); // saves the current lighting, arms effect 21
const rgb = new Uint8Array(3 * air.ledCount);
rgb.set([255, 0, 80], 3 * AIR75_V3_ANSI.KeyA!);
await air.paint(rgb); // RAM only, streamable
await air.restore(); // hands the original lighting backsrc/protocol/: transport (frames, session-key XOR, checksum), device class (handshake, state read/write with the firmware's pacing constraints, effect-21 arming with verification, chunked table writes, restore), layout maps.src/app/andindex.html: the demo page: a connection wizard with actionable error hints, then a clickable virtual keyboard (paint by click or drag, selection-driven color and brightness, rainbow and wave demos, typing-glow and ripple modes reacting to your key presses), and the interactive survey that builds the index map for your layout as you type.src/layouts/*.json: one file per supported board and variant, auto-discovered and picked by the device's LED count. Air75 V3 ANSI and Air100 V3 ISO (AZERTY) are mapped; the page lists what exists and what is wanted, and its survey plus CONTRIBUTING.md is all it takes to add yours.PROTOCOL.md: the written reference, including the documented firmware quirks (session-key persistence, paced doubled writes, echo of unknown frames, the deferred-transmit wedge).
WebHID exists in Chromium only. The bridge is a small Node daemon that owns the HID link and exposes it on a localhost WebSocket, so Firefox, scripts, or anything speaking WebSocket can drive the LEDs.
pnpm bridgeThen use the page's "Connect via local bridge" button, or talk to ws://127.0.0.1:6645 directly: JSON ops {"op": "arm" | "restore" | "colors"}, and a binary message is an RGB table to paint (3 bytes per LED). With several NuPhy devices present (a 2.4G dongle answers for another board), pin one with NUPHY_BRIDGE_PID=1028 pnpm bridge.
macOS gates HID access to keyboards: grant Input Monitoring to your terminal app (System Settings, Privacy & Security) when the first run fails with not permitted.
The firmware-side analysis that established 0xD8 and effect 21 is the work of pda/kbvu (Air75 V3, including a side-bar firmware patch) and gig3m/nuphykit (Air100), both MIT. This repo contributes an independent web implementation, the session-key handling, the layout survey, and the consolidated reference.
NuPhy® is a registered trademark of NuPhy Studio. This is an unofficial project, not affiliated with or endorsed by NuPhy; the name is used only to state which hardware it drives. It interoperates with keyboards its users own, was built by observing the device's HID protocol during normal use and by citing published analyses, and contains no NuPhy code, firmware images, or assets. License: MIT.