cognionics

Rust library and terminal UI for streaming EEG data from Cognionics / CGX headsets over USB serial (FTDI dongle).

Supported Hardware

Device model is auto-detected from the USB descriptor string. All models use the same serial protocol — 24-bit ADC samples at 3 bytes per channel, with sync-byte framing over FTDI USB serial.

Quick Start

CLI

# List available devices and supported models
cargo run -- --list

# Auto-detect and stream from the first CGX device found
cargo run

# Specify a model explicitly
cargo run -- --model quick-20r

# Specify a serial port
cargo run -- --port /dev/ttyUSB0

# Enable impedance check
cargo run -- --impedance

TUI (Terminal UI)

# Real-time waveform viewer (auto-detect device)
cargo run --bin tui

# Simulate a Quick-20r (no hardware needed)
cargo run --bin tui -- --simulate

# Simulate a specific model
cargo run --bin tui -- --simulate --model quick-32r

TUI Keys:

Library Usage

use cognionics::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = CgxClient::new(CgxClientConfig::default());
    let (mut rx, handle) = client.start().await?;

    println!("Connected: {} ({} channels at {} Hz)",
        handle.model(),
        handle.num_signal_channels(),
        handle.sampling_rate());

    while let Some(event) = rx.recv().await {
        match event {
            CgxEvent::Sample(s) => {
                println!("pkt={} ch[0]={:.2} µV", s.packet_counter, s.channels[0]);
            }
            CgxEvent::Disconnected => break,
            _ => {}
        }
    }
    Ok(())
}

Cargo.toml

[dependencies]
# Full build (includes TUI + virtual device):
cognionics = "0.1.0"

# Library only — no TUI, no virtual device:
cognionics = { version = "0.1.0", default-features = false }

# Library + virtual device for testing (no TUI):
cognionics = { version = "0.1.0", default-features = false, features = ["virtual_device"] }

Features

Architecture

USB Dongle ──(FTDI serial)──▸ CgxReader (background OS thread)
                                  │
                                  ▼
                             byte stream → frame sync → 24-bit decode
                                  │
                                  ▼
                             tokio::mpsc::Sender<CgxEvent>
                                  │
                                  ▼
                             user's mpsc::Receiver<CgxEvent>

The reader runs on a dedicated OS thread (not a tokio task) because serial port I/O is blocking. Events are forwarded to the async world through a tokio mpsc channel.

Events

The CgxEvent enum carries all data from the device:

Protocol Details

CGX headsets transmit a continuous byte stream over FTDI USB serial:

• Framing: Each sample starts with sync byte 0xFF followed by overhead bytes (status/battery), then 3 bytes per channel (24-bit big-endian signed ADC)
• Channels: Last two channels are always Packet Counter (8-bit, wrapping 0–255) and TRIGGER
• ADC scale: raw × 3.880510727564494e-10 volts/LSB
• Impedance: 125 Hz carrier wave toggled via DTR; scale factor 0.0390625 ohms/LSB

Linux Permissions

On Linux you may need a udev rule to access the USB port without root:

echo 'KERNEL=="ttyUSB[0-9]*",MODE="0666"' | sudo tee /etc/udev/rules.d/50-cgx.rules
sudo udevadm control --reload-rules
# Unplug and re-plug the dongle

Module Overview

License

MIT