peat_btle/mesh/
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//! Mesh Topology Management
17//!
18//! This module provides mesh topology management for PEAT-BTLE, including:
19//!
20//! - **Topology tracking**: Parent/child/peer relationships
21//! - **Connection management**: Connect, disconnect, failover
22//! - **Message routing**: Upward aggregation, downward dissemination
23//! - **RSSI-based selection**: Best parent/peer selection
24//!
25//! ## Architecture
26//!
27//! ```text
28//! ┌─────────────────────────────────────────────────────────┐
29//! │                    MeshManager                           │
30//! │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
31//! │  │  Topology   │  │   Router    │  │  Parent Failover │  │
32//! │  │   State     │  │             │  │                  │  │
33//! │  └─────────────┘  └─────────────┘  └─────────────────┘  │
34//! └─────────────────────────────────────────────────────────┘
35//!                          │
36//!                          ▼
37//!            ┌──────────────────────────────┐
38//!            │     TopologyEvents           │
39//!            │  • ParentConnected           │
40//!            │  • ChildConnected            │
41//!            │  • TopologyChanged           │
42//!            └──────────────────────────────┘
43//! ```
44//!
45//! ## Usage
46//!
47//! ```ignore
48//! use peat_btle::mesh::{MeshManager, TopologyConfig, TopologyEvent};
49//! use peat_btle::{NodeId, HierarchyLevel};
50//!
51//! // Create mesh manager
52//! let manager = MeshManager::new(
53//!     NodeId::new(0x12345678),
54//!     HierarchyLevel::Platform,
55//!     TopologyConfig::default(),
56//! );
57//!
58//! // Register for topology events
59//! manager.on_topology_event(Box::new(|event| {
60//!     match event {
61//!         TopologyEvent::ParentConnected { node_id, .. } => {
62//!             println!("Connected to parent: {}", node_id);
63//!         }
64//!         _ => {}
65//!     }
66//! }));
67//!
68//! // Start the manager
69//! manager.start()?;
70//!
71//! // Process discovered beacons
72//! manager.process_beacon(&beacon, rssi);
73//!
74//! // Select and connect to best parent
75//! if let Some(candidate) = manager.select_best_parent() {
76//!     manager.connect_parent(candidate.node_id, candidate.level, candidate.rssi)?;
77//! }
78//! ```
79//!
80//! ## Parent Failover
81//!
82//! When parent connection is lost:
83//!
84//! 1. `start_failover()` is called
85//! 2. Manager enters `Failover` state
86//! 3. `ParentFailoverStarted` event is emitted
87//! 4. Application scans for new parent candidates
88//! 5. `complete_failover()` connects to new parent (or gives up)
89//! 6. `ParentFailoverCompleted` event is emitted
90//!
91//! ## Message Routing
92//!
93//! The `MeshRouter` provides routing decisions:
94//!
95//! - **Upward**: To parent (aggregation)
96//! - **Downward**: To children (dissemination)
97//! - **Broadcast**: To all connected peers
98//! - **Targeted**: To a specific node
99//!
100//! ```ignore
101//! use peat_btle::mesh::{MeshRouter, RouteDirection};
102//!
103//! let router = MeshRouter::new(node_id, my_level);
104//! let topology = manager.topology();
105//!
106//! let decision = router.route(RouteDirection::Upward, &topology);
107//! if decision.routed {
108//!     for next_hop in decision.next_hops {
109//!         send_to(&next_hop, &message);
110//!     }
111//! }
112//! ```
113
114#[cfg(feature = "std")]
115mod manager;
116mod routing;
117mod topology;
118
119#[cfg(feature = "std")]
120pub use manager::{ManagerState, MeshManager, TopologyCallback};
121pub use routing::{HopTracker, MeshRouter, RouteDecision, RouteDirection, RouteFailure};
122pub use topology::{
123    ConnectionState, DisconnectReason, MeshTopology, ParentCandidate, PeerInfo, PeerRole,
124    TopologyConfig, TopologyEvent,
125};
peat_btle/mesh/mod.rs

peat_btle/mesh/
mod.rs
