emotiv_cortex_v2/
lib.rs

1//! # emotiv-cortex-v2
2//!
3//! A Rust client for the [Emotiv Cortex v2 WebSocket API](https://emotiv.gitbook.io/cortex-api/).
4//!
5//! This crate provides a complete, typed interface to the Emotiv Cortex service
6//! for interacting with Emotiv EEG headsets (Insight, EPOC+, EPOC X, EPOC Flex).
7//!
8//! ## Quick Start
9//!
10//! ```no_run
11//! use emotiv_cortex_v2::{CortexClient, CortexConfig};
12//! use emotiv_cortex_v2::protocol::headset::QueryHeadsetsOptions;
13//!
14//! #[tokio::main]
15//! async fn main() -> emotiv_cortex_v2::CortexResult<()> {
16//!     // Load config from environment or cortex.toml
17//!     let config = CortexConfig::discover(None)?;
18//!
19//!     // Connect to the Cortex service
20//!     let mut client = CortexClient::connect(&config).await?;
21//!
22//!     // Check service info
23//!     let info = client.get_cortex_info().await?;
24//!     println!("Cortex version: {:?}", info);
25//!
26//!     // Authenticate
27//!     let _token = client.authenticate(&config.client_id, &config.client_secret).await?;
28//!
29//!     // Discover headsets
30//!     let headsets = client.query_headsets(QueryHeadsetsOptions::default()).await?;
31//!     for h in &headsets {
32//!         println!("Found: {} ({})", h.id, h.status);
33//!     }
34//!
35//!     client.disconnect().await?;
36//!     Ok(())
37//! }
38//! ```
39//!
40//! ## Two-Layer API
41//!
42//! | Layer | Type | Token mgmt | Reconnect | Retry | Best for |
43//! |-------|------|-----------|-----------|-------|----------|
44//! | Low-level | [`CortexClient`] | Manual | No | No | Examples, testing, full control |
45//! | High-level | `ResilientClient` | Automatic | Yes | Yes | Production applications |
46//!
47//! ## Configuration
48//!
49//! See [`CortexConfig`] for the full configuration reference.
50//! The simplest setup uses environment variables:
51//!
52//! ```bash
53//! export EMOTIV_CLIENT_ID="your-client-id"
54//! export EMOTIV_CLIENT_SECRET="your-client-secret"
55//! ```
56//!
57//! Or a `cortex.toml` file:
58//!
59//! ```toml
60//! client_id = "your-client-id"
61//! client_secret = "your-client-secret"
62//! ```
63//!
64//! ## Feature Flags
65//!
66//! TLS backend selection is explicit:
67//! - `rustls-tls` (default)
68//! - `native-tls`
69//!
70//! Exactly one TLS backend feature must be enabled.
71//! `config-toml` (default) controls TOML parsing support in [`CortexConfig`];
72//! when disabled, file-based config loading returns [`CortexError::ConfigError`].
73//!
74//! ## Protocol Modules
75//!
76//! Protocol types are grouped by domain:
77//! - `protocol::rpc`
78//! - `protocol::constants`
79//! - `protocol::headset`
80//! - `protocol::session`
81//! - `protocol::streams`
82//! - `protocol::records`
83//! - `protocol::profiles`
84//! - `protocol::training`
85//! - `protocol::auth`
86//! - `protocol::subjects`
87
88#[cfg(all(not(feature = "rustls-tls"), not(feature = "native-tls")))]
89compile_error!(
90    "emotiv-cortex-v2 requires exactly one TLS backend feature: enable `rustls-tls` or `native-tls`."
91);
92
93#[cfg(all(feature = "rustls-tls", feature = "native-tls"))]
94compile_error!(
95    "emotiv-cortex-v2 requires exactly one TLS backend feature: `rustls-tls` and `native-tls` are mutually exclusive."
96);
97
98pub mod client;
99pub mod config;
100pub mod error;
101pub mod headset;
102pub mod health;
103pub mod protocol;
104pub mod reconnect;
105pub mod retry;
106pub mod streams;
107
108// ─── Public re-exports ──────────────────────────────────────────────────
109
110pub use client::CortexClient;
111pub use config::CortexConfig;
112pub use error::{CortexError, CortexResult};
113pub use headset::HeadsetModel;
114pub use reconnect::ResilientClient;
115pub use streams::TypedStream;
emotiv_cortex_v2/lib.rs

emotiv_cortex_v2/
lib.rs
