Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
The battery crate provides a cross-platform, unified API for accessing notebook battery information. Its primary purpose is to abstract away OS-specific interfaces (such as Linux SysFS, macOS IOKit, or Windows IOCTL) and provide typed, SI-compliant measurement units for battery state, charge, energy rate, voltage, and temperature.
Sources: README.md:21-25, src/lib.rs:1-5
Installation
To use the crate, ensure you are using Rustc version 1.89 or greater. Add the dependency to your Cargo.toml:
[dependencies]
battery = "0.8.3"
Sources: README.md:43-51, Cargo.toml:13
Basic Usage
The entry point for the library is the Manager struct. It is used to discover and iterate over batteries available on the system.
Initialization and Iteration
- Create a Manager: Instantiate
battery::Manager. - Access Batteries: Call
.batteries()to get an iterator over available power sources. - Handle Results: Each item in the iterator is a
Result<Battery, Error>.
fn main() -> Result<(), battery::Error> {
let manager = battery::Manager::new()?;
for (idx, maybe_battery) in manager.batteries()?.enumerate() {
let battery = maybe_battery?;
println!("Battery #{}:", idx);
println!("Vendor: {:?}", battery.vendor());
println!("State: {:?}", battery.state());
}
Ok(())
}
Sources: README.md:55-68, src/lib.rs:25
Component Architecture
The following diagram illustrates how the Manager interacts with platform-specific implementations to provide a unified Battery interface.
The library uses a trait-based system where BatteryDevice defines the required behavior for different operating systems.
Sources: src/platform/traits.rs:43-57, src/platform/mod.rs:1-30
Working with Battery Data
The Battery struct provides various methods to retrieve telemetry data. Most numerical values are returned as types from the uom crate, ensuring SI measurement units.
Key Data Methods
| Method | Return Type | Description |
|---|---|---|
state() | State | Current battery status (Charging, Discharging, etc.) |
state_of_charge() | Ratio | The current charge level (0.0 to 1.0) |
energy_rate() | Power | Current power flow (Watts) |
voltage() | ElectricPotential | Current battery voltage |
technology() | Technology | Chemistry type (e.g., Lithium Ion) |
cycle_count() | Option<u32> | Number of charge cycles |
Sources: src/platform/traits.rs:44-77, src/types/technology.rs:8-18
Using Measurement Units
Because the library re-exports uom quantities, you must specify the unit when extracting raw values from types like Energy or Power.
use starship_battery::units::energy::watt_hour;
use starship_battery::units::ratio::percent;
// Get energy in Watt-hours instead of Joules
let energy_wh = battery.energy().get::<watt_hour>();
// Get state of charge as a percentage
let percentage = battery.state_of_charge().get::<percent>();
Sources: src/units.rs:10-38
Supported Battery States and Technologies
The library categorizes battery status and chemistry into exhaustive enums.
Battery State
The State enum represents the current activity of the battery, such as Charging, Discharging, Empty, Full, or Unknown.
Sources: src/lib.rs:25, src/platform/traits.rs:85-115
Battery Technology
| Technology | Description |
|---|---|
LithiumIon | Common Li-ion batteries |
LithiumPolymer | Li-Po batteries |
NickelMetalHydride | NiMH batteries |
LeadAcid | Pb batteries |
Sources: src/types/technology.rs:8-18
Platform Abstraction Flow
The following sequence diagram shows the internal flow when a user requests battery information.
Summary
To get started with the battery crate, developers should initialize a Manager, iterate through the results of the batteries() method, and use the provided SI-typed methods to access specific telemetry. The crate handles the complexity of different OS file systems and API calls, providing a consistent interface regardless of the target platform.