0x1004 · unifiedBattery
Unified battery capability and status feature with a state-of-charge gate and live battery-change events.
unifiedBattery is OpenLogi's preferred battery source.
It reports supported level buckets, a state-of-charge capability, and current battery status.
The device can also push a status event.
Spec: Logitech HID++ 2.0 — x1004 unifiedBattery. Cross-checked: Logi Options+ 2.8 (static analysis), Linux HID++ driver, Solaar. Used by: device inventory and
openlogi list.
Function reference
UnifiedBatteryFeature (0x1004) provides two reads and an event listener.
Methods
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_battery_capabilities | 0 | () | BatteryCapabilities |
get_battery_info | 1 | () | BatteryInfo |
listen | event | () | Receiver<BatteryEvent> |
The two getter methods are async and return Result<…, Hidpp20Error>.
listen is synchronous and comes from EmittingFeature<BatteryEvent>.
Types
BatteryCapabilities
| Field | Type | Description |
|---|---|---|
reported_levels | HashSet<BatteryLevel> | Firmware level variants that the feature reports. |
rechargeable | bool | Battery can recharge. |
percentage | bool | Device has a state-of-charge gauge for BatteryInfo::charging_percentage. |
BatteryInfo
| Field | Type | Description |
|---|---|---|
charging_percentage | u8 | Raw status byte 0. It is zero when the device has no state-of-charge gauge. |
level | BatteryLevel | Firmware coarse battery bucket. |
status | BatteryStatus | Firmware charging status. |
BatteryLevel
| Variant | Value | Description |
|---|---|---|
Critical | 1 | Critical battery level. |
Low | 2 | Low battery level. |
Good | 4 | Good battery level. |
Full | 8 | Full battery level. |
BatteryStatus
| Variant | Value | Description |
|---|---|---|
Discharging | 0 | Battery is discharging. |
Charging | 1 | Battery is charging. |
ChargingNearlyFull | 2 | Battery is charging in its final stage. |
Full | 3 | Battery charge is complete. |
ChargingSlow | 4 | Battery is recharging below its normal rate. |
InvalidBattery | 5 | Battery type is invalid. |
ThermalError | 6 | Battery subsystem reported a thermal error. |
ChargingError | 7 | Battery subsystem reported a charging error. |
Events
BatteryEvent
| Variant | Payload | Description |
|---|---|---|
InfoUpdate | BatteryInfo | Status broadcast decoded from event function 0. |
BatteryEvent::decode(function_id, payload) accepts only function 0.
It returns None for an unknown level or status value.
Wire format
Both request payloads are [0x00, 0x00, 0x00] (no parameters).
get_battery_capabilities (fn 0)
Response:
| Byte and bit | Field | Notes |
|---|---|---|
| 0, bit 0 | reported_levels contains Critical | Set when supported. |
| 0, bit 1 | reported_levels contains Low | Set when supported. |
| 0, bit 2 | reported_levels contains Good | Set when supported. |
| 0, bit 3 | reported_levels contains Full | Set when supported. |
| 1, bit 0 | rechargeable | Set when rechargeable. |
| 1, bit 1 | percentage | State-of-charge gauge is present. |
get_battery_info (fn 1)
Response:
| Byte | Field | Notes |
|---|---|---|
| 0 | charging_percentage | Raw state of charge. Treat as a percentage only when capabilities byte 1, bit 1 is set. |
| 1 | level | BatteryLevel: 1, 2, 4, or 8. |
| 2 | status | BatteryStatus: 0–7. |
| 3 | external-power status | Logi Options+ exposes it. OpenLogi ignores it. Options+ 2.8 |
| 4 | fast-charge status | Present for feature version 4 or later. OpenLogi ignores it. Options+ 2.8 |
| 5 | removable-battery status | Present for feature version 5 or later. OpenLogi ignores it. Options+ 2.8 |
OpenLogi does not preserve these read-only tail bytes. It has no writer for this feature and therefore writes no fixed values.
InfoUpdate event (event fn 0)
The device sends an unsolicited function-0 report when battery information changes.
The event has the same status layout as function 1.
BatteryEvent parses bytes 0–2 only.
OpenLogi ignores bytes 3–5 on an event.
How OpenLogi uses it
Inventory selects 0x1004 before every other battery source.
After the feature-table walk, it reads capabilities once and memoizes the state-of-charge flag.
When the state-of-charge flag is clear, inventory sets its public percentage to None.
The firmware level remains the authoritative display value.
If the capability read fails, OpenLogi temporarily assumes a percentage, marks capabilities incomplete, and retries on the next reconciliation.
PR #1788 shipped in v0.8.14.
It fixed the prior treatment of an unsupported state-of-charge byte as 0%.
The persistent inventory listener accepts an unsolicited software-ID-0 event only when bytes 0–2 decode.
It queues one coalesced authoritative reconciliation.
The wrapper's listen() remains available for direct crate users.
OpenLogi only reads this feature. It does not model external power, fast charging, removable batteries, or version-gated tail lengths.
Open questions
Linux labels status values 2 and 4 differently from the current OpenLogi names.
Logi Options+ preserves the numeric values but its recovered enum names are incomplete.
OpenLogi uses ChargingNearlyFull for 2 and ChargingSlow for 4.
The extended status fields are supported by static analysis, not hardware capture. Their value sets remain unverified.
Usage (Rust)
use hidpp::{
device::Device,
feature::{EmittingFeature, unified_battery::UnifiedBatteryFeature},
};
// `channel` and `device_index` identify an already opened HID++ device.
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:?}");
}
}See also: 0x1000 batteryStatus and 0x1001 batteryVoltage.