battery_estimator/
lib.rs

1//! # Battery SOC (State of Charge) Estimator
2//!
3//! A lightweight, zero-dependency, `no_std` compatible Rust library for estimating
4//! battery state-of-charge (SOC) from voltage measurements. Designed specifically
5//! for embedded systems and microcontrollers.
6//!
7//! ## Features
8//!
9//! - **Minimal dependencies** - Only depends on `thiserror` for error handling
10//! - **`no_std` compatible** - Works in embedded environments
11//! - **No heap allocations** - Uses only stack memory and fixed-size arrays
12//! - **Multiple battery chemistries** - Built-in support for LiPo, LiFePO4, Li-Ion
13//! - **Temperature compensation** - Correct SOC readings based on temperature
14//! - **Aging compensation** - Adjust for battery capacity degradation over time
15//! - **Custom voltage curves** - Define your own voltage-SOC relationships
16//! - **Conservative battery curves** - Extended battery life with conservative thresholds
17//!
18//! ## Quick Start
19//!
20//! ```rust
21//! use battery_estimator::{BatteryChemistry, SocEstimator};
22//!
23//! // Create estimator for a standard LiPo battery
24//! let estimator = SocEstimator::new(BatteryChemistry::LiPo);
25//!
26//! // Estimate SOC at 3.7V (nominal voltage)
27//! match estimator.estimate_soc(3.7) {
28//!     Ok(soc) => println!("Battery SOC: {:.1}%", soc),
29//!     Err(e) => println!("Error estimating SOC: {}", e),
30//! }
31//! ```
32//!
33//! ## Battery Types
34//!
35//! The library supports multiple battery chemistries with built-in voltage curves:
36//!
37//! | Type | Full Charge | Cutoff | Description |
38//! |------|-------------|--------|-------------|
39//! | `LiPo` | 4.2V | 3.2V | Standard Lithium Polymer |
40//! | `LiFePO4` | 3.65V | 3.0V | Lithium Iron Phosphate (long cycle life) |
41//! | `LiIon` | 4.2V | 3.3V | Standard Lithium Ion |
42//! | `Lipo410Full340Cutoff` | 4.1V | 3.4V | Conservative LiPo (extended life) |
43//!
44//! ## Temperature Compensation
45//!
46//! ```rust
47//! use battery_estimator::{BatteryChemistry, SocEstimator};
48//!
49//! // Create estimator with temperature compensation
50//! let estimator = SocEstimator::with_temperature_compensation(
51//!     BatteryChemistry::LiPo,
52//!     25.0,  // Nominal temperature (°C)
53//!     0.0005 // Temperature coefficient
54//! );
55//!
56//! // Estimate SOC with current temperature
57//! match estimator.estimate_soc_compensated(3.7, 20.0) {
58//!     Ok(soc) => println!("Temperature-compensated SOC: {:.1}%", soc),
59//!     Err(e) => println!("Error: {}", e),
60//! }
61//! ```
62//!
63//! ## Custom Voltage Curves
64//!
65//! ```rust
66//! use battery_estimator::{SocEstimator, Curve, CurvePoint};
67//!
68//! // Define a custom voltage-SOC curve
69//! const CUSTOM_CURVE: Curve = Curve::new(&[
70//!     CurvePoint::new(3.0, 0.0),   // 3.0V = 0%
71//!     CurvePoint::new(3.5, 50.0),  // 3.5V = 50%
72//!     CurvePoint::new(4.0, 100.0), // 4.0V = 100%
73//! ]);
74//!
75//! // Create estimator with custom curve
76//! let estimator = SocEstimator::with_custom_curve(&CUSTOM_CURVE);
77//! ```
78//! ## Module Structure
79//!
80//! - [`SocEstimator`] - Main estimator struct for SOC calculations
81//! - [`BatteryChemistry`] - Supported battery types
82//! - [`Curve`] - Voltage-SOC curve representation
83//! - [`CurvePoint`] - Individual voltage-SOC data point
84//! - [`Error`] - Error types for estimation failures
85//! - [`compensate_temperature`] - Temperature compensation function
86//! - [`compensate_aging`] - Aging compensation function
87
88#![no_std]
89#![deny(missing_docs, unsafe_code)]
90
91mod compensation;
92mod curve;
93mod error;
94mod estimator;
95mod types;
96
97pub use compensation::{
98    compensate_aging, compensate_temperature, default_temperature_compensation,
99};
100pub use curve::{default_curves, Curve};
101pub use error::Error;
102pub use estimator::SocEstimator;
103pub use types::{BatteryChemistry, CurvePoint};
104
105/// Prelude module for convenient imports
106///
107/// This module re-exports the most commonly used types and traits,
108/// allowing you to import them with a single `use` statement:
109///
110/// ```rust
111/// use battery_estimator::prelude::*;
112///
113/// let estimator = SocEstimator::new(BatteryChemistry::LiPo);
114/// ```
115pub mod prelude {
116    pub use crate::{BatteryChemistry, CurvePoint, Error, SocEstimator};
117}
battery_estimator/lib.rs

battery_estimator/
lib.rs
