hidproto

A Python DSL for HID device protocols. Define commands and effects as pure data, the runtime handles transport, discovery, checksums, and state tracking. Works on Linux, Windows, and macOS.

Why

Every HID device project (OpenRGB, keyRGB, rivalcfg, openrazer) rewrites the same boilerplate: open device, build reports, send ioctl, manage state. hidproto lets you define a protocol in ~50 lines of pure data and get a working device driver.

Existing Python RGB libraries (PyRGBDev, pychroma, python-rgbkeyboards) all depend on vendor SDKs and only work on Windows. hidproto talks HID directly, no vendor SDK needed.

Install

pip install hidproto            # Linux (hidraw, zero deps)
pip install hidproto[hidapi]    # Windows / macOS (cross-platform)

Platform support

On Linux, hidraw is used by default for zero-dependency operation. On other platforms, the hidapi backend is auto-selected. You can also force hidapi on Linux with pip install hidproto[hidapi].

Supported devices

25 protocols across 19 vendors, all auto-discovered:

Adding a new device is one Python file in protocols/<vendor>/. The registry auto-discovers it.

Quick start

from hidproto import HIDDevice, HIDProtocol, command, effect

class MyKeyboard(HIDProtocol):
    vendor_id    = 0x048D
    product_id   = 0x8910
    report_id    = 0xCC
    report_size  = 6
    rows         = 6
    cols         = 20
    preset_base  = 0x71
    custom_base  = 0xA1
    color_custom = 0xAA

    animation_mode   = command(0x00, args=1, doc="Animation mode")
    set_led          = command(0x01, args=4, doc="Per-key color")
    brightness_speed = command(0x09, args=4, doc="Brightness + speed")
    wave_slot        = command(0x15, args=4, doc="Wave slot")

    effects = {
        "off":  effect("off",  animation=0x0C, needs_clear=True),
        "wave": effect("wave", animation=0x04, slot_cmd="wave_slot",
                        directions=("up", "down", "left", "right")),
    }

Keyboard = HIDDevice.for_protocol(MyKeyboard)

with Keyboard() as kb:
    kb.brightness(8)
    kb.speed(5)
    kb.effect("wave", direction="right", color=(255, 0, 0))

No boilerplate, no subclassing, no transport code.

CLI

hidproto devices                                    # list connected HID devices
hidproto info ite8910                               # show commands, effects, matrix size
hidproto ite8910 wave -d right -b 8 -s 5            # wave rainbow, right, brightness 8
hidproto ite8910 wave -d left -c ff0000             # wave red, left
hidproto ite8910 breathing -c 00ff00 -b 8           # breathing green
hidproto ite8910 scan -c ff0000 --color2 0000ff     # scan red + blue
hidproto ite8910 off                                # turn off

All options are auto-generated from the protocol definition. Each device gets its own subcommands with --help.

Features

• DSL - command() and effect() descriptors generate everything from pure data
• Multi-step effects - step() chains multiple commands for complex protocols (Corsair, Cherry)
• Auto-discovery - protocols registered via entry points or filesystem scan
• Cross-platform - hidraw on Linux, hidapi on Windows/macOS
• Checksums - XOR (Razer, Das), SUM (Cherry), custom via _with_checksum()
• State caching - skip redundant sends, invalidate on resume
• CLI - Click-based with per-device subcommands
• GUI - Qt keyboard visualizer with per-key editing, color picker, auto-connect, dynamic effect controls (directions, colors, random toggle), brightness glow rendering

GUI

pip install hidproto[gui]
hidproto-gui

Auto-detects connected devices and shows the keyboard layout with per-key RGB editing. Effect controls (directions, color pickers, random toggle) are auto-generated from the protocol's EffectSpec.

Architecture

hidproto/
  cli.py              Click CLI with auto-generated subcommands
  command.py           CommandSpec + @command descriptor
  effect.py            EffectSpec + step() for multi-step effects
  protocol.py          HIDProtocol base (report building, transport)
  device.py            HIDDevice wrapper (effects, caching, brightness/speed)
  transport.py         HidrawTransport (Linux native)
  transport_hidapi.py  HidapiTransport (cross-platform)
  discovery.py         sysfs device discovery
  registry.py          Auto-discovery + entry point plugin system
  checksum.py          xor/sum checksum helpers
  layout.py            Key dataclass for keyboard layouts

gui/
  app.py               Qt main window with auto-connect
  keyboard_widget.py   Per-key RGB keyboard renderer
  effect_panel.py      Dynamic effect controls from EffectSpec

protocols/
  alienware/    asus/       cherry/     coolermaster/
  corsair/      das/        ducky/      fnatic/
  hyperx/       ite/        keychron/   logitech/
  mountain/     msi/        nzxt/       obinslab/
  qmk/          razer/      redragon/   roccat/
  sony/         steelseries/ wooting/

License

MIT