Example: Full Data Dump
Relevant source files
The following files were used as context for generating this wiki page:
The "Full Data Dump" refers to the comprehensive collection and presentation of all available battery telemetry and metadata across supported operating systems. The rust-battery crate provides a unified interface to retrieve cross-platform information including state of charge, energy rates, voltage, temperature, and hardware details like vendor and model, all converted into SI measurement units.
Sources: src/lib.rs:1-10, README.md:23-28
System Architecture
The project employs a trait-based abstraction layer where platform-specific modules (Linux, macOS/iOS, Windows, BSDs) implement a common set of traits to expose battery data. The primary interface for users is the Manager and Battery types, which wrap these internal platform implementations.
Core Data Flow
The following diagram illustrates how raw system data is collected from different OS backends and transformed into the unified Battery type.
A brief overview of the flow: the Manager initializes the correct platform backend, which queries OS-specific APIs. This data is then encapsulated in a struct implementing BatteryDevice, ensuring the final consumer receives consistent SI-typed values.
Sources: src/platform/traits.rs:20-50, src/lib.rs:35-40
Battery Data Structures
The "Full Data Dump" is comprised of several technical metrics and metadata fields defined in the BatteryDevice trait. Each platform-specific device (e.g., SysFsDevice for Linux, PowerSource for Darwin, PowerDevice for Windows) must provide these values.
Metrics and Metadata
| Field | Type | Description |
|---|---|---|
state | State | Current battery status (Charging, Discharging, Full, etc.) |
energy | Energy | Current amount of energy in the battery |
energy_full | Energy | Amount of energy when battery is full |
energy_rate | Power | Instantaneous energy flow (input or output) |
voltage | ElectricPotential | Current battery voltage |
temperature | Option<ThermodynamicTemperature> | Battery temperature, if available |
cycle_count | Option<u32> | Number of charge/discharge cycles |
vendor | Option<&str> | Hardware manufacturer name |
Sources: src/platform/traits.rs:52-85, src/platform/linux/device.rs:88-144
Platform Implementation Details
Linux (sysfs)
Linux implementation relies on the /sys/class/power_supply/ filesystem. The DataBuilder collects metrics from various files like energy_now, power_now, and capacity.
The DataBuilder uses a LazyCell approach to cache calculations like state_of_health and state_of_charge until needed.
Sources: src/platform/linux/sysfs/source.rs:40-60, src/platform/linux/device.rs:28-50
macOS (IOKit)
Darwin platforms utilize IOKit to query a CFDictionary of battery properties.
Keys such as kIOPMPSVoltageKey (in mV) and kIOPMPSAmperageKey (in mA) are extracted and converted to SI units like ElectricPotential and ElectricCurrent.
Sources: src/platform/darwin/iokit/power_source.rs:50-80, src/platform/darwin/traits.rs:18-40
Windows (IOCTL)
Windows uses Device IO Control (IOCTL) codes to communicate with the battery driver via BATTERY_QUERY_INFORMATION and BATTERY_STATUS structures.
Sources: src/platform/windows/device.rs:60-85, src/platform/windows/ffi/ioctl/info.rs:50-70
NetBSD (envsys)
NetBSD implementation uses the envsys framework, parsing plist data to populate the EnvSysDevice and subsequent SysMonDevice.
Sources: src/platform/netbsd/device.rs:50-100
Calculations and Derived Data
The library performs internal calculations to provide a "full data dump" even when the OS doesn't provide specific fields directly. These are defined as default methods in the BatteryDevice trait.
Time Estimation
- Time to Full: Calculated as
(energy_full - energy) / energy_rateduring theChargingstate. - Time to Empty: Calculated as
energy / energy_rateduring theDischargingstate.
fn time_to_full(&self) -> Option<Time> {
let energy_rate = self.energy_rate();
match self.state() {
State::Charging if !energy_rate.is_zero() => {
let energy_left = self.energy_full() - self.energy();
Some(energy_left / energy_rate)
}
_ => None,
}
}
Sources: src/platform/traits.rs:104-142
Health and Charge Ratios
- State of Health (SOH):
energy_full / energy_full_design, bounded between 0.0 and 1.0. - State of Charge (SOC):
energy / energy_full, bounded between 0.0 and 1.0.
Sources: src/platform/traits.rs:53-62