Battery Type & Properties
Relevant source files
The following files were used as context for generating this wiki page:
The Battery type is the central representation of a notebook battery's state within the rust-battery ecosystem. It acts as a cross-platform wrapper that provides a unified API for accessing detailed information such as charge levels, energy rates, voltage, and physical properties. The primary goal of this module is to abstract OS-specific complexities and return values in standardized SI measurement units.
The architecture relies on a trait-based system where platform-specific implementations (e.g., Linux sysfs, Windows IOCTL, or NetBSD envsys) populate the data structures required by the high-level Battery struct.
Core Architecture and Data Flow
The Battery struct wraps an underlying Device type that must implement the BatteryDevice trait. This abstraction allows the library to present a consistent interface regardless of the host operating system.
The diagram shows the relationship between the public Battery struct and the internal platform-specific implementations via the BatteryDevice trait.
Sources: src/types/battery.rs:25-27, src/platform/traits.rs:43-118
Lifecycle and Refreshing
Battery data is represented as "instant" information. To update the values held within a Battery instance, the Manager::refresh method must be called, which invokes the platform-specific refresh logic.
Data Properties and SI Units
The library uses the uom (Units of Measurement) crate to ensure type safety and correct units for all physical quantities.
Electrical and Thermodynamic Properties
| Property | Type | Description |
|---|---|---|
state_of_charge | Ratio | Capacity as a percentage of maximum capacity (0.0 to 1.0). |
state_of_health | Ratio | Measure of condition relative to a fresh battery (0.0 to 1.0). |
energy | Energy | Amount of energy currently available (e.g., Joules or Watt-hours). |
energy_rate | Power | Rate of energy being drained or supplied. |
voltage | ElectricPotential | Current battery voltage. |
temperature | Option<ThermodynamicTemperature> | Battery temperature in Kelvin/Celsius. |
Sources: src/types/battery.rs:42-105, src/platform/traits.rs:44-71
Device Identification
Metadata about the battery hardware is retrieved as strings or specialized enums:
- Vendor/Manufacturer: The company that produced the battery.
- Model: The specific model name of the device.
- Serial Number: Unique identifier provided by the manufacturer.
- Technology: An enum representing the chemical composition (e.g., Lithium-Ion, Lead-Acid).
Sources: src/types/battery.rs:114-135, src/types/technology.rs:11-21
Technology and States
Battery Technology
The Technology enum defines the chemical nature of the battery. Different platforms map their internal strings (like "li-ion" or "NiMH") to these standardized values.
pub enum Technology {
Unknown,
LithiumIon,
LeadAcid,
LithiumPolymer,
NickelMetalHydride,
NickelCadmium,
NickelZinc,
LithiumIronPhosphate,
RechargeableAlkalineManganese,
}
Sources: src/types/technology.rs:11-21, src/platform/linux/sysfs/source.rs:319-325
State Definitions
The battery's current operational mode is captured by the State enum, which includes:
Charging: Energy is being added.Discharging: Energy is being consumed.Empty: Battery has no remaining charge.Full: Battery is at maximum capacity.Unknown: State cannot be determined by the OS.
Sources: src/platform/windows/ffi/ioctl/status.rs:65-72, src/platform/linux/sysfs/source.rs:280-286
Calculated Time Estimates
The library provides default implementations for estimating remaining run-time or charge-time based on the current energy_rate.
Time to Empty / Full Logic
If the platform does not provide hardware-level estimates, the following logic is applied:
- Time to Full: Calculated as
(energy_full - energy) / energy_ratewhile inChargingstate. It is capped at 10 hours; higher values returnNone. - Time to Empty: Calculated as
energy / energy_ratewhile inDischargingstate. It is capped at 10 days.
Sources: src/platform/traits.rs:88-124
Sources: src/platform/traits.rs:93-122
Platform Implementation Details
Different operating systems provide data via different mechanisms:
- Linux: Uses
sysfsfiles (e.g.,/sys/class/power_supply/). It handles many edge cases like missingenergy_full_designby falling back tocharge_full_designmultiplied by voltage. - Windows: Interacts with the kernel via
IOCTL_BATTERY_QUERY_INFORMATIONandIOCTL_BATTERY_QUERY_STATUS. - NetBSD: Utilizes the
envsysframework and parsesplistdata to populate device measurements.
Sources: src/platform/linux/sysfs/source.rs:163-176, src/platform/windows/device.rs:80-100, src/platform/netbsd/device.rs:141-168
Summary
The Battery type and its associated properties provide a high-level, safe, and typed interface to complex hardware data. By abstracting platform differences and enforcing SI unit conversions, it enables developers to build battery-aware applications that are portable across Windows, Linux, and BSD systems.