0x1982 · backlight – OpenLogi Docs

0x1982 控制键盘的白色分级背光。OpenLogi 提供版本 3 的类型化封装和设备层控制路径。键盘声明相应控制时，该路径提供开关、自动亮度、固定亮度和电池节能。

**规格：**没有公开的 Logitech 规格。布局来自 Logi Options+ 2.8（静态分析）。**交叉核对：**Solaar。用于：键盘灯光和屏幕提示。

函数参考

BacklightFeature 从版本 3 起实现 HID++ 0x1982。每个异步方法返回 Result<…, Hidpp20Error>。

方法

函数	HID++ fn	签名	返回值
`get_backlight_config`	0	`(&self)`	`BacklightConfig`
`set_backlight_config`	1	`(&self, config: SetBacklightConfig)`	`()`
`get_backlight_info`	2	`(&self)`	`BacklightInfo`
`set_backlight_effect`	3	`(&self, effect: BacklightEffect)`	`()`
`EmittingFeature::listen`	event	`(&self)`	`async_channel::Receiver<BacklightEvent>`

类型

`BacklightConfig`

get_backlight_config 返回此持久化配置。

字段	类型	说明
`enabled`	`bool`	背光系统是否启用。
`options`	`BacklightOptions`	已启用标志、能力标志和保留的未知位。
`mode`	`BacklightMode`	解码后的 2 位模式。
`effect_list`	`BacklightEffectList`	键盘声明支持的特效。
`current_level`	`u8`	存储的手动亮度级别。
`duration_hands_out`	`u16`	第一个淡出时长，单位为 5 秒。
`duration_hands_in`	`u16`	第二个淡出时长，单位为 5 秒。
`duration_powered`	`u16`	第三个淡出时长，单位为 5 秒。
`duration_not_powered`	`u16`	第四个淡出时长，单位为 5 秒。Options+ 2.8 称它为「not powered」，触发条件未验证。

`SetBacklightConfig`

set_backlight_config 持久化写入此配置。

字段	类型	说明
`enabled`	`bool`	请求的总开关状态。
`options`	`BacklightOptions`	只发送 `WOW`、`CROWN` 和 `PWR_SAVE`。
`mode`	`BacklightMode`	编码到请求位 3～4 的模式。
`effect`	`Option<BacklightEffect>`	`None` 发送 `0xff`，不修改特效。
`current_level`	`u8`	请求的手动亮度级别。
`duration_hands_out`	`u16`	第一个淡出时长，单位为 5 秒。
`duration_hands_in`	`u16`	第二个淡出时长，单位为 5 秒。
`duration_powered`	`u16`	第三个淡出时长，单位为 5 秒。
`duration_not_powered`	`u16`	第四个淡出时长，单位为 5 秒。

`BacklightInfo`

get_backlight_info 返回实时状态和出厂时长。

字段	类型	说明
`nb_levels`	`u8`	可选亮度级别数，包含级别 `0`。
`current_level`	`u8`	当前显示的亮度级别。
`status`	`BacklightStatus`	当前运行状态。
`effect`	`BacklightEffect`	当前应用的特效。
`oob_duration_hands_out`	`u16`	第一个出厂淡出时长，单位为 5 秒。
`oob_duration_hands_in`	`u16`	第二个出厂淡出时长，单位为 5 秒。
`oob_duration_powered`	`u16`	第三个出厂淡出时长，单位为 5 秒。
`oob_duration_not_powered`	`u16`	第四个出厂淡出时长，单位为 5 秒。

`BacklightMode`

变体	值	说明
`None`	0	未选择模式。
`Automatic`	1	环境光传感器选择亮度。
`TemporaryManual`	2	键盘背光键选择临时亮度。
`PermanentManual`	3	软件选择并保持亮度。

BacklightMode 带有 #[non_exhaustive]。底层 setter 接受表中的每个变体。OpenLogi 的设备层不会写入 TemporaryManual，而是在设备层写入前改为 Automatic。

`BacklightEffect`

变体	值	说明
`Static`	0	静态特效。
`None`	1	无特效。
`Breathing`	2	呼吸特效。
`Contrast`	3	对比特效。
`Reaction`	4	按键反应特效。
`Random`	5	随机特效。
`Waves`	6	波浪特效。

BacklightEffect 带有 #[non_exhaustive]。

`BacklightStatus`

变体	值	说明
`DisabledBySoftware`	0	软件禁用了背光。
`DisabledByCriticalBattery`	1	电池电量严重不足。
`AlsAutomatic`	2	环境光传感器控制亮度。
`AlsSaturated`	3	传感器认为环境光足够，LED 保持熄灭。
`TemporaryManual`	4	键盘背光键设置了亮度。
`PermanentManual`	5	软件设置了亮度。

BacklightStatus 带有 #[non_exhaustive]。

`BacklightOptions`

封装读取此 u16 位字段时会保留未知位。写入配置时，它只发送三个可写低位。

标志	位	说明
`WOW`	0	启用 WOW 开机特效。
`CROWN`	1	启用 CROWN 触摸特效。
`PWR_SAVE`	2	启用低电量背光节能。
`WOW_SUPPORTED`	8	键盘声明支持 WOW。
`CROWN_SUPPORTED`	9	键盘声明支持 CROWN。
`PWR_SAVE_SUPPORTED`	10	键盘声明支持电池节能。
`AUTO_MODE_SUPPORTED`	11	键盘声明支持自动模式。
`TEMP_MANUAL_SUPPORTED`	12	键盘声明支持临时手动模式。
`PERM_MANUAL_SUPPORTED`	13	键盘声明支持永久手动模式。

`BacklightEffectList`

读取此 u16 位字段时，封装会保留未知位。

标志	位	说明
`STATIC`	0	静态特效。
`NONE`	1	无特效。
`BREATHING`	2	呼吸特效。
`CONTRAST`	3	对比特效。
`REACTION`	4	按键反应特效。
`RANDOM`	5	随机特效。
`WAVES`	6	波浪特效。

事件

BacklightFeature 实现 EmittingFeature<BacklightEvent>。事件源只接受函数 0 的主动报告。

变体	负载	说明
`InfoChanged`	`BacklightInfoUpdate`	背光状态、亮度或特效更新。

BacklightInfoUpdate 包含 nb_levels: u8、current_level: u8、status: BacklightStatus 和 effect: BacklightEffect。

线格式

读取请求使用 3 字节、全零的短负载。set_backlight_config 使用 16 字节长负载。下面的每个多字节字段均为 LE。

OpenLogi 要求函数 0 和 2 返回长报告。它拒绝短报告，避免将可能回写的配置补零。函数 1 和 3 等待响应，但忽略响应负载。

`get_backlight_config`（fn 0）

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

字节	字段	备注
0	`enabled`	位 0 是总开关。
1～2	选项和模式	LE `u16`。位 0～2 是可写选项。OpenLogi 将位 3～4 解码为 `mode`。位 5 未确认。
3～4	`effect_list`	LE `u16` `BacklightEffectList`。
5	`current_level`	存储的手动亮度级别。
6～7	`duration_hands_out`	LE `u16`，单位为 5 秒。
8～9	`duration_hands_in`	LE `u16`，单位为 5 秒。
10～11	`duration_powered`	LE `u16`，单位为 5 秒。
12～13	`duration_not_powered`	LE `u16`，单位为 5 秒。Options+ 2.8。
14～15	未知	OpenLogi 不建模也不读取。

`set_backlight_config`（fn 1）

请求是 16 字节长负载。

字节	字段	备注
0	`enabled`	`0` 禁用，`1` 启用。
1	选项和模式	`(options & 0x07) \| (mode << 3)`。只写入 `WOW`、`CROWN` 和 `PWR_SAVE`。位 5 写为零。
2	`effect`	特效值；`None` 为 `0xff`。
3	`current_level`	请求的手动亮度级别。
4～5	`duration_hands_out`	LE `u16`，单位为 5 秒。
6～7	`duration_hands_in`	LE `u16`，单位为 5 秒。
8～9	`duration_powered`	LE `u16`，单位为 5 秒。
10～11	`duration_not_powered`	LE `u16`，单位为 5 秒。Options+ 2.8。
12～15	填充	OpenLogi 写入零。现有证据没有定义这些字节。

`get_backlight_info`（fn 2）

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

字节	字段	备注
0	`nb_levels`	可选亮度级别数，包含 `0`。
1	`current_level`	当前亮度级别。
2	`status`	`BacklightStatus` 值。
3	`effect`	`BacklightEffect` 值。
4～5	`oob_duration_hands_out`	LE `u16`，单位为 5 秒。
6～7	`oob_duration_hands_in`	LE `u16`，单位为 5 秒。
8～9	`oob_duration_powered`	LE `u16`，单位为 5 秒。
10～11	`oob_duration_not_powered`	LE `u16`，单位为 5 秒。Options+ 2.8。
12～15	未知	OpenLogi 不建模也不读取。

`set_backlight_effect`（fn 3）

请求：[effect, 0x00, 0x00]。字节 0 是 BacklightEffect 值。特效是临时状态，存于 RAM，不写入持久存储。

事件：`backlightInfoEvent`（fn 0）

OpenLogi 将函数 0 的事件解码为 BacklightEvent::InfoChanged。现有证据确认前 4 个负载字节。OpenLogi 忽略其余字节。

字节	字段	备注
0	`nb_levels`	可选亮度级别数。
1	`current_level`	更新后的当前亮度级别。
2	`status`	`BacklightStatus` 值。
3	`effect`	`BacklightEffect` 值。
4～15	未知	OpenLogi 忽略这些字节。

OpenLogi 的用法

OpenLogi 显示背光卡或接受修改前，会读取配置和实时信息。自动亮度需要自动模式和永久手动模式能力位。亮度控制还要求功能版本至少为 3、亮度级别超过一个。电池节能要求 PWR_SAVE_SUPPORTED。

每项已接受的修改都使用完整配置的读-改-写。OpenLogi 使用 0xff 保留特效，并保留全部四个时长和其他读取到的选项。自 v0.8.14 起，它也保留 duration_not_powered，并拒绝短配置和信息回复。写入后，它重新读取配置和信息，并拒绝键盘没有应用的修改。

关闭自动亮度时，OpenLogi 固定实时信息回复中的亮度。设备层的开关或电池节能写入会将 TemporaryManual 改为 Automatic。配置存于键盘的非易失性存储，因此 OpenLogi 退出时不恢复状态。

由库存持有的监听器识别函数 0 广播。它增加键盘设置修订号以刷新状态，并向屏幕指示器发送当前亮度。指示器显示 1,500 ms；详见屏幕提示。

未确认的细节

Options+ 2.8 将选项字节的位 3～5 当作 3 位模式。Solaar 和 OpenLogi 只解码位 3～4。OpenLogi 读取后在 BacklightOptions 中保留位 5，但写入时将它写为零。没有硬件抓包或公开功能规格可以判定哪种解释正确。

Options+ 2.8 将第四个时长称为「not powered」。字节所有权已经确认，但应用该时长的条件没有硬件验证。现有证据也不能确认版本 0～2 的布局。

Rust 用法

use hidpp::{
    feature::backlight::{BacklightFeature, SetBacklightConfig},
    protocol::v20::Hidpp20Error,
};

async fn enable(feature: &BacklightFeature) -> Result<(), Hidpp20Error> {
    let config = feature.get_backlight_config().await?;

    feature
        .set_backlight_config(SetBacklightConfig {
            enabled: true,
            options: config.options,
            mode: config.mode,
            effect: None,
            current_level: config.current_level,
            duration_hands_out: config.duration_hands_out,
            duration_hands_in: config.duration_hands_in,
            duration_powered: config.duration_powered,
            duration_not_powered: config.duration_not_powered,
        })
        .await
}

0x1982 · backlight

本页目录