Crate peat_btle 

PEAT-BTLE: Bluetooth Low Energy mesh transport for Peat Protocol

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

Overview

PEAT-BTLE implements the pluggable transport abstraction (ADR-032) for Bluetooth Low Energy, enabling Peat 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
• Peat-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 peat_btle::{BleConfig, BluetoothLETransport, NodeId};

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

// Create transport with platform adapter
#[cfg(feature = "linux")]
let adapter = peat_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
• transport-only: Pure BLE transport, no app-layer CRDTs
• legacy-chat: Deprecated ChatCRDT support (will be removed in 0.2.0)
• 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 (peat-ffi)

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

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

Then use the appropriate adapter:

use peat_btle::{BleConfig, BluerAdapter, PeatMesh, NodeId};

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

Platform → Adapter Mapping

Feature	Target	Adapter Type
linux	Linux	BluerAdapter
android	Android	AndroidAdapter
macos	macOS	CoreBluetoothAdapter
ios	iOS	CoreBluetoothAdapter
windows	Windows	WinRtBleAdapter

Document Encoding for Translation Layer

For translating between Automerge (full Peat) and peat-btle documents:

use peat_btle::PeatDocument;

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

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

Power Profiles

Profile	Duty Cycle	Watch Battery
Aggressive	20%	~6 hours
Balanced	10%	~12 hours
LowPower	2%	~20+ hours

Related ADRs

• ADR-039: PEAT-BTLE Mesh Transport Crate
• ADR-032: Pluggable Transport Abstraction
• ADR-035: Peat-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::PeatBeacon;

pub use discovery::ScanFilter;

pub use error::BleError;

pub use error::Result;

pub use gatt::PeatGattService;

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::MergeResult;

pub use document::PeatDocument;

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 observer::CollectingObserver;

pub use observer::ObserverManager;

pub use observer::DisconnectReason as PeatDisconnectReason;

pub use observer::PeatEvent;

pub use observer::PeatObserver;

pub use peat_mesh::DataReceivedResult;

pub use peat_mesh::PeatMesh;

pub use peat_mesh::PeatMeshConfig;

pub use peat_mesh::RelayDecision;

pub use peer::ConnectionState;

pub use peer::ConnectionStateGraph;

pub use peer::FullStateCountSummary;

pub use peer::IndirectPeer;

pub use peer::PeatPeer;

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::DeviceIdentity;

pub use security::IdentityAttestation;

pub use security::IdentityError;

pub use security::IdentityRecord;

pub use security::IdentityRegistry;

pub use security::RegistryResult;

pub use security::MembershipPolicy;

pub use security::MeshCredentials;

pub use security::MeshGenesis;

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 security::MemoryStorage;

pub use security::PersistedState;

pub use security::PersistenceError;

pub use security::SecureStorage;

pub use security::PERSISTED_STATE_VERSION;

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;

pub use registry::decode_header;

pub use registry::decode_typed;

pub use registry::encode_with_header;

pub use registry::AppOperation;

pub use registry::DocumentRegistry;

pub use registry::DocumentType;

pub use registry::APP_OP_BASE;

pub use registry::APP_TYPE_MAX;

pub use registry::APP_TYPE_MIN;

Modules

address_rotation

BLE address rotation handling

capabilities

Node capability flags

config

Configuration types for PEAT-BTLE

discovery

Peat Discovery Module

document

Peat Document wire format for BLE mesh sync

document_sync

Document synchronization for Peat BLE mesh

error

Error types for PEAT-BTLE

gatt

Peat GATT Service Module

gossip

Gossip protocol strategies for mesh synchronization

mesh

Mesh Topology Management

observer

Observer pattern for Peat mesh events

peat_mesh

PeatMesh - Unified mesh management facade

peer

Peer management types for Peat BLE mesh

peer_lifetime

Peer lifetime management with stale peer cleanup

peer_manager

Peer management for Peat BLE mesh

persistence

Persistence abstraction for Peat documents

phy

BLE PHY Configuration

platform

Platform abstraction layer for BLE

power

Power Management for Peat-Lite

reconnect

Auto-reconnection manager with exponential backoff

registry

Extensible Document Registry for app-layer CRDT types.

relay

Multi-hop relay support for Peat BLE mesh

security

Security module for PEAT-BTLE

sync

Peat-Lite Sync Protocol

transport

Transport trait implementation for PEAT-BTLE

Structs

NodeId

Node identifier

Enums

HierarchyLevel

Hierarchy levels in the Peat mesh

Constants

CHAR_COMMAND_UUID

PEAT Command Characteristic UUID

CHAR_NODE_INFO_UUID

PEAT Node Info Characteristic UUID

CHAR_STATUS_UUID

PEAT Status Characteristic UUID

CHAR_SYNC_DATA_UUID

PEAT Sync Data Characteristic UUID

CHAR_SYNC_STATE_UUID

PEAT Sync State Characteristic UUID

PEAT_SERVICE_UUID

Peat BLE Service UUID (128-bit)

PEAT_SERVICE_UUID_16BIT

Peat BLE Service UUID (16-bit short form)

VERSION

Crate version