nudelta: an open source replacement for the NuPhy Console on three keyboard models

nudelta exists because NuPhy's own console is closed source

nudelta is an open source alternative to the NuPhy Console, built by reverse engineering the USB protocol that the keyboards speak. The motivation is straightforward: the vendor console is the only supported way to change keymaps on some NuPhy boards, and it is proprietary software for a piece of hardware you already own. The README is careful about its legal and technical position. It states that NuPhy is a registered trademark of NuPhy Studio, that nudelta is an unofficial product and is not affiliated with NuPhy Studio, and that the project only supports Air60, Air75, and Halo75 V1. The audience is Linux, macOS, and Windows users with one of those three boards who want remapping without installing a vendor application, plus people who simply prefer a text file they can keep in version control over a vendor GUI.

The README lists what is missing as plainly as what is there

Most reverse engineering projects advertise. This one enumerates its gaps. There are no macros. There is no multi-layer remapping for the Air60, and no support for other keyboards at all, because the author does not have them. There is no support for keyboards that do not use the NuPhy Console protocol, including the Air75 V2, V3 and HE, because those speak a different protocol. There is no RGB control, with the comment that the author does not need that personally. The README then says contributions are appreciated for all of these gaps. That framing tells you what kind of project this is: a working tool with a clear boundary, not a product roadmap, and the one-line summary of the supported hardware is short enough to memorise: Air75 V1, Air60 V1 with limited support, and Halo75 V1, on Windows 10 or newer, macOS 11.3 or newer, and Linux.

Keymaps load from a yml file with a flat key map

The configuration format is a YAML file with a single top level object named keys, mapping physical keys on the board to their replacements. The minimal example in the README is two lines:

keys:
    capslock: esc

That is the whole schema. The physical keys available for remapping are listed in per-board index files, for example `res/Air75/indices_win.yml` for the Windows mode of the Air75, and the replacement keycodes live in `res/Air75/default_keymap_win.yml`. The existence of a Windows-specific index file is a small but real constraint: the remappable set depends on the mode the keyboard is in, so a profile written for one mode may not map cleanly in another. The repository also ships `example.yml` as a worked profile. Because the format is a plain text mapping of key names to key names, a profile is diffable, reviewable, and easy to keep alongside the rest of a dotfiles repository, which is the practical advantage over a vendor tool where the layout lives in a binary blob.

The CLI covers loading, dumping, and resetting keymaps

Beyond the GUI, the CLI is where the tool earns its keep, and the README lists three capabilities: loading and saving keymap modifications from a `.yml` configuration file, backing up and dumping keymaps to binary formats, and dumping keymaps to a human-readable hex format. Loading a custom profile is one flag:

nudelta -l ./donns_remap.yml

and resetting the board to its default keymap is another:

nudelta -r

The hex dump format is what makes the binary backup useful to a human, because a hex dump of a keymap is something you can diff and read when a profile does not do what you expected. The permissions story differs by platform and the README says so plainly. On Linux you may need sudo. On macOS you need to grant Input Monitoring permission to whichever Terminal host you run the tool from, most likely Terminal.app. On Windows no special permissions are required, as far as the author can tell, which is the honest phrasing of someone who cannot test every configuration.

Building it means a C++ core, an Electron shell, and five toolchains

The architecture is visible in the repository layout and the package scripts. There is a native side built through CMake into `lib`, `include`, and `src`, which is where the USB protocol work lives, and a user interface under `ui` that is bundled with Rollup and shipped as an Electron app. The build requirements are a C++17 compiler, CMake, pkg-config, Node 22 or newer with Yarn, and Ruby 2.0.0 or newer for glue scripts. The documented build sequence is:

git clone https://github.com/donn/nudelta
cd nudelta
rm -rf build
yarn
yarn build_native # CLI / Library
yarn build # GUI

`yarn build_native` produces the command line tool and library, `yarn build` produces the GUI, and the package scripts confirm the split, with `build` running the native build, the UI build, and electron-builder with publishing disabled. The Linux AppImage lands under `./dist` and the Mac app under `./dist/mac`. There is also a Nix path, `nix run github:donn/nudelta`, and a NixOS udev rule in the README for hidraw access.

The NixOS udev rule is the step most people will miss

Running the tool on Linux as a regular user needs a device rule, and the README spells it out:

services.udev.extraRules = ''
  # Hidraw for Seated Users (This rule requires a reboot)
  KERNEL=="hidraw*", SUBSYSTEM=="hidraw", TAG+="uaccess"
'';

The tag gives the hidraw device to the logged-in user rather than to root, which is what removes the need for sudo on Linux for the common case. The comment in the README notes that the rule requires a reboot. That is a small but characteristic detail of this project: the operation depends on raw HID access, so the operating system has to hand the device over explicitly, and on macOS the equivalent gate is the Input Monitoring permission prompt. The repository also includes a `Dockerfile` for Linux builds based on a manylinux image with CMake, Node, libudev development headers, and Ruby installed, which is a convenience for producing the AppImage in a container rather than on your workstation.

GPL-3.0 and a version below 1.0

The project is licensed under the GNU General Public License v3 or, at your option, any later version, and the package metadata records `GPL-3.0-or-later`. For a hardware utility that talks to your own keyboard, that is a reasonable choice for a reverse engineered project, and it is worth reading alongside the trademark statement at the top of the README, since the licence covers the software while the NuPhy name and the hardware stay with their owner. The version number tells the other story: 0.10.0, released on 2026-06-13, after 0.9.0 in October 2025 and 0.8.0 in March 2025. A pre-1.0 version number here signals that the CLI flags and the profile format may still change. The repository also carries a `Changelog.md`, an `OSAcknowledgements.txt`, a `flake.nix`, and a `util/usb` directory holding hex dumps for the Air96 V1 and Halo96 V1 keymaps, with pull requests for support for those boards invited.

Editorial conclusion

nudelta is worth trying if you own an Air75 V1, an Air60 V1, or a Halo75 V1 and want keymap changes without the vendor application or a Windows machine. It is the wrong tool for every other NuPhy board, since the project states those use a different protocol, and it is the wrong tool if you need macros or RGB control. Before you commit to it, confirm your exact board revision against the supported list in the README, then try the CLI reset and a single key remap from a `.yml` profile before touching your daily layout, because a mistaken profile write is as easy to make as a mistaken one in any other remapper.

Frequently asked questions

Official sources

1. donn/nudelta on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases