0x8071 · rgbEffects

The modern per-cluster RGB effect engine, the successor to 0x8070 colorLedEffects. A device groups its LEDs into clusters, each advertising a set of effects. get_device_info, get_cluster_info, and get_effect_info query the three info modes of the polymorphic getInfo function (device, cluster, and per-effect detail respectively). set_rgb_cluster_effect applies a chosen effect, with up to 10 effect-specific parameter bytes, a RgbPersistence flag (volatile RAM or non-volatile EEPROM), and a PowerModeTarget (full-power or power-save mode).

Software must call set_sw_control first to claim ownership of clusters and/or power modes before any write call will be accepted. get_nv_config / set_nv_config read and write named non-volatile capabilities (boot-up effect, demo, active dimming, etc.). Power-mode timeouts are managed with get_power_mode_config / set_power_mode_config; the current mode with get_power_mode / set_power_mode. Three unsolicited events are decoded:

• EffectSync — a periodic effect reached a synchronization point; carries the cluster index and current timing position in milliseconds.
• UserActivity — activity detected or the no-activity timeout was reached (ActivityEventType).
• ClusterChanged — mirrors a setRgbClusterEffect request; carries the full params, persistence, and power-mode target.

Key types: RgbDeviceInfo, RgbClusterInfo, RgbEffectInfo, RgbSwControl, RgbNvConfig, RgbPowerModeConfig, RgbPersistence, RgbPowerMode, SwControlFlags, RgbNvCapabilities, RgbExtCapabilities.

Spec: Logitech HID++ 2.0 — rgbEffects. Used by: Typed wrapper in openlogi-hidpp.

Function reference

The RgbEffectsFeature wrapper (0x8071) exposes methods for querying and configuring per-cluster RGB effects, managing software control and non-volatile capabilities, and receiving unsolicited lighting events.

Methods

All pub async fn methods return Result<…, Hidpp20Error>. listen is synchronous and returns a channel receiver directly.

Types

RgbDeviceInfo

Device-level information from get_device_info.

RgbClusterInfo

Cluster-level information from get_cluster_info.

RgbEffectInfo

Effect-level information from get_effect_info.

RgbSwControl

Software-control state from get_sw_control.

RgbNvConfig

A non-volatile configuration entry from get_nv_config.

RgbPowerModeConfig

Power-mode configuration from get_power_mode_config.

RgbPowerMode

An overall RGB power mode.

PowerModeTarget

The power-mode target an effect applies to, packed into set_rgb_cluster_effect.

SlotInfoType

The kind of slot information requested for an onboard-stored effect.

LedBinIndex

Selects which LED bin parameter a LED-bin call addresses.

ActivityEventType

The kind of user-activity event.

RgbPersistence

Persistence of a cluster effect, packed into the low two bits of the set_rgb_cluster_effect flags byte.

RgbExtCapabilities

Extended device capabilities from get_device_info.

RgbNvCapabilities

Supported non-volatile capabilities from get_device_info.

SwControlFlags

Software-control flags for set_sw_control.

EventsNotificationFlags

Event-notification flags for set_sw_control.

DisplayPersistencyCapabilities

Display-persistency capabilities of a cluster from get_cluster_info.

Events

RgbEffectsFeature implements EmittingFeature<RgbEffectsEvent>; call listen() to receive an async_channel::Receiver<RgbEffectsEvent> channel.

RgbEffectsEvent

Wire format

Short (3-byte) requests use call; long (16-byte) requests use call_long. All multi-byte fields are big-endian. Responses are read from the 16-byte extended payload.

get_device_info (fn 0)

Request: [0xff, 0xff, 0x00] (ALL_CLUSTERS, ALL_EFFECTS, typeOfInfo=0)

Response (byte → field):

get_cluster_info (fn 0)

Request: [cluster_index, 0xff, 0x00] (ALL_EFFECTS, typeOfInfo=0)

Response (byte → field):

get_effect_info (fn 0)

Request: [cluster_index, cluster_effect_index, 0x00] (typeOfInfo=0)

Response (byte → field):

get_onboard_effect_info (fn 0)

Request (long, 16 bytes): [cluster_index, cluster_effect_index, 0x01, slot, slot_info_type, 0…] (typeOfInfo=0x01)

Response: bytes 3–15 → raw [u8; 13] onboard params (meaning depends on SlotInfoType).

set_rgb_cluster_effect (fn 1)

Request (long, 16 bytes):

Response: acknowledged (no payload fields used).

set_multi_led_cluster_pattern (fn 2)

Request: [cluster_index, pattern, 0x00]

Response: acknowledged.

get_nv_config (fn 3)

Request: [0x00, cap_hi, cap_lo] — getOrSet=0, capability bits as big-endian u16.

Response (byte → field):

set_nv_config (fn 3)

Request (long, 16 bytes): [0x01, cap_hi, cap_lo, state, param1, param2, 0…] — getOrSet=1.

Response: acknowledged.

get_led_bin_info (fn 4)

Request: [get_or_set, cluster_index, led_bin_index] — get_or_set is 0x00 (active) or 0x02 (backup).

Response: bytes 3–10 → raw [u8; 8] LED bin params.

set_led_bin_info (fn 4)

Request (long, 16 bytes): [0x01, cluster_index, led_bin_index, params[0..8], 0…]

Response: acknowledged.

get_sw_control (fn 5)

Request: [0x00, 0x00, 0x00] — getOrSet=0.

Response (byte → field):

set_sw_control (fn 5)

Request: [0x01, control.bits(), events.bits()] — getOrSet=1.

Response: acknowledged.

set_effect_sync_correction (fn 6)

Request (long, 16 bytes): [cluster_index, 0x00, drift_hi, drift_lo, 0…] — drift_value as big-endian i16; cluster_index=0xff targets all clusters.

Response: acknowledged.

get_power_mode_config (fn 7)

Request: [0x00, 0x00, 0x00] — getOrSet=0.

Response (byte → field):

set_power_mode_config (fn 7)

Request (long, 16 bytes): [0x01, flags_hi, flags_lo, psave_hi, psave_lo, off_hi, off_lo, 0…] — getOrSet=1.

Response: acknowledged.

get_power_mode (fn 8)

Request: [0x00, 0x00, 0x00] — getOrSet=0.

Response: byte 1 → RgbPowerMode (1=FullRgb, 2=PowerSave, 3=PowerOff).

set_power_mode (fn 8)

Request: [0x01, mode as u8, 0x00] — getOrSet=1.

Response: acknowledged.

shutdown (fn 9)

Request: [0x00, 0x00, 0x00]

Response: acknowledged.

Events (unsolicited)

Usage (Rust)

use hidpp::{
    device::Device,
    feature::rgb_effects::{
        RgbEffectsFeature, RgbPersistence, PowerModeTarget, SwControlFlags,
        EventsNotificationFlags,
    },
};

// device: Device, obtained via Device::new(channel, index).await?
device.enumerate_features().await?;
if let Some(feat) = device.get_feature::<RgbEffectsFeature>() {
    // Claim software control of all clusters and enable effect-sync events.
    feat.set_sw_control(
        SwControlFlags::ALL_CLUSTERS,
        EventsNotificationFlags::EFFECTS_SYNC,
    )
    .await?;

    // Query cluster 0 and its first effect.
    let cluster = feat.get_cluster_info(0).await?;
    let effect = feat.get_effect_info(0, 0).await?;
    println!("cluster 0 has {} effects; first effect_id={:#06x}", cluster.effects_number, effect.effect_id);

    // Apply effect 0 to cluster 0 with default params, volatile, full-power mode.
    feat.set_rgb_cluster_effect(
        0,
        0,
        [0u8; 10],
        RgbPersistence::VOLATILE,
        PowerModeTarget::FullPower,
    )
    .await?;

    // Listen for unsolicited events.
    let rx = feat.listen();
    if let Ok(event) = rx.recv().await {
        println!("event: {event:?}");
    }
}