0x8070 · colorLedEffects

The per-zone RGB effect engine used by Logitech keyboards and mice. A device exposes one or more LED zones (primary, logo, left/right side, …); each zone independently supports a set of effects such as fixed color, breathing, color wave, starlight, or ripple. get_info reports the zone count and capability bitmasks; get_zone_info and get_zone_effect_info enumerate each zone's physical location and the effects it supports. An effect is applied with set_zone_effect, which accepts ten effect-specific parameter bytes (e.g. R, G, B for FixedColor) and a Persistence value choosing between RAM-only or EEPROM storage. get_sw_control / set_sw_control hand the LED engine to software or back to firmware; when sync events are enabled the device emits a SyncEffect event each period, allowing timing drift to be corrected via synchronize_effect.

• EffectId — Disabled, FixedColor, PulsingBreathingLegacy, Cycling, ColorWave, Starlight, LightOnPress, PulsingBreathingWaveform, Ripple, and more.
• LocationEffect — Primary, Logo, LeftSide, RightSide, Combined, or per-numbered primary zones (Primary1–Primary6).
• Persistence — Volatile (RAM only, lost on power cycle), VolatileAndNonVolatile (RAM + EEPROM), NonVolatileOnly (EEPROM only).
• ExtCapabilities — feature flags read from get_info: GET_ZONE_EFFECT, NO_GET_EFFECT_SETTINGS, SET_LED_BIN_INFO, MONOCHROME_ONLY, NO_SYNCHRONIZE_EFFECT.

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

Function reference

The ColorLedEffectsFeature wrapper (0x8070) exposes:

Methods

All async fn methods return Result<_, Hidpp20Error>. listen is synchronous and returns a channel receiver for unsolicited events.

Types

ColorLedInfo

General feature information returned by get_info.

ZoneInfo

Information about one zone, returned by get_zone_info.

ZoneEffectInfo

Information about one effect of a zone, returned by get_zone_effect_info.

ZoneEffect

The configured effect of a zone, returned by get_zone_effect.

EffectSettings

Effect settings of a zone, returned by get_effect_settings.

SwControlState

Software-control state, returned by get_sw_control.

NvConfig

A non-volatile configuration entry, returned by get_nv_config.

LedBinInfo

Manufacturing LED bin information, returned by get_led_bin_info / set_led_bin_info.

Rgb

An 8-bit-per-channel RGB color.

EffectId

Identifies the type of a zone effect.

LocationEffect

The physical location a zone covers.

Persistence

Storage persistence for set_zone_effect.

PersistenceSource

Which storage a read function should read from.

SwControl

Whether the firmware or software owns the LEDs.

CyclingDirection

Direction of color cycling.

LedBinIndex

Selects which LED bin parameter a get_led_bin_info / set_led_bin_info call addresses.

NvCapabilityState

State of a non-volatile configuration capability.

NvCapabilities

Supported non-volatile configuration capabilities, from get_info.

ExtCapabilities

Extended capabilities from get_info. Several flags are "NOT supported" flags whose set state removes a function.

PersistencyCapabilities

Persistency capabilities of a zone, from get_zone_info. A value of zero means persistency is not supported.

Events

ColorLedEffectsFeature implements EmittingFeature<ColorLedEffectsEvent>. Call listen() to receive an async_channel::Receiver<ColorLedEffectsEvent>.

ColorLedEffectsEvent

Wire format

Most getters use a 3-byte short request and read a 16-byte long response payload. The four write-heavy functions (set_zone_effect, set_nv_config, synchronize_effect, set_led_bin_info) send a 16-byte long request. All multi-byte fields are big-endian.

get_info (fn 0)

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

Response (byte → field):

get_zone_info (fn 1)

Request: [zone_index, 0x00, 0x00]

Response (byte → field):

get_zone_effect_info (fn 2)

Request: [zone_index, zone_effect_index, 0x00]

Response (byte → field):

set_zone_effect (fn 3)

16-byte long request:

No response body (acknowledges with an empty reply).

get_nv_config (fn 4)

Request: [cap_hi, cap_lo, 0x00] — cap_hi:cap_lo is the single-bit NvCapabilities value as BE u16.

Response (byte → field):

set_nv_config (fn 5)

16-byte long request:

No response body.

get_led_bin_info (fn 6)

Request: [zone_index, led_bin_index, 0x00] — led_bin_index is LedBinIndex as u8.

Response (byte → field):

get_sw_control (fn 7)

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

Response (byte → field):

set_sw_control (fn 8)

Request: [control, sync_events_u8, 0x00] — control is SwControl as u8; sync_events_u8 is 0 or 1.

No response body.

get_effect_settings (fn 9)

Request: [zone_index, source, 0x00] — source is PersistenceSource as u8.

Response (byte → field):

clear_effect_settings (fn 10)

Request: [zone_index, 0x00, 0x00]

No response body.

set_cycling_direction (fn 11)

Request: [direction, 0x00, 0x00] — direction is CyclingDirection as u8 (0=Clockwise, 1=Anticlockwise).

No response body.

get_current_color (fn 12)

Request: [zone_index, 0x00, 0x00]

Response (byte → field):

synchronize_effect (fn 13)

16-byte long request:

No response body. Valid only while sync events are enabled.

get_zone_effect (fn 14)

Request: [zone_index, source, 0x00] — source is PersistenceSource as u8.

Response (byte → field):

set_led_bin_info (fn 15)

16-byte long request:

Response has the same byte layout as get_led_bin_info (device echoes the written values).

SyncEffect event (event fn 0)

Unsolicited message emitted once per effect period while sync events are enabled.

Usage (Rust)

use hidpp::{
    device::Device,
    feature::color_led_effects::{
        ColorLedEffectsFeature, Persistence, SwControl,
    },
};

// mut device: Device, already created via Device::new(channel, index).await?
device.enumerate_features().await?;
if let Some(feat) = device.get_feature::<ColorLedEffectsFeature>() {
    // Read overall feature info (zone count, capability flags).
    let info = feat.get_info().await?;
    println!("zones: {}, ext_caps: {:?}", info.zone_count, info.ext_capabilities);

    // Take software control so we can drive the LEDs directly.
    feat.set_sw_control(SwControl::Software, true).await?;

    // Apply a fixed red color to zone 0, stored in RAM only.
    let mut params = [0u8; 10];
    params[0] = 0xff; // R
    params[1] = 0x00; // G
    params[2] = 0x00; // B
    feat.set_zone_effect(0, 0, params, Persistence::Volatile).await?;

    // Listen for sync-effect events to correct timing drift.
    let rx = feat.listen();
    if let Ok(event) = rx.recv().await {
        println!("sync event: {:?}", event);
    }

    // Return LED control to the firmware.
    feat.set_sw_control(SwControl::Firmware, false).await?;
}