Battery State & Technology

Relevant source files

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

• src/types/state.rs
• src/types/technology.rs
• src/types/battery.rs
• src/platform/traits.rs
• src/platform/linux/sysfs/source.rs
• src/platform/windows/ffi/ioctl/status.rs
• src/platform/windows/ffi/ioctl/info.rs
• src/platform/netbsd/device.rs

The battery crate provides a unified, cross-platform abstraction for representing the physical and operational characteristics of notebook batteries. At the core of this abstraction are the State and Technology types, which categorize the current activity (e.g., charging, discharging) and the chemical composition of the battery hardware. Sources: src/lib.rs:1-10, src/types/battery.rs:43-90

This module ensures that raw data from various operating systems—such as Linux sysfs strings, Windows IOCTL flags, and NetBSD plist values—is normalized into strongly-typed Enums. This allows developers to write platform-independent code for monitoring battery health and power status. Sources: src/types/state.rs, src/types/technology.rs, src/platform/traits.rs

Battery Operational State

The State enum represents the current activity or status of a battery device. It is marked as #[non_exhaustive] to allow for future additions as hardware capabilities evolve. Sources: src/types/state.rs:7-9

Available States

State	Description
Unknown	The battery state cannot be determined or is not reported by the driver.
Charging	The battery is currently being charged by an external power source.
Discharging	The battery is providing power to the system and losing charge.
Empty	The battery is completely discharged or has reached a critical low level.
Full	The battery is fully charged and may or may not be connected to AC.

Sources: src/types/state.rs:11-22

Platform-Specific Mapping

Each supported platform maps its internal representation to the battery::State enum:

• Linux (sysfs): Reads the status file in the device directory. Sources: src/platform/linux/sysfs/source.rs:252-258
• Windows (IOCTL): Evaluates bitwise flags from BATTERY_STATUS. Logic determines state based on BATTERY_CHARGING, BATTERY_DISCHARGING, BATTERY_CRITICAL, and BATTERY_POWER_ON_LINE. Sources: src/platform/windows/ffi/ioctl/status.rs:56-66
• NetBSD: Derived from the charging value (1 for Charging, 0 for Discharging) and compared against energy thresholds to identify Full or Empty states. Sources: src/platform/netbsd/device.rs:159-174

The diagram shows how disparate platform-specific data sources are unified into a single State enum. Sources: src/platform/traits.rs, src/platform/linux/sysfs/source.rs:252-258, src/platform/windows/ffi/ioctl/status.rs:56-66

Battery Technology

The Technology enum defines the chemical composition of the battery. Similar to State, it is #[non_exhaustive] and implements FromStr for parsing from various system-provided strings. Sources: src/types/technology.rs:7-22

Chemical Classifications

The library recognizes several common battery technologies:

• Lithium-based: LithiumIon, LithiumPolymer, LithiumIronPhosphate.
• Nickel-based: NickelMetalHydride, NickelCadmium, NickelZinc.
• Other: LeadAcid, RechargeableAlkalineManganese, and Unknown.

Sources: src/types/technology.rs:11-21

Technology Identification Logic

The Technology implementation includes a robust parser that handles various common abbreviations used by different OS drivers (e.g., "Li-ion", "lion", "pb", "lipo"). Sources: src/types/technology.rs:27-46

The class diagram illustrates the relationship between the main Battery type and the categorization enums. Sources: src/types/battery.rs:80-90, src/types/state.rs:10, src/types/technology.rs:10

Integration with Battery Device Traits

Operational state and technology are accessed via the BatteryDevice trait, which platform-specific structures must implement. Sources: src/platform/traits.rs:43-70

Default Implementations and Logic

The BatteryDevice trait provides default logic for calculating derived values based on the current state:

• Time to Full: Calculated only when the state() is Charging. It uses the difference between energy_full() and current energy() divided by the energy_rate(). Sources: src/platform/traits.rs:82-95
• Time to Empty: Calculated only when the state() is Discharging. It divides current energy() by the energy_rate(). Sources: src/platform/traits.rs:108-115

Logic flow for calculating remaining time based on the battery's operational state. Sources: src/platform/traits.rs:80-125

Implementation Example: Windows Technology Detection

On Windows, the battery technology is extracted from the Chemistry field of the BATTERY_INFORMATION structure. The raw bytes are converted to a UTF-8 string and then parsed into the Technology enum. Sources: src/platform/windows/ffi/ioctl/info.rs:65-71

pub fn technology(&self) -> Technology {
    let raw = String::from_utf8_lossy(&self.0.Chemistry);
    match Technology::from_str(&raw) {
        Ok(tech) => tech,
        Err(_) => Technology::Unknown,
    }
}

Sources: src/platform/windows/ffi/ioctl/info.rs:65-71

Conclusion

The "Battery State & Technology" components serve as the primary semantic layer of the battery crate. By abstracting away the low-level string parsing and bit-flag manipulation required by different kernels, the library provides a reliable and type-safe interface for monitoring notebook power hardware. Sources: src/types/battery.rs, src/platform/traits.rs