Command-line utility for toggling and changing colorscheme of Clevo RGB keyboards.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
colorschemes
settings
.gitignore
README.md
batterymon
kbsetcolor
kbtoggle

README.md

What is this?

A command-line frontend for clevo-xsm-wmi, the kernel module for controlling the backlight on Clevo laptops. In simpler terms, it lets you switch the backlight on and off, and set the colors on RGB keyboards. I created this on an Ubuntu-based Linux distro and can't guarantee it will work on other distros.

Dependencies

  • clevo-xsm-wmi
    1. Download it here
    2. Install dependencies: sudo apt install gcc make linux-headers-generic
    3. Open a terminal, enter the clevo-xsm-wmi directory and run cd module && make && sudo make install
    4. Just in case:
      sudo install -m644 clevo-xsm-wmi.ko /lib/modules/$(uname -r)/extra
      sudo depmod
      sudo tee /etc/modules-load.d/clevo-xsm-wmi.conf <<< clevo-xsm-wmi
      
  • gksudo (or kdesudo for KDE) if you want to use a keyboard shortcut to run the script. Install with sudo apt install gksu or sudo apt install kdesudo. This is probably already installed.
  • acpi for the battery monitor: sudo apt install acpi

IMPORTANT: you may need to recompile the clevo-xsm-wmi kernel module after system updates, which sometimes overwrite any changes you've made to the kernel configuration. I don't know of any way around this at the moment.

Installation

  1. Download and unzip, or clone, this repo, then add the script to your path by adding the following line to ~/.bashrc: export PATH=$PATH:<dir> where <dir> is the full path to the repo. For example if you downloaded it to your desktop, it would look like export PATH=$PATH:~/Desktop/clevo-keyboard-backlight-control.
  2. cd into the clevo-keyboard-backlight-control directory and make the scripts executable:
chmod +x kbtoggle
chmod +x kbsetcolor
chmod +x batterymon
  1. In order to run the batterymon script through cron, you need to have it in your root path since it has to be added to roots cron table. So, edit /etc/environment as root and append the path to the script.

Turning off the password check

This utility needs to unload and reload the keyboard kernel module in order to update its configuration without a reboot. Therefore, it requires root privileges, so when you run it from the command line, it will ask for your password. This gets annoying, but you can easily disable it:

  1. sudo visudo, this will open the /etc/sudoers file in your terminal
  2. Add the following lines to the end of the file, where <pathtoscript> is the full path to this utility on your system:
username ALL=(ALL) NOPASSWD: <pathtoscript>/kbtoggle,<pathtoscript>/kbsetcolor,<pathtoscript>/batterymon
  1. Save and close the file

Usage

  • To toggle the backlight on and off from the command-line: kbtoggle
  • To toggle the backlight on and off with a keyboard shortcut
    1. Create a custom command shortcut in your system settings (exact steps vary by distro - please google).
    2. Specify the command as gksudo <pathtoscript>/kbtoggle. Replace gksudo with kdesudo if using KDE.
    3. Using gksudo or kdesudo will pop up a graphical interface to ask for your password when you hit your chosen keyboard shortcut. I haven't found a way to make these respect the sudoers file yet, so you'll have to give you password every time.
  • To change the colorscheme of the keyboard, from a terminal run kbsetcolor <colorscheme> where <colorscheme> is the name of one the files in kb-templates without the .txt file extension. Running kbsetcolor without any arguments will give you a list of all the colorscheme arguments you can use.
  • To create a new colorscheme, run kbsetcolor -n and follow the prompts.
  • You can set a default colorscheme to use if there is no colorscheme already set: kbsetcolor -d <colorscheme>
  • To make the keyboard change color when the battery is low (20%) or critical (10%), run sudo crontab -e, add the following line (where <pathtoscript> is the full path to this utility on your system) and save:
*/2 * * * * cd <pathtoscript> && ./batterymon >> batterymon.log

This will check your battery level every 2 minutes, and run a script to change the color of the keyboard if it's low. Any errors from attempting to run the script will be output to batterymon.log. Note: you can also run batterymon manually from the terminal to check your current battery level on a once-off basis.

Advanced usage

The keyboard has 3 sections which can be independantly colored. The kernel module supports the following predefined colors:

red
yellow
green
cyan
blue
magenta
white

Most of the files in kb-templates are named after the initials of the 3 colors in their colorscheme. For example, yrb stands for yellow, red, blue in that order, from left to right, across the keyboard. A few schemes are solid colors (white, cyan) and some are gradients of 2 closely related colors.

You can create your own colorschemes using the kbsetcolor -n command. Alternatively, you can create a colorscheme manually by duplicating one of the existing schemes and replace the specified colors with your choice of colors from the list above. Save it with a name you'll remember so you can easily call it from the command line (you may want to rename your favorite existing schemes for the same reason!)

TODO

  • Maintain brightness set by hardware
  • Add an option to randomly generate a colorscheme when running kbsetcolor with an appropriate parameter.(currently a WIP)
  • Any improvements to this hastily hacked-together code are welcomed.