* rzr

  #+begin_src text
             _            _                 _
            /\ \        /\ \               /\ \
           /  \ \      /  \ \             /  \ \
          / /\ \ \  __/ /\ \ \           / /\ \ \
         / / /\ \_\/___/ /\ \ \         / / /\ \_\
        / / /_/ / /\___\/ / / /        / / /_/ / /
       / / /__\/ /       / / /        / / /__\/ /
      / / /_____/       / / /    _   / / /_____/
     / / /\ \ \         \ \ \__/\_\ / / /\ \ \ 
    / / /  \ \ \         \ \___\/ // / /  \ \ \
    \/_/    \_\/          \/___/_/ \/_/    \_\/
  #+end_src
  
  *rzr* is a simple command line frontend for [[https://openrazer.github.io/][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:

  #+begin_src toml
    w = "red"
    a = "#ff0000"
    s = "#f0f"
    d = "ff2080"
  #+end_src

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

  #+begin_src sh
    rzr fps
  #+end_src
  
  The WASD keys get now lighted accordingly.

  This allows to switch between lighting profiles using the command line, a script or even [[https://direnv.net/][direnv]].
  
** 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 [[https://nixos.wiki/wiki/Flakes][Nix flake]].
   If you are running a recent version of the [[https://nixos.org/][Nix]] package manager and have flakes enabled, you can execute it with:

   #+begin_src sh
     nix run github:Deleh/rzr
   #+end_src

   On legacy systems you need to make sure the [[https://github.com/openrazer/openrazer/tree/master/pylib][Python libraries]] for OpenRazer are in your path, then clone this repository and execute:

   #+begin_src sh
     python setup.py install
   #+end_src

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

   #+begin_src sh
     python bin/rzr
   #+end_src
   
** Usage

#+begin_src text
  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)
#+end_src
 
** Configuration

*** Lightmaps

    The lights of Razer devices 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 be found in the =lightmaps= directory:

    - Razer BlackWidow Chroma 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=:

    #+begin_src toml
      m2 = [2, 0]
      tab = [2, 1]
      q = [2, 2]
      w = [2, 3]
      e = [2, 4]
      r = [2, 5]
      t = [2, 6]
    #+end_src

    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:

    #+begin_src toml
      [keyboard]
      name = "Razer BlackWidow Chroma"
      lightmap = "blackwidow_chroma_de"
    #+end_src

    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:

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

    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 [[https://www.w3schools.com/colors/colors_names.asp][here]])

    Not set lights are turned off.
    
** 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:
  
   #+begin_example sh
     systemctl --user stop openrazer-daemon.service
   #+end_example

   Then run it manually and check the output:
   
   #+begin_src sh
     openrazer-daemon -Fv
   #+end_src

   If it complains about a missing config file, put [[https://github.com/openrazer/openrazer/blob/master/daemon/resources/razer.conf][this]] file in the =~/.config/openrazer= directory and restart the daemon.