UHK60 LED control through Windows / userspace

[benedekkupper]

Plug in the UHK60 to a Windows PC, open Settings / Personalization / Dynamic Lighting, and play around with the settings. My favorite is the Wave effect.

At the moment this is only made to work correctly on UHK60.

For accurate operation, the UHK must tell the PC how long it takes to update all LEDs before a new set of values can be received, this should be set based on real measurements (I just eyeballed it to 35ms).

Furthermore, each LEDs position has to be reported to the PC with um accuracy in 3D space - again, I only eyeballed the currently used values, but they look not half bad IMHO.

[kareltucek]

Interesting!

Furthermore, after a few minutes of animation the keyboard usually gets into an all LEDs off state, which it's not able to recover from, until a button is pressed.

Uhk has independent handling of sleep modes and brightness, which converges here:

firmware/right/src/led_manager.c

Lines 36 to 39 in 8c8c1d7

	bool globalSleepMode = !Cfg.LedsEnabled || CurrentPowerMode > PowerMode_LastAwake || Cfg.LedBrightnessMultiplier == 0.0f;
	bool globalAlwaysOn = Cfg.LedsAlwaysOn || Ledmap_AlwaysOn || InteractivePairingInProgress;
	if (!globalAlwaysOn && (globalSleepMode || KeyBacklightSleepModeActive || StateSync_BatteryBacklightPowersavingMode || Cfg.BacklightingMode == BacklightingMode_LightNone)) {

In practice, just add your mode here:

firmware/right/src/ledmap.c

Line 759 in 8c8c1d7

Ledmap_AlwaysOn = mode == BacklightingMode_LightAll || mode == BacklightingMode_LedTest;

[benedekkupper]

A video on how it looks: https://drive.google.com/file/d/11gFxeSFJDL8kNkSkNB8e0HFM87VdiLmC/view?usp=sharing

I have updated the code to explicitly disable it on UHK80. That system is more complicated, a lot of design decisions need to be made. On UHK60 it is rather straightforward, I just hijacked the temporary backlight mode, which is only used on UHK80 for BT pairing.

Windows allows disabling this feature globally on all devices, or individually per device. I have split the UHK into two virtual devices, as they are more likely used in split mode, but that means that disabling one side and enabling the other doesn't work well.

Another Windows setting is whether applications are allowed to control the LEDs on each device individually. This is managed by the OS itself.

One thing to consider, if there should be a configuration value on the UHK side to enable this feature. At the moment the assumption is that the host side is sending messages that respect the timing requirements specified by the device. This might not always be the case, e.g. if on Linux a userspace app is misusing this HID interface, the LED buffer can get corrupted.

[mondalaci]

Is this LED control feature Windows-specific, or is there an OS agnostic standard behind it?

[benedekkupper]

Is this LED control feature Windows-specific, or is there an OS agnostic standard behind it?

It is standard HID, any OS or userspace application can decide to implement support for it. Example applications:
https://openrgb.org/
https://github.com/xz-dev/hid-rgb-ctl
In particular OpenRGB seems to have a significant community around it.

[kareltucek]

In general this has a huge overlap with a neighbour PR, which also aims to provide controls for the backlight, the segment display, and the oled display, but does so via custom usb command app commands.

Using a standard way is desired if we can get it working without too much hassle and without too much maintenance burden. I think.

I am not sure if there is a way to interface the oled via a similar interface?

---

Quick test experience:

hid-rgb-ctl:

• works with left half.
• The array is written twice (maybe right side values are delivered to the left side handler?)
• The mode is reset multiple times -> I would suggest putting Ledmap_SetTemporaryLedBacklightingMode(BacklightingMode_HidLampArray); after every Ledmap_TriggerFullUpdate(); in the value update path.
• It lists only one device. The tool might simply not support multiple "virtual devices" or not support them with its default profiles.

OpenRgb:

• I might be doing something wrong with its profiles, but I never managed to write any key with it.
• Only the "set led remote mode" report is delivered, but no value updates.
• The matrix is somewhat scattered. Not sure if this is a problem.

[pcooke9]

I tried OpenRGB a couple of days ago, but it's kind of a mess. I gave up on it because it kept interfering with my motherboard lighting, but even weirder, it disables all of my non-UHK mouse buttons except for left click.

Windows 11's built-in dynamic lighting seems to work fine though.

[benedekkupper]

I only tried OpenRGB myself on Windows: it works on a basic level, I could set all LEDs to a specific color, but didn't get further in the customization. It did disable Windows OS's access to the LEDs, so I had to uninstall it to get Windows control on them again.

hid-rgb-ctl is admittedly vibe-coded, so it's probably a bug that it cannot handle a dual configuration.

There are well-defined HID formats for representing both 14-segment displays and pixel-drawn displays (see HID Auxiliary Display usage page), but I'm not aware of any supporting infrastructure for them.