Library Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib.rs
• src/platform/traits.rs
• src/platform/mod.rs
• src/types/mod.rs
• src/platform/linux/device.rs
• src/platform/windows/device.rs
• src/platform/darwin/iokit/power_source.rs
• src/platform/netbsd/device.rs

The rust-battery library 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 a consistent set of typed values, recalculated as necessary into SI measurement units.

Sources: src/lib.rs:1-10, README.md:20-25

Core Abstraction Layer

The library's architecture is built upon a set of traits that define the required behavior for any supported platform. This ensures that regardless of the underlying operating system, the consumer interacts with a standardized Manager, Batteries (iterator), and Battery type.

Architecture Overview

The following diagram illustrates the relationship between the public API types and the internal platform-specific implementations.

The Manager serves as the entry point for the library, responsible for discovering batteries and providing a way to refresh their state. The Batteries iterator yields Battery instances, which wrap the platform-specific BatteryDevice implementation.

Sources: src/platform/traits.rs:12-45, src/platform/mod.rs:1-35, src/types/mod.rs:1-10

Platform Implementation Pattern

Each platform implements the core traits by mapping OS-specific data structures to the internal BatteryDevice requirements.

Data Flow and Refresh Logic

When a battery is queried or refreshed, the following sequence occurs:

1. Discovery: The platform Manager searches for available power sources (e.g., scanning /sys/class/power_supply on Linux or using IOKit on macOS).
2. Initialization: A platform-specific device struct is created (e.g., SysFsDevice for Linux, PowerDevice for Windows).
3. Data Collection: The device implementation reads raw values from the OS.
4. Normalization: Raw values (often in micro-units like µWh or µV) are converted into uom (units of measurement) SI types.

Key Components and Data Structures

Abstraction Traits

The library defines three primary traits in src/platform/traits.rs that every platform must implement:

Trait	Description	Key Methods
BatteryManager	Entry point for battery discovery.	new(), refresh()
BatteryIterator	Handles iterating over system batteries.	new(manager)
BatteryDevice	Provides the actual telemetry data.	energy(), voltage(), state(), temperature()

Sources: src/platform/traits.rs:14-45

Normalized Data Types

The library uses the uom crate to ensure type safety for measurements. Common types found in platform implementations include:

• Energy: Typically read as microwatt_hour on Linux or milliwatt_hour on Windows.
• ElectricPotential: Read as microvolt or millivolt.
• Power: Represented as energy_rate, showing current consumption/charging speed.
• Ratio: Used for state_of_charge and state_of_health.

Sources: src/platform/linux/sysfs/source.rs:12-25, src/platform/windows/device.rs:12-25

Battery State and Technology

Enums are used to represent categorical battery data:

• State: Charging, Discharging, Empty, Full, or Unknown. Derived from strings like "Discharging" (Linux) or bitmasks (FreeBSD/Windows).
• Technology: LithiumIon, LeadAcid, NickelMetalHydride, etc.

Sources: src/types/technology.rs:9-20, src/platform/freebsd/acpi.rs:145-155

Platform Specifics

Linux (Sysfs)

Linux implementation relies on the sysfs filesystem. It uses a DataBuilder to collect information from multiple files in /sys/class/power_supply/, such as energy_now, voltage_now, and status.

Sources: src/platform/linux/sysfs/source.rs:30-100, src/platform/linux/sysfs/fs.rs:15-80

macOS (IOKit)

Uses objc2-io-kit and objc2-core-foundation to interface with the Apple IOKit framework. It queries properties using keys like kIOPMPSExternalConnectedKey and kIOPMPSCurrentCapacityKey.

Sources: src/platform/darwin/iokit/power_source.rs:15-60

Windows (IOCTL)

Utilizes windows-sys to perform DeviceIoControl calls. It uses a "tag" system (BATTERY_QUERY_INFORMATION) to identify and query specific battery hardware through the Windows Power Manager.

Sources: src/platform/windows/device.rs:12-40, src/platform/windows/ffi/ioctl/info.rs:10-50

Conclusion

The rust-battery architecture successfully decouples high-level battery telemetry from low-level OS implementation details through a rigorous trait system and standardized SI unit types. This allows developers to write platform-independent code for monitoring battery health and status while the library handles the complexities of hardware communication across Linux, Windows, macOS, and various BSD flavors.