OpenLogi

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_capabilities0()BatteryCapabilities
get_battery_info1()BatteryInfo
listen事件()Receiver<BatteryEvent>

两个 getter 都是异步方法,返回 Result<…, Hidpp20Error>。 listen 是同步方法,来自 EmittingFeature<BatteryEvent>。

类型

BatteryCapabilities

字段类型说明
reported_levelsHashSet<BatteryLevel>固件会报告的电量等级变体。
rechargeablebool电池可以充电。
percentagebool设备有用于 BatteryInfo::charging_percentage 的 state-of-charge 表。

BatteryInfo

字段类型说明
charging_percentageu8原始状态字节 0。设备没有 state-of-charge 表时,此值为零。
levelBatteryLevel固件的粗略电量等级。
statusBatteryStatus固件的充电状态。

BatteryLevel

变体值说明
Critical1危急电量等级。
Low2低电量等级。
Good4正常电量等级。
Full8满电量等级。

BatteryStatus

变体值说明
Discharging0电池正在放电。
Charging1电池正在充电。
ChargingNearlyFull2电池处于最后充电阶段。
Full3电池已充满。
ChargingSlow4电池以低于正常的速率充电。
InvalidBattery5电池类型无效。
ThermalError6电池子系统报告温度错误。
ChargingError7电池子系统报告充电错误。

事件

BatteryEvent

变体负载说明
InfoUpdateBatteryInfo从事件 function 0 解码出的状态广播。

BatteryEvent::decode(function_id, payload) 仅接受 function 0。 遇到未知的等级值或状态值时,它返回 None。

线格式

两个请求负载均为 [0x00, 0x00, 0x00](没有参数)。

get_battery_capabilities(fn 0)

响应:

字节和位字段说明
0,bit 0reported_levels 包含 Critical设置时表示支持。
0,bit 1reported_levels 包含 Low设置时表示支持。
0,bit 2reported_levels 包含 Good设置时表示支持。
0,bit 3reported_levels 包含 Full设置时表示支持。
1,bit 0rechargeable设置时表示可以充电。
1,bit 1percentage存在 state-of-charge 表。

get_battery_info(fn 1)

响应:

字节字段说明
0charging_percentage原始 state of charge。仅当 capability 字节 1 的 bit 1 已设置时,将它当作百分比。
1levelBatteryLevel:1、2、4 或 8。
2statusBatteryStatus: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:?}");
    }
}

另见:0x1000 batteryStatus 和 0x1001 batteryVoltage。

本页目录