keylightctl 0.1.24
Simple and extensible utility for controlling RGB keyboard lightning.
Requires Python: >=3.8



![DALL-E Generated Glowing RGB keyboard](https://i.imgur.com/3uhJdMI.png)

> **WIP: Now only some Lenovo laptops are supported, looking for other implementations and testers! Tested on linux systems.**

# Keylightctl - RGB Keyboard Light Controller

Simple and extensible utility for controlling RGB keyboard lightning. 

- [Features](#features)
- [Installation](#installaton)
- [Supported Models](#supported-models)
- [Configuration](#configuration)
- [Usage](#usage)
- [Tips](#tips)
- [Plans and Contributing](https://gitlab.com/leswell/keylightctl/-/blob/main/docs/contribute/README.md)

## Features

- define templates for keyboard lightning
- set different options separately (others are remembered)
- restore last options when turning on
- disable/enable keyboard lightning (_only disables this program_)
- set temporary options (eg.: for warning), these can be reset to the remembered options

## Installaton

**IN PROGRESS**

check the requirements section of your controller and make sure everything is working!
- [Lenovo](https://gitlab.com/leswell/keylightctl/-/blob/main/docs/controllers/lenovo.md#requirements)

## Supported Models
There are different controllers for different devices. The controllers define the available options (eg.: colors, speed, effect, ...).

|Controller Name|Description|Compatible Models
|--|--|--|
|[lenovo](https://gitlab.com/leswell/keylightctl/-/blob/main/docs/controllers/lenovo.md)| Based on [InstinctEx's lenovo-ideapad-legion-keyboard-led](https://github.com/https://github.com/InstinctEx/lenovo-ideapad-legion-keyboard-led) project. It uses pyusb. | Lenovo Ideapad Gaming 3 or Legion 5 Pro |

## Configuration

see [the example config.toml](https://gitlab.com/leswell/keylightctl/-/blob/main/examples/config/config.toml)

Keylightctl expects configuration file in `$HOME/.config/keylightctl/config.toml`. You can specify other locations using the `keylightctl -C CONFIG` flag.

### Controller
Choosing controller to use (you MUST set this):
```toml
[controller]
active_controller = "lenovo"
```

Controller specific configurations:
```toml
[controller.lenovo]
usb_vendor = "0x048D"
usb_product = "0xC963"
```

### Defining templates

Everything except description is an option provided by controllers.

```toml
[template.choose_a_name]
description = "white"
effect = "static"
colors = ["ffffff"]
```

## Usage

```bash
# Turn on/off:
keylightctl turn ON/OFF

# Toggle on/off:
keylightctl toggle
```

**Check out the usage section of your controller**, for the available options of set command and templates:
- [Lenovo](https://gitlab.com/leswell/keylightctl/-/blob/main/docs/controllers/lenovo.md#usage)


### Templates

```bash
# Activate a template:
keylightctl template [TEMPLATE_NAME]

# List templates: 
keylightctl list
```


### Others

```bash
# Disable/Enable
keylightctl disable/enable

# Show the current options
keylightctl show

# Show the details of a template
keyligthctl show TEMPLATE_NAME

```

If you are using `keylightctl --no-persist` flag, the new options won't be remembered (either using set or template) and `turn on` will reset to the saved options.

## Tips

I you find a good usecase, feel free to share!

### Warning light

1. Create a template which flashes the keyboard in red.
2. Run `keylightctl --no-persist template WARNING_TEMPLATE_NAME` to warn you
3. Reset it back to previous using `keylight turn on`


### Notifications

Something similar to the previous triggered by notifications.

### Use keybindings
You can you keybindings based on templates.

### Turn on keyboard lightning periodacially
You can create a cron job for example to turn on your keyboard lightning at night.

You may use weather data, integrate with system dark/light mode, etc. 

### Disable/ Enable for idle management
You can do something like this in `hypridle.conf` for example:
```py
# turn off keyboard backlight, comment out this section if you dont have a keyboard backlight.
listener { 
    timeout = 150                                          # 2.5min.
    on-timeout = keylight disable
    on-resume = keylight enable
}
```