0x8070 · colorLedEffects

Logitech 键盘与鼠标所使用的逐区域 RGB 效果引擎。设备暴露一个或多个 LED 区域（主区、Logo 区、左/右侧等）；每个区域均可独立配置效果，例如固定颜色、呼吸、色浪、星光或涟漪。get_info 返回区域数量与能力位掩码；get_zone_info 与 get_zone_effect_info 枚举每个区域的物理位置及其所支持的效果。效果通过 set_zone_effect 应用，该函数接受 10 字节的效果专属参数（如 FixedColor 使用前三字节作为 R、G、B）以及 Persistence 值，用于选择仅写入 RAM（易失性）或写入 EEPROM。get_sw_control / set_sw_control 将 LED 控制权交给软件或归还固件；启用同步事件后，设备每个周期发出一次 SyncEffect 事件，调用方可借此通过 synchronize_effect 修正时序偏差。

• EffectId — Disabled、FixedColor、PulsingBreathingLegacy、Cycling、ColorWave、Starlight、LightOnPress、PulsingBreathingWaveform、Ripple 等。
• LocationEffect — Primary、Logo、LeftSide、RightSide、Combined，或按编号的主区域（Primary1–Primary6）。
• Persistence — Volatile（仅 RAM，断电丢失）、VolatileAndNonVolatile（RAM + EEPROM）、NonVolatileOnly（仅 EEPROM）。
• ExtCapabilities — 由 get_info 读取的功能标志：GET_ZONE_EFFECT、NO_GET_EFFECT_SETTINGS、SET_LED_BIN_INFO、MONOCHROME_ONLY、NO_SYNCHRONIZE_EFFECT。

规格： Logitech HID++ 2.0 —— colorLedEffects。用于： 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?;
}