OpenLogi

0x1000 · batteryStatus

Legacy battery state with a discharge reading, a next threshold, and a charging status for devices without unifiedBattery.

batteryStatus is the legacy battery source for devices such as MX Master 2S. It reports a charge reading, the next lower threshold, and a charging status. OpenLogi selects it when 0x1004 unifiedBattery is absent.

Spec: Logitech HID++ 2.0 — x1000 batteryStatus. Cross-checked: Logi Options+ 2.8 (static analysis), Linux HID++ driver, Solaar. Used by: device inventory and openlogi list.

Function reference

BatteryStatusFeature (0x1000) implements one request method.

Methods

FunctionHID++ fnSignatureReturns
get_battery_level_status0()LegacyBatteryInfo
is_status_broadcastevent helper(function_id: u8)bool

get_battery_level_status is async and returns Result<LegacyBatteryInfo, Hidpp20Error>. The wrapper does not implement getBatteryCapability (function 1).

Types

LegacyBatteryInfo

FieldTypeDescription
discharge_levelu8Charge reading while status is Discharging. Firmware reports coarse steps. A zero in another state means unknown.
next_levelu8Next lower charge step the firmware will report.
statusLegacyBatteryStatusCurrent battery charging status.

LegacyBatteryStatus

VariantValueDescription
Discharging0Battery is discharging.
Recharging1Battery is recharging.
AlmostFull2Battery is charging and nearly full.
Full3Battery charge is complete.
SlowRecharge4Battery is recharging below its normal rate.
InvalidBattery5Battery type is invalid.
ThermalError6Battery subsystem reported a thermal error.
Other7Other charging error. Inventory maps it to an unknown status.

Events

This wrapper does not implement EmittingFeature or expose a typed event. is_status_broadcast(function_id) returns true only for function 0.

Wire format

get_battery_level_status (fn 0)

Request: [0x00, 0x00, 0x00] (no parameters).

Response:

ByteFieldNotes
0discharge_levelCoarse charge reading. 0 is a valid empty reading while discharging. It means unknown in an off-battery state.
1next_levelNext lower charge step.
2statusLegacyBatteryStatus: 0–7 as listed above.

The wrapper rejects a status value outside 0–7 with Hidpp20Error::UnsupportedResponse.

getBatteryCapability (fn 1, not implemented)

Logi Options+ reads this response. OpenLogi does not send this function.

ByteFieldNotes
0number of levelsNumber of firmware charge levels. Options+ 2.8
1capability flagsIncludes disable-OSD, mileage, and rechargeable information. Individual bit assignments are not documented here. Options+ 2.8
2–3nominal battery lifeu16, BE. Options+ 2.8
4critical levelFirmware critical-level value. Options+ 2.8

Status broadcast (event fn 0)

An unsolicited function-0 report carries the same three bytes as get_battery_level_status. It announces a changed reading or charging state.

How OpenLogi uses it

Inventory prefers 0x1004, then 0x1000, then 0x1001, then 0x1F20. OpenLogi maps a discharging reading to a percentage and a local level bucket.

Since v0.8.14, PR #1768 maps an off-battery zero to no percentage. It maps Full with a zero reading to 100% and Full. Other off-battery zero readings become an unknown level.

OpenLogi does not read function 1. It therefore uses fixed 0–19, 20–49, 50–89, and 90–100 display buckets. Those buckets do not use the device capability's level count or mileage flag.

Since v0.8.14, PR #1787 records this feature's runtime index. An unsolicited software-ID-0, function-0 report queues one coalesced inventory reconciliation. OpenLogi re-reads the authoritative state instead of trusting the event payload.

OpenLogi only reads this feature.

Usage (Rust)

use hidpp::{
    device::Device,
    feature::battery_status::BatteryStatusFeature,
};

// `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::<BatteryStatusFeature>() {
    let info = feature.get_battery_level_status().await?;
    println!("level={} status={:?}", info.discharge_level, info.status);
}

See also: 0x1001 batteryVoltage and 0x1004 unifiedBattery.

On this page