OpenLogi

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

FunctionHID++ fnSignatureReturns
get_info0()ColorLedInfo
get_zone_info1(zone_index: u8)ZoneInfo
get_zone_effect_info2(zone_index: u8, zone_effect_index: u8)ZoneEffectInfo
set_zone_effect3(zone_index: u8, zone_effect_index: u8, params: [u8; ZONE_EFFECT_PARAM_COUNT], persistence: Persistence)()
get_nv_config4(capability: NvCapabilities)NvConfig
set_nv_config5(capability: NvCapabilities, state: NvCapabilityState, param1: u8, param2: u8)()
get_led_bin_info6(zone_index: u8, led_bin_index: LedBinIndex)LedBinInfo
get_sw_control7()SwControlState
set_sw_control8(control: SwControl, sync_events: bool)()
get_effect_settings9(zone_index: u8, source: PersistenceSource)EffectSettings
clear_effect_settings10(zone_index: u8)()
set_cycling_direction11(direction: CyclingDirection)()
get_current_color12(zone_index: u8)Rgb
synchronize_effect13(zone_index: u8, drift_value: i16)()
get_zone_effect14(zone_index: u8, source: PersistenceSource)ZoneEffect
set_led_bin_info15(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

TypeFieldsDescription
Rgbred: u8, green: u8, blue: u8One 8-bit value per colour channel.
ColorLedInfozone_count: u8, nv_capabilities: NvCapabilities, ext_capabilities: ExtCapabilitiesFeature-wide information.
ZoneInfozone_index: u8, location: LocationEffect, effects_number: u8, persistency: PersistencyCapabilitiesOne zone. Iterate 0..effects_number with get_zone_effect_info.
ZoneEffectInfozone_index: u8, zone_effect_index: u8, effect_id: EffectId, effect_capabilities: u16, effect_period: u16One effect. A zero effect_capabilities value uses Raptor compatibility defaults. A zero period is unavailable.
ZoneEffectzone_index: u8, zone_effect_index: u8, params: [u8; ZONE_EFFECT_PARAM_COUNT]The configured effect and its raw parameters.
EffectSettingszone_index: u8, color: Rgb, period: u16, brightness: u8, param: u8Decoded settings for one zone.
SwControlStatecontrol: SwControl, sync_events: boolLED ownership and sync-event state.
NvConfigcapability: NvCapabilities, state: NvCapabilityState, param1: u8, param2: u8One non-volatile capability entry.
LedBinInfozone_index: u8, led_bin_index: LedBinIndex, red: u16, green: u16, blue: u16, white: u16Manufacturing 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

TypeVariantsValues
EffectIdDisabled, FixedColor, PulsingBreathingLegacy, Cycling, ColorWave, Starlight, LightOnPress, AudioVisualizer, BootUp, DemoMode, PulsingBreathingWaveform, Ripple0–11 in listed order. AudioVisualizer is reserved.
LocationEffectPrimary, Logo, LeftSide, RightSide, Combined, Primary1, Primary2, Primary3, Primary4, Primary5, Primary61–11 in listed order.
PersistenceVolatile, VolatileAndNonVolatile, NonVolatileOnly0, 1, 2. RAM only; RAM plus EEPROM; EEPROM only.
PersistenceSourceRam, Eeprom0, 1.
SwControlFirmware, Software0, 1.
CyclingDirectionClockwise, Anticlockwise0, 1.
LedBinIndexBinValueBrightness, BinValueColor, CalibrationFactors, Brightness, ColorimetricX, ColorimetricY0–5 in listed order.
NvCapabilityStateNoChange, Enabled, Disabled0, 1, 2. NoChange is a read-only sentinel that assumes enabled.

Bit flags

TypeFlagBitMeaning
NvCapabilitiesBOOT_UP_EFFECT1 << 0A boot-up effect is configurable.
NvCapabilitiesDEMO1 << 1Demo mode is supported.
NvCapabilitiesUSER_DEMO_MODE1 << 2User demo mode is supported.
ExtCapabilitiesGET_ZONE_EFFECT1 << 0get_zone_effect is supported.
ExtCapabilitiesNO_GET_EFFECT_SETTINGS1 << 1get_effect_settings is not supported.
ExtCapabilitiesSET_LED_BIN_INFO1 << 2set_led_bin_info is supported.
ExtCapabilitiesMONOCHROME_ONLY1 << 3Only monochrome effects are supported.
ExtCapabilitiesNO_SYNCHRONIZE_EFFECT1 << 4Sync correction and its event are not supported.
PersistencyCapabilitiesALWAYS_ON1 << 0The zone can persist always-on state.
PersistencyCapabilitiesALWAYS_OFF1 << 1The zone can persist always-off state.
PersistencyCapabilitiesON_THEN_OFF1 << 2The zone can persist on-then-off state.

PersistencyCapabilities::empty() means that the zone has no persistency support.

Events

ColorLedEffectsFeature implements EmittingFeature<ColorLedEffectsEvent>.

VariantFieldsDescription
SyncEffectzone_index: u8, effect_counter: u16A 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].

ByteFieldNotes
0zone_countNumber of zones.
1–2nv_capabilitiesNvCapabilities, BE u16.
3–4ext_capabilitiesExtCapabilities, BE u16.

get_zone_info (fn 1)

Request: [zone_index, 0x00, 0x00].

ByteFieldNotes
0zone_indexEcho. OpenLogi requires it to match the request.
1–2locationLocationEffect, BE u16.
3effects_numberNumber of effects in this zone.
4persistencyPersistencyCapabilities.

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].

ByteFieldNotes
0zone_indexResponse echo.
1zone_effect_indexResponse echo.
2–3effect_idEffectId, BE u16.
4–5effect_capabilitiesEffect-specific bitmask, BE u16.
6–7effect_periodPeriod in milliseconds, BE u16; zero is unavailable.

set_zone_effect (fn 3)

Request: long, 16 bytes.

ByteFieldNotes
0zone_indexTarget zone.
1zone_effect_indexEffect ordinal in that zone.
2–11paramsTen effect-specific bytes. FixedColor uses bytes 2–4 for red, green, and blue.
12persistencePersistence value.
13–15paddingOpenLogi 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.

ByteFieldNotes
0–1capabilityEchoed NvCapabilities, BE u16.
2stateNvCapabilityState.
3param1Capability-specific byte.
4param2Capability-specific byte.

OpenLogi requires exactly one requested capability bit.

set_nv_config (fn 5)

Request: long, 16 bytes.

ByteFieldNotes
0–1capabilityOne NvCapabilities bit, BE u16.
2stateNvCapabilityState.
3param1Capability-specific byte.
4param2Capability-specific byte.
5–15paddingOpenLogi writes 0x00.

The wrapper waits for acknowledgement and discards its payload.

get_led_bin_info (fn 6)

Request: [zone_index, led_bin_index, 0x00].

ByteFieldNotes
0zone_indexResponse echo.
1led_bin_indexLedBinIndex.
2–3redBE u16.
4–5greenBE u16.
6–7blueBE u16.
8–9whiteBE u16.

get_sw_control (fn 7)

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

ByteFieldNotes
0controlSwControl: 0 firmware or 1 software.
1sync_eventsZero 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].

ByteFieldNotes
0zone_indexResponse echo.
1–3colorRed, green, blue bytes.
4–5periodMilliseconds, BE u16.
6brightnessRaw brightness byte.
7paramEffect-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].

ByteFieldNotes
0/OpenLogi ignores this byte.
1–3RgbRed, green, blue bytes.

synchronize_effect (fn 13)

Request: long, 16 bytes.

ByteFieldNotes
0zone_index0xff targets all zones.
1reservedOpenLogi writes 0x00.
2–3drift_valueMilliseconds, BE i16.
4–15paddingOpenLogi 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].

ByteFieldNotes
0zone_indexResponse echo.
1zone_effect_indexResponse effect ordinal.
2–11paramsTen effect-specific bytes.

This function is unavailable unless GET_ZONE_EFFECT is set.

set_led_bin_info (fn 15)

Request: long, 16 bytes.

ByteFieldNotes
0zone_indexTarget zone.
1led_bin_indexLedBinIndex.
2–3redBE u16.
4–5greenBE u16.
6–7blueBE u16.
8–9whiteBE u16.
10–15paddingOpenLogi writes 0x00.

The response has the get_led_bin_info layout. OpenLogi decodes and returns those echoed values.

SyncEffect event (event fn 0)

ByteFieldNotes
0zone_index0xff targets all zones.
1–2effect_counterTiming 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(())
}

On this page