To see which devices are tested take a look at the Compatibility Table.
See CONTRIBUTING Guidelines.
Done
- Set LED animation
- Set single-/multi-color (rainbow)
- Set LED brightness
- Set LED color per key
- Load color profiles from files
Missing
- Individual keymapping
Please see Docs.rs
To workaround the issue of "slow keypresses", @felfert implemented a userspace HID driver/service and a corresponding CLI.
Check out UHID Driver documentation on how to install and use it.
Documentation for the CLI is now generated in separate files:
Alternative CLI and service for Linux
- Color: #00ff00 (green)
- Mode: wave
- Speed: fast
- Brightness: medium
./cherryrgb_cli --brightness medium animation wave fast 00ff00
Please note, that the following modes are unofficial and therefore are not guaranteed to work properly:
radar
vortex
fire
stars
rain
- Brightness: full
- Key 0 color: #ff00ff
- Key 1 color: #0000ff
./cherryrgb_cli --brightness full custom-colors ff00ff 0000ff
In addition to specifying custom colors via arguments you can create your custom color profiles in a separate file and pass the path of the file as an argument.
Color profile file structure:
{
"0": "ff00ff",
"1": "fffff",
"45": "00ff00",
"31": "ff0000"
}
A profile file is a JSON file that contains a root object and a key value pair for each key. Both key and value MUST be strings. The JSON parser now has ben changed slightly to allow for 2 normally unsupported variations:
- C99-style comments (Starting at
//
until the end of a line). - A trailing comma (after the last key value pair) is ignored. Each key is identified by its index. The colors are specified using hexadecimal color codes. The maximum usable index is 124 (currently hardcoded).
Example:
./cherryrgb_cli --brightness full color-profile-file {FILE PATH}
Example bash
script, demonstrating the new --keep-existing-colors
feature:
#!/bin/bash
cherryrgb_cli color-profile-file examples/static_rainbow.json
for i in 1 2 3 4 5 ; do
sleep 0.5
cherryrgb_cli color-profile-file -k examples/white_f12.json
sleep 0.5
cherryrgb_cli color-profile-file -k examples/red_f12.json
done
Note:
Because existing colors cannot be read from the keyboard, they are stored in a local cache
after setting them. Therfore, in order to use this feature, the command color-profile-file
has to be invoked at least once before.
git clone https://github.com/skraus-dev/cherryrgb-rs.git
cd cherryrgb-rs
cargo build
cargo xtask all
For a complete build on Linux (including service and alternative cli), you can do the following:
- install 2 additional native dependencies:
- On Ubuntu or Debian:
sudo apt-get update && sudo apt-get install -y libclang-dev clang
- On Fedora:
sudo dnf install -y llvm-devel clang-devel
- On Ubuntu or Debian:
- append
--all-features --all
to the`cargo build line
Now you can run the binary from ./target/debug/cherryrgb_cli
When running the above command cargo xtask all
, a directory hierarchy
is generated:
target/generated/docs/
man/
completions\
which contain:
- Markup documentation
- Unix man pages. Copy those into your manpath, where
the extension of each file indicates the man secrion (usually a subdirectory named
man1
,man8
etc.) - Shell completion scripts for
bash
,elvish
,fish
,powershell
andzsh
. To use the completion scripts, you mus copy them to the appropriate location (which depends both on your shell and system). For example, on Fedora, the bash completion scripts go into/etc/bash_completion.d/
. Refer to the documentation of your shell/system.
If the interaction with the keyboard is fine as root-user, you need to configure udev to adjust the ownership of the device handle, so a regular user can access it.
The repository contains an example udev rule file udev/99-cherryrgb.rules
.
You might want to adjust it to only handle your specific product id (check via lsusb
).
In the following example we assume your product id is 0x00dd.
-
(optional) Change
ATTR{idProduct}=="*"
toATTR{idProduct}=="00dd"
. -
Copy the file to the correct location:
cp 99-cherryrgb.rules /etc/udev/rules.d/
(as a privileged user) -
Finally, reload the udev rules via
udevadm control --reload
and apply them usingudevadm trigger
or by re-plugging your keyboard.
This is a known issue in the keyboard firmware. It is mentioned here: https://bbs.archlinux.org/viewtopic.php?id=267365
- Proper way to fix it: Contact Cherry Support
- Workaround: Comment out the respective line in
99-cherryrgb.rules
and reload/trigger the udev rule. - See this doc for an alternative solution on Linux.
Use at your own risk. This project is not affiliated or endorsed by Cherry GmbH.
- deps: Migrated from StructOpt+clap v2.x to clap v4.x.
- Fixed #52
- Added xtask for generating docs, manpages and shell completion scripts
- Added woraround in service for handling newer Firmware 0105
- Refactored socket I/O and command handling in service
- Implemented
--keep-existing-colors
option forcolor-profile-file
subcommand (fixes #14) - Relaxed parsing of color-profiles
- Allow comments using
//
- Allow trailing comma after last key-value pair
- Allow comments using
- deps: Bump binrw to v0.11.2 (thx @felfert once again :))
- meta: docs.rs buildfix (by @felfert)
- lib: Query rusb for detach support (by @felfert)
- general: Add ppc64le build (by @felfert)
- compatibility report: G80-3000N FL RGB (by @TheBiochemic)
- docs: Add documentation about service usage (by @felfert)
- service: Implement service daemon and new client (uhid) (by @felfert)
- lib: Rework fetch_device_state to use GetKeymap and GetKeyIndexes
- lib: Use thiserror, deprecate anyhow
- lib: Re-export strum-crate
- lib: Implement auto kernel-driver handling (detach / attach) (by @felfert)
- README/udev: Add workaround for sluggish keyevents via udev; however it makes special keys not work
- cli: Init logger before sending first packets
- cli: Functionality to pass in colors for indexed keys via json file (by @luv4bytes)
- README: Note about reloading udev rules (by @mpldr)
- Compatibility report: MX BOARD 3.0S FL RGB (by @luv4bytes)
- Compatibility report: G80 3000 TKL RGB (by @cewbdex)
- fix: Skip kernel driver detaching for non-unix platforms
- Refactor parameter handling and help for enums (by @felfert)
- Filter unsupported Cherry keyboards (by @felfert)
- Improve README with usage and troubleshooting
- Add example udev rules file
- Refactor internal API
- Models: Correct data_offset and checksum fields from u8 to u16
- API: Improve usability by wrapping device communication inside struct CherryKeyboard
- Implement enumerating all connected Cherry GmbH devices
- Differentiate between payload and flags/commands
- Rename LightingModes: Radar, Stars
- Fix bug with missing padding
- Add custom LED color setting
- General code cleanup
- Initial release