NeuroClient
An independent Rust client for the Emotiv Cortex v2 WebSocket API.
Provides a typed interface to the Emotiv Cortex service for interacting with Emotiv EEG headsets (Insight, EPOC+, EPOC X, EPOC Flex). Protocol coverage is tracked endpoint-by-endpoint against the official API reference in docs/api-parity.md; rows are marked match only where deterministic mock contract tests or documented workflow tests exist.
Hardware validation: end-to-end testing against physical hardware has only been performed with an Insight headset. Other models (EPOC+, EPOC X, EPOC Flex) are supported per the documented protocol but have not been validated on-device.
Features
- Evidence-backed endpoint parity tracking in
docs/api-parity.md, withmatchrows limited to deterministic contract or workflow coverage - Two-layer client: raw
CortexClientfor full control,ResilientClientfor use with auto-reconnect, token refresh, and retry - Typed data streams (EEG, motion, band power, performance metrics, mental commands, facial expressions, device quality)
- Feature-selectable TLS backend (
rustls-tlsdefault,native-tlsopt-in) - TOML config loading can be enabled/disabled via
config-toml
Feature Flags
| Feature | Default | Description |
|---|---|---|
rustls-tls |
yes | Use rustls TLS backend (tokio-tungstenite/rustls-tls-webpki-roots) |
native-tls |
no | Use native TLS backend (tokio-tungstenite/native-tls) |
config-toml |
yes | Enable TOML parsing for CortexConfig::from_file/discover |
Exactly one TLS backend feature must be enabled (rustls-tls or native-tls).
If config-toml is disabled, CortexConfig::from_file and file-based discover return a ConfigError explaining how to re-enable TOML parsing.
Which client should I use?
| Layer | Type | Token mgmt | Reconnect | Best for |
|---|---|---|---|---|
| Low-level | CortexClient |
Manual | No | tooling, tests, direct protocol control |
| High-level | ResilientClient |
Automatic | Yes | ease of use |
Prerequisites
- EMOTIV Launcher installed and running
- API credentials from the Emotiv Developer Portal
Installation
0.4.0 is the first release under the neuroclient package name:
[]
= "0.4.0"
= { = "1", = ["rt-multi-thread", "macros"] }
Use native TLS instead of rustls:
[]
= { = "0.4.0", = false, = ["native-tls", "config-toml"] }
= { = "1", = ["rt-multi-thread", "macros"] }
Versions through 0.3.4 were published as emotiv-cortex-v2. That package is
frozen and remains unyanked for reproducible builds. See the
0.3-to-0.4 migration guide.
Quick Start
use ;
use QueryHeadsetsOptions;
async
Configuration
Set environment variables:
Or create a cortex.toml (see cortex.toml.example for all options). Discovery
checks ./cortex.toml, then the preferred user path
~/.config/neuroclient/cortex.toml, followed by the legacy
~/.config/emotiv-cortex/cortex.toml.
= "your-client-id"
= "your-client-secret"
Examples
See the examples/ directory for working examples across the API
areas listed in the parity matrix.
For endpoint-by-endpoint compatibility tracking against the official API reference,
see docs/api-parity.md. That matrix only marks match
where deterministic mock contract tests or documented workflow tests exist, and
it calls out remaining documentation ambiguity explicitly.
Testing
Run the full crate test suite (unit tests, deterministic mock integration tests, and live smokes):
Protocol Modules
Types are grouped by domain:
protocol::rpc- JSON-RPC request/response/errorprotocol::constants-Methods,ErrorCodes,Streamsprotocol::headset- headset and config-mapping typesprotocol::session-SessionInfoprotocol::streams- stream event payloads and parsed stream structsprotocol::records- record/marker/export typesprotocol::profiles- profile types and actionsprotocol::training- detection/training + advanced BCI typesprotocol::auth- user login typesprotocol::subjects- subject and demographic types
Pre-release. This crate is under active development; APIs and behavior may change. Treat as pre-release when depending on it.
Not affiliated with Emotiv. NeuroClient is independent and is not created by, affiliated with, supported by, sponsored by, or endorsed by Emotiv, Inc. Emotiv and Emotiv Cortex are trademarks of Emotiv, Inc. For official support and products, see emotiv.com.
License
Licensed under either of Apache License, Version 2.0 or MIT License at your option.