pamoja_power/lib.rs
1#![cfg_attr(not(test), no_std)]
2
3//! Power-aware scheduling for the pamoja SDK.
4//!
5//! A node on a battery or a solar panel lives or dies by how much it sleeps. This
6//! crate holds the scheduling math that keeps such a node alive, with no runtime
7//! and no hardware assumptions, so the same decisions can be made on a
8//! microcontroller and verified on a server:
9//!
10//! - [`DutyCycle`] - trade wakefulness for battery life with a repeating
11//! wake/sleep schedule, and read back the duty fraction as a power proxy.
12//! - [`PowerPlan`] - an energy-aware governor that stretches the sampling interval
13//! as the battery drains, picking a [`PowerMode`] from the state of charge and
14//! easing off when the panel is charging.
15//!
16//! The state of charge fed to a [`PowerPlan`] is noisy in the field. Its
17//! [`next_mode`](PowerPlan::next_mode) keeps a node from flapping between modes at a
18//! threshold: it drops to a lower mode at the threshold but climbs back only once the
19//! charge clears the threshold by the plan's hysteresis margin. Smoothing the charge
20//! first, for example with a `Smoother` from `pamoja-kit`, steadies it further.
21//!
22//! The crate is `no_std` and allocation-free.
23//!
24//! # Examples
25//!
26//! ```
27//! use core::time::Duration;
28//! use pamoja_power::{PowerMode, PowerPlan};
29//!
30//! let plan = PowerPlan::new(
31//! Duration::from_secs(60), // sample each minute when healthy
32//! Duration::from_secs(600), // back off to ten minutes to conserve
33//! Duration::from_secs(3600), // once an hour when critically low
34//! );
35//!
36//! assert_eq!(plan.mode(0.8), PowerMode::Active);
37//! assert_eq!(plan.interval(0.1), Duration::from_secs(3600));
38//! ```
39
40mod duty;
41mod plan;
42
43pub use duty::DutyCycle;
44pub use plan::{PowerMode, PowerPlan, DEFAULT_HYSTERESIS};