Add NuPhy Air75 V3 keyboard RGB theme support

[fldc]

Did some AI-assisted reverse engineering and created a CLI utility able to change some (most?) RGB related settings on my Nuphy Air 75v3 and uploaded it to AUR.

This will surely work with other keyboards supported by the NuphyIO web utility but needs some testing, this PR will detect the Air 75v3 for now.

NuPhy keyboard support:

• Added nuphyctl-bin to the package list to ensure it is available for installation.
• Created a new script, nuphyio-keyboard.sh, to conditionally install nuphyctl-bin if a NuPhy keyboard is detected.
• Updated the main packaging script (all.sh) to run the new NuPhy keyboard installation script.

Migration for existing installations:

• Added a migration script (1774642699.sh) to install nuphyctl-bin on systems with a NuPhy keyboard that do not already have it installed.

[Copilot]

Pull request overview

This PR introduces NuPhy Air75 V3 keyboard detection and wires in installation + theme-time RGB application via nuphyctl, so Omarchy can automatically support NuPhy RGB settings similarly to existing device-specific keyboard integrations.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Changes:

• Add NuPhy keyboard detection helper (omarchy-hw-nuphyio-keyboard) and a packaging hook to install nuphyctl-bin when detected.
• Add a migration to install nuphyctl-bin for existing installs with a detected NuPhy keyboard.
• Add a theme hook to apply keyboard.rgb to the keyboard via nuphyctl, and register it in omarchy-theme-set-keyboard.

Reviewed changes

Copilot reviewed 4 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
migrations/1774642699.sh	Installs nuphyctl-bin during migration when NuPhy keyboard is detected.
install/packaging/nuphyio-keyboard.sh	Installs nuphyctl-bin during install when NuPhy keyboard is detected.
install/packaging/all.sh	Runs the new NuPhy packaging hook as part of the packaging phase.
install/omarchy-other.packages	Adds nuphyctl-bin to the ISO-builder “other packages” list.
bin/omarchy-theme-set-keyboard-nuphyio	Applies theme keyboard color to NuPhy keyboard using nuphyctl.
bin/omarchy-theme-set-keyboard	Invokes the NuPhy theme hook alongside other keyboard hooks.
bin/omarchy-hw-nuphyio-keyboard	Detects a connected NuPhy Air75 V3 via HID uevent data.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This migration installs nuphyctl-bin via omarchy-pkg-add (pacman). If nuphyctl-bin is not present in the configured pacman repos and only exists in the AUR, the migration will fail on affected systems; consider using omarchy-pkg-aur-add (after ensuring yay is available) or ensure the package is shipped in the Omarchy pacman repo.

Suggested change

	omarchy-pkg-add nuphyctl-bin
	if ! omarchy-pkg-add nuphyctl-bin; then
	omarchy-pkg-aur-add nuphyctl-bin
	fi

[Copilot]

Pull request overview

Copilot reviewed 4 out of 7 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 7 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[felipe3dfx]

Tested end-to-end on a system with a NuPhy Air75 V3. The overall approach is clean and follows the existing keyboard hook pattern (asus-rog / f16), but the current theme script won't work out of the box on most real setups and there's a packaging question worth discussing. Details below.

Test environment

• OS: Arch Linux (kernel 6.19.10-arch1-1)
• DE: Hyprland on Wayland, seat0/tty1, active session
• Keyboard: NuPhy Air75 V3 wired (vid=0x19f5 pid=0x1028), plus dongle present on the USB bus (pid=0x2620)
• AUR helper: yay
• Theme colors used for tests: #89b4fa and #cdd6f4

What works

• Detection (omarchy-hw-nuphyio-keyboard): matches correctly against /sys/bus/hid/devices/*/uevent. Both wired and dongle entries show HID_NAME=NuPhy Air75 V3.
• Migration script (migrations/1774975945.sh): double-gating with omarchy-hw-nuphyio-keyboard && omarchy-pkg-missing nuphyctl-bin is idempotent and safe.
• nuphyctl itself: once the inline issues below are addressed, nuphyctl rgb set --hex 89b4fa --vid 0x19f5 --pid 0x1028 correctly updates the keyboard RGB on each call.

Permissions gap (upstream in nuphyctl-bin, not strictly this PR — but worth flagging)

By default on Arch, /dev/hidraw* is root:root 0600 and the nuphyctl-bin package does not ship any udev rules. nuphyctl will fail with Permission denied unless one of the following is true:

1. The keyboard is enumerated after the user session becomes active on a seat — in that case the built-in /usr/lib/udev/rules.d/73-seat-late.rules adds TAG+="uaccess" and systemd-logind applies an ACL for the active seat user.
2. The user manually runs sudo udevadm trigger --subsystem-match=hidraw --action=add after login to re-run the uaccess builtin for devices enumerated pre-login.
3. Explicit udev rules are provided by a package.

On a fresh omarchy install where the keyboard is plugged in at boot, case (1) does not apply and the theme hook fails silently for the user (compounded by the &>/dev/null redirect — see inline comment). This probably deserves either a note in this PR that first-run requires a replug / udevadm trigger, or better, a follow-up with the nuphyctl-bin AUR maintainer to ship udev rules.

For reference, the ROG integration avoids this class of problem entirely by running asusd.service as root and exposing functionality over D-Bus, with asusctl shipping its own udev rules. That's a heavier architecture than nuphyctl needs, but it's why the existing asus-rog hook "just works".

Related observation (out of scope)

While reviewing this PR I noticed bin/omarchy-theme-set-keyboard-f16 silences qmk_hid errors with 2>/dev/null on every call. If qmk-hid hits the same kind of hidraw permission issue on some Framework 16 setups, the failure would be invisible. Worth verifying in a follow-up — not blocking this PR.

Happy to help test a revised version once the inline comments are addressed.

[felipe3dfx]

Blocker: this command fails on any system with more than one HID device. Tested on a real setup and got:

Error: multiple matching HID devices; specify --path or narrow with --iface/--usage-page/--usage

Any machine with a mouse, a webcam, a USB receiver, a DMI controller, etc. will hit this — so effectively most end-user installs. nuphyctl supports --vid and --pid for exactly this case. For the Air75 V3 wired (vid=0x19f5 pid=0x1028):

nuphyctl rgb set --hex "$COLOR" --vid 0x19f5 --pid 0x1028

Two more things on this line:

1. &>/dev/null hides real errors. The asusctl script lets stderr propagate, which is how bugs get reported. With the current redirect, the theme hook would have been silently broken on almost every system and nobody would know. Consider removing the redirect entirely, or at least keeping stderr (>/dev/null instead of &>/dev/null).
2. The wireless dongle has a different PID (0x2620). If you want to support both wired and dongle, you'll need to either try both PIDs or have the detection script export which variant is present. Not blocking, but worth a comment in the code about the hardcoded wired PID.

[felipe3dfx]

Minor: quote $KEYBOARD_THEME (and $COLOR on line 8) defensively. Not a practical bug on standard omarchy installs, but consistent with the rest of the codebase and safe against paths containing spaces:

COLOR=$(sed 's/^#//' "$KEYBOARD_THEME")

[felipe3dfx]

Should nuphyctl-bin live here? The existing hardware-specific integrations (asusctl, qmk-hid) are installed exclusively through their gated packaging scripts (install/packaging/asus-rog.sh, install/packaging/framework16.sh) and do not appear in omarchy-other.packages. The companion install/packaging/nuphyio-keyboard.sh in this PR already gates the install on omarchy-hw-nuphyio-keyboard, so this line looks redundant and inconsistent with how the other two keyboard integrations are wired. Is the intent to document the package, or was this an oversight?

[felipe3dfx]

Hey @fldc — quick heads-up: I opened #5284 as an alternative take on this. It builds directly on the approach you established here (detection helper, theme hook, packaging gate) and credits you in the description.

The main differences, for side-by-side comparison:

• Adds a udev layer (default/udev/nuphyio.rules + install/config/hardware/nuphy/nuphyio.sh) so /dev/hidraw* is accessible unprivileged on first boot — this is the permissions gap I flagged in my review above, which bites users who boot with the keyboard already plugged in.
• Drops the install/omarchy-other.packages edit to match how asusctl / qmk-hid are handled (gated packaging scripts only, no global list entry).
• Theme hook fixes from my inline comments: explicit --vid/--pid, quoted vars, no silenced errors.
• Bumps the migration timestamp to sit after origin/dev HEAD.

I'm not trying to land both — #5284 is there as a self-contained option for the maintainer to compare against. If you'd prefer to pull the udev bits into this PR instead, I'm happy to close #5284 and send the diff your way, or open a PR against your branch. Whichever path you want to take, I'm on board. Just wanted the alternative to be visible rather than sitting on a local branch.