hive_btle/phy/
mod.rs

1//! BLE PHY Configuration
2//!
3//! Configures physical layer parameters for BLE connections, including
4//! support for LE Coded PHY for extended range operations.
5//!
6//! ## Overview
7//!
8//! BLE 5.0 introduced multiple PHY options allowing applications to choose
9//! between range and throughput:
10//!
11//! | PHY | Data Rate | Range | Use Case |
12//! |-----|-----------|-------|----------|
13//! | LE 1M | 1 Mbps | ~100m | Default, good balance |
14//! | LE 2M | 2 Mbps | ~50m | High throughput |
15//! | LE Coded S=2 | 500 kbps | ~200m | Extended range |
16//! | LE Coded S=8 | 125 kbps | ~400m | Maximum range |
17//!
18//! ## Architecture
19//!
20//! ```text
21//! ┌────────────────────────────────────────────────────────┐
22//! │                    Application                          │
23//! │            (range/throughput requirements)              │
24//! └─────────────────────┬──────────────────────────────────┘
25//!                       │
26//!                       ▼
27//! ┌────────────────────────────────────────────────────────┐
28//! │                 PhyController                           │
29//! │  ┌──────────────┐  ┌────────────┐  ┌────────────────┐  │
30//! │  │  PhyStrategy │──│   RSSI     │──│    PHY         │  │
31//! │  │   (Adaptive) │  │  Monitor   │  │   Switch       │  │
32//! │  └──────────────┘  └────────────┘  └────────────────┘  │
33//! └─────────────────────┬──────────────────────────────────┘
34//!                       │
35//!                       ▼
36//! ┌────────────────────────────────────────────────────────┐
37//! │              BLE Controller (HCI)                       │
38//! │         LE Set PHY / PHY Update Procedure              │
39//! └────────────────────────────────────────────────────────┘
40//! ```
41//!
42//! ## Usage
43//!
44//! ### Fixed PHY
45//!
46//! ```ignore
47//! use hive_btle::phy::{PhyController, PhyStrategy, PhyCapabilities, BlePhy};
48//!
49//! let caps = PhyCapabilities::ble5_full();
50//! let mut ctrl = PhyController::with_defaults(caps);
51//!
52//! // Force maximum range mode
53//! ctrl.set_strategy(PhyStrategy::MaxRange);
54//! ```
55//!
56//! ### Adaptive PHY
57//!
58//! ```ignore
59//! use hive_btle::phy::{PhyController, PhyStrategy, PhyCapabilities};
60//!
61//! let caps = PhyCapabilities::ble5_full();
62//! let mut ctrl = PhyController::with_defaults(caps);
63//!
64//! // Adaptive selection based on RSSI
65//! ctrl.set_strategy(PhyStrategy::adaptive(-50, -75, 5));
66//!
67//! // Record RSSI samples
68//! if let Some(event) = ctrl.record_rssi(rssi, current_time) {
69//!     // Handle switch recommendation
70//! }
71//! ```
72//!
73//! ## Range Estimation
74//!
75//! Approximate relationship between RSSI and range for each PHY:
76//!
77//! | RSSI | LE 1M | LE 2M | Coded S=2 | Coded S=8 |
78//! |------|-------|-------|-----------|-----------|
79//! | -40 dBm | 10m | 5m | 20m | 40m |
80//! | -60 dBm | 30m | 15m | 60m | 120m |
81//! | -80 dBm | 80m | 40m | 160m | 320m |
82//! | -90 dBm | -- | -- | 200m | 400m |
83//!
84//! ## Hardware Requirements
85//!
86//! - LE 2M: BLE 5.0 hardware
87//! - LE Coded: BLE 5.0 hardware with Long Range support
88//! - Not all BLE 5.0 devices support Coded PHY
89
90pub mod controller;
91pub mod strategy;
92pub mod types;
93
94pub use controller::{
95    PhyController, PhyControllerConfig, PhyControllerEvent, PhyControllerState, PhyStats,
96    PhyUpdateResult,
97};
98pub use strategy::{evaluate_phy_switch, PhyStrategy, PhySwitchDecision};
99pub use types::{BlePhy, PhyCapabilities, PhyPreference};
hive_btle/phy/mod.rs

hive_btle/phy/
mod.rs
