neurosky 0.0.1

Rust library and TUI for NeuroSky MindWave EEG headsets via the ThinkGear serial protocol
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

# neurosky

Rust library and terminal UI for **NeuroSky MindWave** EEG headsets via the
[ThinkGear serial protocol](http://developer.neurosky.com/docs/doku.php?id=thinkgear_communications_protocol).
Pure Rust — works on Windows, Linux, and macOS.

## Installation

```shell
cargo add neurosky
```

## Supported devices

| Device | Channels | Raw Hz | ASIC Hz | Connection |
|---|---|---|---|---|
| **MindWave** | 1 EEG (Fp1) + 8 ASIC bands + eSense | 512 | 1 | USB dongle (57 600 baud) |
| **MindWave Mobile** | Same | 512 | 1 | Bluetooth SPP (115 200 baud) |
| **MindWave Mobile 2** | Same | 512 | 1 | Bluetooth SPP (115 200 baud) |

## Quick start

```rust
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:

```text
[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

| Code | Type | Value |
|---|---|---|
| `0x02` | Poor signal | 0 = good, 200 = off-head |
| `0x04` | Attention eSense | 0–100 |
| `0x05` | Meditation eSense | 0–100 |
| `0x16` | Blink strength | 1–255 |
| `0x80` | Raw EEG (16-bit signed, 512 Hz) | 2 bytes big-endian |
| `0x83` | ASIC EEG band powers (1 Hz) | 24 bytes (8 × 3-byte u24 big-endian) |

### ASIC band layout

| Band | Bytes | Range (Hz) |
|---|---|---|
| Delta | [0..2] | 0.5–2.75 |
| Theta | [3..5] | 3.5–6.75 |
| Low Alpha | [6..8] | 7.5–9.25 |
| High Alpha | [9..11] | 10–11.75 |
| Low Beta | [12..14] | 13–16.75 |
| High Beta | [15..17] | 18–29.75 |
| Low Gamma | [18..20] | 31–39.75 |
| Mid Gamma | [21..23] | 41–49.75 |

## DSP pipeline

Inspired by the [neuromore/studio](https://github.com/neuromore/studio) signal-processing
architecture. All processing is pure Rust, no FFTW or BLAS required.

```text
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](https://www.w3.org/TR/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

| Crate | Purpose |
|---|---|
| [serialport](https://crates.io/crates/serialport) | Cross-platform serial port I/O |
| [thiserror](https://crates.io/crates/thiserror) | Error type derivation |
| [libc](https://crates.io/crates/libc) | seccomp syscalls for network sandboxing (Linux) |
| [log](https://crates.io/crates/log) | Logging facade |
| [env_logger](https://crates.io/crates/env_logger) | Log output |
| [ratatui](https://ratatui.rs) | Terminal UI (optional, `tui` feature) |
| [crossterm](https://github.com/crossterm-rs/crossterm) | Terminal backend (optional, `tui` feature) |

## Running tests

```shell
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](./LICENSE)