kovarctl 0.1.0__tar.gz

kovarctl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lars Kiesow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kovarctl-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: kovarctl
+Version: 0.1.0
+Summary: Control the lighting of KOVAR keyboards (ROYUAN YC500 firmware) on Linux
+Author-email: Lars Kiesow <lkiesow@uos.de>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lkiesow/kovarctl
+Project-URL: Issues, https://github.com/lkiesow/kovarctl/issues
+Keywords: kovar,keyboard,rgb,lighting,hidraw
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8
+Dynamic: license-file
+
+# kovarctl
+
+Command line tool for the lighting of KOVAR keyboards (ROYUAN YC500 firmware, USB ID `3151:4010`) on Linux.
+
+Supported models, identified by the firmware model ID:
+
+| ID  | Model                       | Tested |
+|-----|-----------------------------|--------|
+| 738 | KOVAR                       | yes    |
+| 723 | KOVAR Wireless (USB cable)  | yes    |
+| 737 | KOVAR TKL                   | no     |
+| 736 | KOVAR 60                    | no     |
+
+The 2.4 GHz dongle (`3151:4011`) is not supported, because it uses a different protocol. Connect the keyboard with a USB cable instead.
+
+## Installation
+
+```sh
+pipx install kovarctl
+```
+
+`pip install --user kovarctl` and `uv tool install kovarctl` work as well.
+
+The only dependency is [click](https://click.palletsprojects.com/). Your user needs access to the keyboard's `/dev/hidraw*` nodes. Desktop sessions usually grant it, and the OpenRGB udev rules do too.
+
+## Usage
+
+```sh
+kovarctl list                                    # connected keyboards
+kovarctl info                                    # model, firmware, current lighting
+kovarctl effects                                 # effects and their options
+kovarctl mode wave --direction left --color 00ffff
+kovarctl mode breathing --speed 3                # options not given stay as they are
+kovarctl mode static --rainbow
+kovarctl off
+kovarctl side breathing --color red              # side light
+kovarctl live ff8000                             # one color for all keys, no flash write
+kovarctl live --fade 30                          # rainbow fade for 30 s
+some-program | kovarctl live --stdin             # one color per line
+kovarctl keys                                    # key names
+kovarctl custom set escape=red w=green --activate
+kovarctl custom set all=000040
+kovarctl custom save picture.json
+kovarctl custom load picture.json --activate
+kovarctl recover                                 # if the keyboard stopped answering
+```
+
+Use `--dry-run` to see what would be written, `-v` to report flash writes, and `--device` or `--id` to choose a keyboard when several are connected.
+
+## Shell completion
+
+kovarctl can complete commands, effect names and option values such as `--direction`. This needs the installed `kovarctl` command; it does not work with `python3 -m kovarctl`.
+
+**Bash** (version 4.4 or newer), add to `~/.bashrc`:
+
+```sh
+eval "$(_KOVARCTL_COMPLETE=bash_source kovarctl)"
+```
+
+**Zsh**, add to `~/.zshrc` after `compinit` has run (frameworks like Oh My Zsh run it for you):
+
+```sh
+eval "$(_KOVARCTL_COMPLETE=zsh_source kovarctl)"
+```
+
+**Fish**, add to `~/.config/fish/config.fish`:
+
+```sh
+_KOVARCTL_COMPLETE=fish_source kovarctl | source
+```
+
+Open a new shell afterwards. The completion is generated each time a shell starts (about 30 ms), so it always matches the installed version.
+
+## Keyboard flash
+
+The keyboard stores effect settings, the side light and the custom picture in its flash memory. Each write keeps the firmware busy for up to 1.4 seconds. During that time the keyboard ignores requests and can even lock up its lighting interface. kovarctl protects the keyboard in four ways:
+
+- It reads the current state first and skips writes that change nothing.
+- It waits until the keyboard is idle before sending anything, including across separate kovarctl calls.
+- It refuses more than 12 flash writes per minute unless you pass `--force`.
+- It refuses to run while another program, such as OpenRGB, has the keyboard open.
+
+For colors that change often, use `live`. Only switching into live mode is a flash write; after that, colors can change as often as you like.
+
+The blue LED between Esc and F1 cannot be controlled.
+
+## Development
+
+Install from a checkout of the repository and run the tests:
+
+```sh
+pip install -e . pytest
+python3 -m pytest
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/lkiesow/kovarctl/blob/main/LICENSE).
+
+## Releasing
+
+1. Set the new version in `pyproject.toml`, commit and tag it:
+
+   ```sh
+   git commit -am 'Release 0.2.0'
+   git tag v0.2.0
+   ```
+
+2. Build the packages and check them, in a virtual environment:
+
+   ```sh
+   rm -rf dist/
+   python3 -m build
+   twine check --strict dist/*
+   ```
+
+3. Upload to [PyPI](https://pypi.org/project/kovarctl/) and push the tag:
+
+   ```sh
+   twine upload dist/*
+   git push origin main v0.2.0
+   ```

kovarctl-0.1.0/README.md

@@ -0,0 +1,122 @@
+# kovarctl
+
+Command line tool for the lighting of KOVAR keyboards (ROYUAN YC500 firmware, USB ID `3151:4010`) on Linux.
+
+Supported models, identified by the firmware model ID:
+
+| ID  | Model                       | Tested |
+|-----|-----------------------------|--------|
+| 738 | KOVAR                       | yes    |
+| 723 | KOVAR Wireless (USB cable)  | yes    |
+| 737 | KOVAR TKL                   | no     |
+| 736 | KOVAR 60                    | no     |
+
+The 2.4 GHz dongle (`3151:4011`) is not supported, because it uses a different protocol. Connect the keyboard with a USB cable instead.
+
+## Installation
+
+```sh
+pipx install kovarctl
+```
+
+`pip install --user kovarctl` and `uv tool install kovarctl` work as well.
+
+The only dependency is [click](https://click.palletsprojects.com/). Your user needs access to the keyboard's `/dev/hidraw*` nodes. Desktop sessions usually grant it, and the OpenRGB udev rules do too.
+
+## Usage
+
+```sh
+kovarctl list                                    # connected keyboards
+kovarctl info                                    # model, firmware, current lighting
+kovarctl effects                                 # effects and their options
+kovarctl mode wave --direction left --color 00ffff
+kovarctl mode breathing --speed 3                # options not given stay as they are
+kovarctl mode static --rainbow
+kovarctl off
+kovarctl side breathing --color red              # side light
+kovarctl live ff8000                             # one color for all keys, no flash write
+kovarctl live --fade 30                          # rainbow fade for 30 s
+some-program | kovarctl live --stdin             # one color per line
+kovarctl keys                                    # key names
+kovarctl custom set escape=red w=green --activate
+kovarctl custom set all=000040
+kovarctl custom save picture.json
+kovarctl custom load picture.json --activate
+kovarctl recover                                 # if the keyboard stopped answering
+```
+
+Use `--dry-run` to see what would be written, `-v` to report flash writes, and `--device` or `--id` to choose a keyboard when several are connected.
+
+## Shell completion
+
+kovarctl can complete commands, effect names and option values such as `--direction`. This needs the installed `kovarctl` command; it does not work with `python3 -m kovarctl`.
+
+**Bash** (version 4.4 or newer), add to `~/.bashrc`:
+
+```sh
+eval "$(_KOVARCTL_COMPLETE=bash_source kovarctl)"
+```
+
+**Zsh**, add to `~/.zshrc` after `compinit` has run (frameworks like Oh My Zsh run it for you):
+
+```sh
+eval "$(_KOVARCTL_COMPLETE=zsh_source kovarctl)"
+```
+
+**Fish**, add to `~/.config/fish/config.fish`:
+
+```sh
+_KOVARCTL_COMPLETE=fish_source kovarctl | source
+```
+
+Open a new shell afterwards. The completion is generated each time a shell starts (about 30 ms), so it always matches the installed version.
+
+## Keyboard flash
+
+The keyboard stores effect settings, the side light and the custom picture in its flash memory. Each write keeps the firmware busy for up to 1.4 seconds. During that time the keyboard ignores requests and can even lock up its lighting interface. kovarctl protects the keyboard in four ways:
+
+- It reads the current state first and skips writes that change nothing.
+- It waits until the keyboard is idle before sending anything, including across separate kovarctl calls.
+- It refuses more than 12 flash writes per minute unless you pass `--force`.
+- It refuses to run while another program, such as OpenRGB, has the keyboard open.
+
+For colors that change often, use `live`. Only switching into live mode is a flash write; after that, colors can change as often as you like.
+
+The blue LED between Esc and F1 cannot be controlled.
+
+## Development
+
+Install from a checkout of the repository and run the tests:
+
+```sh
+pip install -e . pytest
+python3 -m pytest
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/lkiesow/kovarctl/blob/main/LICENSE).
+
+## Releasing
+
+1. Set the new version in `pyproject.toml`, commit and tag it:
+
+   ```sh
+   git commit -am 'Release 0.2.0'
+   git tag v0.2.0
+   ```
+
+2. Build the packages and check them, in a virtual environment:
+
+   ```sh
+   rm -rf dist/
+   python3 -m build
+   twine check --strict dist/*
+   ```
+
+3. Upload to [PyPI](https://pypi.org/project/kovarctl/) and push the tag:
+
+   ```sh
+   twine upload dist/*
+   git push origin main v0.2.0
+   ```

kovarctl-0.1.0/kovarctl/__init__.py

@@ -0,0 +1 @@
+"""Control the lighting of KOVAR keyboards (ROYUAN YC500 firmware)."""

kovarctl-0.1.0/kovarctl/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()