gtec 0.0.1

Rust library and TUI for g.tec Unicorn Hybrid Black 8-channel EEG headset via the Unicorn C API (runtime-loaded)
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

# gtec

A Rust library and terminal UI for the **g.tec Unicorn Hybrid Black** 8-channel
EEG headset via the [Unicorn C API](https://github.com/unicorn-bi/Unicorn-Hybrid-Black-Windows-APIs).

Rust FFI wrapper with 100% API parity — all 16 functions from `unicorn.h` bound,
all types mapped to `#[repr(C)]` Rust equivalents, SHA-256 verification, and
OS-level network sandboxing.

## Installation

```shell
cargo add gtec
```

## Supported hardware

| Device | Channels | Sampling Rate | Connection |
|---|---|---|---|
| Unicorn Hybrid Black | 8 EEG + 3 accel + 3 gyro + battery + counter + validation (17 total) | 250 Hz | Bluetooth |

## Cross-platform

Works on **Windows** and **Linux** (x86_64). The Unicorn library is loaded at
runtime via `libloading` — no build-time C dependencies.

**Note:** No macOS native library is provided by g.tec.

### Native library sources

| Platform | Repository | File |
|---|---|---|
| **Windows** | [Unicorn-Hybrid-Black-Windows-APIs](https://github.com/unicorn-bi/Unicorn-Hybrid-Black-Windows-APIs) | `Unicorn.dll` |
| **Linux** | [Unicorn-Suite-Hybrid-Black](https://github.com/unicorn-bi/Unicorn-Suite-Hybrid-Black) | `libunicorn.so` |

## Quick start

```rust
use gtec::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let serials = UnicornDevice::scan(true)?;
    let mut device = UnicornDevice::open(&serials[0])?;

    println!("Info: {:?}", device.device_info()?);

    let scans = device.capture(UNICORN_SAMPLING_RATE * 4)?;
    for s in &scans[..5] {
        println!("EEG: {:?}", s.eeg());
    }

    device.close()?;
    Ok(())
}
```

## Project layout

```
gtec-rs/
├── Cargo.toml
├── README.md
├── CHANGELOG.md
├── LICENSE
└── src/
    ├── lib.rs            # Crate root + prelude
    ├── main.rs           # CLI binary
    ├── bin/tui.rs        # ratatui TUI (8-channel EEG charts)
    ├── ffi.rs            # Runtime-loaded Unicorn C API (16 functions)
    ├── types.rs          # #[repr(C)] types matching unicorn.h
    ├── device.rs         # High-level device API
    ├── error.rs          # Error types
    ├── verify.rs         # SHA-256 integrity verification
    └── sandbox.rs        # OS-level network sandboxing
├── sdk/
│   ├── download.sh       # Download + verify native libraries
│   └── checksums.sha256  # Pinned SHA-256 hashes
├── examples/
│   ├── scan.rs           # Device discovery
│   ├── stream.rs         # Signal streaming
│   └── read_eeg.rs       # 4-second EEG capture
└── tests/
    └── types_tests.rs    # FFI type layout + constant tests
```

## Dependencies

| Crate | Purpose |
|---|---|
| [libloading](https://crates.io/crates/libloading) | Runtime DLL/so loading |
| [thiserror](https://crates.io/crates/thiserror) | Error type derivation |
| [log](https://crates.io/crates/log) | Logging facade |
| [env_logger](https://crates.io/crates/env_logger) | Log output |
| [libc](https://crates.io/crates/libc) | seccomp syscalls (Linux) |
| [ratatui](https://ratatui.rs) | Terminal UI (optional) |
| [crossterm](https://github.com/crossterm-rs/crossterm) | Terminal backend (optional) |

## Running tests

```bash
cargo test
```

## License

[MIT](./LICENSE)