Dev-Thoughts: Background information on the new keyboard lighting control - TUXEDO Computers

Hi, Werner here.

Last year I wrote about Mainlining and the TUXEDO kernel here in our TUXEDO blog, but then never got to the third part of the article series: Ubuntu installation via WebFAI vs. an ISO from ubuntu.com. So with kudos to all who waited for it… Sorry, not today xD. But with good reasons, there was a lot to do and one of them was the complete the rewrite of our keyboard backlight drivers.

Many APIs, many standards

I want to go into a little bit of the technical background of why the driver behaves the way it does and start with the realities: Across the devices we’ve sold over the last few years, we’re dealing with a total of seven different keyboard lighting firmware APIs in different versions, spread across four Linux kernel modules we’ve written.

Besides the obvious differences, of for example single-color, multi-zone or even per key individually adjustable RGB lighting, there are also less obvious differences in certain keyboard models, such as brightness adjustable in 3, 5, 10 or 256 steps.

In the past, these four modules “historically” had no sysfs interface at all or each had a completely separate sysfs interface to control the lighting from within the Linux operating system. This was the reason for the rewrite: If we have a unified GUI, the backend API should also be unified at some point.

Uniform interfaces necessary

To resolve this complex situation, we decided to use what is already standardized in the kernel: /sys/class/leds. For the old sysfs entries, we had to make a radical cut and delete them from the driver.

The most important in a nutshell

For our keyboards, there is now a white:kbd_backlight entry and one or more rgb:kbd_backlight entries under /sys/class/leds. Each of them has the attributes brightness (readable and writable) for the current and max_brightness (read-only) for the maximum brightness level.

If there are multiple rgb:kbd_backlight entries (e.g. for the per-key RGB keyboards), the brightness attribute is currently still kept in sync across all entries. This is not quite in specification for the interface, but a workaround for KDE Plasma – if you change the keyboard brightness via the Plasma power settings, only one value is currently rewritten.

For rgb:kbd_backlight entries, we have additionally introduced the multi_intensity attribute, which takes three space-separated integers between 0 and 255 to set the RGB value of the respective keyboard zone or key. On the TUXEDO Aura 15 Gen2, for example, the command…

echo 255 0 0 | sudo tee /sys/class/leds/rgb:kbd_backlight/multi_intensity

…sets the color of the keyboard leds to red. Accordingly the command…

echo 0 255 0 | sudo tee /sys/class/leds/rgb:kbd_backlight/multi_intensity

…turns all leds green and…

echo 0 0 255 | sudo tee /sys/class/leds/rgb:kbd_backlight/multi_intensity

…finally into a blue landscape.

On per-key keyboards, the numbering of the rgb:kbd_backlight entries goes from top left to bottom right or from bottom left to top right, depending on the model, and there are more entries than there are actual keys.

This is partly because some keys have multiple LEDs (such as the Enter key), and partly because the LED controller keeps a few placeholders free for other current or future keyboard layouts, which are not associated with any LED at all on our models.

However, since the driver cannot know which ones these are, it cannot filter them out. In the future, this mapping will probably happen model-specifically at the level of the TUXEDO Control Center.

Questions for the developers

Before the update I could switch through three brightness levels with FN+Spacebar, now only through two?

This is because before the update, the behavior of the FN+Spacebar shortcut was implemented directly by the firmware or driver. Now, the behavior of the “toggle keyboard illumination” shortcut is implemented by the respective desktop environment. KDE Plasma and Gnome, for example, only toggle it on and off, so there are now only two levels.

Shortcuts like FN+Spacebar or FN+× (the multiplication sign on the numeric keypad) don’t work at all anymore?

Some desktop environments do not implement the “Toggle keyboard backlight” shortcut at all. Here, an extra configuration or script may be necessary.

My script or tool that I used until now to change the keyboard illumination does not work anymore?

This is to be expected, since – as described above – we have implemented a completely new interface and removed the old one. The script or tool must be rewritten to the new interface.

The TUXEDO Control Center says that my keyboard is not supported (yet)

This can have two causes: The device is still running on an Ubuntu 20.04 base and thus still has the tuxedo-keyboard driver version 3.1.x installed instead of the required 3.2.0 (or newer). We deliberately did not include the 3.2.0 driver in the 20.04 package sources, since these systems could theoretically still run on the Linux kernel 5.4, which is not compatible with the new driver.

If you only have the Linux kernel 5.15 installed, you can manually install the newer package from our repository. However, for anyone who generally values the latest features, I recommend upgrading to a 22.04-based Ubuntu or the current 22.04-based Tuxedo OS. The 20.04-based systems will still receive security updates until 2025, but increasingly no new features.

The second cause could be that the firmware of the device does not offer the possibility to control the lighting through the operating system or it has an API that only occurs on this one older model. In this case, I can’t promise that the GUI control will be added (in a timely manner), but the keyboard shortcuts will continue to work as usual.

The Windows Control Center has more setting options than the TUXEDO Control Center for my device?

We are working on adding all functions and a few more. We are just at the beginning of the TUXEDO Control Center 2.

I noticed bug XY.

As part of our development, we test a lot, but with a rewrite like this, you always miss something. Don’t worry, we collect all the bugs that are reported to us on Github and see that we fix them in a timely manner.

• tuxedo-keyboard on github
• tuxedo-control-center on Github

The important thing is: Which device in which configuration is it? Which distribution in which version? Which kernel in which version? Which desktop environment in which version? Which version of the kernel modules tuxedo-control-center, tuxedo-keyboard and tuxedo-keyboard-ite is installed? Which versions of BIOS and EC firmware?

With this information, we can take the corresponding device from the archive shelf and try to recreate the bug, which is usually the first step in bug fixing.

Many greetings from the TUXEDO Tower in Augsburg!