awear-rs

Rust client for AWEAR EEG devices over Bluetooth Low Energy.

Provides a library crate (awear) for scanning, connecting, authenticating, and streaming EEG data, plus a full-screen terminal UI for real-time waveform visualization.

Features

• BLE scanning and connection via btleplug
• HMAC-SHA256 challenge-response authentication (AWEAR handshake protocol)
• LUCA protocol parsing (header + hex-encoded EEG data blocks)
• Legacy packet format fallback (24-bit signed EEG, battery, signal, misc)
• Async event stream via tokio::sync::mpsc
• Full-screen TUI with real-time scrolling EEG waveform (ratatui + crossterm)
• Simulation mode for development without hardware (--simulate)

Quick Start

Library

use awear::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = AwearClient::new(AwearClientConfig::default());
    let (mut rx, handle) = client.connect().await?;
    handle.start().await?;
    while let Some(event) = rx.recv().await {
        match event {
            AwearEvent::Eeg(r) => println!("EEG: {} samples", r.samples.len()),
            AwearEvent::Battery(b) => println!("Battery: {}%", b),
            _ => {}
        }
    }
    Ok(())
}

Headless CLI

cargo run --bin awear-rs

Scans for AWEAR devices, connects to the first one found, authenticates, sends START, and prints all events to stdout.

Terminal UI

cargo run --bin tui

Full-screen EEG waveform display with:

Simulation mode (no hardware needed):

cargo run --bin tui -- --simulate

Building

# Full build (library + CLI + TUI)
cargo build

# Library only (no TUI dependencies)
cargo build --no-default-features

macOS Bluetooth Permissions

On macOS, Bluetooth access requires an embedded Info.plist. The build.rs script handles this automatically via ld -sectcreate. If scanning returns no devices, ensure Bluetooth is enabled and the terminal has Bluetooth permission in System Settings > Privacy & Security.

Protocol Overview

The AWEAR device uses a custom BLE protocol over a single GATT service:

Connection Flow

1. Scan for devices advertising "AWEAR" in their name
2. Connect and discover GATT services
3. Handshake: device sends AWEAR_CONNECTED:<challenge>\n
4. Authenticate: reply with CRPL:<HMAC-SHA256-truncated> (write-without-response)
5. Ready: device confirms with AWEAR_READY:...\n
6. Stream: send START command to begin EEG data flow

Data Format (LUCA Protocol)

EEG data arrives as LUCA blocks:

• LUCA header (36 bytes): magic LUCA + data type + sequence + payload hint
• Data chunks (multiple BLE notifications): ASCII hex-encoded, decoded to 16-bit signed big-endian samples
• Single channel, 256 Hz sampling rate

Crate Structure

src/
├── lib.rs            # Public API and prelude
├── awear_client.rs   # BLE scanning, connection, authentication, event dispatch
├── protocol.rs       # GATT UUIDs, constants, HMAC challenge-response
├── types.rs          # AwearEvent, EegReading, DeviceStatus, config types
├── parse.rs          # LUCA and legacy binary packet parsers
├── main.rs           # Headless CLI binary
└── bin/
    └── tui.rs        # ratatui terminal UI

License

This project is licensed under the GNU General Public License v3.0.