HRBand-LSL

Connect BLE Heart Rate bands to Lab Streaming Layer (LSL) systems for real-time heart rate monitoring and data streaming. It works with any BLE device that supports the Heart Rate service.

Features

• BLE Device Scanning - Discover and connect to Bluetooth Low Energy heart rate devices
• Heart Rate Parsing - Parse BLE Heart Rate Measurement characteristic (0x2A37) with full BLE spec compliance
• RR Interval Extraction - Extract RR interval data from BLE notifications
• LSL Integration - Stream heart rate and RR interval data to Lab Streaming Layer
• Hook System - Extensible lifecycle hooks for custom behavior at key points:
  • PreScan / PostScan
  • PreConnect / PostConnect
  • DataReceived
  • PreStream / PostStream
  • PreDisconnect
• Interactive Device Selection - User-friendly device selection with inquire
• Async Runtime - Built on Tokio for efficient async/await patterns
• Error Handling - Comprehensive error handling with anyhow

Requirements

• Rust 1.70+ (Edition 2021)
• Tokio 1.35+ for async runtime
• btleplug 0.11+ for BLE operations
• lsl 0.1+ for Lab Streaming Layer (optional feature)
• inquire 0.7+ for interactive prompts
• Optional: libdbus development libraries for Linux BLE support

System Requirements

• Linux: libdbus-dev, cmake, gcc
• macOS: XCode Command Line Tools
• Windows: No additional dependencies required

Building

nix build

With cargo

Access the development shell:

nix develop
cargo build --release

Standard Build:

cargo build --release

Build without LSL support:

cargo build --release --no-default-features

Usage

With Nix

nix run

Basic Application

cargo run

With Example Hook

cargo run --example with_logging_hook

Custom Implementation

use hrband_lsl::{Application, hooks::Hook};
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut app = Application::new();
    
    // Register custom hooks
    app.register_hook(Arc::new(MyCustomHook));
    
    // Run the application
    app.run().await?;
    
    Ok(())
}

Architecture

Module Structure

src/
├── lib.rs              # Application struct and main logic
├── main.rs             # CLI entry point
├── ble.rs              # BLE device scanning and filtering
├── heart_rate.rs       # Heart rate data parsing
├── hooks.rs            # Hook system and registry
└── lsl_stream.rs       # LSL outlet management

Data Flow

1. Scan BLE Devices
   ↓ [PostScan Hook]
2. Filter Devices (remove those with "-" in name)
   ↓
3. User Selects Device
   ↓ [PreConnect Hook]
4. Connect to Device & Discover Services
   ↓ [PostConnect Hook]
5. Subscribe to Heart Rate Characteristic (0x2A37)
   ↓ [PreStream Hook]
6. Receive Notifications & Parse Data
   ↓ [DataReceived Hook]
7. Push to LSL Outlets
   ↓ [PostStream Hook]
8. Disconnect
   ↓ [PreDisconnect Hook]

Hook System

The hook system provides extensibility at key lifecycle points:

Hook Point	Description	When Used
PreScan	Before device scanning begins	Setup/initialization
PostScan	After devices are scanned	Logging device count
PreConnect	Before connecting to selected device	Connection logging
PostConnect	After successful connection	Device initialization
DataReceived	When new HR data arrives	Metrics/monitoring
PreStream	Before LSL streaming starts	Stream setup
PostStream	After streaming completes	Stream cleanup
PreDisconnect	Before device disconnect	Cleanup operations

Heart Rate Data Parsing

The parse_heart_rate_measurement() function fully implements BLE spec 0x2A37:

Flags Byte (Byte 0):

• Bit 0: Heart Rate Format (0 = uint8, 1 = uint16)
• Bits 1-2: Sensor Contact Status (0 = not supported, 2 = no contact, 3 = contact)
• Bit 3: Energy Expended Present
• Bit 4: RR Intervals Present

Data Fields:

• Heart Rate: 1 or 2 bytes (based on format flag)
• Energy Expended: 2 bytes (optional)
• RR Intervals: 2-byte chunks until end (optional)

Testing

With Nix

nix run

With cargo

Run all tests:

cargo test

Run specific test file:

cargo test --test heart_rate_test
cargo test --lib lsl_stream

Run with no-default-features (LSL disabled):

cargo test --no-default-features

Test Coverage

• heart_rate.rs: 8 tests covering all BLE spec formats
• ble.rs: UUID constant verification
• hooks.rs: 8 tests for hook registry and execution
• lsl_stream.rs: Feature-gated stream creation tests
• Integration tests: Full application compilation

Code Quality

Format Check

cargo fmt --check

Lint Check

cargo clippy

Full Quality Pipeline

cargo fmt && cargo clippy && cargo test

Migration from Python

The Rust implementation maintains API compatibility while improving performance:

Aspect	Python	Rust
BLE Library	bleak	btleplug
LSL Library	pylsl	lsl-rust
Async Runtime	asyncio	Tokio
Error Handling	Exception-based	Result-based
Performance	10-50ms latency	<1ms latency
Binary Size	5-10MB	3-5MB
Startup Time	500-1000ms	50-100ms
Memory Usage	80-120MB	20-40MB

Examples

Logging Hook

See examples/with_logging_hook.rs for a complete logging implementation that tracks all lifecycle events.

Custom Metrics Hook

struct MetricsHook {
    start_time: Instant,
}

impl Hook for MetricsHook {
    fn execute(&self, point: HookPoint, context: &HookContext) -> anyhow::Result<()> {
        match point {
            HookPoint::DataReceived => {
                if let Some(hr) = context.heart_rate {
                    println!("HR: {} bpm @ {}ms", hr, self.start_time.elapsed().as_millis());
                }
            }
            _ => {}
        }
        Ok(())
    }
}

Troubleshooting

No BLE Adapters Found

Linux: Ensure bluetoothd is running and dbus is available

systemctl start bluetooth

macOS: Check System Preferences > Bluetooth

Windows: Enable Bluetooth in Settings

Device Connection Fails

1. Ensure device is powered and in range
2. Check device is not already paired with another client
3. Verify BLE permissions in system settings
4. Try connection again

LSL Stream Not Receiving Data

1. Verify LSL library is properly installed (liblsl)
2. Check (LabRecorder)[https://github.com/labstreaminglayer/App-LabRecorder] for the streams
3. Verify stream name and channel count match expected format

Building for Release

cargo build --release

# Binary location:
./target/release/hrband-lsl

Contributing

1. Run cargo fmt before committing
2. Ensure cargo clippy passes with no warnings
3. Add tests for new functionality
4. Update documentation as needed