wayle_battery/lib.rs
1//! Battery monitoring via UPower D-Bus interface.
2//!
3//! # Quick Start
4//!
5//! ```rust,no_run
6//! use wayle_battery::BatteryService;
7//!
8//! # async fn example() -> Result<(), wayle_battery::Error> {
9//! let service = BatteryService::new().await?;
10//!
11//! // Access battery state
12//! let percentage = service.device.percentage.get();
13//! let state = service.device.state.get();
14//!
15//! println!("Battery: {percentage}% ({state})");
16//! # Ok(())
17//! # }
18//! ```
19//!
20//! # Reactive Properties
21//!
22//! All device properties are wrapped in [`Property<T>`](wayle_core::Property):
23//! - **Snapshot**: `.get()` returns the current value
24//! - **Stream**: `.watch()` yields on every change
25//!
26//! ```rust,no_run
27//! # use wayle_battery::BatteryService;
28//! # use futures::StreamExt;
29//! # async fn example() -> Result<(), wayle_battery::Error> {
30//! # let service = BatteryService::new().await?;
31//! // React to state changes
32//! let mut state_stream = service.device.state.watch();
33//! while let Some(new_state) = state_stream.next().await {
34//! println!("State changed: {new_state}");
35//! }
36//! # Ok(())
37//! # }
38//! ```
39//!
40//! # DisplayDevice vs Specific Devices
41//!
42//! By default, [`BatteryService::new`] monitors UPower's DisplayDevice - a composite
43//! that aggregates all batteries. For specific device monitoring:
44//!
45//! ```rust,no_run
46//! # use wayle_battery::BatteryService;
47//! use zbus::zvariant::OwnedObjectPath;
48//!
49//! # async fn example() -> Result<(), wayle_battery::Error> {
50//! let path = OwnedObjectPath::try_from("/org/freedesktop/UPower/devices/battery_BAT0")?;
51//! let service = BatteryService::builder()
52//! .device_path(path)
53//! .build()
54//! .await?;
55//! # Ok(())
56//! # }
57//! ```
58//!
59//! # Control Methods
60//!
61//! The [`Device`](core::device::Device) type exposes UPower operations:
62//! - [`refresh`](core::device::Device::refresh) - Force data refresh from hardware
63//! - [`get_history`](core::device::Device::get_history) - Historical charge/rate data
64//! - [`get_statistics`](core::device::Device::get_statistics) - Charge/discharge statistics
65//! - [`enable_charge_threshold`](core::device::Device::enable_charge_threshold) - Battery charge limiting
66
67mod builder;
68/// Core battery device functionality.
69pub mod core;
70mod error;
71mod proxy;
72mod service;
73/// Type definitions for battery service domain models and enums.
74pub mod types;
75
76pub use builder::BatteryServiceBuilder;
77pub use error::Error;
78pub use service::BatteryService;
79
80#[doc = include_str!("../README.md")]
81#[cfg(doctest)]
82pub struct ReadmeDocTests;