hive_btle/sync/
mod.rs

1//! HIVE-Lite Sync Protocol
2//!
3//! Efficient CRDT synchronization over BLE GATT characteristics.
4//!
5//! ## Overview
6//!
7//! This module provides the sync layer for HIVE-Lite nodes, enabling
8//! efficient state synchronization over bandwidth-constrained BLE links.
9//!
10//! ## Key Components
11//!
12//! - **CRDTs**: Conflict-free replicated data types (LWW-Register, G-Counter)
13//! - **Batching**: Accumulates changes to reduce radio activity
14//! - **Delta Encoding**: Only sends changes since last sync
15//! - **Chunking**: Splits large messages across MTU boundaries
16//!
17//! ## Architecture
18//!
19//! ```text
20//! ┌────────────────────────────────────────────────────┐
21//! │                  Application                        │
22//! │    (position updates, health status, alerts)       │
23//! └─────────────────────┬──────────────────────────────┘
24//!                       │
25//!                       ▼
26//! ┌────────────────────────────────────────────────────┐
27//! │              GattSyncProtocol                       │
28//! │  ┌──────────────┐  ┌────────────┐  ┌────────────┐  │
29//! │  │    Batch     │  │   Delta    │  │  Chunked   │  │
30//! │  │ Accumulator  │─▶│  Encoder   │─▶│  Transfer  │  │
31//! │  └──────────────┘  └────────────┘  └────────────┘  │
32//! └─────────────────────┬──────────────────────────────┘
33//!                       │
34//!                       ▼
35//! ┌────────────────────────────────────────────────────┐
36//! │              GATT Characteristics                   │
37//! │           (Sync Data, Sync State)                  │
38//! └────────────────────────────────────────────────────┘
39//! ```
40//!
41//! ## Usage
42//!
43//! ```ignore
44//! use hive_btle::sync::{GattSyncProtocol, SyncConfig, CrdtOperation, Position};
45//! use hive_btle::NodeId;
46//!
47//! // Create sync protocol
48//! let mut sync = GattSyncProtocol::new(
49//!     NodeId::new(0x12345678),
50//!     SyncConfig::default(),
51//! );
52//!
53//! // Add a peer
54//! sync.add_peer(&peer_id);
55//!
56//! // Queue position update
57//! sync.queue_operation(CrdtOperation::UpdatePosition {
58//!     node_id: my_node_id,
59//!     position: Position::new(37.7749, -122.4194),
60//!     timestamp: current_time_ms,
61//! });
62//!
63//! // Check if time to sync
64//! if sync.should_sync() {
65//!     let chunks = sync.prepare_sync(&peer_id);
66//!     for chunk in chunks {
67//!         // Write chunk to GATT characteristic
68//!         gatt.write_sync_data(&chunk.encode());
69//!     }
70//! }
71//!
72//! // Process received data
73//! if let Some(ops) = sync.process_received(chunk, &peer_id) {
74//!     for op in ops {
75//!         // Apply CRDT operation to local state
76//!         apply_operation(op);
77//!     }
78//! }
79//! ```
80//!
81//! ## Power Efficiency
82//!
83//! The sync protocol is designed for constrained devices:
84//!
85//! | Feature | Benefit |
86//! |---------|---------|
87//! | Batching | Reduces sync frequency (less radio time) |
88//! | Delta Encoding | Sends only changes (less bytes) |
89//! | Configurable Intervals | Trade freshness for battery |
90//! | Compact CRDT Encoding | Minimal overhead |
91//!
92//! ## Sync Profiles
93//!
94//! ```ignore
95//! // For smartwatch (battery critical)
96//! let config = SyncConfig::low_power();
97//!
98//! // For tablet (responsiveness preferred)
99//! let config = SyncConfig::responsive();
100//! ```
101
102pub mod batch;
103pub mod crdt;
104pub mod delta;
105pub mod protocol;
106
107pub use batch::{BatchAccumulator, BatchConfig, OperationBatch};
108pub use crdt::{
109    CrdtOperation, EventType, GCounter, HealthStatus, LwwRegister, Peripheral, PeripheralEvent,
110    PeripheralType, Position, Timestamp,
111};
112pub use delta::{DeltaEncoder, DeltaStats, PeerSyncState, VectorClock};
113pub use protocol::{
114    chunk_data, ChunkHeader, ChunkReassembler, GattSyncProtocol, SyncChunk, SyncConfig, SyncState,
115    SyncStats, CHUNK_HEADER_SIZE, DEFAULT_MTU, MAX_MTU,
116};
hive_btle/sync/mod.rs

hive_btle/sync/
mod.rs
