Crate hive_btle

Crate hive_btle 

Source
Expand description

HIVE-BTLE: Bluetooth Low Energy mesh transport for HIVE Protocol

This crate provides BLE-based peer-to-peer mesh networking for HIVE, supporting discovery, advertisement, connectivity, and HIVE-Lite sync.

§Overview

HIVE-BTLE implements the pluggable transport abstraction (ADR-032) for Bluetooth Low Energy, enabling HIVE Protocol to operate over BLE in resource-constrained environments like smartwatches.

§Key Features

  • Cross-platform: Linux, Android, macOS, iOS, Windows, ESP32
  • Power efficient: Designed for 18+ hour battery life on watches
  • Long range: Coded PHY support for 300m+ range
  • HIVE-Lite sync: Optimized CRDT sync over GATT

§Architecture

┌─────────────────────────────────────────────────┐
│                  Application                     │
├─────────────────────────────────────────────────┤
│           BluetoothLETransport                   │
│  (implements MeshTransport from ADR-032)        │
├─────────────────────────────────────────────────┤
│              BleAdapter Trait                    │
├──────────┬──────────┬──────────┬────────────────┤
│  Linux   │ Android  │  Apple   │    Windows     │
│ (BlueZ)  │  (JNI)   │(CoreBT)  │    (WinRT)     │
└──────────┴──────────┴──────────┴────────────────┘

§Quick Start

ⓘ
use hive_btle::{BleConfig, BluetoothLETransport, NodeId};

// Create HIVE-Lite optimized config for battery efficiency
let config = BleConfig::hive_lite(NodeId::new(0x12345678));

// Create transport with platform adapter
#[cfg(feature = "linux")]
let adapter = hive_btle::platform::linux::BluerAdapter::new()?;

let transport = BluetoothLETransport::new(config, adapter);

// Start advertising and scanning
transport.start().await?;

// Connect to a peer
let conn = transport.connect(&peer_id).await?;

§Feature Flags

  • std (default): Standard library support
  • linux: Linux/BlueZ support via bluer
  • android: Android support via JNI
  • macos: macOS support via CoreBluetooth
  • ios: iOS support via CoreBluetooth
  • windows: Windows support via WinRT
  • embedded: Embedded/no_std support
  • coded-phy: Enable Coded PHY for extended range
  • extended-adv: Enable extended advertising

§External Crate Usage (hive-ffi)

This crate exports platform adapters for use by external crates like hive-ffi. Each platform adapter is conditionally exported based on feature flags:

# In your Cargo.toml
[dependencies]
hive-btle = { version = "0.0.5", features = ["linux"] }

Then use the appropriate adapter:

ⓘ
use hive_btle::{BleConfig, BluerAdapter, HiveMesh, NodeId};

// Platform adapter is automatically available via feature flag
let adapter = BluerAdapter::new().await?;
let config = BleConfig::hive_lite(NodeId::new(0x12345678));

§Platform → Adapter Mapping

FeatureTargetAdapter Type
linuxLinuxBluerAdapter
androidAndroidAndroidAdapter
macosmacOSCoreBluetoothAdapter
iosiOSCoreBluetoothAdapter
windowsWindowsWinRtBleAdapter

§Document Encoding for Translation Layer

For translating between Automerge (full HIVE) and hive-btle documents:

ⓘ
use hive_btle::HiveDocument;

// Decode bytes received from BLE
let doc = HiveDocument::from_bytes(&received_bytes)?;

// Encode for BLE transmission
let bytes = doc.to_bytes();

§Power Profiles

ProfileDuty CycleWatch Battery
Aggressive20%~6 hours
Balanced10%~12 hours
LowPower2%~20+ hours
  • ADR-039: HIVE-BTLE Mesh Transport Crate
  • ADR-032: Pluggable Transport Abstraction
  • ADR-035: HIVE-Lite Embedded Nodes
  • ADR-037: Resource-Constrained Device Optimization

Re-exports§

pub use config::BleConfig;
pub use config::BlePhy;
pub use config::DiscoveryConfig;
pub use config::GattConfig;
pub use config::MeshConfig;
pub use config::PowerProfile;
pub use config::DEFAULT_MESH_ID;
pub use discovery::Scanner;
pub use discovery::Advertiser;
pub use discovery::HiveBeacon;
pub use discovery::ScanFilter;
pub use error::BleError;
pub use error::Result;
pub use gatt::HiveGattService;
pub use gatt::SyncProtocol;
pub use mesh::MeshManager;
pub use mesh::MeshRouter;
pub use mesh::MeshTopology;
pub use mesh::TopologyConfig;
pub use mesh::TopologyEvent;
pub use phy::PhyCapabilities;
pub use phy::PhyController;
pub use phy::PhyStrategy;
pub use platform::BleAdapter;
pub use platform::ConnectionEvent;
pub use platform::DisconnectReason;
pub use platform::DiscoveredDevice;
pub use platform::StubAdapter;
pub use platform::linux::BluerAdapter;
pub use platform::mock::MockBleAdapter;
pub use power::BatteryState;
pub use power::RadioScheduler;
pub use power::SyncPriority;
pub use sync::GattSyncProtocol;
pub use sync::SyncConfig;
pub use sync::SyncState;
pub use transport::BleConnection;
pub use transport::BluetoothLETransport;
pub use transport::MeshTransport;
pub use transport::TransportCapabilities;
pub use document::HiveDocument;
pub use document::MergeResult;
pub use document::ENCRYPTED_MARKER;
pub use document::EXTENDED_MARKER;
pub use document::KEY_EXCHANGE_MARKER;
pub use document::PEER_E2EE_MARKER;
pub use document_sync::DocumentCheck;
pub use document_sync::DocumentSync;
pub use hive_mesh::DataReceivedResult;
pub use hive_mesh::HiveMesh;
pub use hive_mesh::HiveMeshConfig;
pub use hive_mesh::RelayDecision;
pub use observer::CollectingObserver;
pub use observer::ObserverManager;
pub use observer::DisconnectReason as HiveDisconnectReason;
pub use observer::HiveEvent;
pub use observer::HiveObserver;
pub use peer::ConnectionState;
pub use peer::ConnectionStateGraph;
pub use peer::FullStateCountSummary;
pub use peer::HivePeer;
pub use peer::IndirectPeer;
pub use peer::PeerConnectionState;
pub use peer::PeerDegree;
pub use peer::PeerManagerConfig;
pub use peer::SignalStrength;
pub use peer::StateCountSummary;
pub use peer::MAX_TRACKED_DEGREE;
pub use peer_manager::PeerManager;
pub use security::EncryptedDocument;
pub use security::EncryptionError;
pub use security::MeshEncryptionKey;
pub use security::KeyExchangeMessage;
pub use security::PeerEncryptedMessage;
pub use security::PeerIdentityKey;
pub use security::PeerSession;
pub use security::PeerSessionKey;
pub use security::PeerSessionManager;
pub use security::SessionState;
pub use gossip::BroadcastAll;
pub use gossip::EmergencyAware;
pub use gossip::GossipStrategy;
pub use gossip::RandomFanout;
pub use gossip::SignalBasedFanout;
pub use persistence::DocumentStore;
pub use persistence::FileStore;
pub use persistence::MemoryStore;
pub use persistence::SharedStore;
pub use relay::MessageId;
pub use relay::RelayEnvelope;
pub use relay::RelayFlags;
pub use relay::SeenMessageCache;
pub use relay::DEFAULT_MAX_HOPS;
pub use relay::DEFAULT_SEEN_TTL_MS;
pub use relay::RELAY_ENVELOPE_MARKER;

Modules§

capabilities
Node capability flags
config
Configuration types for HIVE-BTLE
discovery
HIVE Discovery Module
document
HIVE Document wire format for BLE mesh sync
document_sync
Document synchronization for HIVE BLE mesh
error
Error types for HIVE-BTLE
gatt
HIVE GATT Service Module
gossip
Gossip protocol strategies for mesh synchronization
hive_mesh
HiveMesh - Unified mesh management facade
mesh
Mesh Topology Management
observer
Observer pattern for HIVE mesh events
peer
Peer management types for HIVE BLE mesh
peer_manager
Peer management for HIVE BLE mesh
persistence
Persistence abstraction for HIVE documents
phy
BLE PHY Configuration
platform
Platform abstraction layer for BLE
power
Power Management for HIVE-Lite
relay
Multi-hop relay support for HIVE BLE mesh
security
Security module for HIVE-BTLE
sync
HIVE-Lite Sync Protocol
transport
Transport trait implementation for HIVE-BTLE

Structs§

NodeId
Node identifier

Enums§

HierarchyLevel
Hierarchy levels in the HIVE mesh

Constants§

CHAR_COMMAND_UUID
HIVE Command Characteristic UUID
CHAR_NODE_INFO_UUID
HIVE Node Info Characteristic UUID
CHAR_STATUS_UUID
HIVE Status Characteristic UUID
CHAR_SYNC_DATA_UUID
HIVE Sync Data Characteristic UUID
CHAR_SYNC_STATE_UUID
HIVE Sync State Characteristic UUID
HIVE_SERVICE_UUID
HIVE BLE Service UUID (128-bit)
HIVE_SERVICE_UUID_16BIT
HIVE BLE Service UUID (16-bit short form)
VERSION
Crate version