OpenLogi

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

FunctionHID++ fnSignatureReturns
get_battery_capabilities0()BatteryCapabilities
get_battery_info1()BatteryInfo
listenevent()Receiver<BatteryEvent>

The two getter methods are async and return Result<…, Hidpp20Error>. listen is synchronous and comes from EmittingFeature<BatteryEvent>.

Types

BatteryCapabilities

FieldTypeDescription
reported_levelsHashSet<BatteryLevel>Firmware level variants that the feature reports.
rechargeableboolBattery can recharge.
percentageboolDevice has a state-of-charge gauge for BatteryInfo::charging_percentage.

BatteryInfo

FieldTypeDescription
charging_percentageu8Raw status byte 0. It is zero when the device has no state-of-charge gauge.
levelBatteryLevelFirmware coarse battery bucket.
statusBatteryStatusFirmware charging status.

BatteryLevel

VariantValueDescription
Critical1Critical battery level.
Low2Low battery level.
Good4Good battery level.
Full8Full battery level.

BatteryStatus

VariantValueDescription
Discharging0Battery is discharging.
Charging1Battery is charging.
ChargingNearlyFull2Battery is charging in its final stage.
Full3Battery charge is complete.
ChargingSlow4Battery is recharging below its normal rate.
InvalidBattery5Battery type is invalid.
ThermalError6Battery subsystem reported a thermal error.
ChargingError7Battery subsystem reported a charging error.

Events

BatteryEvent

VariantPayloadDescription
InfoUpdateBatteryInfoStatus 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 bitFieldNotes
0, bit 0reported_levels contains CriticalSet when supported.
0, bit 1reported_levels contains LowSet when supported.
0, bit 2reported_levels contains GoodSet when supported.
0, bit 3reported_levels contains FullSet when supported.
1, bit 0rechargeableSet when rechargeable.
1, bit 1percentageState-of-charge gauge is present.

get_battery_info (fn 1)

Response:

ByteFieldNotes
0charging_percentageRaw state of charge. Treat as a percentage only when capabilities byte 1, bit 1 is set.
1levelBatteryLevel: 1, 2, 4, or 8.
2statusBatteryStatus: 0–7.
3external-power statusLogi Options+ exposes it. OpenLogi ignores it. Options+ 2.8
4fast-charge statusPresent for feature version 4 or later. OpenLogi ignores it. Options+ 2.8
5removable-battery statusPresent 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.

On this page