OpenLogi
功能清单

0x8070 · colorLedEffects

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

colorLedEffects 是 Logitech 键盘和鼠标的按区域 RGB 引擎。每个 LED 区域报告位置和效果列表。效果索引只属于一个区域。

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

函数参考

方法

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

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

类型

ZONE_EFFECT_PARAM_COUNT 的值为 10。

数据结构

类型字段说明
Rgbred: u8、green: u8、blue: u8每个颜色通道使用一个 8 位值。
ColorLedInfozone_count: u8、nv_capabilities: NvCapabilities、ext_capabilities: ExtCapabilities功能的全局信息。
ZoneInfozone_index: u8、location: LocationEffect、effects_number: u8、persistency: PersistencyCapabilities一个区域。使用 get_zone_effect_info 遍历 0..effects_number。
ZoneEffectInfozone_index: u8、zone_effect_index: u8、effect_id: EffectId、effect_capabilities: u16、effect_period: u16一个效果。effect_capabilities 为 0 时使用 Raptor 兼容默认值。周期为 0 表示不可用。
ZoneEffectzone_index: u8、zone_effect_index: u8、params: [u8; ZONE_EFFECT_PARAM_COUNT]已配置的效果及其原始参数。
EffectSettingszone_index: u8、color: Rgb、period: u16、brightness: u8、param: u8一个区域的已解码设置。
SwControlStatecontrol: SwControl、sync_events: boolLED 控制权和同步事件状态。
NvConfigcapability: NvCapabilities、state: NvCapabilityState、param1: u8、param2: u8一个非易失能力项。
LedBinInfozone_index: u8、led_bin_index: LedBinIndex、red: u16、green: u16、blue: u16、white: u16LED 制造分档值。

这些结构中的所有时长和周期单位都是毫秒。effect_capabilities 保持原始位掩码，因为其位含义取决于 effect_id。

枚举

类型变体值
EffectIdDisabled、FixedColor、PulsingBreathingLegacy、Cycling、ColorWave、Starlight、LightOnPress、AudioVisualizer、BootUp、DemoMode、PulsingBreathingWaveform、Ripple按列出顺序为 0～11。AudioVisualizer 为保留值。
LocationEffectPrimary、Logo、LeftSide、RightSide、Combined、Primary1、Primary2、Primary3、Primary4、Primary5、Primary6按列出顺序为 1～11。
PersistenceVolatile、VolatileAndNonVolatile、NonVolatileOnly0、1、2。仅 RAM；RAM 加 EEPROM；仅 EEPROM。
PersistenceSourceRam、Eeprom0、1。
SwControlFirmware、Software0、1。
CyclingDirectionClockwise、Anticlockwise0、1。
LedBinIndexBinValueBrightness、BinValueColor、CalibrationFactors、Brightness、ColorimetricX、ColorimetricY按列出顺序为 0～5。
NvCapabilityStateNoChange、Enabled、Disabled0、1、2。NoChange 是只读哨兵值，并假定功能已启用。

位标志

类型标志位含义
NvCapabilitiesBOOT_UP_EFFECT1 << 0可配置开机效果。
NvCapabilitiesDEMO1 << 1支持演示模式。
NvCapabilitiesUSER_DEMO_MODE1 << 2支持用户演示模式。
ExtCapabilitiesGET_ZONE_EFFECT1 << 0支持 get_zone_effect。
ExtCapabilitiesNO_GET_EFFECT_SETTINGS1 << 1不支持 get_effect_settings。
ExtCapabilitiesSET_LED_BIN_INFO1 << 2支持 set_led_bin_info。
ExtCapabilitiesMONOCHROME_ONLY1 << 3只支持单色效果。
ExtCapabilitiesNO_SYNCHRONIZE_EFFECT1 << 4不支持同步校正和同步事件。
PersistencyCapabilitiesALWAYS_ON1 << 0区域可持久保存常亮状态。
PersistencyCapabilitiesALWAYS_OFF1 << 1区域可持久保存常灭状态。
PersistencyCapabilitiesON_THEN_OFF1 << 2区域可持久保存先亮后灭状态。

PersistencyCapabilities::empty() 表示区域不支持持久化。

事件

ColorLedEffectsFeature 实现 EmittingFeature<ColorLedEffectsEvent>。

变体字段说明
SyncEffectzone_index: u8、effect_counter: u16周期效果到达同步点。0xff 指向所有区域。计数器单位为毫秒。

线格式

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

get_info（fn 0）

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

字节字段备注
0zone_count区域数量。
1–2nv_capabilitiesNvCapabilities，BE u16。
3–4ext_capabilitiesExtCapabilities，BE u16。

get_zone_info（fn 1）

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

字节字段备注
0zone_index回显。OpenLogi 要求它与请求值相同。
1–2locationLocationEffect，BE u16。
3effects_number此区域的效果数量。
4persistencyPersistencyCapabilities。

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

get_zone_effect_info（fn 2）

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

字节字段备注
0zone_index回复回显。
1zone_effect_index回复回显。
2–3effect_idEffectId，BE u16。
4–5effect_capabilities效果专属位掩码，BE u16。
6–7effect_period周期，单位为毫秒，BE u16；零表示不可用。

set_zone_effect（fn 3）

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

字节字段备注
0zone_index目标区域。
1zone_effect_index此区域中的效果序号。
2–11params10 个效果专属字节。FixedColor 使用字节 2–4 存放红、绿、蓝。
12persistencePersistence 值。
13–15填充OpenLogi 写入 0x00。

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

get_nv_config（fn 4）

请求：[cap_hi, cap_lo, 0x00]。能力值是一个 NvCapabilities 位，采用 BE u16。

字节字段备注
0–1capability回显的 NvCapabilities，BE u16。
2stateNvCapabilityState。
3param1能力专属字节。
4param2能力专属字节。

OpenLogi 要求请求值恰好设置一个能力位。

set_nv_config（fn 5）

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

字节字段备注
0–1capability一个 NvCapabilities 位，BE u16。
2stateNvCapabilityState。
3param1能力专属字节。
4param2能力专属字节。
5–15填充OpenLogi 写入 0x00。

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

get_led_bin_info（fn 6）

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

字节字段备注
0zone_index回复回显。
1led_bin_indexLedBinIndex。
2–3redBE u16。
4–5greenBE u16。
6–7blueBE u16。
8–9whiteBE u16。

get_sw_control（fn 7）

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

字节字段备注
0controlSwControl：0 为固件，1 为软件。
1sync_events零为 false。任何非零值为 true。

set_sw_control（fn 8）

请求：[control, sync_events, 0x00]。sync_events 为 0 或 1。

封装等待确认，并丢弃确认 payload。同步事件选择不保存到 EEPROM。

get_effect_settings（fn 9）

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

字节字段备注
0zone_index回复回显。
1–3color红、绿、蓝字节。
4–5period毫秒，BE u16。
6brightness原始亮度字节。
7param效果专属字节。

当 NO_GET_EFFECT_SETTINGS 置位时，此函数不可用。

clear_effect_settings（fn 10）

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

封装等待确认，并丢弃确认 payload。该操作将区域恢复为默认模式。

set_cycling_direction（fn 11）

请求：[direction, 0x00, 0x00]。Clockwise 为 0。Anticlockwise 为 1。

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

get_current_color（fn 12）

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

字节字段备注
0/OpenLogi 忽略此字节。
1–3Rgb红、绿、蓝字节。

synchronize_effect（fn 13）

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

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

此函数仅在启用同步事件时有效。当 NO_SYNCHRONIZE_EFFECT 置位时，它不可用。

get_zone_effect（fn 14）

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

字节字段备注
0zone_index回复回显。
1zone_effect_index回复中的效果序号。
2–11params10 个效果专属字节。

只有 GET_ZONE_EFFECT 置位时，此函数才可用。

set_led_bin_info（fn 15）

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

字节字段备注
0zone_index目标区域。
1led_bin_indexLedBinIndex。
2–3redBE u16。
4–5greenBE u16。
6–7blueBE u16。
8–9whiteBE u16。
10–15填充OpenLogi 写入 0x00。

回复使用 get_led_bin_info 的布局。OpenLogi 解码并返回这些回显值。

SyncEffect 事件（事件 fn 0）

字节字段备注
0zone_index0xff 指向所有区域。
1–2effect_counter时序位置，单位为毫秒，BE u16。

OpenLogi 的用法

自动键盘灯光路径先尝试 0x8070，再尝试 0x8071、0x8081 和 0x8080。该路径只写入易失固定颜色效果。代理会在键盘重新连接时应用已保存的颜色，而不是每次选色都写入 EEPROM。

从 v0.8.14 开始，PR #1758 会在每个已枚举区域中查找 EffectId::FixedColor。该路径写入发现的效果索引，而不是 EffectId 值。区域没有该效果时会跳过该区域。没有任何目标时会回退到下一个灯光路径。

该写入器目前只枚举前 4 个报告的区域。当 zone_count 为零或 get_zone_info 被拒绝时，它还会为区域 0..4 使用旧版效果索引 1。这些兼容回退仍可能写入错误效果或遗漏区域。

生产灯光路径只使用函数 0～3。该路径不获取此功能的软件控制权，也不调用 NV 配置、同步或其他仅限 v1 的函数。用户界面入口是键盘灯光标签页。

未确认的细节

版本门控函数

Options+ 2.8 只在功能版本至少为 1 时调用函数 4、5、7、8 和 13。G HUB 静态分析也标明存在功能版本检查。OpenLogi 从版本 0 注册同一个封装，且这些调用没有运行时门控。

版本条件有静态分析支持，但提供的证据没有硬件抓包。静态颜色界面不调用这些函数。封装调用方必须接受版本 0 返回错误的可能性。

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(())
}

0x8061 · extendedAdjustableReportRate

按连接类型查询最高 8000 Hz 的回报率能力，并读取或设置当前的扩展回报率。

0x8071 · rgbEffects

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

本页目录

函数参考方法类型数据结构枚举位标志事件线格式get_info（fn 0）get_zone_info（fn 1）get_zone_effect_info（fn 2）set_zone_effect（fn 3）get_nv_config（fn 4）set_nv_config（fn 5）get_led_bin_info（fn 6）get_sw_control（fn 7）set_sw_control（fn 8）get_effect_settings（fn 9）clear_effect_settings（fn 10）set_cycling_direction（fn 11）get_current_color（fn 12）synchronize_effect（fn 13）get_zone_effect（fn 14）set_led_bin_info（fn 15）SyncEffect 事件（事件 fn 0）OpenLogi 的用法未确认的细节版本门控函数Rust 用法