aranet_core/
lib.rs

1#![deny(unsafe_code)]
2
3//! Core BLE library for Aranet environmental sensors.
4//!
5//! This crate provides low-level Bluetooth Low Energy (BLE) communication
6//! with Aranet sensors including the Aranet4, Aranet2, AranetRn+ (Radon), and
7//! Aranet Radiation devices.
8//!
9//! # Features
10//!
11//! - **Device discovery**: Scan for nearby Aranet devices via BLE
12//! - **Current readings**: CO₂, temperature, pressure, humidity, radon, radiation
13//! - **Historical data**: Download measurement history with timestamps
14//! - **Device settings**: Read/write measurement interval, Bluetooth range
15//! - **Auto-reconnection**: Configurable backoff and retry logic
16//! - **Real-time streaming**: Subscribe to sensor value changes
17//! - **Multi-device support**: Manage multiple sensors simultaneously
18//!
19//! # Supported Devices
20//!
21//! | Device | Sensors |
22//! |--------|---------|
23//! | Aranet4 | CO₂, Temperature, Pressure, Humidity |
24//! | Aranet2 | Temperature, Humidity |
25//! | AranetRn+ | Radon (Bq/m³), Temperature, Pressure, Humidity |
26//! | Aranet Radiation | Dose Rate (µSv/h), Total Dose (mSv) |
27//!
28//! # Platform Differences
29//!
30//! Device identification varies by platform due to differences in BLE implementations:
31//!
32//! - **macOS**: Devices are identified by a UUID assigned by CoreBluetooth. This UUID
33//!   is stable for a given device on a given Mac, but differs between Macs. The UUID
34//!   is not the same as the device's MAC address.
35//!
36//! - **Linux/Windows**: Devices are identified by their Bluetooth MAC address
37//!   (e.g., `AA:BB:CC:DD:EE:FF`). This is consistent across machines.
38//!
39//! When storing device identifiers for reconnection, be aware that:
40//! - On macOS, the UUID may change if Bluetooth is reset or the device is unpaired
41//! - Cross-platform applications should store both the device name and identifier
42//! - The [`Device::address()`] method returns the appropriate identifier for the platform
43//!
44//! # Quick Start
45//!
46//! ```no_run
47//! use aranet_core::{Device, scan};
48//!
49//! #[tokio::main]
50//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
51//!     // Scan for devices
52//!     let devices = scan::scan_for_devices().await?;
53//!     println!("Found {} devices", devices.len());
54//!
55//!     // Connect to a device
56//!     let device = Device::connect("Aranet4 12345").await?;
57//!
58//!     // Read current values
59//!     let reading = device.read_current().await?;
60//!     println!("CO2: {} ppm", reading.co2);
61//!
62//!     // Read device info
63//!     let info = device.read_device_info().await?;
64//!     println!("Serial: {}", info.serial);
65//!
66//!     Ok(())
67//! }
68//! ```
69
70pub mod advertisement;
71#[cfg(target_os = "linux")]
72pub mod bluez_agent;
73pub mod commands;
74pub mod device;
75pub mod diagnostics;
76pub mod error;
77pub mod events;
78pub mod guard;
79pub mod history;
80pub mod manager;
81pub mod messages;
82pub mod metrics;
83pub mod mock;
84pub mod passive;
85pub mod platform;
86pub mod readings;
87pub mod reconnect;
88pub mod retry;
89pub mod scan;
90pub mod settings;
91pub mod streaming;
92pub mod thresholds;
93pub mod traits;
94pub mod util;
95pub mod validation;
96
97#[cfg(feature = "service-client")]
98pub mod service_client;
99
100// Re-export types and uuid modules from aranet-types for backwards compatibility
101pub use aranet_types::types;
102pub use aranet_types::uuid;
103
104// Core exports
105pub use device::{ConnectionConfig, Device, SignalQuality};
106pub use error::{ConnectionFailureReason, DeviceNotFoundReason, Error, Result};
107pub use history::{
108    HistoryCheckpoint, HistoryInfo, HistoryOptions, HistoryParam, PartialHistoryData,
109};
110pub use readings::ExtendedReading;
111pub use scan::{
112    DiscoveredDevice, FindProgress, ProgressCallback, ScanOptions, find_device_with_progress,
113    scan_with_retry,
114};
115pub use settings::{BluetoothRange, CalibrationData, DeviceSettings, MeasurementInterval};
116pub use traits::AranetDevice;
117
118/// Type alias for a shared device reference.
119///
120/// This is the recommended way to share a `Device` across multiple tasks.
121/// Since `Device` intentionally does not implement `Clone` (to prevent
122/// connection ownership ambiguity), wrapping it in `Arc` is the standard
123/// pattern for concurrent access.
124///
125/// # Choosing the Right Device Type
126///
127/// This crate provides several device types for different use cases:
128///
129/// | Type | Use Case | Auto-Reconnect | Thread-Safe |
130/// |------|----------|----------------|-------------|
131/// | [`Device`] | Single command, short-lived | No | Yes (via Arc) |
132/// | [`ReconnectingDevice`] | Long-running apps | Yes | Yes |
133/// | [`SharedDevice`] | Sharing Device across tasks | No | Yes |
134/// | [`DeviceManager`] | Managing multiple devices | Yes | Yes |
135///
136/// ## Decision Guide
137///
138/// ### Use [`Device`] when:
139/// - Running a single command (read, history download)
140/// - Connection lifetime is short and well-defined
141/// - You'll handle reconnection yourself
142///
143/// ```no_run
144/// # async fn example() -> aranet_core::Result<()> {
145/// use aranet_core::Device;
146/// let device = Device::connect("Aranet4 12345").await?;
147/// let reading = device.read_current().await?;
148/// device.disconnect().await?;
149/// # Ok(())
150/// # }
151/// ```
152///
153/// ### Use [`ReconnectingDevice`] when:
154/// - Building a long-running application (daemon, service)
155/// - You want automatic reconnection on connection loss
156/// - Continuous monitoring over extended periods
157///
158/// ```no_run
159/// # async fn example() -> aranet_core::Result<()> {
160/// use aranet_core::{AranetDevice, ReconnectingDevice, ReconnectOptions};
161/// let options = ReconnectOptions::default();
162/// let device = ReconnectingDevice::connect("Aranet4 12345", options).await?;
163/// // Will auto-reconnect on connection loss
164/// let reading = device.read_current().await?;
165/// # Ok(())
166/// # }
167/// ```
168///
169/// ### Use [`SharedDevice`] when:
170/// - Sharing a single [`Device`] across multiple async tasks
171/// - You need concurrent reads but want one connection
172///
173/// ```no_run
174/// # async fn example() -> aranet_core::Result<()> {
175/// use aranet_core::{Device, SharedDevice};
176/// use std::sync::Arc;
177///
178/// let device = Device::connect("Aranet4 12345").await?;
179/// let shared: SharedDevice = Arc::new(device);
180///
181/// let shared_clone = Arc::clone(&shared);
182/// tokio::spawn(async move {
183///     let reading = shared_clone.read_current().await;
184/// });
185/// # Ok(())
186/// # }
187/// ```
188///
189/// ### Use [`DeviceManager`] when:
190/// - Managing multiple devices simultaneously
191/// - Need centralized connection/disconnection handling
192/// - Building a multi-device monitoring application
193///
194/// ```no_run
195/// # async fn example() -> aranet_core::Result<()> {
196/// use aranet_core::DeviceManager;
197/// let manager = DeviceManager::new();
198/// manager.add_device("AA:BB:CC:DD:EE:FF").await?;
199/// manager.add_device("11:22:33:44:55:66").await?;
200/// // Manager handles connections for all devices
201/// # Ok(())
202/// # }
203/// ```
204pub type SharedDevice = std::sync::Arc<Device>;
205
206// New module exports
207pub use advertisement::{AdvertisementData, parse_advertisement, parse_advertisement_with_name};
208pub use commands::{
209    HISTORY_V1_REQUEST, HISTORY_V2_REQUEST, SET_BLUETOOTH_RANGE, SET_INTERVAL, SET_SMART_HOME,
210};
211pub use diagnostics::{
212    AdapterInfo, AdapterState, BluetoothDiagnostics, ConnectionStats, DiagnosticsCollector,
213    ErrorCategory, OperationStats, RecordedError, global_diagnostics,
214};
215pub use events::{DeviceEvent, EventReceiver, EventSender};
216pub use guard::{DeviceGuard, SharedDeviceGuard};
217pub use manager::{AdaptiveInterval, DeviceManager, DevicePriority, ManagedDevice, ManagerConfig};
218pub use messages::{CachedDevice, Command, SensorEvent};
219pub use metrics::{ConnectionMetrics, OperationMetrics};
220pub use mock::{MockDevice, MockDeviceBuilder};
221pub use passive::{PassiveMonitor, PassiveMonitorOptions, PassiveReading};
222pub use platform::{
223    AliasStore, DeviceAlias, Platform, PlatformConfig, current_platform, platform_config,
224};
225pub use reconnect::{ReconnectOptions, ReconnectingDevice};
226pub use retry::{RetryConfig, with_retry};
227pub use streaming::{ReadingStream, StreamOptions, StreamOptionsBuilder};
228pub use thresholds::{Co2Level, ThresholdConfig, Thresholds};
229pub use util::{create_identifier, format_peripheral_id};
230pub use validation::{ReadingValidator, ValidationResult, ValidationWarning};
231
232// Re-export from aranet-types
233pub use aranet_types::uuid as uuids;
234pub use aranet_types::{CurrentReading, DeviceInfo, DeviceType, HistoryRecord, Status};
aranet_core/lib.rs

aranet_core/
lib.rs
