Serialization & Schema
Relevant source files
The following files were used as context for generating this wiki page:
The rust-battery crate provides optional support for data serialization and schema generation for its core battery types. This functionality is primarily designed to allow battery information to be easily exported to other formats (such as JSON) or used in configuration systems where structural validation is required.
The system leverages the serde framework for serialization and the schemars crate for generating JSON schemas. These features are encapsulated behind the config-schema feature flag, ensuring that users who do not require serialization do not incur the overhead of these dependencies.
Sources: Cargo.toml:19-20, CHANGELOG.md:83-85
Configuration and Dependencies
Serialization and schema features are optional and must be enabled via the crate's feature flags. The config-schema feature acts as a gateway that enables both serde and schemars.
| Feature | Dependency | Purpose |
|---|---|---|
config-schema | N/A | Enables serialization and schema generation for battery types. |
serde | serde v1.0 | Provides the Serialize and Deserialize traits for data structures. |
schemars | schemars v1 | Generates JSON Schema documents from Rust types. |
Sources: Cargo.toml:19-20, Cargo.toml:24-25, CHANGELOG.md:18-20
Data Models and Schemas
The primary types that support serialization are the State and Technology enums. These represent the operational status of the battery and its chemical composition, respectively.
Battery State
The State enum represents the current charging status of the battery. It implements serialization traits when the relevant features are enabled.
pub enum State {
Unknown,
Charging,
Discharging,
Empty,
Full,
}
Sources: src/types/state.rs:11-18, CHANGELOG.md:83-85
Battery Technology
The Technology enum defines the chemical makeup of the battery. It supports string-based representation which is used during platform-specific data collection (e.g., parsing sysfs strings on Linux or IOCTL chemistry strings on Windows).
| Technology | Internal String Identifiers |
|---|---|
LithiumIon | "li-i", "li-ion", "lion" |
LeadAcid | "pb", "pbac" |
LithiumPolymer | "lip", "lipo", "li-poly" |
NickelMetalHydride | "nimh" |
NickelCadmium | "nicd" |
Sources: src/types/technology.rs:24-37, src/platform/windows/ffi/ioctl/info.rs:64-67
Data Flow Architecture
The serialization system sits at the end of the data acquisition pipeline. Platform-specific builders collect raw data from the OS (sysfs, IOKit, or IOCTL), convert them into typed quantities using the uom crate, and then populate the internal structures that can be serialized.
The diagram shows how raw platform data is converted into SI-compliant typed values before being available for serialization.
Sources: src/platform/linux/sysfs/source.rs:56-70, src/platform/netbsd/device.rs:136-155, Cargo.toml:19-20
Implementation Details
Serialization in Changelog History
The project has undergone several iterations to improve serialization support. Significant milestones include:
- v0.8.0: Initial implementation of
serdeandschemarsfor theStateenum to allow its use in configuration-heavy environments like thestarshipprompt. - v0.10.3: Migration to
schemarsv1 to maintain compatibility with modern Rust ecosystem tools.
Sources: CHANGELOG.md:18-20, CHANGELOG.md:83-85
Platform Mapping to Schemas
When platform-specific data is collected, it is mapped to the common schema. For instance, on Windows, the BATTERY_INFORMATION structure's Chemistry field is mapped to the Technology enum, which then follows the standard serialization path.
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:64-70
Summary
Serialization and schema support in rust-battery provide a bridge between raw hardware data and high-level application requirements. By using serde and schemars behind the config-schema feature, the library maintains its performance-oriented core while offering the flexibility needed for modern Rust applications to validate and export battery telemetry.