Hardware overview

Hypercolor talks to RGB hardware through two parallel systems: a Hardware Abstraction Layer (HAL) for local devices connected over USB or SMBus/I2C, and a set of network driver crates for LAN and cloud-connected devices. Both converge on the same render pipeline, so your effects see one unified canvas and the drivers handle the rest.

This section covers how the transport stack is organized, what device families are supported, and how to get each one working. The compatibility matrix is the authoritative device list; start there if you want to confirm whether your hardware is supported.

#Device categories

#USB and SMBus devices

The hypercolor-hal crate implements protocol encoding for every device that plugs into your machine or sits on the system bus. It exports a Protocol trait (pure encoding, no I/O) and a Transport trait (async byte-level I/O) as separate layers, so the wire format for a Razer keyboard never reaches into network code, and the SMBus probe for an ASUS motherboard never touches USB.

Transport types live in the TransportType enum in hal/src/registry.rs and are the authoritative taxonomy:

Getting USB devices working on Linux requires udev rules. Getting SMBus/I2C devices working on Linux requires the i2c-dev kernel module and correct permissions on /dev/i2c-*. These are separate permission paths with separate failure modes. See USB devices and SMBus/I2C for each.

#Network devices

Network drivers live in separate crates behind the hypercolor-driver-api trait boundary. The hypercolor-network crate provides only the registry and orchestration shell; protocol logic belongs to each driver crate. Current network backends:

The ROLI Blocks bridge is a fifth registered driver module, but it speaks to a local blocksd Unix socket rather than the network. Both bridges are covered further down this page.

See network devices for the setup overview, then follow the per-vendor guide for pairing details.

#LCD and display devices

Some hardware carries a small LCD or display panel that Hypercolor can drive alongside its RGB zones. The Corsair LCD modules, Elite Capellix (0x0C39, 0x0C33), iCUE LINK (0x0C4E), Nautilus RS (0x0C55), XC7 RGB Elite (0x0C42), and XD6 Elite (0x0C43), stream 480×480 JPEG frames over USB HID/HIDAPI reports at up to 30 fps. The Ableton Push 2 uses a composite MIDI + bulk transport for its pad-grid lighting and display. These are treated as ordinary device outputs in Hypercolor; effect output is composited from the same canvas as everything else.

#OpenRGB bridge

For hardware that Hypercolor does not yet support natively, the OpenRGB fallback bridge connects to a user-managed OpenRGB SDK server (default port 6742) and routes frames through it. This lets you bring nearly any device into the render pipeline while native support is in progress. See OpenRGB fallback for configuration and caveats around device ownership.

#Transport architecture

The render pipeline delivers zone colors to the HAL; the HAL turns them into wire-format packets and ships them to the device:

graph TD
    C[SparkleFlinger canvas] --> S[SpatialEngine]
    S -->|per-zone colors| BM[BackendManager]
    BM --> HAL[hypercolor-hal]
    BM --> NET[Network drivers]
    HAL --> USB[USB transports]
    HAL --> SMB[SMBus transport]
    NET --> HUE[Hue DTLS :2100]
    NET --> NL[Nanoleaf UDP :60222]
    NET --> WLED[WLED DDP :4048]
    NET --> GV[Govee LAN UDP :4003]
    NET --> ORG[OpenRGB SDK :6742]
    USB --> Razer[Razer peripherals]
    USB --> Corsair[Corsair devices]
    USB --> ASUS_USB[ASUS USB HID]
    USB --> LianLi[Lian Li hubs]
    USB --> Other[QMK · PrismRGB · Nollie · Push 2]
    SMB --> ASUS_SMB[ASUS motherboard / GPU / DRAM]

Device fingerprints are stable across reconnects: USB devices key on VID/PID plus descriptor heuristics; network devices key on MAC address (WLED: net:wled:<mac>, Govee: net:govee:<mac>) or bridge serial (Hue, Nanoleaf). A DHCP IP change does not lose pairing.

#Supported hardware

The full device list lives in the compatibility matrix, which is generated from data/drivers/vendors/*.toml (32 vendor files). The summary below shows the driver families and their current status.

Neither bridge is counted among the 12 driver families with shipping device support. The OpenRGB bridge ships compiled in but its config entry is minted disabled, so enable it per OpenRGB fallback. The ROLI Blocks bridge scans by default (discovery.blocks_scan = true) and finds devices only when a blocksd socket is present; set discovery.blocks_socket_path if yours is not in the default location. Dygma is the thirteenth family implemented in the tree; it is excluded from the twelve because no Dygma device lights up yet.

#Device discovery

Hypercolor discovers devices automatically at startup and whenever a rescan is triggered.

USB/SMBus: scans for known VID/PID combinations and probes /dev/i2c-* bus nodes at startup. Hotplug events trigger rescan automatically when the daemon is running.

Network: runs mDNS browsing for each network driver’s service type. Devices can also be added by IP address in the config; the key differs per driver (known_ips for WLED and Govee, bridge_ips for Hue, device_ips for Nanoleaf) for networks where mDNS is blocked across VLANs. See network discovery troubleshooting for the exact snippets.

Trigger a manual scan:

# CLI: filter by target type
hypercolor devices discover
hypercolor devices discover --target wled --target hue

# REST: one scan at a time; concurrent requests return 409
curl -X POST http://localhost:9420/api/v1/devices/discover \
  -H 'Content-Type: application/json' \
  -d '{"targets": ["wled", "hue"], "timeout_ms": 5000}'

If a device does not appear after discovery, see devices not found for a transport-specific diagnosis checklist.

#Setup guides

Each transport path has its own setup page because the failure modes are different:

• USB devices: udev rules, hidraw vs hidapi, replug, hotplug
• SMBus/I2C: ASUS Aura motherboard, GPU, DRAM lighting; i2c-dev module; /dev/i2c-* permissions
• Network devices: mDNS discovery, known-IP config, pairing overview
• Philips Hue: link-button pairing, DTLS streaming
• Nanoleaf: power-button pairing, panel layout
• WLED: DDP vs E1.31, RGB vs RGBW
• Govee: LAN control setup, Razer-streaming SKUs, cloud API key
• OpenRGB fallback: bridge config, ownership modes
• Device quirks: rebrands, firmware splits, known edge cases
• Conflicting software: openrazer, OpenRGB, Aura Sync, iCUE

#Adding a driver

Driver modules in hypercolor-hal are organized by silicon/OEM family, not by retail branding. Rebranded SKUs are model-enum variants within an existing driver, not new modules. New USB drivers implement the Protocol trait (pure encoding) and register a DeviceDescriptor with the appropriate TransportType; new network drivers implement the hypercolor-driver-api traits and register with the DriverModuleRegistry.

See adding a driver and adding a network driver for the full implementation checklist and wire-format conventions.