# via-lighting-api
This Python API provides an interface for controlling the RGB lighting of keyboards that support the VIA protocol. It
allows you to dynamically change the brightness, effect, effect speed, and color of the lighting.
## Features
- Set lighting brightness
- Set lighting effect
- Set lighting effect speed
- Set lighting color in RGB or HSV format (HS only)
- Set absolute lighting color (real RGB color instead of HS only)
- Color correction algorithm allows to display accurate colors
- Save lighting settings to EEPROM
## Requirements
- Python 3.x
## Installation
```shell
pip install via-lighting-api
```
## Usage
> See a full example code in `example.py`.
### Init
First, import the `ViaLightingAPI` class from the module where it’s defined:
```python
from via_lighting_api import ViaLightingAPI
```
To initialize the API and control the lighting, you need to know the Vendor ID (VID) and Product ID (PID) of your
keyboard. If you don't know these values, run: `via-lighting-api --list-devices` and follow the hint to find them.
```python
# Replace with your keyboard's VID and PID
vid = 0x1234
pid = 0xABCD
# Initialize the API
api = ViaLightingAPI(vid, pid)
```
### Set Brightness
```python
# Set brightness to maximum
api.set_brightness(255)
```
### Set Effect
```python
# Set effect to 'Rainbow Moving Chevron'
api.set_effect(15)
```
### Set Effect Speed
```python
# Set effect speed to medium
api.set_effect_speed(127)
```
### Set Color
```python
# Set color to red (in RGB)
api.set_color([255, 0, 0])
# Set color to blue (in HSV)
api.set_color([170, 255])
```
### Set Absolute Color
> Set absolute lighting color (adjust both HS color and brightness), RGB format supported.
>
> The effect will be better only if your keyboard switch has a light-guiding design or the color saturation of the
> switch is low, because the color displayed will be greatly biased towards the color of the switch when the light
> brightness is low.
>
> If not, try out the color correction function.
```python
# Set absolute color to purple
api.set_color_abs([128, 0, 128])
```
### Color Correction
> This is useful when your keyboard switches do not have light guide designs, or they have highly saturated colors, and
> you want them to display accurate colors.
>
> To use it, you first need to test the RGB values of the light settings when your keyboard displays true white.
>
> This algorithm only applies to **set_color_abs()**
```python
# Enable color correction
api.set_color_correction([150, 240, 60])
# Disable color correction
api.disable_color_correction()
```
### Save Settings
```python
# Save current lighting settings to EEPROM
api.save()
```
## Troubleshooting
If your device is not detected, ensure that it is connected properly and that you have the correct VID and PID. Also,
check that your keyboard firmware supports VIA control.
## Disclaimer
This API provides an interface that can send user-defined commands directly to your device, which may cause unexpected
results if used improperly. Make sure you fully understand the VIA protocol and the commands you are sending.
## License
This API is open-source and can be used and modified by anyone. Please respect the original author’s work when using or
distributing this software.
Raw data
{
"_id": null,
"home_page": "https://github.com/JerryZhangZZY/via-lighting-api",
"name": "via-lighting-api",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "via api",
"author": "JerryZhangZZY",
"author_email": "JerryZhang20010417@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/aa/91/651fdda445ed6ef0ca7ab542161ee91d9a36ba341ae476787ce58dec9651/via_lighting_api-0.2.1.tar.gz",
"platform": null,
"description": "# via-lighting-api\n\nThis Python API provides an interface for controlling the RGB lighting of keyboards that support the VIA protocol. It\nallows you to dynamically change the brightness, effect, effect speed, and color of the lighting.\n\n## Features\n\n- Set lighting brightness\n- Set lighting effect\n- Set lighting effect speed\n- Set lighting color in RGB or HSV format (HS only)\n- Set absolute lighting color (real RGB color instead of HS only)\n- Color correction algorithm allows to display accurate colors\n- Save lighting settings to EEPROM\n\n## Requirements\n\n- Python 3.x\n\n## Installation\n\n```shell\npip install via-lighting-api\n```\n\n## Usage\n\n> See a full example code in `example.py`.\n\n### Init\n\nFirst, import the `ViaLightingAPI` class from the module where it\u2019s defined:\n\n```python\nfrom via_lighting_api import ViaLightingAPI\n```\n\nTo initialize the API and control the lighting, you need to know the Vendor ID (VID) and Product ID (PID) of your\nkeyboard. If you don't know these values, run: `via-lighting-api --list-devices` and follow the hint to find them.\n\n```python\n# Replace with your keyboard's VID and PID\nvid = 0x1234\npid = 0xABCD\n\n# Initialize the API\napi = ViaLightingAPI(vid, pid)\n```\n\n### Set Brightness\n\n```python\n# Set brightness to maximum\napi.set_brightness(255)\n```\n\n### Set Effect\n\n```python\n# Set effect to 'Rainbow Moving Chevron'\napi.set_effect(15)\n```\n\n### Set Effect Speed\n\n```python\n# Set effect speed to medium\napi.set_effect_speed(127)\n```\n\n### Set Color\n\n```python\n# Set color to red (in RGB)\napi.set_color([255, 0, 0])\n\n# Set color to blue (in HSV)\napi.set_color([170, 255])\n```\n\n### Set Absolute Color\n\n> Set absolute lighting color (adjust both HS color and brightness), RGB format supported.\n>\n> The effect will be better only if your keyboard switch has a light-guiding design or the color saturation of the\n> switch is low, because the color displayed will be greatly biased towards the color of the switch when the light\n> brightness is low.\n>\n> If not, try out the color correction function.\n\n```python\n# Set absolute color to purple\napi.set_color_abs([128, 0, 128])\n```\n\n### Color Correction\n\n> This is useful when your keyboard switches do not have light guide designs, or they have highly saturated colors, and\n> you want them to display accurate colors.\n>\n> To use it, you first need to test the RGB values of the light settings when your keyboard displays true white.\n>\n> This algorithm only applies to **set_color_abs()**\n\n```python\n# Enable color correction\napi.set_color_correction([150, 240, 60])\n# Disable color correction\napi.disable_color_correction()\n```\n\n### Save Settings\n\n```python\n# Save current lighting settings to EEPROM\napi.save()\n```\n\n## Troubleshooting\n\nIf your device is not detected, ensure that it is connected properly and that you have the correct VID and PID. Also,\ncheck that your keyboard firmware supports VIA control.\n\n## Disclaimer\n\nThis API provides an interface that can send user-defined commands directly to your device, which may cause unexpected\nresults if used improperly. Make sure you fully understand the VIA protocol and the commands you are sending.\n\n## License\n\nThis API is open-source and can be used and modified by anyone. Please respect the original author\u2019s work when using or\ndistributing this software.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This Python API provides an interface for controlling the RGB lighting of keyboards that support the VIA protocol. It allows you to dynamically change the brightness, effect, effect speed, and color of the lighting.",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/JerryZhangZZY/via-lighting-api"
},
"split_keywords": [
"via",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ba6debac7594c2ccf62d0f87014bacf5a41e1f933343d35e7d78d17488a727a5",
"md5": "6e963c941cf8590cdc7d8f4afb175e8e",
"sha256": "1cc097fd871fa790bf8f46930b3fdf53909d10d585e9e14983242a076914fedc"
},
"downloads": -1,
"filename": "via_lighting_api-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e963c941cf8590cdc7d8f4afb175e8e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6721,
"upload_time": "2024-11-15T02:06:57",
"upload_time_iso_8601": "2024-11-15T02:06:57.241980Z",
"url": "https://files.pythonhosted.org/packages/ba/6d/ebac7594c2ccf62d0f87014bacf5a41e1f933343d35e7d78d17488a727a5/via_lighting_api-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aa91651fdda445ed6ef0ca7ab542161ee91d9a36ba341ae476787ce58dec9651",
"md5": "e69a424ed83ad7477c26f1e65016e81f",
"sha256": "545e9558e4a7bce7b1f28a5a66ff616c93662c81ebfd0d8d64784a045ce2ed50"
},
"downloads": -1,
"filename": "via_lighting_api-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "e69a424ed83ad7477c26f1e65016e81f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5604,
"upload_time": "2024-11-15T02:06:58",
"upload_time_iso_8601": "2024-11-15T02:06:58.953071Z",
"url": "https://files.pythonhosted.org/packages/aa/91/651fdda445ed6ef0ca7ab542161ee91d9a36ba341ae476787ce58dec9651/via_lighting_api-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 02:06:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JerryZhangZZY",
"github_project": "via-lighting-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "hidapi",
"specs": []
}
],
"lcname": "via-lighting-api"
}
JSON
