0x1004 · unifiedBattery
统一电池 capability 和状态功能包含 state-of-charge 门控及实时电量变化事件。
unifiedBattery 是 OpenLogi 首选的电量来源。
它报告支持的等级、state-of-charge capability 和当前电池状态。
设备还可以主动发送状态事件。
**规格:**Logitech HID++ 2.0 —— x1004 unifiedBattery。**交叉核对:**Logi Options+ 2.8(静态分析)、Linux HID++ 驱动程序、Solaar。**用于:**设备清单和
openlogi list。
函数参考
UnifiedBatteryFeature(0x1004)提供两项读取和一个事件监听器。
方法
| 函数 | HID++ fn | 签名 | 返回值 |
|---|---|---|---|
get_battery_capabilities | 0 | () | BatteryCapabilities |
get_battery_info | 1 | () | BatteryInfo |
listen | 事件 | () | Receiver<BatteryEvent> |
两个 getter 都是异步方法,返回 Result<…, Hidpp20Error>。
listen 是同步方法,来自 EmittingFeature<BatteryEvent>。
类型
BatteryCapabilities
| 字段 | 类型 | 说明 |
|---|---|---|
reported_levels | HashSet<BatteryLevel> | 固件会报告的电量等级变体。 |
rechargeable | bool | 电池可以充电。 |
percentage | bool | 设备有用于 BatteryInfo::charging_percentage 的 state-of-charge 表。 |
BatteryInfo
| 字段 | 类型 | 说明 |
|---|---|---|
charging_percentage | u8 | 原始状态字节 0。设备没有 state-of-charge 表时,此值为零。 |
level | BatteryLevel | 固件的粗略电量等级。 |
status | BatteryStatus | 固件的充电状态。 |
BatteryLevel
| 变体 | 值 | 说明 |
|---|---|---|
Critical | 1 | 危急电量等级。 |
Low | 2 | 低电量等级。 |
Good | 4 | 正常电量等级。 |
Full | 8 | 满电量等级。 |
BatteryStatus
| 变体 | 值 | 说明 |
|---|---|---|
Discharging | 0 | 电池正在放电。 |
Charging | 1 | 电池正在充电。 |
ChargingNearlyFull | 2 | 电池处于最后充电阶段。 |
Full | 3 | 电池已充满。 |
ChargingSlow | 4 | 电池以低于正常的速率充电。 |
InvalidBattery | 5 | 电池类型无效。 |
ThermalError | 6 | 电池子系统报告温度错误。 |
ChargingError | 7 | 电池子系统报告充电错误。 |
事件
BatteryEvent
| 变体 | 负载 | 说明 |
|---|---|---|
InfoUpdate | BatteryInfo | 从事件 function 0 解码出的状态广播。 |
BatteryEvent::decode(function_id, payload) 仅接受 function 0。
遇到未知的等级值或状态值时,它返回 None。
线格式
两个请求负载均为 [0x00, 0x00, 0x00](没有参数)。
get_battery_capabilities(fn 0)
响应:
| 字节和位 | 字段 | 说明 |
|---|---|---|
| 0,bit 0 | reported_levels 包含 Critical | 设置时表示支持。 |
| 0,bit 1 | reported_levels 包含 Low | 设置时表示支持。 |
| 0,bit 2 | reported_levels 包含 Good | 设置时表示支持。 |
| 0,bit 3 | reported_levels 包含 Full | 设置时表示支持。 |
| 1,bit 0 | rechargeable | 设置时表示可以充电。 |
| 1,bit 1 | percentage | 存在 state-of-charge 表。 |
get_battery_info(fn 1)
响应:
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | charging_percentage | 原始 state of charge。仅当 capability 字节 1 的 bit 1 已设置时,将它当作百分比。 |
| 1 | level | BatteryLevel:1、2、4 或 8。 |
| 2 | status | BatteryStatus:0~7。 |
| 3 | 外部电源状态 | Logi Options+ 会公开它。OpenLogi 忽略它。Options+ 2.8 |
| 4 | 快速充电状态 | 仅在 feature version 4 或更高版本存在。OpenLogi 忽略它。Options+ 2.8 |
| 5 | 可拆卸电池状态 | 仅在 feature version 5 或更高版本存在。OpenLogi 忽略它。Options+ 2.8 |
OpenLogi 不保留这些只读尾部字节。 此功能没有写入器,因此 OpenLogi 不会写入固定值。
InfoUpdate 事件(事件 fn 0)
设备在电池信息变化时发送未请求的 function 0 报告。
该事件采用与 function 1 相同的状态布局。
BatteryEvent 仅解析字节 0~2。
OpenLogi 在事件中忽略字节 3~5。
OpenLogi 的用法
清单会在所有其他电量来源之前选择 0x1004。
在 feature-table walk 后,它会读取一次 capability,并记住 state-of-charge 标志。
state-of-charge 标志为 clear 时,清单会将公开的百分比设为 None。
固件等级仍是权威显示值。
capability 读取失败时,OpenLogi 暂时假定有百分比,标记 capability 不完整,并在下一次重协调时重试。
PR #1788 在 v0.8.14 发布。
它修复了将不支持的 state-of-charge 字节视为 0% 的旧行为。
持久清单监听器仅接受字节 0~2 可解码的 software-ID 0 事件。
它会排队一个合并后的权威重协调。
封装器的 listen() 仍可供 crate 用户直接使用。
OpenLogi 只读取此功能。 它不建模外部电源、快速充电、可拆卸电池或 version-gated 尾部长度。
未确认的细节
Linux 对状态值 2 和 4 的命名与当前 OpenLogi 名称不同。
Logi Options+ 会保留数值,但恢复出的枚举名称不完整。
OpenLogi 对 2 使用 ChargingNearlyFull,对 4 使用 ChargingSlow。
扩展状态字段由静态分析支持,不是硬件捕获结果。 它们的取值集合尚未确认。
Rust 用法
use hidpp::{
device::Device,
feature::{EmittingFeature, unified_battery::UnifiedBatteryFeature},
};
// `channel` 和 `device_index` 用于标识已打开的 HID++ 设备。
let mut device = Device::new(channel, device_index).await?;
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<UnifiedBatteryFeature>() {
let caps = feature.get_battery_capabilities().await?;
let info = feature.get_battery_info().await?;
println!("gauge={} status={:?}", caps.percentage, info.status);
let events = feature.listen();
while let Ok(event) = events.recv().await {
println!("battery event: {event:?}");
}
}