0x1001 · batteryVoltage – OpenLogi Docs

无线 G 系列设备通过大端序毫伏读数和充电标志报告电池状态。

batteryVoltage 会报告实测电池电压和一个充电标志字节。 G915、G903 LIGHTSPEED 和 G502 LIGHTSPEED 不提供 0x1000 或 0x1004，但提供此功能。此功能不包含百分比。

**规格：**没有公开的 Logitech 规格。布局来自 Logi Options+ 2.8（静态分析）的逆向。**交叉核对：**Linux HID++ 驱动程序、Solaar。**用于：**设备清单和 openlogi list。

函数参考

BatteryVoltageFeature（0x1001）实现一个请求方法。

方法

函数	HID++ fn	签名	返回值
`get_battery_info`	0	`()`	`VoltageBatteryInfo`
`is_status_broadcast`	事件辅助方法	`(function_id: u8)`	`bool`

get_battery_info 是异步方法，返回 Result<VoltageBatteryInfo, Hidpp20Error>。封装器没有对应 function 1 的 show_battery_status 方法。

类型

`VoltageBatteryInfo`

字段	类型	说明
`voltage_mv`	`u16`	电池电压，单位为毫伏。代码将单节 Li-Po 的范围描述为约 `3,500`～`4,200 mV`。
`status`	`VoltageChargingStatus`	由标志字节解码出的充电状态。
`critical`	`bool`	固件的危急电量标记，来自 bit `5`。

`VoltageChargingStatus`

变体	说明
`Discharging`	使用电池供电，外部电源 bit 为 clear。
`Charging`	有外部电源，且以标准速率充电。
`ChargingFast`	有外部电源，且有快速充电标记。
`ChargingSlow`	有外部电源，且有慢速充电标记。
`Full`	有外部电源，且充电状态值为 `1`。
`NotCharging`	有外部电源，且充电状态值为 `2`。
`Unknown`	有外部电源，且充电状态值未定义。

事件

此封装器未实现 EmittingFeature，也不公开类型化事件。仅当 function 为 0 时，is_status_broadcast(function_id) 返回 true。

线格式

`get_battery_info`（fn 0）

请求：[0x00, 0x00, 0x00]（没有参数）。

响应：

字节	字段	说明
0～1	`voltage_mv`	`u16`，BE，单位为毫伏。
2	flags	链路、充电、充电速率和危急标记。

标志：

位	含义	OpenLogi 解码
7	存在外部电源	clear 时为 `Discharging`。其他标志位不会改变此结果。
0～2	有外部电源时的充电状态	`0` 为充电中，`1` 为 `Full`，`2` 为 `NotCharging`。值 `3`～`7` 会变成 `Unknown`。
3	快速充电标记	状态为 `0` 时，结果为 `ChargingFast`。
4	慢速充电标记	状态为 `0` 且 bit `3` 为 clear 时，结果为 `ChargingSlow`。
5	危急标记	独立公开为 `critical`。
6	/	未建模任何含义。

有外部电源时，低位状态 0x03 表示 Unknown。例如，完整标志字节 0x83 不表示 Full。

`showBatteryStatus`（fn 1，未实现）

Logi Options+ 会调用 function 1，并检查是否收到非空回复。它的请求布局、回复布局和物理效果均未确认。 OpenLogi 不公开或调用此 function。

状态广播（事件 fn 0）

未请求的 function 0 报告携带与 get_battery_info 相同的 3 个字节。该报告表示电压或充电状态已经变化。

OpenLogi 的用法

只有 0x1004 和 0x1000 都缺席时，清单才会选择此来源。它优先于 0x1F20 ADC measurement。

OpenLogi 使用 13 个点的单节 Li-Po 曲线估算百分比。该曲线在 3,500 mV 时限制为 0%，在 4,186 mV 时限制为 100%。危急标记会覆盖估算出的显示等级。

从 v0.8.14 起，PR #1768 将未定义的外部电源状态值映射为 Unknown。这包括低位状态 0x03。因为 function 1 的效果未确认，OpenLogi 不会调用它。

从 v0.8.14 起，PR #1787 会记录此功能的运行时索引。未请求的 software-ID 0、function 0 报告会排队一个合并后的清单重协调。 OpenLogi 会重新读取权威状态，不会信任事件负载。

OpenLogi 只读取此功能。

未确认的细节

Logi Options+ 会在 function 1 使用 showBatteryStatus，并要求非空回复。静态分析无法确认它控制 LED、屏幕提示还是其他设备动作。 OpenLogi 在硬件捕获确认效果前不会调用此 function。

Rust 用法

use hidpp::{
    device::Device,
    feature::battery_voltage::BatteryVoltageFeature,
};

// `channel` 和 `device_index` 用于标识已打开的 HID++ 设备。
let mut device = Device::new(channel, device_index).await?;
device.enumerate_features().await?;

if let Some(feature) = device.get_feature::<BatteryVoltageFeature>() {
    let info = feature.get_battery_info().await?;
    println!("{} mV: {:?}", info.voltage_mv, info.status);
}

另见：0x1000 batteryStatus 和 0x1004 unifiedBattery。

0x1001 · batteryVoltage

本页目录