OpenLogi
功能清单

0x8071 · rgbEffects

按集群控制 RGB 效果的引擎。它管理效果、非易失配置、软件控制权、电源模式和 RGB 通知。

rgbEffects 是 0x8070 colorLedEffects 的按集群后继功能。每个集群有自己的效果序号。软件必须先取得目标集群的控制权，才能设置集群效果。

**规格：**Logitech HID++ 2.0 —— rgbEffects（v4）。**交叉核对：**Logi Options+ 2.8（静态分析）、Solaar、G HUB（静态分析）。用于：键盘灯光。

函数参考

方法

函数HID++ fn签名返回值
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>

除 listen 外，所有操作都是返回 Result<_, Hidpp20Error> 的 async fn。listen 由 EmittingFeature<RgbEffectsEvent> 提供。

类型

CLUSTER_EFFECT_PARAM_COUNT 的值为 10。ONBOARD_INFO_PARAM_COUNT 的值为 13。LED_BIN_PARAM_COUNT 的值为 8。ALL_CLUSTERS 和 ALL_EFFECTS 均为 0xff。

数据结构

类型字段说明
RgbDeviceInfocluster_count: u8、nv_capabilities: RgbNvCapabilities、ext_capabilities: RgbExtCapabilities、multicluster_effect_count: u8设备级信息。
RgbClusterInfocluster_index: u8、location: u16、effects_number: u8、display_persistency: DisplayPersistencyCapabilities、effect_persistency: bool、multiled_pattern: bool一个集群。location 是原始 locationEffect 值。
RgbEffectInfocluster_index: u8、cluster_effect_index: u8、effect_id: u16、effect_capabilities: u16、effect_period: u16一个集群效果。两个标识符均为原始值。能力为零时使用 Raptor 兼容默认值。周期为零表示不可用。
RgbSwControlcontrol: SwControlFlags、events: EventsNotificationFlags软件控制权和事件请求标志。
RgbNvConfigcapability: RgbNvCapabilities、state: u8、params: [u8; 6]一个非易失配置项。6 个参数均与能力相关。
RgbPowerModeConfigflags: u16、no_activity_timeout_to_power_save: u16、no_activity_timeout_to_off: u16原始标志和两个以秒为单位的超时值。

RgbNvConfig 是非穷举类型。crate 外部的调用方必须通过 get_nv_config 获取它，修改所需字段后再传给 set_nv_config。

枚举

类型变体值
SlotInfoTypeSlotState、Defaults、Uuid0To10、Uuid11To16、EffectName0To10、EffectName11To21、EffectName21To31按列出顺序为 0～6。
RgbPowerModeFullRgb、PowerSave、PowerOff1、2、3。
PowerModeTargetFullPower、PowerSave0、1。
LedBinIndexBinValueBrightness、BinValueColor、CalibrationFactors、Brightness、ColorimetricX、ColorimetricY按列出顺序为 0～5。
ActivityEventTypeNoActivityTimeoutReached、UserActivityDetected、Other(u8)0、1 或未建模原始值。

位标志

类型标志位含义
RgbPersistenceVOLATILE1 << 0将效果应用到 RAM。
RgbPersistenceNON_VOLATILE1 << 1将效果保存到 EEPROM。
RgbExtCapabilitiesGET_ZONE_EFFECT1 << 0支持存储效果的 get_info 模式。
RgbExtCapabilitiesSET_LED_BIN_INFO1 << 2支持 set_led_bin_info。
RgbExtCapabilitiesMONOCHROME_ONLY1 << 3只支持单色效果。
RgbExtCapabilitiesNO_EFFECT_SYNC1 << 4不支持效果同步和校正。
RgbExtCapabilitiesSHUTDOWN1 << 5支持 shutdown。
RgbExtCapabilitiesCLUSTER_CHANGED_EVENT1 << 6支持集群变化事件。
RgbNvCapabilitiesBOOT_UP_EFFECT1 << 0开机效果。
RgbNvCapabilitiesDEMO1 << 1演示模式。
RgbNvCapabilitiesUSER_DEMO_MODE1 << 2用户演示模式。
RgbNvCapabilitiesEVENTS_DISPLAY1 << 3事件显示。
RgbNvCapabilitiesACTIVE_DIMMING1 << 4主动调光。
RgbNvCapabilitiesRAMP_DOWN_TO_OFF1 << 5渐暗至关闭。
RgbNvCapabilitiesSHUTDOWN_EFFECT1 << 6关闭效果。
SwControlFlagsALL_CLUSTERS1 << 0软件控制 RGB 集群。
SwControlFlagsPOWER_MODES1 << 1软件控制电源模式。
EventsNotificationFlagsEFFECTS_SYNC1 << 0请求效果同步事件。
EventsNotificationFlagsUSER_ACTIVITY1 << 1请求用户活动事件。
EventsNotificationFlagsNO_USER_ACTIVITY_TIMEOUT1 << 2请求无用户活动超时事件。
DisplayPersistencyCapabilitiesALWAYS_ON1 << 0集群可持久保存常亮状态。
DisplayPersistencyCapabilitiesALWAYS_OFF1 << 1集群可持久保存常灭状态。
DisplayPersistencyCapabilitiesON_THEN_OFF1 << 2集群可持久保存先亮后灭状态。

这些位标志类型会保留未知位。封装会公开能力标志，但不会在发送前统一门控这些操作。

事件

RgbEffectsFeature 实现 EmittingFeature<RgbEffectsEvent>。

变体字段说明
EffectSynccluster_index: u8、effect_counter: u16周期效果到达同步点。0xff 指向所有集群。计数器单位为毫秒。
UserActivityActivityEventType用户活动开始，或用户无活动已超时。
ClusterChangedcluster_index: u8、cluster_effect_index: u8、params: [u8; CLUSTER_EFFECT_PARAM_COUNT]、persistence: RgbPersistence、power_mode: Option<PowerModeTarget>一个集群效果发生变化。未建模的 2 位电源模式值会返回 None。
NvEffectSyncpayload: [u8; 16]设备保存的 NV 效果配置可能已变化。payload 是原始字节，其布局未知。短报告会用零扩展到 16 个字节。请把此事件当作提示，用 get_nv_config 重新读取你依赖的每个 NV 能力。

线格式

以下偏移量均为 payload 字节。短请求携带 3 个字节。长请求携带 16 个字节。以下每个多字节值均为 BE。

get_device_info（fn 0）

请求：[0xff, 0xff, 0x00]，分别表示所有集群、所有效果和常规信息。

字节字段备注
0–1/OpenLogi 忽略这两个回复字节。
2cluster_count集群数量。
3–4nv_capabilitiesRgbNvCapabilities，BE u16。
5–6ext_capabilitiesRgbExtCapabilities，BE u16。
7multicluster_effect_count多集群效果数量。

get_cluster_info（fn 0）

请求：[cluster_index, 0xff, 0x00]，分别表示目标集群、所有效果和常规信息。

字节字段备注
0cluster_index回显。OpenLogi 要求它与请求值相同。
1/OpenLogi 忽略此回复字节。
2–3location原始位置标识符，BE u16。
4effects_number此集群的效果数量。
5display_persistencyDisplayPersistencyCapabilities。
6effect_persistency非零表示支持 EEPROM 效果持久化。
7multiled_pattern非零表示支持多 LED 图案。

OpenLogi 要求长回复。短回复或索引不匹配时，OpenLogi 返回 UnsupportedResponse。

get_effect_info（fn 0）

请求：[cluster_index, cluster_effect_index, 0x00]，用于获取常规信息。

字节字段备注
0cluster_index回复回显。
1cluster_effect_index回复回显。
2–3effect_id原始效果标识符，BE u16。
4–5effect_capabilities效果专属位掩码，BE u16。
6–7effect_period周期，单位为毫秒，BE u16；零表示不可用。

get_onboard_effect_info（fn 0）

**请求：**长请求，[cluster_index, cluster_effect_index, 0x01, slot, slot_info_type, 0x00…]。

字节字段备注
0–2/OpenLogi 忽略这些回复字节。
3–15返回值原始 [u8; ONBOARD_INFO_PARAM_COUNT]。含义取决于 SlotInfoType。

set_rgb_cluster_effect（fn 1）

**请求：**长请求，16 个字节。

字节字段备注
0cluster_index目标集群。
1cluster_effect_index此集群中的效果序号。
2–11params10 个效果专属字节。
12标志RgbPersistence 位于位 0–1。PowerModeTarget 位于位 2–3。
13–15填充OpenLogi 写入 0x00。

封装先等待原生写入完成，再等待确认。软件必须先设置 SwControlFlags::ALL_CLUSTERS。

set_multi_led_cluster_pattern（fn 2）

请求：[cluster_index, pattern, 0x00]。

封装等待确认，并丢弃确认 payload。

get_nv_config（fn 3）

请求：[0x00, cap_hi, cap_lo]。字节 0 选择读取。能力值采用 BE u16。

字节字段备注
0选择器OpenLogi 忽略此回复字节。
1–2capabilityRgbNvCapabilities，BE u16。
3state能力专属状态字节。
4–9params6 个能力专属字节。OpenLogi 保留全部 6 个字节。

OpenLogi 要求长回复。封装不命名这 6 个参数，因为它们的含义取决于能力。

set_nv_config（fn 3）

**请求：**长请求，16 个字节。

字节字段备注
0选择器OpenLogi 写入 0x01 表示写入。
1–2capabilityRgbNvCapabilities，BE u16。
3state能力专属状态字节。
4–9params来自 RgbNvConfig 的全部 6 个字节。
10–15填充OpenLogi 写入 0x00。

从 v0.8.14 开始，crate 外部只能传入已读取的 RgbNvConfig。这会在读取、修改和写回时保留每个参数。

get_led_bin_info（fn 4）

请求：[selector, cluster_index, led_bin_index]。选择器 0x00 表示活动数据。选择器 0x02 表示备份数据。

字节字段备注
0–2/OpenLogi 忽略这些回复字节。
3–10返回值原始 [u8; LED_BIN_PARAM_COUNT]。

set_led_bin_info（fn 4）

**请求：**长请求，[0x01, cluster_index, led_bin_index, params[0..8], 0x00…]。

封装等待确认，并丢弃确认 payload。

get_sw_control（fn 5）

请求：[0x00, 0x00, 0x00]。字节 0 选择读取。

字节字段备注
0选择器OpenLogi 忽略此回复字节。
1controlSwControlFlags。
2eventsEventsNotificationFlags。

set_sw_control（fn 5）

请求：[0x01, control.bits(), events.bits()]。字节 0 选择写入。

确认必须回显全部 3 个请求字节。OpenLogi 先等待原生写入完成，再开始有界确认等待。

set_effect_sync_correction（fn 6）

**请求：**长请求，[cluster_index, 0x00, drift_hi, drift_lo, 0x00…]。

字节字段备注
0cluster_index0xff 指向所有集群。
1保留OpenLogi 写入 0x00。
2–3drift_value毫秒，BE i16。
4–15填充OpenLogi 写入 0x00。

get_power_mode_config（fn 7）

请求：[0x00, 0x00, 0x00]。字节 0 选择读取。

字节字段备注
0选择器OpenLogi 忽略此回复字节。
1–2flags原始标志，BE u16。
3–4no_activity_timeout_to_power_save秒，BE u16。
5–6no_activity_timeout_to_off秒，BE u16。

set_power_mode_config（fn 7）

**请求：**长请求，[0x01, flags_hi, flags_lo, psave_hi, psave_lo, off_hi, off_lo, 0x00…]。

标志和两个超时值均为 BE u16。封装等待确认，并丢弃确认 payload。

get_power_mode（fn 8）

请求：[0x00, 0x00, 0x00]。字节 0 选择读取。

字节字段备注
0选择器OpenLogi 忽略此回复字节。
1RgbPowerMode1 为全 RGB，2 为省电，3 为关闭。

set_power_mode（fn 8）

请求：[0x01, mode, 0x00]。字节 0 选择写入。

软件必须先设置 SwControlFlags::POWER_MODES。封装等待确认，并丢弃确认 payload。

shutdown（fn 9）

请求：[0x00, 0x00, 0x00]。

封装等待确认，并丢弃确认 payload。设备通过 RgbExtCapabilities::SHUTDOWN 报告此操作。

事件（主动上报）

子 ID事件字节布局
0EffectSync字节 0 是 cluster_index。字节 1–2 是 effect_counter，即 BE u16 毫秒值。0xff 指向所有集群。
1UserActivity字节 0 是 ActivityEventType。
2ClusterChanged字节 0 是 cluster_index。字节 1 是 cluster_effect_index。字节 2–11 是参数。字节 12 的位 0–1 存放持久化，位 2–3 存放目标电源模式。
3NvEffectSyncOptions+ 2.8 有第四个通知处理器。其 payload 布局未确认。OpenLogi 把字节 0–15 以原始字节发布到 payload。

OpenLogi 的用法

自动灯光路径仅在 0x8070 无法提供固定颜色时使用 0x8071。它会在写入前枚举每个集群和每个集群的效果。只有每个集群都具有静态效果 ID 1 时，它才取得控制权。

对于 0x8081 逐键输出，如果此效果引擎存在，OpenLogi 会使用同一控制权。它先为每个支持的集群应用静态颜色，再发送帧，并在新取得控制权后重复该帧。部分可用的引擎会在取得控制权前回退。

从 v0.8.14 开始，PR #1769 会把成功的控制权请求记录为代理会话租约。PR #1770 修复了交还竞争。代理正常退出时，OpenLogi 先拒绝新的灯光写入，最多等待 2 秒处理已接纳写入，再在共享的 2 秒预算内交还每个已记录设备的控制权。

交还操作只清除 ALL_CLUSTERS。它保留保存的事件标志和其他保存的控制标志。设备断开或交还失败时只记录日志，不延迟退出。独立诊断写入会保留易失颜色和控制权。

键盘灯光标签页提供一种静态颜色和亮度。它不提供动画效果、逐键编辑、电源模式配置或 NV 配置。从 v0.8.14 开始，PR #1753 会在封装调用方修改已读取配置时保留全部 6 个 NV 参数。

未确认的细节

第四个通知

Options+ 2.8 的静态分析将子 ID 3 标识为 NV 效果同步通知。该分析没有恢复 payload schema。OpenLogi 逐字段解码子 ID 0～2。从 PR #1951 开始，OpenLogi 以原始字节发布子 ID 3 的 16 字节 payload。对应的事件变体是 NvEffectSync。

payload 的含义仍未确认。需要硬件抓包、公开规格或更强的分析证据，OpenLogi 才能发布类型化字段。本页不会猜测此通知的字节含义。

速率限制

G HUB 静态分析列出了此功能的速率限制操作。提供的证据没有确定其函数索引或 payload 布局。OpenLogi v0.8.15 未公开该操作。

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
}

0x8070 · colorLedEffects

按区域控制 RGB 效果的引擎。它可枚举 LED 区域和效果、应用带持久化选项的效果，并同步效果时序。

0x8080 · perKeyLighting

旧版逐键 RGB 灯光控制，通过超长报告流式写入 HID 用法和颜色条目，再提交暂存的帧。

本页目录

函数参考方法类型数据结构枚举位标志事件线格式get_device_info（fn 0）get_cluster_info（fn 0）get_effect_info（fn 0）get_onboard_effect_info（fn 0）set_rgb_cluster_effect（fn 1）set_multi_led_cluster_pattern（fn 2）get_nv_config（fn 3）set_nv_config（fn 3）get_led_bin_info（fn 4）set_led_bin_info（fn 4）get_sw_control（fn 5）set_sw_control（fn 5）set_effect_sync_correction（fn 6）get_power_mode_config（fn 7）set_power_mode_config（fn 7）get_power_mode（fn 8）set_power_mode（fn 8）shutdown（fn 9）事件（主动上报）OpenLogi 的用法未确认的细节第四个通知速率限制Rust 用法