0x8070 · colorLedEffects
Per-zone RGB effect engine that enumerates LED zones and effects, applies an effect with selectable persistence, and can synchronize effect timing.
colorLedEffects is the per-zone RGB engine in Logitech keyboards and mice. Each LED zone reports its location and effect list. An effect index belongs to one zone only.
Spec: Logitech HID++ 2.0 — colorLedEffects (v7). Cross-checked: Logi Options+ 2.8 (static analysis), Solaar, G HUB (static analysis). Used by: Keyboard lighting.
Function reference
Methods
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_info | 0 | () | ColorLedInfo |
get_zone_info | 1 | (zone_index: u8) | ZoneInfo |
get_zone_effect_info | 2 | (zone_index: u8, zone_effect_index: u8) | ZoneEffectInfo |
set_zone_effect | 3 | (zone_index: u8, zone_effect_index: u8, params: [u8; ZONE_EFFECT_PARAM_COUNT], persistence: Persistence) | () |
get_nv_config | 4 | (capability: NvCapabilities) | NvConfig |
set_nv_config | 5 | (capability: NvCapabilities, state: NvCapabilityState, param1: u8, param2: u8) | () |
get_led_bin_info | 6 | (zone_index: u8, led_bin_index: LedBinIndex) | LedBinInfo |
get_sw_control | 7 | () | SwControlState |
set_sw_control | 8 | (control: SwControl, sync_events: bool) | () |
get_effect_settings | 9 | (zone_index: u8, source: PersistenceSource) | EffectSettings |
clear_effect_settings | 10 | (zone_index: u8) | () |
set_cycling_direction | 11 | (direction: CyclingDirection) | () |
get_current_color | 12 | (zone_index: u8) | Rgb |
synchronize_effect | 13 | (zone_index: u8, drift_value: i16) | () |
get_zone_effect | 14 | (zone_index: u8, source: PersistenceSource) | ZoneEffect |
set_led_bin_info | 15 | (info: &LedBinInfo) | LedBinInfo |
listen | — | (&self) | async_channel::Receiver<ColorLedEffectsEvent> |
Every operation except listen is an async fn that returns Result<_, Hidpp20Error>. listen is supplied by EmittingFeature<ColorLedEffectsEvent>.
Types
ZONE_EFFECT_PARAM_COUNT is 10.
Data structures
| Type | Fields | Description |
|---|---|---|
Rgb | red: u8, green: u8, blue: u8 | One 8-bit value per colour channel. |
ColorLedInfo | zone_count: u8, nv_capabilities: NvCapabilities, ext_capabilities: ExtCapabilities | Feature-wide information. |
ZoneInfo | zone_index: u8, location: LocationEffect, effects_number: u8, persistency: PersistencyCapabilities | One zone. Iterate 0..effects_number with get_zone_effect_info. |
ZoneEffectInfo | zone_index: u8, zone_effect_index: u8, effect_id: EffectId, effect_capabilities: u16, effect_period: u16 | One effect. A zero effect_capabilities value uses Raptor compatibility defaults. A zero period is unavailable. |
ZoneEffect | zone_index: u8, zone_effect_index: u8, params: [u8; ZONE_EFFECT_PARAM_COUNT] | The configured effect and its raw parameters. |
EffectSettings | zone_index: u8, color: Rgb, period: u16, brightness: u8, param: u8 | Decoded settings for one zone. |
SwControlState | control: SwControl, sync_events: bool | LED ownership and sync-event state. |
NvConfig | capability: NvCapabilities, state: NvCapabilityState, param1: u8, param2: u8 | One non-volatile capability entry. |
LedBinInfo | zone_index: u8, led_bin_index: LedBinIndex, red: u16, green: u16, blue: u16, white: u16 | Manufacturing LED-bin values. |
All durations and periods in these structures are milliseconds. effect_capabilities remains a raw bitmask because its bits depend on effect_id.
Enumerations
| Type | Variants | Values |
|---|---|---|
EffectId | Disabled, FixedColor, PulsingBreathingLegacy, Cycling, ColorWave, Starlight, LightOnPress, AudioVisualizer, BootUp, DemoMode, PulsingBreathingWaveform, Ripple | 0–11 in listed order. AudioVisualizer is reserved. |
LocationEffect | Primary, Logo, LeftSide, RightSide, Combined, Primary1, Primary2, Primary3, Primary4, Primary5, Primary6 | 1–11 in listed order. |
Persistence | Volatile, VolatileAndNonVolatile, NonVolatileOnly | 0, 1, 2. RAM only; RAM plus EEPROM; EEPROM only. |
PersistenceSource | Ram, Eeprom | 0, 1. |
SwControl | Firmware, Software | 0, 1. |
CyclingDirection | Clockwise, Anticlockwise | 0, 1. |
LedBinIndex | BinValueBrightness, BinValueColor, CalibrationFactors, Brightness, ColorimetricX, ColorimetricY | 0–5 in listed order. |
NvCapabilityState | NoChange, Enabled, Disabled | 0, 1, 2. NoChange is a read-only sentinel that assumes enabled. |
Bit flags
| Type | Flag | Bit | Meaning |
|---|---|---|---|
NvCapabilities | BOOT_UP_EFFECT | 1 << 0 | A boot-up effect is configurable. |
NvCapabilities | DEMO | 1 << 1 | Demo mode is supported. |
NvCapabilities | USER_DEMO_MODE | 1 << 2 | User demo mode is supported. |
ExtCapabilities | GET_ZONE_EFFECT | 1 << 0 | get_zone_effect is supported. |
ExtCapabilities | NO_GET_EFFECT_SETTINGS | 1 << 1 | get_effect_settings is not supported. |
ExtCapabilities | SET_LED_BIN_INFO | 1 << 2 | set_led_bin_info is supported. |
ExtCapabilities | MONOCHROME_ONLY | 1 << 3 | Only monochrome effects are supported. |
ExtCapabilities | NO_SYNCHRONIZE_EFFECT | 1 << 4 | Sync correction and its event are not supported. |
PersistencyCapabilities | ALWAYS_ON | 1 << 0 | The zone can persist always-on state. |
PersistencyCapabilities | ALWAYS_OFF | 1 << 1 | The zone can persist always-off state. |
PersistencyCapabilities | ON_THEN_OFF | 1 << 2 | The zone can persist on-then-off state. |
PersistencyCapabilities::empty() means that the zone has no persistency support.
Events
ColorLedEffectsFeature implements EmittingFeature<ColorLedEffectsEvent>.
| Variant | Fields | Description |
|---|---|---|
SyncEffect | zone_index: u8, effect_counter: u16 | A periodic effect reached a sync point. 0xff targets all zones. The counter is in milliseconds. |
Wire format
Offsets are payload bytes. Short requests carry three bytes. Long requests carry 16 bytes. Every multi-byte value below is BE.
get_info (fn 0)
Request: [0x00, 0x00, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_count | Number of zones. |
| 1–2 | nv_capabilities | NvCapabilities, BE u16. |
| 3–4 | ext_capabilities | ExtCapabilities, BE u16. |
get_zone_info (fn 1)
Request: [zone_index, 0x00, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_index | Echo. OpenLogi requires it to match the request. |
| 1–2 | location | LocationEffect, BE u16. |
| 3 | effects_number | Number of effects in this zone. |
| 4 | persistency | PersistencyCapabilities. |
OpenLogi requires a long reply. It rejects a short reply or a mismatched index with UnsupportedResponse.
get_zone_effect_info (fn 2)
Request: [zone_index, zone_effect_index, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_index | Response echo. |
| 1 | zone_effect_index | Response echo. |
| 2–3 | effect_id | EffectId, BE u16. |
| 4–5 | effect_capabilities | Effect-specific bitmask, BE u16. |
| 6–7 | effect_period | Period in milliseconds, BE u16; zero is unavailable. |
set_zone_effect (fn 3)
Request: long, 16 bytes.
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_index | Target zone. |
| 1 | zone_effect_index | Effect ordinal in that zone. |
| 2–11 | params | Ten effect-specific bytes. FixedColor uses bytes 2–4 for red, green, and blue. |
| 12 | persistence | Persistence value. |
| 13–15 | padding | OpenLogi writes 0x00. |
The wrapper waits for acknowledgement and discards its payload.
get_nv_config (fn 4)
Request: [cap_hi, cap_lo, 0x00]. The capability is one NvCapabilities bit as BE u16.
| Byte | Field | Notes |
|---|---|---|
| 0–1 | capability | Echoed NvCapabilities, BE u16. |
| 2 | state | NvCapabilityState. |
| 3 | param1 | Capability-specific byte. |
| 4 | param2 | Capability-specific byte. |
OpenLogi requires exactly one requested capability bit.
set_nv_config (fn 5)
Request: long, 16 bytes.
| Byte | Field | Notes |
|---|---|---|
| 0–1 | capability | One NvCapabilities bit, BE u16. |
| 2 | state | NvCapabilityState. |
| 3 | param1 | Capability-specific byte. |
| 4 | param2 | Capability-specific byte. |
| 5–15 | padding | OpenLogi writes 0x00. |
The wrapper waits for acknowledgement and discards its payload.
get_led_bin_info (fn 6)
Request: [zone_index, led_bin_index, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_index | Response echo. |
| 1 | led_bin_index | LedBinIndex. |
| 2–3 | red | BE u16. |
| 4–5 | green | BE u16. |
| 6–7 | blue | BE u16. |
| 8–9 | white | BE u16. |
get_sw_control (fn 7)
Request: [0x00, 0x00, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | control | SwControl: 0 firmware or 1 software. |
| 1 | sync_events | Zero is false. Any non-zero value is true. |
set_sw_control (fn 8)
Request: [control, sync_events, 0x00]. sync_events is 0 or 1.
The wrapper waits for acknowledgement and discards its payload. Sync-event selection is not stored in EEPROM.
get_effect_settings (fn 9)
Request: [zone_index, source, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_index | Response echo. |
| 1–3 | color | Red, green, blue bytes. |
| 4–5 | period | Milliseconds, BE u16. |
| 6 | brightness | Raw brightness byte. |
| 7 | param | Effect-specific byte. |
This function is unavailable when NO_GET_EFFECT_SETTINGS is set.
clear_effect_settings (fn 10)
Request: [zone_index, 0x00, 0x00].
The wrapper waits for acknowledgement and discards its payload. The operation reverts the zone to its default mode.
set_cycling_direction (fn 11)
Request: [direction, 0x00, 0x00]. direction is 0 for Clockwise or 1 for Anticlockwise.
The wrapper waits for acknowledgement and discards its payload.
get_current_color (fn 12)
Request: [zone_index, 0x00, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | / | OpenLogi ignores this byte. |
| 1–3 | Rgb | Red, green, blue bytes. |
synchronize_effect (fn 13)
Request: long, 16 bytes.
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_index | 0xff targets all zones. |
| 1 | reserved | OpenLogi writes 0x00. |
| 2–3 | drift_value | Milliseconds, BE i16. |
| 4–15 | padding | OpenLogi writes 0x00. |
The function is valid while sync events are enabled. It is unavailable when NO_SYNCHRONIZE_EFFECT is set.
get_zone_effect (fn 14)
Request: [zone_index, source, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_index | Response echo. |
| 1 | zone_effect_index | Response effect ordinal. |
| 2–11 | params | Ten effect-specific bytes. |
This function is unavailable unless GET_ZONE_EFFECT is set.
set_led_bin_info (fn 15)
Request: long, 16 bytes.
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_index | Target zone. |
| 1 | led_bin_index | LedBinIndex. |
| 2–3 | red | BE u16. |
| 4–5 | green | BE u16. |
| 6–7 | blue | BE u16. |
| 8–9 | white | BE u16. |
| 10–15 | padding | OpenLogi writes 0x00. |
The response has the get_led_bin_info layout. OpenLogi decodes and returns those echoed values.
SyncEffect event (event fn 0)
| Byte | Field | Notes |
|---|---|---|
| 0 | zone_index | 0xff targets all zones. |
| 1–2 | effect_counter | Timing position in milliseconds, BE u16. |
How OpenLogi uses it
The automatic keyboard-lighting path tries 0x8070 before 0x8071, 0x8081, and 0x8080. It writes only a volatile fixed-colour effect. The agent reapplies the saved colour when the keyboard reconnects instead of writing EEPROM for each colour change.
Since v0.8.14, PR #1758 finds EffectId::FixedColor in each enumerated zone. It writes the discovered effect index, not the EffectId value. A zone without that effect is skipped, and no target causes fallback to the next lighting path.
The writer currently limits normal enumeration to the first four reported zones. It also uses legacy effect index 1 for zones 0..4 when zone_count is zero or get_zone_info is rejected. These compatibility fallbacks can still write a wrong effect or omit zones.
The production lighting path uses only functions 0–3. It does not take this feature's software control or invoke NV configuration, synchronization, or other v1-only functions. The user-facing control is the Keyboard lighting tab.
Open questions
Version-gated functions
Options+ 2.8 gates functions 4, 5, 7, 8, and 13 on feature version 1 or later. G HUB static analysis also identifies a feature-version check. OpenLogi registers one wrapper from version 0 and has no runtime gate for these calls.
The version condition has static-analysis support but no hardware capture confirms it. The static-colour UI does not call these functions. Wrapper consumers must treat a version-0 error as possible.
Usage (Rust)
use hidpp::feature::color_led_effects::{
ColorLedEffectsFeature, EffectId, Persistence, ZONE_EFFECT_PARAM_COUNT,
};
use hidpp::protocol::v20::Hidpp20Error;
async fn set_red(feature: &ColorLedEffectsFeature) -> Result<(), Hidpp20Error> {
let mut params = [0_u8; ZONE_EFFECT_PARAM_COUNT];
params[..3].copy_from_slice(&[0xff, 0x00, 0x00]);
let device = feature.get_info().await?;
for zone in 0..device.zone_count {
let zone_info = feature.get_zone_info(zone).await?;
for effect in 0..zone_info.effects_number {
let info = feature.get_zone_effect_info(zone, effect).await?;
if info.effect_id == EffectId::FixedColor {
feature
.set_zone_effect(zone, effect, params, Persistence::Volatile)
.await?;
break;
}
}
}
Ok(())
}