Package: ite8291r3-ctl
What is it?ite8291r3-ctlis a userspace driver for the ITE 8291 (rev 0.03) RGB keyboard backlight controller.DisclaimerThis software is in early stages of developement. Futhermore, to quote GPL: Everything is provided as is. There is no warranty for the program, to the extent permitted by applicable law.This software is licensed under the GNU General Public License v2.0CompatibilityThe following devices have been reported to work:idVendoridProductbcdDevicemanufacturerproduct048d60040.03Integrated Technology Express, Inc.ITE Device(8291)048dce000.03Integrated Technology Express, Inc.ITE Device(8291)If you believen your device should be supported, but it is not, please open an issue. You can runite8291r3-ctl query --devicesto see the supported devices found in the system. Alternatively, you can uselsusb -d 048d:.DependenciesRequiredPython 3.6or abovepyusb(and thus one of the backend that it supports, e.g.libusb)Optionalfor thescreenmodepython-xlibPython packagePillowPython packageFeaturesCurrentSupport for built-in effectsMonocolor modeColor palette managementPer-key RGB colorsAnimationsColoring the keyboard according to what is on screen[exprimental, Linux+Xorg only]Querying parts of the controller stateTO-DOUser interface for instructing the controller to save changesModify timeoutA more sane way of assigning colors to specific keysPossibly a GUIColoring the keyboard based on audioHow to installUsing PIPThe simplest way to install is to usepip:pip install ite8291r3-ctlNote:This will not download anything from theassetsdirectory, it only installs the program. You will have to download them manually if you want to try them out.Note:If you want to install for all users, runpipas root.ManuallyDownloadingIf you havegitinstalled:git clone https://github.com/pobrn/ite8291r3-ctlIf you don't, then you can download ithere.InstallingAfter downloading the files, open the directory in a terminal, and runpip install .(orpip install .[mode-screen]if you want the optional dependencies for thescreenmode). If you have multiple Python versions installed, specify one that satisfies the requirements.How to useRunning it without installationIt is possible to run the utility without installation. Open the directory in a terminal, then runpython -m ite8291r3_ctl. In this case you need to install the dependencies manually.pip install -r requirements.txtto install the requiredpyusbpackage. If you want to try thescreenmode, you need to install the optional dependencies as well.Accessing the USB deviceBy default you needrootprivileges if you want to use this utility. As notedhereandhere, you can create audevrule to allow everyone on your system to access this particular USB device, and thus you won't need to run the program asroot.If you want to do that, create a file/etc/udev/rules.d/99-ite8291.rules:SUBSYSTEMS=="usb", ATTRS{idVendor}=="048d", ATTRS{idProduct}=="ce00", MODE:="0666"or you can make it accessible only for a given group if you don't want anyone to have access to it:SUBSYSTEMS=="usb", ATTRS{idVendor}=="048d", ATTRS{idProduct}=="ce00", GROUP="name_of_the_group", MODE:="0660"after creating the file, runsudo udevadm control --reload, thensudo udevadm trigger. Or reboot.SubcommandsUseite8291r3-ctl -hto get a list of subcommands. Useite8291r3 <subcommand> -hto get the help for a given subcommand. Useite8291r3-ctl --device <bus>/<addr>to select a device to control, if the device is not specified, the first available will be used.offTurns off the keyboard backlight.Example:ite8291r3-ctl offbrightnessChanges the keyboard backlight brightness. The argument must be an integer between 0 and 50 (inclusive). Zero is no backlight, 50 is the brightest.Example:ite8291r3-ctl brightness 33test-patternite8291r3-ctl test-pattern[for testing]Shows a test pattern. It takes 10 seconds to run. It will turn off all key backlighting once it is finished.freeze[for testing, potentially unsafe]Changes the speed of the current effect to 11 (one above the maximum). This appears to stop the effect (which are animated).Example:ite8291r3-ctl freezeeffectChanges the current effect. You can specify the following properties for effects:propertypossible valuesnotedefaultspeedinteger from 0 to 100 is fastest, 10 is slowest5brightnessinteger from 0 to 500 is no backlight, 50 is brightest25colorsee help-randomdirectionleft, right, up, down-leftreactive--noExample:ite8291r3-ctl effect wave -s 0 -d up
// enable 'wave' effect with speed 0 (fastest) and bottom-up direction

ite8291r3-ctl effect rainbow -b 50
// enable rainbow effect with brightness 50 (max)

ite8291r3-ctl effect aurora -s 2 -c red -r
// enable reactive 'aurora' effect with speed 2 and color redHelp:positional arguments:
  {breathing,wave,random,rainbow,ripple,marquee,raindrop,aurora,fireworks}

optional arguments:
  -h, --help            show this help message and exit
  -s, --speed SPEED
                        Speed of the effect.
  -b, --brightness BRIGHTNESS
                        Brightness of the effect.
  -c, --color {none,red,orange,yellow,green,blue,teal,purple,random}
                        Color of the effect.
  -d, --direction {none,right,left,up,down}
                        Direction of the effect.
  -r, --reactive        Specify if you want the effect to be reactive.Note:If you specifyrandomfor color value, then all colors in the palette will be used in some fashion (depending on the effect).Note:Donotusenonefordirectionorcolor, because nothing will show up.Note:Not all effects support all properties. You will get an error message if you try to use an unsupported property. See theEffect property support matrixsection for more info.Note:The color names might be misleading.redactually refers to the first color in the palette,orangeto the second, and so on. If you modify the palette, and then set the color for an effect, you might not get what you expect.Note:Enabling an effect will change the brightness. If not specified, the default value (25) will be applied.monocolorChanges the color of the keyboard to a single color which may be specified as an RGB code or a predefined name. For the list of color names seeite8291r3-ctl monocolor -h.Example:ite8291r3-ctl monocolor -b 5 --name white
// set the backlight color to white and the brightness to 5 (very low)

ite8291r3-ctl monocolor --rgb 255,45,23
// change the backlight to color (255, 45, 23)Note:If you don't specify the brightness, it will not be changed.Note:No whitespaces are allowed in the RGB color code.--rgb 255, 45, 23is invalid and will be rejected.paletteManages the color palette on the device.Example:ite8291r3-ctl palette --restore
// restores the palette to the default values

ite8291r3-ctl palette --set-color 3 255,13,14
// sets the 3rd color of the palette to (255, 13, 14)

ite8291r3-ctl palette --random
// sets all color to something randomly generatedNote:The index specified for--set-colormust lie between 1 and 7 (inclusive).mode[experimental]Enables one of the interactive modes. There is only a single mode available at the moment:screen, and it only works on Linux, with Xorg. You also need to installpython-xlibandPillowPython pacakges. You can install them by installing the utility withpip install ite8291r3_ctl[mode-screen].Thescreenmode takes a screenshot every 0.2 seconds of your screen, downsizes it to 16x6, and lights up the backlight LEDs according to the colors on the picture.This videois perfect for trying it out. The colors are not cleared after exiting, so I guess this is also a way to set the desired colors if you don't want to spend time with the more robust way described in the following section.Example:ite8291r3-ctl mode --screen
// take screenshots of the whole screen and color according to that

ite8291r3-ctl mode --screen 1000,1000,200,300
// take screenshots of the rectangle whose top left corner is at (1000, 1000) and has a width of 200 and height of 300Note:You can exit by pressingCtrl+C(or sedingSIGINTto the process).Demo (video byVJ Loops):animPlays an animation from a file. The name might be a bit misleading, because this is actually the facility of the program that allows you to set the color values on a per key basis. Read the README file inassets/animatinsto see how animations may be made. It is a bit cumbersome, I am aware, however, a better way has yet to be found. The animation may be read from the standard input, so you can programatically generate it.Example:ite8291r3-ctl anim --file test_anim_file --loop 3
// read animation from 'anin_test_file' and loop it three times

ite8291r3-ctl anim --loop
// read animation from the standard input and loop it indefinitelyNote:If looping is required, then the whole file must be read into memory.queryQueries the controller.Example:ite8291r3-ctl query --fw-version
// prints the controller firmware version as X.Y.Z.W

ite8291r3-ctl query --brightness
// prints the current brightness

ite8291r3-ctl query --state
// prints the current state of the keyboard backlight: "on" or "off"

ite8291r3-ctl query --devices
// prints the list of supported devices found in the systemNote:This information may be useful if you want to use it in a script.Effect property support matrixThis matrix shows which effects support which properties.effectspeedcolordirectionreactivitybreathingyesyes--waveyes-yes-randomyesyes-yesrainbow----rippleyesyes-yesmarqueeyes---raindropyesyes--aurorayesyes-yesfireworksyesyes-yesNote:brightness may be specified for all currently supported effects.ContributionAll contribution is welcome. If you find a bug, typo, or have a feature request, do not hestitate to report it on theIssuespage (but please do a search first, maybe someone has already reported it). If you have an addition to the software and you want it to be inclueded, open apull request.Acknowledgementsaucc,ite-backlight, andProject Starbeathave been incredily useful in gaining insight into how this controller works, without them, this program would not have been created.