frenz-cli 0.2.1

Command-line tool for the FRENZ brainband: scan, record, summarize
frenz-cli-0.2.1 is not a library.

openfrenz

CI

Open-source tools for the FRENZ brainband: connect over Bluetooth LE, stream every sensor, record sessions losslessly, and export time-aligned data for analysis. Written in Rust, with a small Python package for loading the exported data.

Unofficial. This project is not affiliated with or endorsed by Earable. "FRENZ" is used only to describe compatibility.

What you get

Piece What it does
frenz (command-line tool) scan, record, summary, export, synth — see the CLI guide
frenz (Rust library) async client: connect, typed events for every stream, commands, crash-safe recording
frenz-proto packet decoders and command encoders; no_std, no dependencies, never panics on any input
frenz-export recordings → one Parquet file per stream with an estimated acquisition time for every sample
openfrenz (Python) load exported sessions into pandas; build aligned fixed-length windows

Streams: EEG (4 channels, 125 Hz), accelerometer and gyroscope (50 Hz), PPG (25 Hz), heart rate, SpO2, battery and electrode-contact quality. What is known about the hardware and its Bluetooth interface is written up in docs/HARDWARE.md.

Quick start

cargo install frenz-cli          # installs the `frenz` command

frenz scan                       # find bands nearby
frenz record FRENZA12            # record until Ctrl-C (use the name `scan` printed)
frenz summary recordings/FRENZA12-1800000000.sqlite
frenz export  recordings/FRENZA12-1800000000.sqlite -o sessions/

No band at hand? frenz synth demo.sqlite writes a synthetic recording you can summarize and export the same way.

from openfrenz import load_session

s = load_session("sessions/FRENZA12-1800000000")
t, eeg, segment = s.signal("eeg")      # eeg: (4, n) raw counts; t: Unix seconds

From Rust:

use frenz::{Band, ConnectOptions, Event};
use frenz::proto::Packet;

let band = Band::connect("FRENZA12", ConnectOptions::default()).await?;
let mut events = band.subscribe();
while let Ok(event) = events.recv().await {
    if let Event::Packet { packet, .. } = event {
        if let Packet::Eeg(eeg) = packet.as_ref() {
            println!("{:?}", eeg.samples[0]);
        }
    }
}

Design principles

  • Nothing is silently changed. Recordings store every notification exactly as received. Lost packets, repeated blocks, frozen sensor output and disconnects are reported and flagged, never dropped, filled in or smoothed over.
  • Honest timing. Arrival times, the band's own clock and estimated acquisition times are kept separately; the estimate and its measured jitter are documented in each export.
  • Raw units. Values stay in device counts, with known scales and open questions documented.

Status and limits

Tested with one band (firmware X8.2.2_1.1.19) on macOS. Linux and Windows build and pass the hardware-free tests in CI but have not been tried with a band. The live Bluetooth path (including automatic reconnection) is tested by hand, not in CI. Not yet implemented: audio and stimulation commands, and conversion of EEG counts to microvolts (the scale is not yet known). Recordings contain physiological data: keep them out of version control.

Development

cargo test --workspace           # includes an end-to-end test on a synthetic recording
cargo clippy --workspace --all-targets -- -D warnings
cd python && uv venv && uv pip install -e '.[test]' && pytest

License

MIT