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
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_device_info | 0 | () | RgbDeviceInfo |
get_cluster_info | 0 | (cluster_index: u8) | RgbClusterInfo |
get_effect_info | 0 | (cluster_index: u8, cluster_effect_index: u8) | RgbEffectInfo |
get_onboard_effect_info | 0 | (cluster_index: u8, cluster_effect_index: u8, slot: u8, slot_info_type: SlotInfoType) | [u8; ONBOARD_INFO_PARAM_COUNT] |
set_rgb_cluster_effect | 1 | (cluster_index: u8, cluster_effect_index: u8, params: [u8; CLUSTER_EFFECT_PARAM_COUNT], persistence: RgbPersistence, power_mode: PowerModeTarget) | () |
set_multi_led_cluster_pattern | 2 | (cluster_index: u8, pattern: u8) | () |
get_nv_config | 3 | (capability: RgbNvCapabilities) | RgbNvConfig |
set_nv_config | 3 | (config: &RgbNvConfig) | () |
get_led_bin_info | 4 | (cluster_index: u8, led_bin_index: LedBinIndex, backup: bool) | [u8; LED_BIN_PARAM_COUNT] |
set_led_bin_info | 4 | (cluster_index: u8, led_bin_index: LedBinIndex, params: [u8; LED_BIN_PARAM_COUNT]) | () |
get_sw_control | 5 | () | RgbSwControl |
set_sw_control | 5 | (control: SwControlFlags, events: EventsNotificationFlags) | () |
set_effect_sync_correction | 6 | (cluster_index: u8, drift_value: i16) | () |
get_power_mode_config | 7 | () | RgbPowerModeConfig |
set_power_mode_config | 7 | (config: RgbPowerModeConfig) | () |
get_power_mode | 8 | () | RgbPowerMode |
set_power_mode | 8 | (mode: RgbPowerMode) | () |
shutdown | 9 | () | () |
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
| Type | Fields | Description |
|---|---|---|
RgbDeviceInfo | cluster_count: u8, nv_capabilities: RgbNvCapabilities, ext_capabilities: RgbExtCapabilities, multicluster_effect_count: u8 | Device-level information. |
RgbClusterInfo | cluster_index: u8, location: u16, effects_number: u8, display_persistency: DisplayPersistencyCapabilities, effect_persistency: bool, multiled_pattern: bool | One cluster. location is a raw locationEffect value. |
RgbEffectInfo | cluster_index: u8, cluster_effect_index: u8, effect_id: u16, effect_capabilities: u16, effect_period: u16 | One cluster effect. Both identifiers are raw. A zero capability value uses Raptor compatibility defaults. A zero period is unavailable. |
RgbSwControl | control: SwControlFlags, events: EventsNotificationFlags | Software-ownership and event-request flags. |
RgbNvConfig | capability: RgbNvCapabilities, state: u8, params: [u8; 6] | One non-volatile configuration entry. The six parameters are capability-specific. |
RgbPowerModeConfig | flags: u16, no_activity_timeout_to_power_save: u16, no_activity_timeout_to_off: u16 | Raw 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
| Type | Variants | Values |
|---|---|---|
SlotInfoType | SlotState, Defaults, Uuid0To10, Uuid11To16, EffectName0To10, EffectName11To21, EffectName21To31 | 0–6 in listed order. |
RgbPowerMode | FullRgb, PowerSave, PowerOff | 1, 2, 3. |
PowerModeTarget | FullPower, PowerSave | 0, 1. |
LedBinIndex | BinValueBrightness, BinValueColor, CalibrationFactors, Brightness, ColorimetricX, ColorimetricY | 0–5 in listed order. |
ActivityEventType | NoActivityTimeoutReached, UserActivityDetected, Other(u8) | 0, 1, or an unmodelled raw value. |
Bit flags
| Type | Flag | Bit | Meaning |
|---|---|---|---|
RgbPersistence | VOLATILE | 1 << 0 | Apply the effect to RAM. |
RgbPersistence | NON_VOLATILE | 1 << 1 | Store the effect in EEPROM. |
RgbExtCapabilities | GET_ZONE_EFFECT | 1 << 0 | Stored-effect get_info mode is supported. |
RgbExtCapabilities | SET_LED_BIN_INFO | 1 << 2 | set_led_bin_info is supported. |
RgbExtCapabilities | MONOCHROME_ONLY | 1 << 3 | Only monochrome effects are supported. |
RgbExtCapabilities | NO_EFFECT_SYNC | 1 << 4 | Effect sync and correction are not supported. |
RgbExtCapabilities | SHUTDOWN | 1 << 5 | shutdown is supported. |
RgbExtCapabilities | CLUSTER_CHANGED_EVENT | 1 << 6 | The cluster-change event is supported. |
RgbNvCapabilities | BOOT_UP_EFFECT | 1 << 0 | Boot-up effect. |
RgbNvCapabilities | DEMO | 1 << 1 | Demo mode. |
RgbNvCapabilities | USER_DEMO_MODE | 1 << 2 | User demo mode. |
RgbNvCapabilities | EVENTS_DISPLAY | 1 << 3 | Events display. |
RgbNvCapabilities | ACTIVE_DIMMING | 1 << 4 | Active dimming. |
RgbNvCapabilities | RAMP_DOWN_TO_OFF | 1 << 5 | Ramp down to off. |
RgbNvCapabilities | SHUTDOWN_EFFECT | 1 << 6 | Shutdown effect. |
SwControlFlags | ALL_CLUSTERS | 1 << 0 | Software controls RGB clusters. |
SwControlFlags | POWER_MODES | 1 << 1 | Software controls power modes. |
EventsNotificationFlags | EFFECTS_SYNC | 1 << 0 | Request effect-sync events. |
EventsNotificationFlags | USER_ACTIVITY | 1 << 1 | Request user-activity events. |
EventsNotificationFlags | NO_USER_ACTIVITY_TIMEOUT | 1 << 2 | Request no-activity-timeout events. |
DisplayPersistencyCapabilities | ALWAYS_ON | 1 << 0 | The cluster can persist always-on state. |
DisplayPersistencyCapabilities | ALWAYS_OFF | 1 << 1 | The cluster can persist always-off state. |
DisplayPersistencyCapabilities | ON_THEN_OFF | 1 << 2 | The 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>.
| Variant | Fields | Description |
|---|---|---|
EffectSync | cluster_index: u8, effect_counter: u16 | A periodic effect reached a sync point. 0xff targets all clusters. The counter is in milliseconds. |
UserActivity | ActivityEventType | User activity began or its absence timed out. |
ClusterChanged | cluster_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. |
NvEffectSync | payload: [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.
| Byte | Field | Notes |
|---|---|---|
| 0–1 | / | OpenLogi ignores these response bytes. |
| 2 | cluster_count | Number of clusters. |
| 3–4 | nv_capabilities | RgbNvCapabilities, BE u16. |
| 5–6 | ext_capabilities | RgbExtCapabilities, BE u16. |
| 7 | multicluster_effect_count | Number of multi-cluster effects. |
get_cluster_info (fn 0)
Request: [cluster_index, 0xff, 0x00] for all effects and general information.
| Byte | Field | Notes |
|---|---|---|
| 0 | cluster_index | Echo. OpenLogi requires it to match the request. |
| 1 | / | OpenLogi ignores this response byte. |
| 2–3 | location | Raw location identifier, BE u16. |
| 4 | effects_number | Number of effects in this cluster. |
| 5 | display_persistency | DisplayPersistencyCapabilities. |
| 6 | effect_persistency | Non-zero means EEPROM effect persistence. |
| 7 | multiled_pattern | Non-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.
| Byte | Field | Notes |
|---|---|---|
| 0 | cluster_index | Response echo. |
| 1 | cluster_effect_index | Response echo. |
| 2–3 | effect_id | Raw effect identifier, BE u16. |
| 4–5 | effect_capabilities | Effect-specific bitmask, BE u16. |
| 6–7 | effect_period | Period 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…].
| Byte | Field | Notes |
|---|---|---|
| 0–2 | / | OpenLogi ignores these response bytes. |
| 3–15 | return value | Raw [u8; ONBOARD_INFO_PARAM_COUNT]. Meaning depends on SlotInfoType. |
set_rgb_cluster_effect (fn 1)
Request: long, 16 bytes.
| Byte | Field | Notes |
|---|---|---|
| 0 | cluster_index | Target cluster. |
| 1 | cluster_effect_index | Effect ordinal in that cluster. |
| 2–11 | params | Ten effect-specific bytes. |
| 12 | flags | RgbPersistence in bits 0–1. PowerModeTarget is in bits 2–3. |
| 13–15 | padding | OpenLogi 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.
| Byte | Field | Notes |
|---|---|---|
| 0 | selector | OpenLogi ignores this response byte. |
| 1–2 | capability | RgbNvCapabilities, BE u16. |
| 3 | state | Capability-specific state byte. |
| 4–9 | params | Six 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.
| Byte | Field | Notes |
|---|---|---|
| 0 | selector | OpenLogi writes 0x01 for write. |
| 1–2 | capability | RgbNvCapabilities, BE u16. |
| 3 | state | Capability-specific state byte. |
| 4–9 | params | All six bytes from RgbNvConfig. |
| 10–15 | padding | OpenLogi 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.
| Byte | Field | Notes |
|---|---|---|
| 0–2 | / | OpenLogi ignores these response bytes. |
| 3–10 | return value | Raw [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.
| Byte | Field | Notes |
|---|---|---|
| 0 | selector | OpenLogi ignores this response byte. |
| 1 | control | SwControlFlags. |
| 2 | events | EventsNotificationFlags. |
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…].
| Byte | Field | Notes |
|---|---|---|
| 0 | cluster_index | 0xff targets all clusters. |
| 1 | reserved | OpenLogi writes 0x00. |
| 2–3 | drift_value | Milliseconds, BE i16. |
| 4–15 | padding | OpenLogi writes 0x00. |
get_power_mode_config (fn 7)
Request: [0x00, 0x00, 0x00]. Byte 0 selects read.
| Byte | Field | Notes |
|---|---|---|
| 0 | selector | OpenLogi ignores this response byte. |
| 1–2 | flags | Raw flags, BE u16. |
| 3–4 | no_activity_timeout_to_power_save | Seconds, BE u16. |
| 5–6 | no_activity_timeout_to_off | Seconds, 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.
| Byte | Field | Notes |
|---|---|---|
| 0 | selector | OpenLogi ignores this response byte. |
| 1 | RgbPowerMode | 1 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-ID | Event | Byte layout |
|---|---|---|
| 0 | EffectSync | Byte 0 is cluster_index. Bytes 1–2 are effect_counter, BE u16 milliseconds. 0xff targets all clusters. |
| 1 | UserActivity | Byte 0 is ActivityEventType. |
| 2 | ClusterChanged | Byte 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. |
| 3 | NvEffectSync | Options+ 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
}