Skip to content

Latest commit

 

History

History
200 lines (138 loc) · 8.17 KB

README.org

File metadata and controls

200 lines (138 loc) · 8.17 KB
Raw

rzr

         _            _                 _
        /\ \        /\ \               /\ \
       /  \ \      /  \ \             /  \ \
      / /\ \ \  __/ /\ \ \           / /\ \ \
     / / /\ \_\/___/ /\ \ \         / / /\ \_\
    / / /_/ / /\___\/ / / /        / / /_/ / /
   / / /__\/ /       / / /        / / /__\/ /
  / / /_____/       / / /    _   / / /_____/
 / / /\ \ \         \ \ \__/\_\ / / /\ \ \ 
/ / /  \ \ \         \ \___\/ // / /  \ \ \
\/_/    \_\/          \/___/_/ \/_/    \_\/

rzr is a simple command line frontend for OpenRazer. It allows to set static lighting profiles of Razer devices, based on configuration files.

Lets assume you have created a profile with the name fps, containing the following color declarations:

w = "red"
a = "#ff0000"
s = "#f0f"
d = "ff2080"

All you have to do to apply the profile is to execute the following command:

$ rzr fps

The WASD keys get now lighted accordingly.

This allows to switch quickly between lighting profiles using the command line or a script. Profile switching per current work-directory can e.g. easily be achieved with direnv.

An instruction how to apply profiles automatically while running Steam games can be found below.

Currently only devices with the LED matrix feature are supported. Every device on which single LED colors can be set should fall into this category.

Features

  • Write lighting profiles in TOML
  • Apply profiles with one command

Installation

At first, make sure the OpenRazer daemon is running and your user can access it. If you are having trouble, take a look at the troubleshooting section.

This project is a Nix flake. If you are running a recent version of the Nix package manager and have flakes enabled, you can execute it with:

$ nix run github:Deleh/rzr

On legacy systems you need to make sure the Python libraries for OpenRazer are in your path, then clone this repository and execute:

$ python setup.py install

Or make sure the requirements in requirements.txt are fulfilled and call the program directly with:

$ python bin/rzr

Usage

usage: rzr [-h] [-ld LIGHTMAP_DIRECTORY] [-pd PROFILE_DIRECTORY] [COMMAND]

Set color profiles of your Razer devices.

positional arguments:
  COMMAND               one of the following:
                          list-devices   - list available devices
                          list-lightmaps - list available lightmaps
                          list-profiles  - list available profiles
                          iterate-lights - iterate though all lights of all devices
                          <PROFILE>      - apply the given profile

optional arguments:
  -h, --help            show this help message and exit
  -ld LIGHTMAP_DIRECTORY, --lightmap-directory LIGHTMAP_DIRECTORY
                        path to directory with lightmaps (default: ~/.config/rzr/lightmaps)
  -pd PROFILE_DIRECTORY, --profile-directory PROFILE_DIRECTORY
                        path to directory with profiles (default: ~/.config/rzr/profiles)

If no command is given and the profile default exists, it is applied.

Configuration

Lightmaps

The lights of Razer devices (on which single LED colors can be set) are arranged in two dimensional matrices with various numbers of columns and rows. So called lightmaps are TOML files which map identifiers to positions in the matrices. For every device at least one lightmap must be created and be placed in the LIGHTMAP_DIRECTORY (default: ~/.config/rzr/lightmaps).

Lightmaps for the following devices can already be found in the lightmaps directory:

  • Razer BlackWidow Chroma with german keyboard layout (blackwidow_chroma_de.toml)
  • Razer Mamba Elite (mamba_elite.toml)

If your device is not in the list, use one of those as template and feel free to create a pull request.

The iterate-lights command iterates through every found device, turns on one light after another and prints the matrix position to stdout. This should ease the creation of new lightmaps.

Here is an excerpt of the file blackwidow_chroma_de.toml:

m2 = [2, 0]
tab = [2, 1]
q = [2, 2]
w = [2, 3]
e = [2, 4]
r = [2, 5]
t = [2, 6]

The tab identifies for example the key in the third row and second colum (counting starts at 0) which is the tabulator key on the keyboard. Those identifiers can then be used in profiles to set light colors.

Profiles

Profiles are configuration files for light colors of one or more devices. They are also TOML files and map identifiers of lightmaps to colors. Create a new profile for every light setup and place it in the PROFILE_DIRECTORY (default: ~/.config/rzr/profiles).

An example for a profile can be found in the profiles directory.

Make up a name for every used device in a profile, e.g. mouse for your mouse and keyboard for the keyboard (obvious) or choose other names. Then create a new field for every device with the chosen name, followed by the mandatory name and lightmap. Lightmaps are identified by their filename without the .toml part, for example:

[keyboard]
name = "Razer BlackWidow Chroma"
lightmap = "blackwidow_chroma_de"

The name of your device can be found with the list-devices command. Available lightmaps can be listed with the list-lightmaps command.

Then create another field [<chosen_device_name>.lights], followed by any key value pairs. The keys are the identifiers from the set lightmap, values are color strings. For example:

[keyboard.lights]
logo = "green"
w = "aqua"
a = "#ff0000"
s = "#f0f"
d = "white"

A color string can be one of the following:

  • Hexadecimal value with or without leading hash (e.g. #ff0000)
  • Short hexadecimal value with or without leading hash (e.g. f0f, then interpreted as #ff00ff)
  • HTML color name (e.g. green) (a full list can be found here)

Not set lights are turned off.

Steam

Steam allows to set various launch options for games. This functionality can also be used to apply lighting profiles before the startup and after the exit of a game.

Lets assume you created a profile called my_favourite_game and another one called default. Right click on your favourite game in the Steam launcher and click Properties…. On the bottom of the General section is a text field, labeled launch options. Insert the following command:

rzr my_favourite_game & %command%; rzr

The first command applies the profile my_favourite_game as usual. & ensures that the next command is called even if the first one failed. Your game should start even if rzr failed or you have messed up your profile file.

Steam then substitutes the %command% part with the binary of the game and runs it.

The ; waits until the game exited and the rzr command finally applies your default profile.

It is neccessary that rzr is installed correctly and available in your $PATH, otherwise Steam will not be able to call it.

Troubleshooting

Make sure your user is in the plugdev group to access the OpenRazer daemon.

If this is the case and you still have problems, stop the daemon with the following command:

$ systemctl --user stop openrazer-daemon.service

Then run it manually and check the output:

$ openrazer-daemon -Fv

If it complains about a missing config file, put this file in the ~/.config/openrazer directory and restart the daemon.