hive_btle/phy/
mod.rs

1// Copyright (c) 2025-2026 (r)evolve - Revolve Team LLC
2// SPDX-License-Identifier: Apache-2.0
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8//     http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16//! BLE PHY Configuration
17//!
18//! Configures physical layer parameters for BLE connections, including
19//! support for LE Coded PHY for extended range operations.
20//!
21//! ## Overview
22//!
23//! BLE 5.0 introduced multiple PHY options allowing applications to choose
24//! between range and throughput:
25//!
26//! | PHY | Data Rate | Range | Use Case |
27//! |-----|-----------|-------|----------|
28//! | LE 1M | 1 Mbps | ~100m | Default, good balance |
29//! | LE 2M | 2 Mbps | ~50m | High throughput |
30//! | LE Coded S=2 | 500 kbps | ~200m | Extended range |
31//! | LE Coded S=8 | 125 kbps | ~400m | Maximum range |
32//!
33//! ## Architecture
34//!
35//! ```text
36//! ┌────────────────────────────────────────────────────────┐
37//! │                    Application                          │
38//! │            (range/throughput requirements)              │
39//! └─────────────────────┬──────────────────────────────────┘
40//!                       │
41//!                       ▼
42//! ┌────────────────────────────────────────────────────────┐
43//! │                 PhyController                           │
44//! │  ┌──────────────┐  ┌────────────┐  ┌────────────────┐  │
45//! │  │  PhyStrategy │──│   RSSI     │──│    PHY         │  │
46//! │  │   (Adaptive) │  │  Monitor   │  │   Switch       │  │
47//! │  └──────────────┘  └────────────┘  └────────────────┘  │
48//! └─────────────────────┬──────────────────────────────────┘
49//!                       │
50//!                       ▼
51//! ┌────────────────────────────────────────────────────────┐
52//! │              BLE Controller (HCI)                       │
53//! │         LE Set PHY / PHY Update Procedure              │
54//! └────────────────────────────────────────────────────────┘
55//! ```
56//!
57//! ## Usage
58//!
59//! ### Fixed PHY
60//!
61//! ```ignore
62//! use hive_btle::phy::{PhyController, PhyStrategy, PhyCapabilities, BlePhy};
63//!
64//! let caps = PhyCapabilities::ble5_full();
65//! let mut ctrl = PhyController::with_defaults(caps);
66//!
67//! // Force maximum range mode
68//! ctrl.set_strategy(PhyStrategy::MaxRange);
69//! ```
70//!
71//! ### Adaptive PHY
72//!
73//! ```ignore
74//! use hive_btle::phy::{PhyController, PhyStrategy, PhyCapabilities};
75//!
76//! let caps = PhyCapabilities::ble5_full();
77//! let mut ctrl = PhyController::with_defaults(caps);
78//!
79//! // Adaptive selection based on RSSI
80//! ctrl.set_strategy(PhyStrategy::adaptive(-50, -75, 5));
81//!
82//! // Record RSSI samples
83//! if let Some(event) = ctrl.record_rssi(rssi, current_time) {
84//!     // Handle switch recommendation
85//! }
86//! ```
87//!
88//! ## Range Estimation
89//!
90//! Approximate relationship between RSSI and range for each PHY:
91//!
92//! | RSSI | LE 1M | LE 2M | Coded S=2 | Coded S=8 |
93//! |------|-------|-------|-----------|-----------|
94//! | -40 dBm | 10m | 5m | 20m | 40m |
95//! | -60 dBm | 30m | 15m | 60m | 120m |
96//! | -80 dBm | 80m | 40m | 160m | 320m |
97//! | -90 dBm | -- | -- | 200m | 400m |
98//!
99//! ## Hardware Requirements
100//!
101//! - LE 2M: BLE 5.0 hardware
102//! - LE Coded: BLE 5.0 hardware with Long Range support
103//! - Not all BLE 5.0 devices support Coded PHY
104
105pub mod controller;
106pub mod strategy;
107pub mod types;
108
109pub use controller::{
110    PhyController, PhyControllerConfig, PhyControllerEvent, PhyControllerState, PhyStats,
111    PhyUpdateResult,
112};
113pub use strategy::{evaluate_phy_switch, PhyStrategy, PhySwitchDecision};
114pub use types::{BlePhy, PhyCapabilities, PhyPreference};
hive_btle/phy/mod.rs

hive_btle/phy/
mod.rs
