Supported Platforms
Relevant source files
The following files were used as context for generating this wiki page:
The battery crate is a cross-platform library designed to provide unified access to notebook battery information across various operating systems. Its primary objective is to wrap OS-specific interfaces and legacy hacks into a consistent API that returns values in SI measurement units.
Sources: README.md:21-25, src/lib.rs:1-5
The project achieves this through a modular architecture where platform-specific implementations are abstracted behind common traits. The library currently supports the following platforms:
- Linux: Kernel 2.6.39+
- MacOS: 10.10+
- Windows: 7+
- iOS: Using IOKit bindings
- FreeBSD
- DragonFlyBSD
- NetBSD
Sources: README.md:31-40, src/lib.rs:11-17
Platform Abstraction Layer
The library uses conditional compilation (cfg-if) to map generic types like Manager, Iterator, and Device to their platform-specific counterparts.
The diagram above illustrates how the high-level Manager wraps a platform-specific implementation.
Sources: src/platform/mod.rs:1-38, src/types/manager.rs:27-50
Core Traits
Every platform implementation must satisfy three primary traits defined in src/platform/traits.rs:
| Trait | Responsibility |
|---|---|
BatteryManager | Handles system-level discovery and refreshing of devices. |
BatteryIterator | Manages the enumeration of available battery devices. |
BatteryDevice | Provides the actual telemetry data (energy, voltage, state, etc.). |
Sources: src/platform/traits.rs:14-41
Linux Implementation
The Linux backend utilizes the sysfs filesystem, specifically looking for devices under the /sys/class/power_supply/ directory.
Architecture
The SysFsDevice identifies valid batteries by checking if the type file contains "Battery" and the scope file contains "System". It uses a DataBuilder to lazily collect and cache information from various sysfs files.
Sources: src/platform/linux/device.rs:25-34, src/platform/linux/sysfs/source.rs:46-60
Data Retrieval Logic
The implementation includes logic to handle inconsistent driver reports, such as:
- Falling back to
charge_now * design_voltageifenergy_nowis missing. - Sanity checking
energy_rate(ignoring values > 100W or "Ones" ACPI values). - Ignoring
cycle_countif it is reported as zero, as some drivers default to zero for old batteries.
Sources: src/platform/linux/sysfs/source.rs:135-144, src/platform/linux/sysfs/source.rs:185-230, src/platform/linux/sysfs/source.rs:282-293
Windows Implementation
The Windows backend is built upon the windows-sys crate and communicates with battery devices using IOCTL (Input/Output Control) requests.
Sources: src/platform/windows/device.rs:11-13, Cargo.toml:47-60
Architecture
It utilizes the Windows Power Management API to query battery information and status. The PowerDevice struct maintains a tag (BATTERY_QUERY_INFORMATION) required for subsequent refreshes of a specific device.
| Component | Description |
|---|---|
BatteryInformation | Wraps BATTERY_INFORMATION struct; provides technology and capacity. |
BatteryStatus | Wraps BATTERY_STATUS struct; provides voltage, rate, and state. |
DeviceHandle | Manages the file handle to the battery device for IOCTL calls. |
Sources: src/platform/windows/ffi/ioctl/info.rs:11-20, src/platform/windows/device.rs:60-91
MacOS and iOS Implementation
The Darwin-based implementation relies on the IOKit framework to access the I/O Registry.
Data Extraction
The library queries the IOPMPowerSource service. On Apple Silicon (M-series) chips, it specifically prefers AppleRawMaxCapacity and AppleRawCurrentCapacity because the standard keys may return percentages instead of mAh.
Sources: src/platform/darwin/iokit/power_source.rs:22-30, src/platform/darwin/iokit/power_source.rs:55-66
The flow shows how property dictionaries from IOKit are transformed into internal data structures.
Sources: src/platform/darwin/iokit/power_source.rs:75-120
BSD Variants (NetBSD/FreeBSD)
NetBSD
NetBSD support is implemented via the envsys (Environmental Systems) ioctl interface. It specifically supports the acpibat battery driver.
Sources: src/platform/netbsd/device.rs:17-27
The implementation parses plist data returned by the kernel. It maps NetBSD-specific units like "Ampere hour" or "Watt hour" into the crate's internal Energy types. It also handles specific NetBSD behaviors, such as setting the state to Empty when energy is zero, even if the driver doesn't explicitly report it.
Sources: src/platform/netbsd/device.rs:135-155, src/platform/netbsd/device.rs:168-175
FreeBSD and DragonFlyBSD
These platforms use the nix crate to perform ioctl calls for battery telemetry. They support multiple devices and map OS-specific states to the unified State enum.
Sources: src/lib.rs:26-27, CHANGELOG.md:129-130
Summary of Platform Support
| Feature | Linux | Windows | MacOS | NetBSD |
|---|---|---|---|---|
| Source | SysFS | IOCTL | IOKit | EnvSys/Plist |
| Technology | Parsed string | Chemistry string | N/A | Unknown |
| Cycle Count | Supported | Supported | Supported | Not Provided |
| Temp | Supported | Supported | Supported | Not Provided |
Sources: src/platform/linux/device.rs:115-158, src/platform/windows/device.rs:114-150, src/platform/darwin/iokit/power_source.rs:163-210, src/platform/netbsd/device.rs:204-245
This multi-platform architecture ensures that users of the battery crate, such as the starship prompt, can access reliable battery data regardless of the underlying operating system.
Sources: README.md:75-80