Metadata-Version: 2.1
Name: ite8291r3-ctl
Version: 0.3
Summary: ITE 8291 (rev 0.03) userspace driver
Home-page: https://github.com/pobrn/ite8291r3-ctl
Author: Barnabás Pőcze
Author-email: pobrn@protonmail.com
License: GPLv2
Project-URL: Source, https://github.com/pobrn/ite8291r3-ctl
Project-URL: Bug Reports, https://github.com/pobrn/ite8291r3-ctl/issues
Keywords: ITE,ITE8291,RGB,keyboard,backlight,linux
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: pyusb
Provides-Extra: mode-screen
Requires-Dist: python-xlib; extra == "mode-screen"
Requires-Dist: Pillow; extra == "mode-screen"

# What is it?
`ite8291r3-ctl` is a userspace driver for the ITE 8291 (rev 0.03) RGB keyboard backlight controller.


# Disclaimer
**This 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.0**


# Compatibility
The following devices have been reported to work:

| idVendor | idProduct | bcdDevice |             manufacturer             |      product      |
|----------|-----------|-----------|--------------------------------------|-------------------|
| 048d     | 6004      | 0.03      | Integrated Technology Express, Inc.  | ITE Device(8291)  |
| 048d     | ce00      | 0.03      | Integrated Technology Express, Inc.  | ITE Device(8291)  |

If you believen your device should be supported, but it is not, please open an issue. You can run `ite8291r3-ctl query --devices` to see the supported devices found in the system. Alternatively, you can use `lsusb -d 048d:`.


# Dependencies
### Required
* [`Python 3.6`](https://python.org) or above
* [`pyusb`](https://github.com/pyusb/pyusb) *(and thus one of the backend that it supports, e.g. [`libusb`](https://libusb.info))*
### Optional
#### for the `screen` mode
* [`python-xlib`](https://pypi.org/project/python-xlib) Python package
* [`Pillow`](https://pypi.org/project/Pillow) Python package


# Features
## Current
* Support for built-in effects
* Monocolor mode
* Color palette management
* Per-key RGB colors
* Animations
* Coloring the keyboard according to what is on screen **[exprimental, Linux+Xorg only]**
* Querying parts of the controller state

## TO-DO
* User interface for instructing the controller to save changes
* Modify timeout
* A more sane way of assigning colors to specific keys
* Possibly a GUI
* Coloring the keyboard based on audio


# How to install
## Using PIP
The simplest way to install is to use `pip`:
```
pip install ite8291r3-ctl
```

*Note:* This will not download anything from the `assets` directory, 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, run `pip` as root.

## Manually
### Downloading
If you have `git` installed:
```
git clone https://github.com/pobrn/ite8291r3-ctl
```

If you don't, then you can download it [here](https://github.com/pobrn/ite8291r3-ctl/archive/master.zip).

### Installing
After downloading the files, open the directory in a terminal, and run `pip install .` (or `pip install .[mode-screen]` if you want the optional dependencies for the `screen` mode). If you have multiple Python versions installed, specify one that satisfies the requirements.


# How to use
## Running it without installation
It is possible to run the utility without installation. Open the directory in a terminal, then run `python -m ite8291r3_ctl`. In this case you need to install the dependencies manually. `pip install -r requirements.txt` to install the required `pyusb` package. If you want to try the `screen` mode, you need to install the optional dependencies as well.

## Accessing the USB device
By default you need *root* privileges if you want to use this utility. As noted [here](https://github.com/rodgomesc/avell-unofficial-control-center/issues/45) and [here](https://aur.archlinux.org/cgit/aur.git/tree/10-ite-backlight.rules?h=ite-backlight), you can create a `udev` rule to allow everyone on your system to access this particular USB device, and thus you won't need to run the program as `root`.

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, run `sudo udevadm control --reload`, then `sudo udevadm trigger`. Or reboot.

## Subcommands
Use `ite8291r3-ctl -h` to get a list of subcommands. Use `ite8291r3 <subcommand> -h` to get the help for a given subcommand. Use `ite8291r3-ctl --device <bus>/<addr>` to select a device to control, if the device is not specified, the first available will be used.
### off
Turns off the keyboard backlight.

*Example:*
```
ite8291r3-ctl off
```
___
### brightness
Changes 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 33
```
___
### test-pattern
```
ite8291r3-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 freeze
```

___
### effect
Changes the current effect. You can specify the following properties for effects:
| property   | possible values       | note                               | default |
|------------|-----------------------|------------------------------------|---------|
| speed      | integer from 0 to 10  | 0 is fastest, 10 is slowest        | 5       |
| brightness | integer from 0 to 50  | 0 is no backlight, 50 is brightest | 25      |
| color      | *see help*            | -                                  | random  |
| direction  | left, right, up, down | -                                  | left    |
| reactive   | -                     | -                                  | no      |

*Example:*
```
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 red
```

*Help*:
```
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 specify `random` for color value, then all colors in the palette will be used in some fashion (depending on the effect).

*Note:* Do **not** use `none` for *direction* or *color*, 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 the *Effect property support matrix* section for more info.

*Note:* The color names might be misleading. `red` actually refers to the first color in the palette, `orange` to 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.

___
### monocolor
Changes 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 see `ite8291r3-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, 23` is invalid and will be rejected.

___
### palette
Manages 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 generated
```

*Note:* The index specified for `--set-color` must 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 install `python-xlib` and `Pillow` Python pacakges. You can install them by installing the utility with `pip install ite8291r3_ctl[mode-screen]`.

The `screen` mode 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 video](https://www.youtube.com/watch?v=3VZthcTSBrI) is 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 300
```

*Note:* You can exit by pressing `Ctrl+C` (or seding `SIGINT` to the process).

*Demo (video by [VJ Loops](https://www.youtube.com/channel/UCo-cAdBNbXbWF5e_efkof7Q))*:

![screen mode demo](https://i.imgur.com/qYapxwf.gif)

___
### anim
Plays 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 in `assets/animatins` to 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 indefinitely
```

*Note:* If looping is required, then the whole file must be read into memory.

___
### query
Queries 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 system
```

*Note:* This information may be useful if you want to use it in a script.


# Effect property support matrix
This matrix shows which effects support which properties.

| effect    | speed | color | direction | reactivity |
|-----------|-------|-------|-----------|------------|
| breathing | yes   | yes   | -         | -          |
| wave      | yes   | -     | yes       | -          |
| random    | yes   | yes   | -         | yes        |
| rainbow   | -     | -     | -         | -          |
| ripple    | yes   | yes   | -         | yes        |
| marquee   | yes   | -     | -         | -          |
| raindrop  | yes   | yes   | -         | -          |
| aurora    | yes   | yes   | -         | yes        |
| fireworks | yes   | yes   | -         | yes        |

*Note:* brightness may be specified for all currently supported effects.


# Contribution
All contribution is welcome. If you find a bug, typo, or have a feature request, do not hestitate to report it on the [*Issues*](https://github.com/pobrn/ite8291r3-ctl/issues) page (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 a [*pull request*](https://github.com/pobrn/ite8291r3-ctl/pulls).


# Acknowledgements
[`aucc`](https://github.com/rodgomesc/avell-unofficial-control-center), [`ite-backlight`](https://github.com/hexagonal-sun/ite-backlight), and [*Project Starbeat*](https://github.com/kirainmoe/tongfang-hackintosh-utility) have been incredily useful in gaining insight into how this controller works, without them, this program would not have been created.
