OpenLogi

0x8071 · rgbEffects

Per-cluster RGB effect engine that controls effects, non-volatile configuration, software ownership, power modes, and RGB notifications.

rgbEffects is the per-cluster successor to 0x8070 colorLedEffects. A cluster has its own effect ordinals. Software must own the affected clusters before it sets a cluster effect.

Spec: Logitech HID++ 2.0 — rgbEffects (v4). Cross-checked: Logi Options+ 2.8 (static analysis), Solaar, G HUB (static analysis). Used by: Keyboard lighting.

Function reference

Methods

FunctionHID++ fnSignatureReturns
get_device_info0()RgbDeviceInfo
get_cluster_info0(cluster_index: u8)RgbClusterInfo
get_effect_info0(cluster_index: u8, cluster_effect_index: u8)RgbEffectInfo
get_onboard_effect_info0(cluster_index: u8, cluster_effect_index: u8, slot: u8, slot_info_type: SlotInfoType)[u8; ONBOARD_INFO_PARAM_COUNT]
set_rgb_cluster_effect1(cluster_index: u8, cluster_effect_index: u8, params: [u8; CLUSTER_EFFECT_PARAM_COUNT], persistence: RgbPersistence, power_mode: PowerModeTarget)()
set_multi_led_cluster_pattern2(cluster_index: u8, pattern: u8)()
get_nv_config3(capability: RgbNvCapabilities)RgbNvConfig
set_nv_config3(config: &RgbNvConfig)()
get_led_bin_info4(cluster_index: u8, led_bin_index: LedBinIndex, backup: bool)[u8; LED_BIN_PARAM_COUNT]
set_led_bin_info4(cluster_index: u8, led_bin_index: LedBinIndex, params: [u8; LED_BIN_PARAM_COUNT])()
get_sw_control5()RgbSwControl
set_sw_control5(control: SwControlFlags, events: EventsNotificationFlags)()
set_effect_sync_correction6(cluster_index: u8, drift_value: i16)()
get_power_mode_config7()RgbPowerModeConfig
set_power_mode_config7(config: RgbPowerModeConfig)()
get_power_mode8()RgbPowerMode
set_power_mode8(mode: RgbPowerMode)()
shutdown9()()
listen—(&self)async_channel::Receiver<RgbEffectsEvent>

Every operation except listen is an async fn that returns Result<_, Hidpp20Error>. listen is supplied by EmittingFeature<RgbEffectsEvent>.

Types

CLUSTER_EFFECT_PARAM_COUNT is 10. ONBOARD_INFO_PARAM_COUNT is 13. LED_BIN_PARAM_COUNT is 8. ALL_CLUSTERS and ALL_EFFECTS are both 0xff.

Data structures

TypeFieldsDescription
RgbDeviceInfocluster_count: u8, nv_capabilities: RgbNvCapabilities, ext_capabilities: RgbExtCapabilities, multicluster_effect_count: u8Device-level information.
RgbClusterInfocluster_index: u8, location: u16, effects_number: u8, display_persistency: DisplayPersistencyCapabilities, effect_persistency: bool, multiled_pattern: boolOne cluster. location is a raw locationEffect value.
RgbEffectInfocluster_index: u8, cluster_effect_index: u8, effect_id: u16, effect_capabilities: u16, effect_period: u16One cluster effect. Both identifiers are raw. A zero capability value uses Raptor compatibility defaults. A zero period is unavailable.
RgbSwControlcontrol: SwControlFlags, events: EventsNotificationFlagsSoftware-ownership and event-request flags.
RgbNvConfigcapability: RgbNvCapabilities, state: u8, params: [u8; 6]One non-volatile configuration entry. The six parameters are capability-specific.
RgbPowerModeConfigflags: u16, no_activity_timeout_to_power_save: u16, no_activity_timeout_to_off: u16Raw flags and two timeouts in seconds.

RgbNvConfig is non-exhaustive. Outside this crate, obtain it through get_nv_config, change the required fields, then pass it to set_nv_config.

Enumerations

TypeVariantsValues
SlotInfoTypeSlotState, Defaults, Uuid0To10, Uuid11To16, EffectName0To10, EffectName11To21, EffectName21To310–6 in listed order.
RgbPowerModeFullRgb, PowerSave, PowerOff1, 2, 3.
PowerModeTargetFullPower, PowerSave0, 1.
LedBinIndexBinValueBrightness, BinValueColor, CalibrationFactors, Brightness, ColorimetricX, ColorimetricY0–5 in listed order.
ActivityEventTypeNoActivityTimeoutReached, UserActivityDetected, Other(u8)0, 1, or an unmodelled raw value.

Bit flags

TypeFlagBitMeaning
RgbPersistenceVOLATILE1 << 0Apply the effect to RAM.
RgbPersistenceNON_VOLATILE1 << 1Store the effect in EEPROM.
RgbExtCapabilitiesGET_ZONE_EFFECT1 << 0Stored-effect get_info mode is supported.
RgbExtCapabilitiesSET_LED_BIN_INFO1 << 2set_led_bin_info is supported.
RgbExtCapabilitiesMONOCHROME_ONLY1 << 3Only monochrome effects are supported.
RgbExtCapabilitiesNO_EFFECT_SYNC1 << 4Effect sync and correction are not supported.
RgbExtCapabilitiesSHUTDOWN1 << 5shutdown is supported.
RgbExtCapabilitiesCLUSTER_CHANGED_EVENT1 << 6The cluster-change event is supported.
RgbNvCapabilitiesBOOT_UP_EFFECT1 << 0Boot-up effect.
RgbNvCapabilitiesDEMO1 << 1Demo mode.
RgbNvCapabilitiesUSER_DEMO_MODE1 << 2User demo mode.
RgbNvCapabilitiesEVENTS_DISPLAY1 << 3Events display.
RgbNvCapabilitiesACTIVE_DIMMING1 << 4Active dimming.
RgbNvCapabilitiesRAMP_DOWN_TO_OFF1 << 5Ramp down to off.
RgbNvCapabilitiesSHUTDOWN_EFFECT1 << 6Shutdown effect.
SwControlFlagsALL_CLUSTERS1 << 0Software controls RGB clusters.
SwControlFlagsPOWER_MODES1 << 1Software controls power modes.
EventsNotificationFlagsEFFECTS_SYNC1 << 0Request effect-sync events.
EventsNotificationFlagsUSER_ACTIVITY1 << 1Request user-activity events.
EventsNotificationFlagsNO_USER_ACTIVITY_TIMEOUT1 << 2Request no-activity-timeout events.
DisplayPersistencyCapabilitiesALWAYS_ON1 << 0The cluster can persist always-on state.
DisplayPersistencyCapabilitiesALWAYS_OFF1 << 1The cluster can persist always-off state.
DisplayPersistencyCapabilitiesON_THEN_OFF1 << 2The cluster can persist on-then-off state.

The bitflag types retain unknown bits. The wrapper exposes capability flags but does not apply a generic before-send capability gate.

Events

RgbEffectsFeature implements EmittingFeature<RgbEffectsEvent>.

VariantFieldsDescription
EffectSynccluster_index: u8, effect_counter: u16A periodic effect reached a sync point. 0xff targets all clusters. The counter is in milliseconds.
UserActivityActivityEventTypeUser activity began or its absence timed out.
ClusterChangedcluster_index: u8, cluster_effect_index: u8, params: [u8; CLUSTER_EFFECT_PARAM_COUNT], persistence: RgbPersistence, power_mode: Option<PowerModeTarget>A cluster effect changed. power_mode is None for an unmodelled two-bit value.
NvEffectSyncpayload: [u8; 16]The stored NV effect configuration may have changed. The payload is raw and its layout is unknown. A short report is zero-extended to 16 bytes. Treat the event as a hint to re-read every NV capability you depend on with get_nv_config.

Wire format

Offsets are payload bytes. Short requests carry three bytes. Long requests carry 16 bytes. Every multi-byte value below is BE.

get_device_info (fn 0)

Request: [0xff, 0xff, 0x00] for all clusters, all effects, and general information.

ByteFieldNotes
0–1/OpenLogi ignores these response bytes.
2cluster_countNumber of clusters.
3–4nv_capabilitiesRgbNvCapabilities, BE u16.
5–6ext_capabilitiesRgbExtCapabilities, BE u16.
7multicluster_effect_countNumber of multi-cluster effects.

get_cluster_info (fn 0)

Request: [cluster_index, 0xff, 0x00] for all effects and general information.

ByteFieldNotes
0cluster_indexEcho. OpenLogi requires it to match the request.
1/OpenLogi ignores this response byte.
2–3locationRaw location identifier, BE u16.
4effects_numberNumber of effects in this cluster.
5display_persistencyDisplayPersistencyCapabilities.
6effect_persistencyNon-zero means EEPROM effect persistence.
7multiled_patternNon-zero means multi-LED patterns.

OpenLogi requires a long reply. It rejects a short reply or a mismatched index with UnsupportedResponse.

get_effect_info (fn 0)

Request: [cluster_index, cluster_effect_index, 0x00] for general information.

ByteFieldNotes
0cluster_indexResponse echo.
1cluster_effect_indexResponse echo.
2–3effect_idRaw effect identifier, BE u16.
4–5effect_capabilitiesEffect-specific bitmask, BE u16.
6–7effect_periodPeriod in milliseconds, BE u16; zero is unavailable.

get_onboard_effect_info (fn 0)

Request: long, [cluster_index, cluster_effect_index, 0x01, slot, slot_info_type, 0x00…].

ByteFieldNotes
0–2/OpenLogi ignores these response bytes.
3–15return valueRaw [u8; ONBOARD_INFO_PARAM_COUNT]. Meaning depends on SlotInfoType.

set_rgb_cluster_effect (fn 1)

Request: long, 16 bytes.

ByteFieldNotes
0cluster_indexTarget cluster.
1cluster_effect_indexEffect ordinal in that cluster.
2–11paramsTen effect-specific bytes.
12flagsRgbPersistence in bits 0–1. PowerModeTarget is in bits 2–3.
13–15paddingOpenLogi writes 0x00.

The wrapper waits for native write completion and then the acknowledgement. Software must first set SwControlFlags::ALL_CLUSTERS.

set_multi_led_cluster_pattern (fn 2)

Request: [cluster_index, pattern, 0x00].

The wrapper waits for acknowledgement and discards its payload.

get_nv_config (fn 3)

Request: [0x00, cap_hi, cap_lo]. Byte 0 selects read. The capability is BE u16.

ByteFieldNotes
0selectorOpenLogi ignores this response byte.
1–2capabilityRgbNvCapabilities, BE u16.
3stateCapability-specific state byte.
4–9paramsSix capability-specific bytes. OpenLogi preserves all six.

OpenLogi requires a long reply. It does not name the six parameters because their meanings vary by capability.

set_nv_config (fn 3)

Request: long, 16 bytes.

ByteFieldNotes
0selectorOpenLogi writes 0x01 for write.
1–2capabilityRgbNvCapabilities, BE u16.
3stateCapability-specific state byte.
4–9paramsAll six bytes from RgbNvConfig.
10–15paddingOpenLogi writes 0x00.

Since v0.8.14, OpenLogi accepts only a read RgbNvConfig outside the crate. This preserves every parameter during a read-modify-write.

get_led_bin_info (fn 4)

Request: [selector, cluster_index, led_bin_index]. The selector is 0x00 for active data or 0x02 for backup data.

ByteFieldNotes
0–2/OpenLogi ignores these response bytes.
3–10return valueRaw [u8; LED_BIN_PARAM_COUNT].

set_led_bin_info (fn 4)

Request: long, [0x01, cluster_index, led_bin_index, params[0..8], 0x00…].

The wrapper waits for acknowledgement and discards its payload.

get_sw_control (fn 5)

Request: [0x00, 0x00, 0x00]. Byte 0 selects read.

ByteFieldNotes
0selectorOpenLogi ignores this response byte.
1controlSwControlFlags.
2eventsEventsNotificationFlags.

set_sw_control (fn 5)

Request: [0x01, control.bits(), events.bits()]. Byte 0 selects write.

The acknowledgement must echo all three request bytes. OpenLogi waits for native write completion before the bounded acknowledgement wait.

set_effect_sync_correction (fn 6)

Request: long, [cluster_index, 0x00, drift_hi, drift_lo, 0x00…].

ByteFieldNotes
0cluster_index0xff targets all clusters.
1reservedOpenLogi writes 0x00.
2–3drift_valueMilliseconds, BE i16.
4–15paddingOpenLogi writes 0x00.

get_power_mode_config (fn 7)

Request: [0x00, 0x00, 0x00]. Byte 0 selects read.

ByteFieldNotes
0selectorOpenLogi ignores this response byte.
1–2flagsRaw flags, BE u16.
3–4no_activity_timeout_to_power_saveSeconds, BE u16.
5–6no_activity_timeout_to_offSeconds, BE u16.

set_power_mode_config (fn 7)

Request: long, [0x01, flags_hi, flags_lo, psave_hi, psave_lo, off_hi, off_lo, 0x00…].

The flags and both timeouts are BE u16 values. The wrapper waits for acknowledgement and discards its payload.

get_power_mode (fn 8)

Request: [0x00, 0x00, 0x00]. Byte 0 selects read.

ByteFieldNotes
0selectorOpenLogi ignores this response byte.
1RgbPowerMode1 full RGB, 2 power-save, 3 power-off.

set_power_mode (fn 8)

Request: [0x01, mode, 0x00]. Byte 0 selects write.

Software must first set SwControlFlags::POWER_MODES. The wrapper waits for acknowledgement and discards its payload.

shutdown (fn 9)

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

The wrapper waits for acknowledgement and discards its payload. Devices advertise this operation with RgbExtCapabilities::SHUTDOWN.

Events (unsolicited)

Sub-IDEventByte layout
0EffectSyncByte 0 is cluster_index. Bytes 1–2 are effect_counter, BE u16 milliseconds. 0xff targets all clusters.
1UserActivityByte 0 is ActivityEventType.
2ClusterChangedByte 0 is cluster_index. Byte 1 is cluster_effect_index. Bytes 2–11 are parameters. Byte 12 stores persistence in bits 0–1 and target power mode in bits 2–3.
3NvEffectSyncOptions+ 2.8 has a fourth notification handler. Its payload layout is unverified. OpenLogi publishes bytes 0–15 as raw bytes in payload.

How OpenLogi uses it

The automatic lighting path uses 0x8071 after 0x8070 cannot supply a fixed colour. It enumerates every cluster and each cluster's effects before a write. It claims control only when every cluster has static effect ID 1.

For 0x8081 per-key output, OpenLogi uses the same claim when this effect engine exists. It first applies static colour to every supporting cluster, sends the frame, and repeats the frame after a fresh claim. A partial engine falls back before it claims software control.

Since v0.8.14, PR #1769 records a successful claim as an agent-session lease. PR #1770 closes the release races. On an orderly agent exit, OpenLogi refuses new lighting writes, waits up to 2 seconds for admitted writes, then releases each recorded device within a shared 2-second budget.

The release clears only ALL_CLUSTERS. It preserves the saved event flags and any other saved control flags. A disconnected device or failed release is logged and does not delay exit. A standalone diagnostic write deliberately leaves the volatile colour and its control claim in place.

The Keyboard lighting tab provides one static colour and brightness. It does not expose animated effects, per-key editing, power-mode configuration, or NV configuration. Since v0.8.14, PR #1753 preserves all six NV parameters when a wrapper consumer edits a read configuration.

Open questions

Fourth notification

Options+ 2.8 static analysis identifies sub-ID 3 as an NV-effect synchronization notification. It does not recover the payload schema. OpenLogi decodes sub-IDs 0–2 field by field. Since PR #1951, it publishes sub-ID 3 as NvEffectSync with the raw 16-byte payload.

The payload meaning is still an open question. The event needs a hardware capture, a public specification, or stronger analysis before OpenLogi can publish typed fields. This page deliberately documents no byte meanings for it.

Rate restrictions

G HUB static analysis lists a rate-restrictions operation for this feature. The analysis does not establish its function index or payload layout. OpenLogi v0.8.15 does not expose that operation.

Usage (Rust)

use hidpp::feature::rgb_effects::{RgbEffectsFeature, RgbNvCapabilities};
use hidpp::protocol::v20::Hidpp20Error;

async fn enable_boot_effect(feature: &RgbEffectsFeature) -> Result<(), Hidpp20Error> {
    let device = feature.get_device_info().await?;
    if !device
        .nv_capabilities
        .contains(RgbNvCapabilities::BOOT_UP_EFFECT)
    {
        return Ok(());
    }

    let mut config = feature
        .get_nv_config(RgbNvCapabilities::BOOT_UP_EFFECT)
        .await?;
    config.state = 1;
    feature.set_nv_config(&config).await
}

On this page