asus-kbd-rgb

Control the RGB keyboard backlight on ASUS laptops from the Linux command line.

Uses the standard HID LampArray protocol via hidraw — no kernel modules, no Secure Boot issues, no external dependencies.

Supported devices

Model	VID:PID	Status
ASUS Vivobook S14 (ITE5570)	0B05:5570	Tested

Other ASUS laptops with I2C-HID LampArray keyboards may also work. Contributions welcome.

Requirements

• Linux with I2C-HID support (standard in modern kernels)
• Python 3.6+
• No external Python packages needed

Installation

# Clone the repository
git clone https://github.com/SimonBlancoE/asus-kbd-rgb.git
cd asus-kbd-rgb

# Install binary + udev rule (recommended, one command)
./install.sh
# Or with auto-restore service:
./install.sh --with-service

What this installs:

• /usr/local/bin/kbd-rgb
• /etc/udev/rules.d/90-asus-kbd-rgb.rules
• Optional: /etc/systemd/system/asus-kbd-rgb-restore.service and /usr/lib/systemd/system-sleep/asus-kbd-rgb (--with-service)

Then log out and back in (or reboot) once so udev permissions apply. The optional boot service and resume hook only restore saved colors as root; they do not replace user access via udev.

Uninstall

./uninstall.sh
# Or also remove/disable systemd restore service:
./uninstall.sh --with-service

Usage

# Set color using a name
kbd-rgb set red
kbd-rgb set cyan

# Set color using hex code
kbd-rgb set '#ff6600'

# Set color using RGB values (0-255)
kbd-rgb set 255 100 0

# Adjust intensity
kbd-rgb set blue --intensity 128

# Turn off the backlight
kbd-rgb off

# Restore device default behavior
kbd-rgb reset

# List available color names
kbd-rgb colors

Saving and restoring colors

# Set a color and save it as the default
kbd-rgb set '#00ff88' --save

# Save with a named preset
kbd-rgb set red --save gaming
kbd-rgb set warm --save night

# Restore the default saved color
kbd-rgb restore

# Restore a named preset
kbd-rgb restore gaming

# List all saved presets
kbd-rgb presets

Colors are saved to ~/.config/asus-kbd-rgb/config.json.

Persistence across reboots

The keyboard resets to its default color on every boot and after suspend/hibernate. To automatically restore your saved color:

# Install service (if not already done with --with-service)
sudo kbd-rgb install --with-service

# Save preferred color in root config (service runs as root)
sudo /usr/local/bin/kbd-rgb set '#ff6600' --save

# Test the boot restore service without rebooting
sudo systemctl start asus-kbd-rgb-restore.service

The boot service and resume hook are only for persistence. If you also want to run kbd-rgb as your normal user, you still need the udev rule from kbd-rgb install and a fresh login session. On systems where sudo does not include /usr/local/bin in secure_path, use /usr/local/bin/kbd-rgb explicitly for root commands.

Permissions

By default, /dev/hidrawN devices require root access. There are two options:

1. udev rule (recommended): Run sudo kbd-rgb install to install a udev rule that grants access to logged-in users via uaccess. Log out and back in after installing.

2. sudo: Just prefix commands with sudo.

How it works

The keyboard controller exposes a standard HID LampArray interface (HID Usage Page 0x59). This tool communicates with it through the Linux hidraw interface using feature reports:

1. Finds the correct /dev/hidrawN by scanning sysfs for the ASUS VID:PID
2. Disables autonomous mode (device-controlled backlight)
3. Sends the desired RGB color via LampRangeUpdateReport
4. To restore defaults, re-enables autonomous mode

No custom kernel modules or EC access required. Works with Secure Boot enabled.

Troubleshooting

"No compatible ASUS keyboard found"

• Check that your device is listed in Supported devices above
• Verify the device exists: ls /sys/bus/hid/devices/ | grep 0B05
• Make sure hid-generic is loaded: lsmod | grep hid_generic

"Permission denied"

• Run sudo kbd-rgb install to install the udev rule, then log out and back in
• Or use sudo kbd-rgb ...
• --with-service only adds boot/resume restore as root; it does not grant user access to /dev/hidrawN
• If sudo kbd-rgb ... says command not found, use sudo /usr/local/bin/kbd-rgb ...

Color resets after suspend

• Install the systemd service (see Persistence across reboots)

My ASUS laptop has a LampArray keyboard but a different PID

• Run cat /sys/bus/hid/devices/*/uevent | grep -A1 0B05 to find the PID
• Open an issue with the PID so it can be added to the supported list

License

MIT