hive-btle

Bluetooth Low Energy mesh transport for tactical edge networking.

Overview

hive-btle provides a cross-platform Bluetooth Low Energy mesh networking stack optimized for resource-constrained tactical devices. It enables peer-to-peer discovery, advertisement, connectivity, and efficient CRDT-based data synchronization over BLE.

Key Features

• Cross-Platform: Linux, Android, iOS, macOS, Windows, ESP32
• Power Efficient: Designed for 18+ hour battery life on smartwatches
• Long Range: Coded PHY support for 300m+ range (BLE 5.0+)
• Mesh Topology: Hierarchical mesh with automatic peer discovery
• Efficient Sync: Delta-based CRDT synchronization over GATT
• Embedded Ready: no_std support for bare-metal targets

Why hive-btle?

Traditional BLE mesh implementations (like those in commercial sync SDKs) often suffer from:

Status

Pre-release: This crate is under active development. APIs may change.

Installation

Add to your Cargo.toml:

[dependencies]
hive-btle = { version = "0.1", features = ["linux"] }

Feature Flags

Quick Start

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create power-efficient configuration
    let config = BleConfig::hive_lite(NodeId::new(0x12345678))
        .with_power_profile(PowerProfile::LowPower);

    // Create platform adapter (Linux example)
    #[cfg(feature = "linux")]
    let adapter = hive_btle::platform::linux::BluerAdapter::new().await?;

    // Create and start transport
    let transport = BluetoothLETransport::new(config, adapter);
    transport.start().await?;

    // Transport is now advertising and ready for connections
    println!("Node {} is running", transport.node_id());

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

    Ok(())
}

Architecture

Standalone vs HIVE Integration

hive-btle is designed for dual use:

1. Standalone: Pure embedded mesh (ESP32/Pico devices) without any full HIVE nodes
2. HIVE Integration: BLE transport for full HIVE nodes, with gateway translation to Automerge

┌─────────────────────────────────────────────────────────────────────────┐
│                         HIVE Integration Mode                            │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                    Full HIVE Node (Phone)                          │  │
│  │  ┌─────────────────────────────────────────────────────────────┐  │  │
│  │  │                   AutomergeIroh                              │  │  │
│  │  │             (Full CRDT documents)                            │  │  │
│  │  └─────────────────────────────────────────────────────────────┘  │  │
│  │                            ↕                                       │  │
│  │  ┌─────────────────────────────────────────────────────────────┐  │  │
│  │  │              Translation Layer (HIVE repo)                   │  │  │
│  │  │        Maps: Automerge ↔ hive-btle lightweight               │  │  │
│  │  └─────────────────────────────────────────────────────────────┘  │  │
│  │                            ↕                                       │  │
│  │  ┌─────────────────────────────────────────────────────────────┐  │  │
│  │  │                      hive-btle                               │  │  │
│  │  │            (BLE transport + lightweight CRDTs)               │  │  │
│  │  └─────────────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                ↕ BLE                                     │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │               Embedded Node (ESP32/Pico)                           │  │
│  │                        hive-btle                                   │  │
│  │              (standalone, lightweight CRDTs)                       │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

Why two modes? Automerge is too resource-intensive for embedded targets (requires ~10MB+ RAM, std library). hive-btle's lightweight CRDTs (GCounter, Peripheral) provide the same semantics in <256KB RAM. Full HIVE nodes translate between formats.

Component Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Application                             │
├─────────────────────────────────────────────────────────────┤
│                  BluetoothLETransport                        │
│         (MeshTransport trait implementation)                 │
├──────────────┬──────────────┬──────────────┬────────────────┤
│   Discovery  │     GATT     │     Mesh     │     Power      │
│  (Beacon,    │  (Service,   │  (Topology,  │  (Scheduler,   │
│   Scanner)   │   Protocol)  │   Routing)   │   Profiles)    │
├──────────────┴──────────────┴──────────────┴────────────────┤
│                     BleAdapter Trait                         │
├──────────┬──────────┬──────────┬──────────┬─────────────────┤
│  Linux   │ Android  │   iOS    │ Windows  │     ESP32       │
│ (BlueZ)  │  (JNI)   │(CoreBT)  │ (WinRT)  │   (NimBLE)      │
└──────────┴──────────┴──────────┴──────────┴─────────────────┘

Core Components

Power Profiles

*Estimated for typical smartwatch (300mAh battery)

GATT Service

hive-btle defines a custom GATT service for mesh communication:

Mesh-Wide Encryption

hive-btle supports optional mesh-wide encryption using ChaCha20-Poly1305 AEAD. When enabled, all documents are encrypted before transmission, providing confidentiality across multi-hop BLE relay.

Enabling Encryption

use hive_btle::{HiveMesh, HiveMeshConfig, NodeId};

// Create a 32-byte shared secret (distribute securely to all mesh nodes)
let secret: [u8; 32] = [0x42; 32]; // Use a real secret in production!

// Configure mesh with encryption
let config = HiveMeshConfig::new(NodeId::new(0x12345678), "ALPHA-1", "DEMO")
    .with_encryption(secret);

let mesh = HiveMesh::new(config);

// All documents sent through this mesh are now encrypted
let encrypted_doc = mesh.build_document();

How It Works

• Algorithm: ChaCha20-Poly1305 authenticated encryption
• Key Derivation: HKDF-SHA256 from shared secret + mesh ID
• Overhead: 30 bytes per document (2 marker + 12 nonce + 16 auth tag)
• Wire Format: ENCRYPTED_MARKER (0xAE) | reserved | nonce | ciphertext

Multi-Hop Security

Node A ──encrypted──> Node B (relay) ──encrypted──> Node C
                           │
                    Can forward but
                    only decrypts if
                    has formation key

Nodes without the shared secret can relay encrypted documents but cannot read their contents. This provides end-to-end confidentiality even across untrusted relay nodes.

Backward Compatibility

• Encrypted nodes can receive unencrypted documents (for gradual rollout)
• Unencrypted nodes will reject encrypted documents they can't decrypt

Per-Peer E2EE (End-to-End Encryption)

For sensitive communications, hive-btle supports per-peer end-to-end encryption using X25519 key exchange and ChaCha20-Poly1305. Unlike mesh-wide encryption where all formation members share a key, per-peer E2EE ensures only the sender and recipient can decrypt messages—even other mesh members cannot read them.

Enabling Per-Peer E2EE

use hive_btle::{HiveMesh, HiveMeshConfig, NodeId};

// Create mesh instances
let config1 = HiveMeshConfig::new(NodeId::new(0x11111111), "ALPHA-1", "DEMO");
let mesh1 = HiveMesh::new(config1);

let config2 = HiveMeshConfig::new(NodeId::new(0x22222222), "BRAVO-1", "DEMO");
let mesh2 = HiveMesh::new(config2);

// Enable E2EE on both nodes (generates identity keys)
mesh1.enable_peer_e2ee();
mesh2.enable_peer_e2ee();

// Initiate E2EE session from mesh1 to mesh2
let key_exchange1 = mesh1.initiate_peer_e2ee(NodeId::new(0x22222222), now_ms).unwrap();
// Send key_exchange1 to mesh2 over BLE...

// mesh2 handles incoming key exchange and responds
let key_exchange2 = mesh2.handle_key_exchange(&key_exchange1, now_ms).unwrap();
// Send key_exchange2 back to mesh1...

// mesh1 completes the handshake
mesh1.handle_key_exchange(&key_exchange2, now_ms);

// Session established! Now send encrypted messages
let encrypted = mesh1.send_peer_e2ee(NodeId::new(0x22222222), b"Secret message", now_ms).unwrap();
// Send encrypted to mesh2...

// mesh2 decrypts
let plaintext = mesh2.handle_peer_e2ee_message(&encrypted, now_ms).unwrap();
assert_eq!(plaintext, b"Secret message");

How It Works

1. Key Exchange: X25519 Diffie-Hellman to establish a shared secret
2. Key Derivation: HKDF-SHA256 binds the session key to both node IDs
3. Encryption: ChaCha20-Poly1305 AEAD with replay protection
4. Wire Format: PEER_E2EE_MARKER (0xAF) | reserved | recipient | sender | counter | nonce | ciphertext

Security Properties

Overhead

Per-peer E2EE adds 46 bytes overhead per message:

• 2 bytes: Marker header
• 4 bytes: Recipient node ID
• 4 bytes: Sender node ID
• 8 bytes: Counter (replay protection)
• 12 bytes: Nonce
• 16 bytes: Authentication tag

Use Cases

• Sensitive Commands: Squad leader → specific soldier
• Private Messages: Point-to-point communication within formation
• Credential Exchange: Secure key material distribution

Encryption Layers

┌─────────────────────────────────────────────────────────────────┐
│  Phase 1: Mesh-Wide (Formation Key)                             │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  All formation members can decrypt                       │    │
│  │  Protects: External eavesdroppers                        │    │
│  │  Overhead: 30 bytes                                      │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  Phase 2: Per-Peer E2EE (Session Key)                           │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Only sender + recipient can decrypt                     │    │
│  │  Protects: Other mesh members, compromised relays        │    │
│  │  Overhead: 46 bytes                                      │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Platform Requirements

Linux

• BlueZ 5.48 or later
• D-Bus system bus access
• Bluetooth adapter with BLE support

# Check BlueZ version
bluetoothctl --version

# Ensure bluetooth service is running
sudo systemctl start bluetooth

Android

• Android 6.0 (API 23) or later
• BLUETOOTH, BLUETOOTH_ADMIN, ACCESS_FINE_LOCATION permissions
• For BLE 5.0 features: Android 8.0 (API 26) or later

iOS

• iOS 13.0 or later
• NSBluetoothAlwaysUsageDescription in Info.plist
• CoreBluetooth framework

Examples

See the examples/ directory:

• linux_scanner.rs - Scan for HIVE nodes on Linux
• linux_advertiser.rs - Advertise as a HIVE node
• mesh_demo.rs - Two-node mesh demonstration

Run examples with:

cargo run --example linux_scanner --features linux

Testing

# Run unit tests (no hardware required)
cargo test

# Run with Linux platform tests (requires Bluetooth adapter)
cargo test --features linux

# Run specific test module
cargo test sync::

Contributing

Contributions are welcome! Priority areas:

1. Android Implementation - JNI bindings to Android Bluetooth API
2. Windows Implementation - WinRT Bluetooth APIs
3. Hardware Testing - Real-world validation on various devices

Please see CONTRIBUTING.md for guidelines.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Acknowledgments

Developed by (r)evolve - Revolve Team LLC as part of the HIVE Protocol project.