Struct CortexClient 

pub struct CortexClient { /* private fields */ }

WebSocket JSON-RPC client for the Emotiv Cortex API.

This client manages a single WebSocket connection, split into reader and writer halves. The writer is shared (behind Arc<Mutex>) so that API calls can be made concurrently with data streaming. The reader runs in a background task that dispatches:

• RPC responses → matched by id to pending oneshot channels
• Data events → routed by stream type to mpsc channels

Implementations

impl CortexClient

pub async fn connect(config: &CortexConfig) -> CortexResult<Self>

Connect to the Cortex API WebSocket service.

The Cortex service must be running on the local machine. TLS is configured based on the CortexConfig settings.

Examples

use emotiv_cortex_v2::{CortexClient, CortexConfig};

let config = CortexConfig::discover(None)?;
let mut client = CortexClient::connect(&config).await?;

let info = client.get_cortex_info().await?;
client.disconnect().await?;

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn connect_url(url: &str) -> CortexResult<Self>

Connect to the Cortex API using just a URL (convenience for simple use cases).

Uses default timeouts and localhost TLS settings.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub fn create_stream_channels(&self, streams: &[&str]) -> StreamReceivers

Create data stream channels for the specified streams.

This replaces ALL existing stream channels. Call before subscribe_streams.

pub fn add_stream_channel(&self, stream: &str) -> Option<Receiver<Value>>

Add a single stream channel without disturbing existing ones.

Returns a receiver for the new channel.

pub fn remove_stream_channel(&self, stream: &str)

Remove a single stream channel sender.

pub fn clear_stream_channels(&self)

Clear all stream senders.

pub fn stream_dispatch_stats( &self, ) -> HashMap<&'static str, StreamDispatchStats>

Returns the current stream dispatch stats keyed by stream type ("eeg", "mot", …).

pub async fn pending_response_count(&self) -> usize

Returns the number of currently pending RPC responses.

pub async fn get_cortex_info(&self) -> CortexResult<Value>

Query Cortex service version and build info.

No authentication required. Useful as a health check.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn has_access_right( &self, client_id: &str, client_secret: &str, ) -> CortexResult<bool>

Check if the application has been granted access rights.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn get_user_login(&self) -> CortexResult<Vec<UserLoginInfo>>

Get the currently logged-in Emotiv user.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn authenticate( &self, client_id: &str, client_secret: &str, ) -> CortexResult<String>

Authenticate with the Cortex API.

Performs: getCortexInfo → requestAccess → authorize.

Returns the cortex token needed for all subsequent operations.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn generate_new_token( &self, cortex_token: &str, client_id: &str, client_secret: &str, ) -> CortexResult<String>

Generate a new cortex token (or refresh an existing one).

Can be used to obtain a fresh token without the full requestAccess → authorize flow.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn get_user_info(&self, cortex_token: &str) -> CortexResult<Value>

Get information about the current user.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn get_license_info(&self, cortex_token: &str) -> CortexResult<Value>

Get information about the license used by the application.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn query_headsets( &self, options: QueryHeadsetsOptions, ) -> CortexResult<Vec<HeadsetInfo>>

Query available headsets.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn connect_headset(&self, headset_id: &str) -> CortexResult<()>

Connect to a specific headset via the Cortex service.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn disconnect_headset(&self, headset_id: &str) -> CortexResult<()>

Disconnect a headset from the Cortex service.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn refresh_headsets(&self) -> CortexResult<()>

Trigger headset scanning / refresh.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn sync_with_headset_clock( &self, headset_id: &str, ) -> CortexResult<HeadsetClockSyncResult>

Synchronize the system clock with the headset clock.

Cortex method: syncWithHeadsetClock Required state: reachable headset. Parameters: headset_id. Returns: typed clock sync details from Cortex. Errors: session/headset/transport errors from Cortex are propagated. Related methods: Self::query_headsets, Self::connect_headset.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn config_mapping( &self, cortex_token: &str, request: ConfigMappingRequest, ) -> CortexResult<ConfigMappingResponse>

Manage EEG channel mapping configurations for an EPOC Flex headset.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn update_headset( &self, cortex_token: &str, headset_id: &str, setting: Value, ) -> CortexResult<Value>

Update settings of an EPOC+ or EPOC X headset.

Cortex method: updateHeadset Required state: authenticated token. Parameters:

• headset_id: headset identifier
• setting: device-specific JSON object (for example: {"mode": "EPOC", "eegRate": 256, "memsRate": 64})

Returns: raw JSON-RPC result payload from Cortex. Errors: validation/headset/license/auth errors are propagated. Retry/idempotency: safe to retry when the same setting is reused. Related methods: Self::update_headset_custom_info, Self::query_headsets.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn update_headset_custom_info( &self, cortex_token: &str, headset_id: &str, headband_position: Option<&str>, custom_name: Option<&str>, ) -> CortexResult<Value>

Update the headband position or custom name of an EPOC X headset.

Cortex method: updateHeadsetCustomInfo Required state: authenticated token. Parameters:

• headset_id: headset identifier
• headband_position: optional position string
• custom_name: optional display name

Returns: raw JSON-RPC result payload from Cortex. Errors: validation/headset/auth errors are propagated. Related methods: Self::update_headset, Self::query_headsets.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn create_session( &self, cortex_token: &str, headset_id: &str, ) -> CortexResult<SessionInfo>

Create a session for a headset.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn query_sessions( &self, cortex_token: &str, ) -> CortexResult<Vec<SessionInfo>>

Query existing sessions.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn close_session( &self, cortex_token: &str, session_id: &str, ) -> CortexResult<()>

Close an active session.

Cortex method: updateSession with status = "close". Required state: authenticated token and a valid session_id. Returns: Ok(()) only when Cortex confirms the session update call. Errors: session/auth/transport errors are propagated. Retry/idempotency: generally safe to retry close on transient failures. Related methods: Self::create_session, Self::query_sessions.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn subscribe_streams( &self, cortex_token: &str, session_id: &str, streams: &[&str], ) -> CortexResult<Value>

Subscribe to one or more data streams.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn unsubscribe_streams( &self, cortex_token: &str, session_id: &str, streams: &[&str], ) -> CortexResult<()>

Unsubscribe from one or more data streams.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn create_record( &self, cortex_token: &str, session_id: &str, title: &str, ) -> CortexResult<RecordInfo>

Start a new recording.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn stop_record( &self, cortex_token: &str, session_id: &str, ) -> CortexResult<RecordInfo>

Stop an active recording.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn query_records( &self, cortex_token: &str, limit: Option<u32>, offset: Option<u32>, ) -> CortexResult<Vec<RecordInfo>>

Query recorded sessions.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn export_record( &self, cortex_token: &str, record_ids: &[String], folder: &str, format: ExportFormat, ) -> CortexResult<()>

Export a recording to CSV or EDF format.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn update_record_with( &self, cortex_token: &str, request: &UpdateRecordRequest, ) -> CortexResult<RecordInfo>

Update a recording’s metadata (title, description, tags).

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn update_record( &self, cortex_token: &str, record_id: &str, title: Option<&str>, description: Option<&str>, tags: Option<&[String]>, ) -> CortexResult<RecordInfo>

👎Deprecated: Use update_record_with and UpdateRecordRequest instead.

Update a recording’s metadata (title, description, tags).

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn delete_record( &self, cortex_token: &str, record_ids: &[String], ) -> CortexResult<Value>

Delete one or more recordings.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn get_record_infos( &self, cortex_token: &str, record_ids: &[String], ) -> CortexResult<Value>

Get detailed information for specific records by their IDs.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn config_opt_out( &self, cortex_token: &str, status: &str, new_opt_out: Option<bool>, ) -> CortexResult<Value>

Configure the opt-out setting for data sharing.

Use status: "get" to query, status: "set" with new_opt_out to change.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn download_record( &self, cortex_token: &str, record_ids: &[String], ) -> CortexResult<Value>

Request to download recorded data from the Emotiv cloud.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn inject_marker( &self, cortex_token: &str, session_id: &str, label: &str, value: i32, port: &str, time: Option<f64>, ) -> CortexResult<MarkerInfo>

Inject a time-stamped marker during an active recording.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn update_marker( &self, cortex_token: &str, session_id: &str, marker_id: &str, time: Option<f64>, ) -> CortexResult<()>

Update a marker to convert it from an instance marker to an interval marker.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn create_subject_with( &self, cortex_token: &str, request: &SubjectRequest, ) -> CortexResult<SubjectInfo>

Create a new subject.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn create_subject( &self, cortex_token: &str, subject_name: &str, date_of_birth: Option<&str>, sex: Option<&str>, country_code: Option<&str>, state: Option<&str>, city: Option<&str>, attributes: Option<&[Value]>, ) -> CortexResult<SubjectInfo>

👎Deprecated: Use create_subject_with and SubjectRequest instead.

Create a new subject.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn update_subject_with( &self, cortex_token: &str, request: &SubjectRequest, ) -> CortexResult<SubjectInfo>

Update an existing subject’s information.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn update_subject( &self, cortex_token: &str, subject_name: &str, date_of_birth: Option<&str>, sex: Option<&str>, country_code: Option<&str>, state: Option<&str>, city: Option<&str>, attributes: Option<&[Value]>, ) -> CortexResult<SubjectInfo>

👎Deprecated: Use update_subject_with and SubjectRequest instead.

Update an existing subject’s information.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn delete_subjects( &self, cortex_token: &str, subject_names: &[String], ) -> CortexResult<Value>

Delete one or more subjects.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn query_subjects_with( &self, cortex_token: &str, request: &QuerySubjectsRequest, ) -> CortexResult<(Vec<SubjectInfo>, u32)>

Query subjects with filtering, sorting, and pagination.

Returns a tuple of (subjects, total_count).

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn query_subjects( &self, cortex_token: &str, query: Value, order_by: Value, limit: Option<u32>, offset: Option<u32>, ) -> CortexResult<(Vec<SubjectInfo>, u32)>

👎Deprecated: Use query_subjects_with and QuerySubjectsRequest instead.

Query subjects with filtering, sorting, and pagination.

Returns a tuple of (subjects, total_count).

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn get_demographic_attributes( &self, cortex_token: &str, ) -> CortexResult<Vec<DemographicAttribute>>

Get the list of valid demographic attributes.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn query_profiles( &self, cortex_token: &str, ) -> CortexResult<Vec<ProfileInfo>>

List all profiles for the current user.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn get_current_profile( &self, cortex_token: &str, headset_id: &str, ) -> CortexResult<CurrentProfileInfo>

Get the profile currently loaded for a headset.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn setup_profile( &self, cortex_token: &str, headset_id: &str, profile_name: &str, action: ProfileAction, ) -> CortexResult<()>

Manage a profile (create, load, unload, save, rename, delete).

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn load_guest_profile( &self, cortex_token: &str, headset_id: &str, ) -> CortexResult<()>

Load an empty guest profile for a headset.

This unloads any currently loaded profile and loads a blank guest profile, useful for starting fresh without trained data.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn get_detection_info( &self, detection: DetectionType, ) -> CortexResult<DetectionInfo>

Get detection info for a specific detection type.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn training( &self, cortex_token: &str, session_id: &str, detection: DetectionType, status: TrainingStatus, action: &str, ) -> CortexResult<Value>

Control the training lifecycle for mental commands or facial expressions.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn mental_command_active_action( &self, cortex_token: &str, session_id: &str, actions: Option<&[&str]>, ) -> CortexResult<Value>

Get or set the active mental command actions.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn mental_command_action_sensitivity( &self, cortex_token: &str, session_id: &str, values: Option<&[i32]>, ) -> CortexResult<Value>

Get or set the mental command action sensitivity.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn mental_command_brain_map( &self, cortex_token: &str, session_id: &str, ) -> CortexResult<Value>

Get the mental command brain map.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn mental_command_training_threshold( &self, cortex_token: &str, session_id: &str, ) -> CortexResult<Value>

Get the mental command training threshold for an active session.

Cortex method: mentalCommandTrainingThreshold Required state: authenticated token and active session. Parameters: session_id selects the target session. Returns: raw JSON payload from Cortex. Related methods: Self::mental_command_training_threshold_with_params, Self::mental_command_training_threshold_for_profile.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn mental_command_training_threshold_for_profile( &self, cortex_token: &str, profile: &str, status: Option<&str>, value: Option<f64>, ) -> CortexResult<Value>

Get or set the mental command training threshold for a profile.

Set status to Some("set") and provide value to update. Use status = None (or Some("get")) to read the threshold.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn mental_command_training_threshold_with_request( &self, cortex_token: &str, request: &MentalCommandTrainingThresholdRequest, ) -> CortexResult<Value>

Get or set the mental command training threshold using a typed request.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn mental_command_training_threshold_with_params( &self, cortex_token: &str, session_id: Option<&str>, profile: Option<&str>, status: Option<&str>, value: Option<f64>, ) -> CortexResult<Value>

👎Deprecated: Use mental_command_training_threshold_with_request and MentalCommandTrainingThresholdRequest instead.

Get or set the mental command training threshold using either session or profile targeting.

Exactly one of session_id or profile must be provided. If status is None, this infers "get" when value is None, otherwise "set".

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn get_trained_signature_actions( &self, cortex_token: &str, detection: DetectionType, profile: Option<&str>, session: Option<&str>, ) -> CortexResult<TrainedSignatureActions>

Get a list of trained actions for a profile’s detection type.

Specify either profile (by name) or session (by ID), not both.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn get_training_time( &self, cortex_token: &str, detection: DetectionType, session_id: &str, ) -> CortexResult<TrainingTime>

Get the duration of a training session.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn facial_expression_signature_type_with( &self, cortex_token: &str, request: &FacialExpressionSignatureTypeRequest, ) -> CortexResult<Value>

Get or set the facial expression signature type.

Use status: "get" to query, status: "set" with signature to change. Specify either profile or session, not both.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn facial_expression_signature_type( &self, cortex_token: &str, status: &str, profile: Option<&str>, session: Option<&str>, signature: Option<&str>, ) -> CortexResult<Value>

👎Deprecated: Use facial_expression_signature_type_with and FacialExpressionSignatureTypeRequest instead.

Get or set the facial expression signature type.

Use status: "get" to query, status: "set" with signature to change. Specify either profile or session, not both.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn facial_expression_threshold_with( &self, cortex_token: &str, request: &FacialExpressionThresholdRequest, ) -> CortexResult<Value>

Get or set the threshold of a facial expression action.

Use status: "get" to query, status: "set" with value to change. Specify either profile or session, not both. The value range is 0–1000.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub async fn facial_expression_threshold( &self, cortex_token: &str, status: &str, action: &str, profile: Option<&str>, session: Option<&str>, value: Option<u32>, ) -> CortexResult<Value>

👎Deprecated: Use facial_expression_threshold_with and FacialExpressionThresholdRequest instead.

Get or set the threshold of a facial expression action.

Use status: "get" to query, status: "set" with value to change. Specify either profile or session, not both. The value range is 0–1000.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.

pub fn is_connected(&self) -> bool

Returns whether the reader loop is still running.

pub async fn stop_reader(&mut self)

Stop the reader loop.

pub async fn disconnect(&mut self) -> CortexResult<()>

Close the WebSocket connection.

Errors

Returns any error produced by the underlying Cortex API call, including connection, authentication, protocol, timeout, and configuration errors.