combustion_rust_ble/lib.rs
1// Allow holding locks across await points - we use parking_lot which is designed for this
2#![allow(clippy::await_holding_lock)]
3// Allow derivable impls for clarity
4#![allow(clippy::derivable_impls)]
5// Allow unusual byte groupings for UUIDs which have standard format
6#![allow(clippy::unusual_byte_groupings)]
7
8//! # combustion-rust-ble
9//!
10//! A cross-platform Rust library for communicating with Combustion Inc's
11//! Predictive Thermometer probes via Bluetooth Low Energy.
12//!
13//! This library specifically targets **Predictive Probes** (ProductType 1).
14//! Other Combustion devices (Display, Booster, MeatNet Repeater, Giant Grill Gauge)
15//! are intentionally ignored during discovery.
16//!
17//! ## Features
18//!
19//! - **Probe Discovery**: Automatically discover nearby Predictive Probes
20//! - **Real-time Temperatures**: Read all 8 sensors in real-time
21//! - **Virtual Sensors**: Computed Core, Surface, and Ambient temperatures
22//! - **Temperature Logging**: Download complete temperature history
23//! - **Prediction Engine**: Set target temperatures and get time predictions
24//! - **Food Safety**: SafeCook/USDA Safe compliance monitoring
25//! - **Multi-probe Support**: Manage up to 8 probes simultaneously
26//!
27//! ## Quick Start
28//!
29//! ```rust,no_run
30//! use combustion_rust_ble::{DeviceManager, Result};
31//!
32//! #[tokio::main]
33//! async fn main() -> Result<()> {
34//! // Create device manager and start scanning
35//! let manager = DeviceManager::new().await?;
36//! manager.start_scanning().await?;
37//!
38//! // Wait for probes to be discovered
39//! tokio::time::sleep(std::time::Duration::from_secs(5)).await;
40//!
41//! // Get all discovered probes
42//! for (id, probe) in manager.probes() {
43//! println!("Found probe: {} ({})", probe.serial_number_string(), id);
44//!
45//! // Read current temperatures
46//! let temps = probe.current_temperatures();
47//! let virtual_temps = probe.virtual_temperatures();
48//!
49//! if let Some(core) = virtual_temps.core {
50//! println!(" Core temperature: {:.1}°C", core);
51//! }
52//! }
53//!
54//! manager.shutdown().await?;
55//! Ok(())
56//! }
57//! ```
58//!
59//! ## Using an existing btleplug adapter
60//!
61//! If your application already holds a `btleplug::platform::Adapter`, pass it to
62//! [`DeviceManager::with_adapter`] instead of calling [`DeviceManager::new`]. The
63//! crate re-exports `btleplug` so the adapter type always matches.
64//!
65//! ## Platform Notes
66//!
67//! ### macOS
68//! Requires Bluetooth permission. Add `NSBluetoothAlwaysUsageDescription`
69//! to your Info.plist for bundled apps.
70//!
71//! ### Linux
72//! Requires BlueZ. User may need to be in the `bluetooth` group.
73//!
74//! ### Windows
75//! Requires Windows 10 or later with Bluetooth LE support.
76//!
77//! ## Feature Flags
78//!
79//! - `serde`: Enable serialization/deserialization for data types
80
81/// The btleplug version this crate is built against.
82///
83/// Use it when handing an existing adapter to [`DeviceManager::with_adapter`] so the
84/// `Adapter` type is guaranteed to match.
85pub use btleplug;
86
87// Public modules
88pub mod ble;
89pub mod data;
90pub mod device_manager;
91pub mod error;
92pub mod probe;
93pub mod protocol;
94pub mod utils;
95
96// Re-exports for convenience
97pub use device_manager::{DeviceManager, DisconnectedProbeEvent, DiscoveredProbeEvent, MAX_PROBES};
98pub use error::{Error, Result};
99pub use probe::{CallbackHandle, Probe};
100pub use utils::{celsius_to_fahrenheit, fahrenheit_to_celsius};
101
102// Re-export commonly used types from submodules
103pub use ble::advertising::{BatteryStatus, Overheating, ProbeColor, ProbeId, ProbeMode};
104pub use ble::connection::ConnectionState;
105pub use ble::scanner::ScanMode;
106pub use data::{
107 AlarmConfig, AlarmStatus, FoodSafeConfig, FoodSafeData, FoodSafeMode, FoodSafeProduct,
108 FoodSafeServingState, FoodSafeState, FoodSafeStatus, IntegratedProduct, LoggedDataPoint,
109 PowerMode, PredictionInfo, PredictionLog, PredictionMode, PredictionState, PredictionType,
110 ProbeTemperatures, RawTemperature, Serving, SessionInfo, SimplifiedProduct, TemperatureLog,
111 ThermometerPreferences, VirtualSensorSelection, VirtualTemperatures,
112};
113
114#[cfg(test)]
115mod tests {
116 use super::*;
117
118 #[test]
119 fn test_public_exports() {
120 // Verify that key types are exported
121 let _ = std::any::TypeId::of::<DeviceManager>();
122 let _ = std::any::TypeId::of::<Probe>();
123 let _ = std::any::TypeId::of::<Error>();
124 let _ = std::any::TypeId::of::<ProbeTemperatures>();
125 let _ = std::any::TypeId::of::<VirtualTemperatures>();
126 let _ = std::any::TypeId::of::<PredictionInfo>();
127 let _ = std::any::TypeId::of::<FoodSafeData>();
128 }
129
130 #[test]
131 fn test_temperature_conversion() {
132 assert!((celsius_to_fahrenheit(100.0) - 212.0).abs() < 0.001);
133 assert!((fahrenheit_to_celsius(212.0) - 100.0).abs() < 0.001);
134 }
135}