Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zsa/kontroll
Kontroll demonstates how to control the Keymapp API, making it easy to control your ZSA keyboard from the command line and scripts.
https://github.com/zsa/kontroll
Last synced: about 2 months ago
JSON representation
Kontroll demonstates how to control the Keymapp API, making it easy to control your ZSA keyboard from the command line and scripts.
- Host: GitHub
- URL: https://github.com/zsa/kontroll
- Owner: zsa
- License: mit
- Created: 2024-05-22T13:02:02.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2024-07-31T11:45:18.000Z (about 2 months ago)
- Last Synced: 2024-08-01T09:08:04.422Z (about 2 months ago)
- Language: Rust
- Size: 167 KB
- Stars: 94
- Watchers: 5
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Kontroll 
Kontroll demonstates how to control the Keymapp API, making it easy to control your ZSA keyboard from the command line and scripts. You can read more about it on [our blog](https://blog.zsa.io/introducing-kontroll/).
You can use it to switch layers and control the keyboard's RGB and status LEDs programmatically via Keymapp. Call it from a script to make your ZSA keyboard react to system events in useful ways (switching to layers when apps are activated, or changing lighting when you get an important email, etc).
Note: All features of Kontroll work on the Moonlander and the Voyager. Only some features work on the ErgoDox EZ, since that board has a different processor (Teensy). You're able to use Kontroll to switch layers (which is really the crucial bit) and to set the status LEDs, but you will not be able to control the RGB LEDs of the ErgoDox EZ.
Feel free to submit scripts that use Kontroll as pull requests via the [examples](examples/) directory.
## Installation
If you have the [rust toolchain and protoc installed](/dependencies.md), you can build Kontroll by cloning this repository and running the following command:
```bash
cargo build --release
```
Otherwise, you can download the latest release from the [releases page](https://github.com/zsa/kontroll/releases) and add it to your PATH.
## Prerequisites
Make sure you have a recent version of Keymapp (v1.3.2+) running with a ZSA keyboard connected to your computer. In Keymapp's config page, make sure the API is enabled.
On Linux and macOS, keymapp creates a Unix Domain Socket located at $CONFIG_DIR/.keymapp/keymapp.sock.
On Windows, by default, the API listens on port 50051. If you have changed the port in keymapp's settings UI, you can specify the port to Kontroll by setting the `KEYMAPP_PORT` environment variable.
## Usage
```cli
Usage: kontroll
Commands:
status Get the status of the currently connected keyboard
list List all available keyboards
connect Connect to a keyboard given the index returned by the list command
connect-any Connect to the first keyboard detected by keymapp
set-layer Set the layer of the currently connected keyboard
set-rgb Sets the RGB color of a LED
set-rgb-all Sets the RGB color of all LEDs
restore-rgb-leds Restores the RGB color of all LEDs to their default
set-status-led Set / Unset a status LED
restore-status-leds Restores the status of all status LEDs to their default
increase-brightness Increase the brightness of the keyboard's LEDs
decrease-brightness Decrease the brightness of the keyboard's LEDs
disconnect Disconnect from the currently connected keyboard
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
```
## Examples
Under [examples](/examples/README.md) is a showcase on how you could use the API.
Run the examples by having the rust toolchain installed and run the following command:
```bash
cargo run --release --example snake
```
## Development
We developed Kontroll to showcase the Keymapp API and to provide a simple way to control your ZSA keyboard from the command line and scripts.
If you wish to build your own client, you need to implement the Keymapp API using gRPC. The protobuf file [available here](proto/keymapp.proto) describes all the remote call procedures and messages available.
An example on how to implement each procedure call can be found in the [api.rs](src/api.rs) file.
If you are using the Rust programming language, you may use the [Kontroll crate](https://crates.io/crates/kontroll).