Skip to content
Linux CLI tool to control per-key RGB lighting on MSI laptops.
Python
Branch: master
Clone or download

Latest commit

Askannz Reverted the effects protocol
#24
There is a critical issue that LOCKS the RGB controller in an unusable
state, which persists after reboot. At least 2 machines are affected,
including mine. Still trying to figure out a solution to reset the
controller and make it usable again, bit in the meantime I'm reverting
all the new features that may have caused this.
Latest commit e185a29 Oct 28, 2019

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
documentation Moved protocol doc and utils scripts to "documentation" subfolder Oct 27, 2019
msi_perkeyrgb Reverted the effects protocol Oct 28, 2019
.gitignore Add IntelliJ IDE's project folder to the gitignore file Nov 17, 2018
99-msi-rgb.rules Fixed wrong permissions in udev rule Sep 9, 2018
LICENSE Initial commit Aug 10, 2018
README.md Reverted the effects protocol Oct 28, 2019
setup.py Reverted the effects protocol Oct 28, 2019

README.md

msi-perkeyrgb

This progam allows to control the SteelSeries per-key RGB keyboard backlighting on MSI laptops such as the GE63VR. It will not work on models with region-based backlighting (such as GE62VR and others). For those you should use tools like MSIKLM.

This is an unofficial tool, I am not affiliated to MSI nor SteelSeries in any way.

Installation

If you are on Archlinux, use this AUR package : msi-perkeyrgb (not up-to-date with the Git version yet)

For Ubuntu or others :

git clone https://github.com/Askannz/msi-perkeyrgb
cd msi-perkeyrgb/
sudo python3 setup.py install
sudo cp 99-msi-rgb.rules /etc/udev/rules.d/

After installation, you must reboot your computer (necessary for the udev rule to take effect, if you don't you will run into permission problems)

Features

Keys can be assigned a fixed color ("steady" mode), either through a configuration file for each individual key, or via a command-line argument for the whole keyboard,

A few select presets are also available for supported models, which emulate vendor-provided SteelSeries configurations.

Compatibility

This tool should probably work on any recent MSI laptop with a per-key RGB keyboard. It was tested with the following models :

Model Basic color support
GE63 Yes
GE73 Yes
GE75 Yes
GL63 Yes
GS63 Yes
GS65 Yes
GS75 Yes
GT63 Yes
GT75 Yes

If you have some additional test results, feel free to open a GitHub issue to help expand this list !

Requirements

  • Python 3.4+
  • setuptools
    • Archlinux : # pacman -S python-setuptools
    • Ubuntu : # apt install python3-setuptools
    • Fedora : # dnf install python3-setuptools
  • libhidapi 0.8+
    • Archlinux : # pacman -S hidapi
    • Ubuntu : # apt install libhidapi-hidraw0
    • Fedora : # dnf install hidapi

Permissions

IMPORTANT : you need to have read/write access to the HID interface of your keyboard. The included udev rule should take care of that, but here are some instructions just in case :

The HID interface is shown as /dev/hidraw* where * can be 0, 1, 2... (there can be more than one if you have a USB mouse or keyboard plugged in). Find the right one (try them all if necessary) and give yourself permissions with # chmod 666 /dev/hidraw*.

Usage

Simple usage

Steady color :

msi-perkeyrgb --model <MSI model> -s <COLOR>

Built-in preset (see --list-presets for available options) :

msi-perkeyrgb --model <MSI model> -p <preset>

Advanced usage

Set from configuration file :

msi-perkeyrgb --model <MSI model> -c <path to your configuration file>

The configuration file allows you to set individual key configurations. It can have any extension. See the dedicated wiki page for its syntax and examples.

How does it work, and credits

The SteelSeries keyboard is connected to the MSI laptop by two independent interfaces :

  • A PS/2 interface to send keypresses
  • a USB HID-compliant interface to receive RGB commands

Talking to the RGB controller from Linux is a matter of sending the correct binary packets on the USB HID interface. I used Wireshark to capture the traffic between the SteelSeries Engine on Windows and the keyboard, and then analyzed the captured data to figure out the protocol used. I was only able to reverse-engineer the simple "steady color" commands, but that work was massively improved upon by TauAkiou, who figured out the rest of the protocol and implemented the remaining effects (UPDATE: effects support been disabled for now, for security reasons. See https://github.com/Askannz/msi-perkeyrgb/issues/24 ). His work include an amazingly detailed write-up of the protocol which you can read here.

Also thanks to tbh1 for providing packet dumps of presets effects.

The HID communication code was inspired by other tools designed for previous generations of MSI laptops, such as MSIKLM.

You can’t perform that action at this time.