neurosky

Rust library and terminal UI for NeuroSky MindWave EEG headsets via the ThinkGear serial protocol. Pure Rust — works on Windows, Linux, and macOS.

Installation

cargo add neurosky

Supported devices

Quick start

use neurosky::prelude::*;

let ports = MindWaveDevice::find()?;
let mut device = MindWaveDevice::open(&ports[0])?;
device.auto_connect()?;

let mut extractor = BandPowerExtractor::new(512.0, 50.0, 512);

loop {
    for packet in device.read()? {
        match packet {
            Packet::Attention(v)  => println!("Attention:  {v}/100"),
            Packet::Meditation(v) => println!("Meditation: {v}/100"),
            Packet::RawValue(v)   => { let bp = extractor.push(v); }
            Packet::AsicEeg(eeg)  => println!("δ={} θ={} α={}", eeg.delta, eeg.theta, eeg.low_alpha),
            _ => {}
        }
    }
}

Protocol details

ThinkGear uses a simple framed binary protocol over UART:

[0xAA] [0xAA] [PLENGTH] [PAYLOAD…] [CHECKSUM]
  sync   sync   1 byte    N bytes     1 byte

Checksum = bitwise NOT of sum of payload bytes (mod 256).

Packet codes

ASIC band layout

DSP pipeline

Inspired by the neuromore/studio signal-processing architecture. All processing is pure Rust, no FFTW or BLAS required.

raw ADC (i16, 512 Hz)
  └─► notch filter (50 / 60 Hz, Q = 30)
        └─► delta bandpass  (0.5–4 Hz)  ──► 1-s epoch ──► mean power
        └─► theta bandpass  (4–8 Hz)    ──► 1-s epoch ──► mean power
        └─► alpha bandpass  (8–13 Hz)   ──► 1-s epoch ──► mean power
        └─► beta  bandpass  (13–30 Hz)  ──► 1-s epoch ──► mean power
        └─► gamma bandpass  (30–50 Hz)  ──► 1-s epoch ──► mean power

All filters are 2nd-order biquad IIR (Direct Form II Transposed) with coefficients from the Audio EQ Cookbook.

Project layout

neurosky-rs/
├── Cargo.toml
├── README.md
├── CHANGELOG.md
├── LICENSE
└── src/
    ├── lib.rs        # Crate root and prelude
    ├── main.rs       # CLI binary
    ├── bin/tui.rs    # ratatui TUI — live waveform + band power bars
    ├── types.rs      # ThinkGear protocol constants, codes, packet types
    ├── parser.rs     # Stateful ThinkGear binary protocol parser
    ├── device.rs     # High-level MindWaveDevice API
    ├── dsp.rs        # Real-time DSP pipeline (biquad filters, band powers)
    ├── verify.rs     # Pure-Rust SHA-256 + ThinkGear packet validation
    ├── sandbox.rs    # OS-level network sandboxing
    └── error.rs      # Error types
├── examples/
│   ├── scan.rs       # Port discovery
│   ├── stream.rs     # Packet streaming
│   └── read_eeg.rs   # Capture 4 s of raw EEG + band powers
└── tests/
    └── protocol_tests.rs  # Protocol constants, decode, parser — no hardware needed

Dependencies

Running tests

cargo test

44 unit tests covering protocol constants, all ThinkGear packet types, checksum validation, DSP filter behaviour, band power extraction, SHA-256 correctness, and sandboxing — all without hardware.

License

MIT