/rust-battery

Rust crate providing cross-platform information about the notebook batteries.

Primary LanguageRustApache License 2.0Apache-2.0

battery

Latest Version Latest Version Build Status Minimum rustc version Apache 2.0 OR MIT licensed Backers on Open Collective Sponsors on Open Collective

Rust crate providing cross-platform information about the notebook batteries.

Table of contents

Overview

battery provides a cross-platform unified API to a notebook batteries state.

Its main goal is to wrap the OS-specific interfaces, cover all the hacks and legacy cases and get the batteries information (such as state of charge, energy rate, voltage and temperature) as a typed values, recalculated as necessary to be returned as a SI measurement units.

Supported platforms

  • Linux 2.6.39+
  • MacOS 10.10+
  • iOS
  • Windows 7+
  • FreeBSD
  • DragonFlyBSD

Do note that iOS implementation uses IOKit bindings, your application might be automatically rejected by Apple based on that fact. Use it on your own risk.

Install

As a prerequisite, battery crate requires at least Rustc version 1.36 or greater.

Add the following line into a Cargo.toml:

[dependencies]
battery = "0.7.8"

Examples

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!("Model: {:?}", battery.model());
        println!("State: {:?}", battery.state());
        println!("Time to full charge: {:?}", battery.time_to_full());
        println!("");
    }

    Ok(())
}

See the battery/examples/ folder in the repository for additional examples.

FFI bindings

Experimental battery-ffi crate provides the FFI bindings to the battery crate, so it can be used with other languages, such as C, Python or NodeJS.

Check its README and documentation for details.

Users

This an incomplete list of the battery crate users. If you are using it too, send me a message and I'll add your project here!

battop

battop is an interactive viewer, similar to top, htop and other *top utilities, but about the batteries installed in your notebook.
It is using the battery crate API to show the batteries information in your terminal.

starship

starship is a Rust port of the minimalistic, powerful, and extremely customizable prompt Spaceship ZSH.
It is using the battery crate to show the the current battery level and status in a shell prompt.

Here is what @matchai says:

I really appreciate how easily we were able to get your library up and running! Battery APIs were a headache for us in predecessors of this project 😅

And there is this tweet also!

License

Licensed under either of Apache License 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Donations

If you appreciate my work and want to support me, you can do it here or support this project at Open Collective.

Contributors

This project exists thanks to all the people who contribute.

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]