$ show flozz/rivalcfg
Rivalcfg is a Python 3 library and command-line tool for configuring SteelSeries gaming mice (Rival, Sensei, Prime, Aerox, Kana, Kinzu, etc.) on Linux, macOS, and Windows. It communicates with devices via HID (using hidapi) using reverse-engineered HID report protocols. The system provides a clean device profile dictionary schema for each mouse, a plugin-like handler system for different value types (choice, range, RGB color, button mapping, gradients, etc.), and a CLI that dynamically generates argparse options from the device profiles. It also includes persistent settings storage in JSON, udev rule management for Linux, and test doubles (FakeDevice, FakeMouseSettings) for testing without physical hardware. The project is community-driven, with new devices added frequently through reverse engineering.
The LLM identified 4 files worth highlighting for reuse:
The handler registry and base protocol. Each device setting has a value_type (e.g., 'choice', 'range', 'rgbcolor') that maps to a handler module in rivalcfg/handlers/. Each handler exports 'process_value(value, device)' to convert a user-provided value into HID bytes, and 'add_cli_option(parser, setting_name, setting_spec)' to dynamically generate argparse arguments. This pattern is highly reusable for any CLI tool that needs to encode user input into device-specific binary commands.
Provides an abstraction layer over the hidapi library, including a FakeDevice class that captures all HID writes to a BytesIO buffer for test assertions. Also supports environment-variable-driven dry-run mode (RIVALCFG_DRY) and debug mode. This is a clean, self-contained pattern for testing hardware-interacting code without actual hardware.
A standalone utility for parsing color strings (hex like '#ff0000' or named colors like 'red') into RGB tuples. It includes a dictionary of common color names mapped to hex values. This is a reusable module that could be extracted into any project needing color input handling.
An example device profile module. It exports a 'profile' dict containing vendor_id, product_id, and functions like set_sensitivity, set_polling_rate, set_buttons_mapping, set_color, etc. Each function constructs a raw HID report as bytes. This pattern is consistent across all device modules, making it easy to add new mice by only implementing the HID byte sequences. The profile schema could serve as a template for any HID-configurable peripheral.