donn / nudelta

Open source NuPhy Console alternative

ν∂ / Nudelta

Note: This software is in beta. NuPhy® is a registered trademark of NuPhy Studio. Nudelta is an unofficial product and is not affiliated with NuPhy Studio.

Download

An open-source alternative to the NuPhy Console created by reverse-engineering the keyboards' USB protocol.

What this has:

• Support for NuPhy Air75 and Halo75 on Windows 10+, macOS 11+, and Linux
• Loading and saving keymap modifications from a .yml configuration file
• The ability to back up and dump keymaps to binary formats (CLI)
• The ability to dump keymaps to a human-readable hex format (CLI)

What this DOESN'T have:

• Macros
  • Need to reverse engineer those.
• Support for Air60, Halo65, etc.
  • I don't have them.
• RGB Control
  • I don't need that, personally.

Contributions are super appreciated for all of these.

Running Requirements

• An x86-64 processor
• Windows 10 or higher
• macOS 11 or higher
• Linux 2.6.39 or higher with glibc 2.17 or higher.

Rosetta

The app may run under Rosetta 2.0, but a number of issues have popped up, with most getting some error messages while trying to write to the keyboard, and in one case after that error, a user's keyboard was bricked.

Proceed with extreme caution.

Build Requirements

• C++17 Compiler
  • Clang recommended for macOS/Linux
  • MSVC recommended for Windows
• Cmake
• Node 14+ with Yarn

Build

git clone https://github.com/donn/nudelta
cd nudelta
git submodule update --init --recursive
rm -rf build
yarn
yarn build-native # CLI / Library
yarn build # GUI

The Linux AppImage will be found under ./dist, and the Mac app will be found under ./dist/mac.

Using the CLI

You will need to use sudo on Linux. On macOS, you will need to grant Input Monitoring permissions to whichever Terminal host you're using to run Nudelta, likely Terminal.app.

No special permissions are required on Windows as far as I can tell.

Load a custom profile

nudelta -l ./donns_remap.yml

The configuration .yml file is simple: there's a top level object called "keys": which is a map of physical keys on the actual keyboard to their replacements:

keys:
    capslock: esc

See example.yml for a profile and somewhat more detailed examples.

You can find a list of:

• Replaceable keys (for the Windows mode) in res/air75/indices_win.yml.
• Replacement keycodes in res/air75/default_keymap_win.yml.

Reset keymap to default

nudelta -r

License

The GNU General Public License v3 or, at your option, any later version. Check 'License'.

nudelta's Issues

[Apple Silicon] Keyboard unusable after failed remap

Version

0.7.2

Operating System

MacOS 13.5
but it doesn't work for everyone

Description

I instaled the app on my mac m1 and try to set up key, after save I get an error that the shortcut can't save and now my keyboard don't connect to any device, light is not on, reset (fn, tab, r) can't be helped
I also try to connect via a console on Win but device didn't detect

When I try to update firmware I always see text waiting and nothing happen 😭

[Support] Air60

Hello!

I have an Air60 and I'm willing to help support it.

Just like the others, I too have read your post about how to do it.
However, after reading it I am still unsure exactly what I need to do. It is possible to perhaps reformulate that into a series of steps?

Also, I have little experience with C++ so I was hoping I could be helpful by providing the data from my Keyboard. Would that be helpful enough?

Thank you for your time!

Special character

Hello,
first of all - thanks for making nudelta.

I am about to buy a nuphy air75.
I wonder if it is possible nutelda to send custom characters? Example:

Fn+s = ß
Fn+o = ö
etc

Edit: If that is not possible - is it possible to send AltGr+p or AltGr+s? With the right layout this would create the special characters.

Best regards,
Qua

[Apple Silicon] Failed to write config - `hid_error is not implemented yet`

Hi, just got my brand new Air75 and was looking for a way to remap some of the keys (as Nuphy Console doesn't work on Mac) and found Nudelta!

Plugged it in and looks like something might be broken (saw the same report at #35) but thought I'd open a new ticket as looks like it could be a different issue.

Tried to add as much info as I could - please let me know if you need more - thanks!

---

Device: Nuphy Air75
Firmware: 0124
Nudelta version: 0.6.6
MacOS: 13.2.1

To replicate:

• Keyboard is set to "Mac" and "Wired" mode
• Connect keyboard to USB
• Switch to Mac mode in Nudelta
• Re-map any key
• Click "write"
• Get the error "Failed to write to keyboard: hid_error is not implemented yet"

Windows build

Hello, since this is already running on Linux and MacOS, and is written in C++ and Python, I think Windows build would be appropriate even if there already original Nuphy Console on Windows. I can imagine many would like to use an open-source alternative.

Also off-topic, but I have both Air75 and Air60, so if there is a way I can help you I can - I would like to use this on my Air60 too :)

Failed to write configuration after grant Input Monitoring permissions in System Preferences

Version

0.7.4

Operating System

macOS: Ventura 13.4.1
chip: Apple M2

Description

I already gave Input Monitoring permission but kept receiving this error popup. No matter how many times I killed the app and permission in System Preferences, then reinstalled, gave permission but still failed.

Halo75 - remap is written but not applied nor saved

Remaps are said to be written

Typing in Notepad, the mapping is not applied.

Closing nudelta, opening nudelta again, and reloading keyboard, the default keymap is shown. (proving the keymap has not been written)

Nudelta version : 0.6.3
OS: Win 10
Keyboard: Halo75
Firmware: 0102

[Support] Air96

Please add support for the air96.

Thank you.

F5 & F6 Keys Default Mapping on Mac layout

Version

0.7.3

Operating System

Description

All of the F keys are mapped to their appropriate value by default (F1 mapping is f1, F2 is f2, etc), except for F5 and F6. On the non-Fn layer, on the mac layout, they're mapped to backlightup/backlightdown instead of f5 & f6. Simple to correct in place, but the behaviour after writing is puzzling if you don't know it's set like that.

Remapping `del` not working

Hey,
first of all - thanks for making this!
Nuphy's Console is a piece of ****, i was so frustrated about it before finding this... So thanks again and good job!

Bug?

I wanted to report a (supposed) bug:
I was not able to remap my (top-right) del key to anything else - even after a "Write successful" it still functions as a del key.

When rebinding the button below (pgup) to del, this works without a problem. So only remapping del to anything else seems to not be functional.

Not related suggestion

I respect your wish to not implement LED controlling functionality as I do not wish to use the LEDs either... But it would be nice to have a function to simply "deactivate all LEDs" :)
(Except for battery indicator and status)

How to add support for Air60

Description

Hey, how can I help to add support for Air60. Just wanted to make changes to keys.

Please add a changelog file and/or release notes

Hi, love the project so far, and my Mac, Air75 and I thank you for it. :)

However, would it be possible to add a change log so we can tell what's new or changed in every release? Either that or could you add the list of relevant changes to each release note?

Thank you, and please keep up the good work!

Share your dumps!

So, with Nudelta 0.6.7, I added a new CLI flag named --no-verify/-N. This will allow you to provide data dumps from other keyboards so I can mess around with them.

I'm looking for dumps from the following keyboards:

• Air96
• Halo96
• Air60
• Halo65

You will need terminal experience and the ability to build Nudelta from source, but the commands to run are as follows:

./nudelta -N -D win.bin -H win.hex
./nudelta -NM -D mac.bin -H mac.hex

Then I'd like you to just zip up the files and upload them.

Nuphy Air75, Ventura 13.2.1: can't write to keyboard

macOS 13.2.1
NuPhy Air75 (Firmware 0121)
nudelta 0.6.6

Update: I got it working again, but as a heads-up — I had to remove the nudelta entry from the Input Monitoring list, then restarting nudelta. That triggered the "Please update permissions" macOS dialog, the app got re-added to the Input Monitoring list, I gave the permission, and everything was peachy again. I'll just leave that here for the next poor soul who comes across this issue 😉

---

I can't write my config to my keyboard. It has worked fine in the past. The permissions have been set; I've tried to unset them, restart the app, re-enable the permissions, restart again, to no avail.

My guess the cause is something in the latest Ventura update, IIRC it worked fine in 13.1 & 13.2.

"Search" key not working?

Great software!!!

I tried assigning "search" key from GUI,
but not working on Windows/Android.

"search" key works with my niz 82 keyboard on both Windows and Android.

Remapping a key combination

Is it possible to remap "Win" + "Left" combination to "Home"?

Distribute on Flathub

I use Endless OS and Fedora Silverblue, which both come with the Flathub remote for apps by default. Distributing NuDelta as a Flatpak on Flathub would make it much easier to discover and install on these OSes—and virtually every other Linux-based OS.

Logging USB Feature Reports

Description

This is related to issue #58

I think it could be useful if Nudelta saved a log of the raw content (i.e. what HIDAPI was called with) of all feature reports sent to the keyboard, this would help immensely to understand when a brick happened and what data was malformed. They also shouldn’t be too big, so I think it’s safe to just save them by default.

[Support] Halo65

I'll reverse engineer Halo65 using this method. Hopefully it won't take too long.

• Report IDs
• Default keymaps
• Indices
• Keycodes
• Modifiers

RAlt to Menu

Hi,

I was wondering if there is an option for the menu or you could include it?
The menu exists on other keyboards and replaces, for example, when you are on a file, the right mouse click. I hope you know what I mean.

Best regards

Additional check to prevent breaking keyboards

Description

Problem

An issue while remapping the keyboard can bring it to a bricked state, as described in the issue #58. It looks like the issue may be related to the architecture of the host machine (arm64 apple silicon), and it is not discarded something else like encoding/locale.

Potential Solutions

• Before remapping the keyboard, the solution could generate the byte array for the default config and match it with an expected output (logic similar to a test run, but it would be executed at runtime). This step could be removed in the future, when the confidence on the solution increases. An extended version could also assert some conditions for custom remaps (as you cannot compare them to an expected output because they will vary based on the key maps), e.g. is there an expected number of bytes to be written, is it fixed or could we assert for a range?
• Similar to the solution above, it would be great to have a unit test on this, or a command to check whether the platform is generating the expected output (in case you don't have the unit test framework setup and don't want to waste time setting it up);
• Add a dry-run option to the commands that would output the bytes instead of writing them to the usb;

Notes

I'm not an experienced C/C++ developer but I can try to help. I'm considering to port the logic to Go (language I'm more familiar with) as it has less architecture dependencies and would be easier to build/distribute.

Halo 65

Description

Please add support halo65. I can help u

MacOS: Uncaught exception

Hi! Triyng to get nudelta working on MacOS Ventura 13.2 running on Apple Silicon M1. Doing everything to build GUI version like you said, copy and paste app to whatever folder I want, doubleclick it to run and get this error:

Uncaught Exception:
Error: dlopen(/var/folders/y6/37hy5g1s6x95c4lnfwgbn6r00000gn/T/.website.donn.nudelta.2Ho0nc, 0x0001): tried: '/var/folders/y6/37hy5g1s6x95c4lnfwgbn6r00000gn/T/.website.donn.nudelta.2Ho0nc' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64')), '/System/Volumes/Preboot/Cryptexes/OS/var/folders/y6/37hy5g1s6x95c4lnfwgbn6r00000gn/T/.website.donn.nudelta.2Ho0nc' (no such file), '/var/folders/y6/37hy5g1s6x95c4lnfwgbn6r00000gn/T/.website.donn.nudelta.2Ho0nc' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64')), '/private/var/folders/y6/37hy5g1s6x95c4lnfwgbn6r00000gn/T/.website.donn.nudelta.2Ho0nc' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64')), '/System/Volumes/Preboot/Cryptexes/OS/private/var/folders/y6/37hy5g1s6x95c4lnfwgbn6r00000gn/T/.website.donn.nudelta.2Ho0nc' (no such file), '/private/var/folders/y6/37hy5g1s6x95c4lnfwgbn6r00000gn/T/.website.donn.nudelta.2Ho0nc' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64'))
at process.func [as dlopen] (node:electron/js2c/asar_bundle:5:1810)
at Module._extensions..node (node:internal/modules/cjs/loader:1205:18)
at Object.func [as .node] (node:electron/js2c/asar_bundle:5:2037)
at Module.load (node:internal/modules/cjs/loader:988:32)
at Module._load (node:internal/modules/cjs/loader:829:12)
at c._load (node:electron/js2c/asar_bundle:5:13339)
at Module.require (node:internal/modules/cjs/loader:1012:19)
at require (node:internal/modules/cjs/helpers:102:18)
at Object. (/Applications/nudelta.app/Contents/Resources/app.asar/index.cjs:12:15)
at Module._compile (node:internal/modules/cjs/loader:1120:14)

Appreciate any help to run Nudelta properly. Thanx!

Help to support Halo75

Hello, how can I reverse engineer USB comm for the Halo75?
I'd like to submit a patch to support it, if possible.

Another question: does nudelta save the remappings on the keyboard itself?

Some keys can't be redefined

Version

0.7.0

Operating System

Windows 10 22H2 (19045.2846)

Description

Keyboard: Air75
Firmware: 0124

Hi,

I was trying to redefine Mac keymap to Colemak DH layout. It mostly worked, but some keys can't be redefined: U, O, N. The rest worked fine. I have tried this also for Windows (for U) with the same effect (or lack thereof).

Saved keymap contains this mapping.

Unsupported Keyboard Error for air96

Version

0.7.3

Operating System

macOS 13.4.1 (22F82)

Description

Hello,
first of all - This s a really cool project!

I encountered an issue with my Air96 when attempting to use it. Upon plugging it in, I received the following error message:

"No supported keyboards found, but a similar keyboard, 'BY Tech NuPhy Air96', has been found. If you believe this keyboard not being supported is an error, please file a bug report."

It seems that the system recognizes a similar keyboard, but not the exact model I own.

Steps to Reproduce:

Plug in Air96 to the computer.
Observe the error message: "No supported keyboards found, but a similar keyboard, 'BY Tech NuPhy Air96', has been found."

Actual Behavior:
The system does not recognize the keyboard and displays an error message suggesting a similar but different keyboard.

Thank you for your attention

Allow for remapping of the default fn key

Neither nuphy console nor nudelta seem to allow remapping of this key. Is there a physical limitation of some kind?

[Support] Field75

Description

Want to request the support of nuphy field75 gaming keeb

Backwards brightness keys

Whenever I make any change to the keymap, the default brightness keys change to be backwards: brightness down becomes brightness up and brightness up becomes brightness down (F1 key becomes brightness up, F2 key becomes brightness down). This is not really an issue since i can easily fix it with the yml file, but it would be nice if it was fixed by default. Maybe this is expected behaviour and I missed something, in that case sorry.

I fixed it by doing this:
keys:
brightnessdown:
key: brightnessup
brightnessup:
key: brightnessdown

Keyboard: Nuphy Air75 (Firmware 0122)
NuDelta Version: 0.6.5
Windows 11 Version: 22H2 (OS Build 22621.1105)

Edit: Also tested on Arch Linux (6.1.10 zen), same thing happens with appimage version 0.6.5.

Verifiable signing for MacOS

Description

This isn't signed in a way MacOS can verify it reliably. On my company Macbook I therefore can't use it.

I hope this is fixable.

HID error writing to keyboard "Invalid function"

Version

0.7.1

Operating System

Windows 10.0.19045.2846 (22H2)

Description

Keyboard: Air75
Firmware: 0124

Hi

Attempt to write any changes to keyboard results with a dialog:

Failed to write to keyboard: HidD_SetFeature: (0x00000001) Invalid function

It works with version 0.7.0.

F key and Fn

Hi, Im aware that probably this is not an issue from your side.

I've trying to set up a Mac setting that work on windows too. But for some odd reason I notice that every single F key is pressing a Fn key for a second, and even when it is set to do F1 in both F1 and F1 +Fn it is always triggering F1+Fn, and this is the default configuration.

add print screen as an option

Description

currently I can't map the screenshot key (next to F12) to KC_PRINT_SCREEN key which would be very nice

Semicolon and Quote are backwards

Version

0.7.3

Operating System

Version 22H2 (OS Build 23526.1000)

Description

I was trying get the Colemak-DH CAW Wide layout into my Air75 directly which has the semicolon where the Left Bracket normally is and Quote where the Right Bracket is. Setting it like that in Nudelta produces the opposite result, hitting the Left Bracket key types Quote and Right Bracket does Semicolon. I had to reverse it manually to get it to work properly

FN-layer remapping is (somewhat) possible using "02 00 00 ??" mappings

Description

I was investigating how the default macOS screenshot macro works, since the physical screenshot key doesn't actually have separate keymap entries, but still has different behavior depending on FN-key press.

I discovered that the "02 ?? ?? ??" bindings aren't actually redundant, but "redirect" the key press to other keymap offsets, depending on if FN is pressed.

The macOS screenshot macro uses 02 00 00 0C, which splits into offset 0240 and 0300. For example, I set 0240 to 00 00 00 68 for F13, and 0300 to 00 00 00 49 for Insert.

Further details like how many free slots are available is TBD, and still needs to be systematically analyzed.

icu4c dylib not found

I was running yarn command and it gave me the following errors:

dyld[20859]: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.64.dylib
  Referenced from: /usr/local/Cellar/node/12.12.0/bin/node
  Reason: tried: '/usr/local/opt/icu4c/lib/libicui18n.64.dylib' (no such file), 
'/usr/local/lib/libicui18n.64.dylib' (no such file), 
'/usr/lib/libicui18n.64.dylib' (no such file), 
'/usr/local/Cellar/icu4c/72.1/lib/libicui18n.64.dylib' (no such file), 
'/usr/local/lib/libicui18n.64.dylib' (no such file), '
/usr/lib/libicui18n.64.dylib' (no such file)
[1]    20859 abort      yarn

I then tried arch -arm64 install icu4c and arch -x86_64 install icu4c but still no luck.

Currently using macbook air M2 with OS version 12.4

Halo65 not supported

Version

0.7.4

Operating System

Getting error saying Nuphy Halo65 is not a supported keyboard.

Description

Getting error saying Nuphy Halo65 is not a supported keyboard.

Cannot recognize my air75

Hello ,the AppImage cannot recognize my air75 on debian linux. Do I need to do anything else besides connect my usb?

Windows 11 JavaScript error at launch

When I try to run the new windows build it throws a JavaScript error (attached below). My Java and Windows 11 install are all up to date, not sure what the issue is.

I want to assign an FN key

I'd like to see these features added

Lock Macbook with a key

Thanks a lot for making the effort and building this!

It would be amazing if one could use the button next to "del" as the "locking the machine" button. If you have any hints on how to solve that, I might be able to help out with implementation.

Cheers!

Resetting config via GUI

Description

Is it possible to reset the config using the app?

I use it on a M1 Mac.

Tried

nudelta -r

but get "command not found".

incompatible architecture

How can i rebuild the macos app? i am getting this error

(mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64'))

could not find CMAKE_PROJECT_NAME in Cache

Hey hey.
Thank you for your tool, I hope it good :)

I trying to execute yarn build, and got error:
could not find CMAKE_PROJECT_NAME in Cache

Can you please tell me what I am doing wrong?

Keyboard: Nuphy Air75
NuDelta Version: 0.6.6
Distro: Ubuntu 20.04

Thank you

info TOOL Using Unix Makefiles generator.
info CMD BUILD
info RUN [
info RUN   'cmake',
info RUN   '--build',
info RUN   '/home/nazar/nudelta/build',
info RUN   '--config',
info RUN   'Release'
info RUN ]
Error: could not find CMAKE_PROJECT_NAME in Cache
ERR! OMG Error: Process terminated: 1
ERR! OMG     at ChildProcess.<anonymous> (/home/nazar/nudelta/node_modules/cmake-js/lib/processHelpers.js:32:32)
ERR! OMG     at ChildProcess.emit (node:events:513:28)
ERR! OMG     at ChildProcess._handle.onexit (node:internal/child_process:291:12)
Error: Cmake-js exited with a non-zero code
    at main (file:///home/nazar/nudelta/util/build-native.js:24:15)

Error: could not find CMAKE_PROJECT_NAME in Cache

Version

0.7.4

Operating System

I am using Ubuntu distribution:

• Linux tatooine 5.15.0-79-generic #86~20.04.2-Ubuntu SMP Mon Jul 17 23:27:17 UTC 2023 x86_64 x86_64 x86_64 GNU/Linux

Description

When i execute any of the following commands: yarn build-native or yarn build

I get the following error:

info TOOL Using Unix Makefiles generator.
info CMD BUILD
info RUN [
info RUN 'cmake',
info RUN '--build',
info RUN '/home/jcordero/nudelta/build',
info RUN '--config',
info RUN 'Release'
info RUN ]
Error: could not find CMAKE_PROJECT_NAME in Cache
ERR! OMG Error: Process terminated: 1
ERR! OMG at ChildProcess. (/home/jcordero/nudelta/node_modules/cmake-js/lib/processHelpers.js:32:32)
ERR! OMG at ChildProcess.emit (events.js:400:28)
ERR! OMG at Process.ChildProcess._handle.onexit (internal/child_process.js:285:12)
Error: Cmake-js exited with a non-zero code
at main (file:///home/jcordero/nudelta/util/build-native.js:24:15)
at processTicksAndRejections (internal/process/task_queues.js:95:5)
error Command failed with exit code 255.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Any clues?

Thanks in advance

Command is missing from the keymap list

Hi,

Thank you for working on such a nice app!

It looks better than the official app! 👍

I've tried to remap caps lock to command key on a Mac, but it looks like command key is missing from the list.

Is it missing or am I looking at a wrong place?

What permissions do I need to enable

Hello, I am using on mac and getting this error:

But can't see what permissions I need to apply.

Thanks

Air 75 - No supported keyboard found

Hi,

I know it was asked before but it was said that it got fixed on a previous version. I am trying to configure my Air 75 on my mac but I get the error message "No supported keyboard found. Make sure it's plugged in via USB, then File > Reload Keyboard to retry.".

Does anyone know how I could solve it?

Thanks in advance!

[Support] Halo96

Version 0.6.4 (0.6.4) reports the Halo96 as an unsupported keyboard.

No supported keyboards found, but a similar keyboard, 'BY Tech NuPhy Halo96', has been found.

Hoping to help contribute by using the same methods mentioned in the Halo65 support issue as necessary.

can not remap screenshot key as shift + command + any other key

Version

0.7.3

Operating System

macOS Ventura 13.6.3

Description

I am facing an issue with remapping the screenshot key on my computer to a combination of Shift, Command, and another key. When I use Nudelta App, and click on Shift, and on Command, then both the keys turn off together. It is weird.