There are a few steps to prepare before you can get the data streaming out from Cortex web socket server:

1. First you have to login to the EMOTIV Launcher with your EmotivID.

2. Make sure that you are using the correct application ID, client ID and client secret that you generated from the Account dashboard on Emotiv website in your application (see here).

3. Call the API from your app to Cortex, and accept via the EMOTIV Launcher.

4. After access is granted, connect your EMOTIV brainwear headset via the USB dongle or Bluetooth.

5. Call the API with "refresh" command to start the headset scanning.

6. Call the API to list the available headsets.

7. Call the API with "connect" command to connect to the desire headset.

8. Call the API to get a Cortex token for subsequence requests.

9. Call the API to open up a new session and be ready for BCI data streaming.

After your application is successfully connected to the Cortex service, you must go through the authentication procedure.

First, you should call getUserLogin to check if the user has already logged in though EMOTIV Launcher. Then, you must call requestAccess to ask the user to approve your application.

Finally, call authorize to generate a Cortex token or you can reuse a token that you previously got from this method, if it is not expired.

Once the app authenticates with the Cortex successfully, it can use the Cortex token to stay offline while working with Cortex for a period of time (see soft limit, hard limit below).

Here is the recommended flow to work offline with Cortex:

Step 1: Follow this API flow to get Cortex token the first time. This flow requires the Internet connection. A Cortex token will be available for 48 hours.

Step 2: When the Cortex token is expired, call generateNewToken API to generate another token. This API doesn't require the Internet connection.

Step 3: Check soft limit, hard limit of the current license via getLicenseInfo API and warn the users to be online.

In the license information, there are 2 fields "softLimitTime" and "hardLimitTime".

softLimitTime

This is the reasonable time to warn users that the app will not be able to use offline soon. The app can still work offline until hardLimitTime.

hardLimitTime

This is the time that the app will be no longer to use offline. The app must call API with the Internet connection to be able to continue working with Cortex.

Request user approval for the current application through EMOTIV Launcher.

When your application calls this method for the first time, EMOTIV Launcher displays a message to approve your application. You can call this API many times, but EMOTIV Launcher will prompt the user only once. If the user has already approved your application, then this API does nothing.

Almost all the methods of the API require that your application was approved in EMOTIV Launcher. These methods will return an error if your application wasn't approved.

Parameters

Result

The result is an object containing a boolean value "accessGranted" and a message.

If accessGranted is false, then your application should ask the user to check EMOTIV Launcher and approve your application. Then you should wait for a while and call this API again. If accessGranted is true, then no action is required.

Examples

Application was already approved

Application is not approved yet, or declined

This documentation contains guidance for developing applications with EMOTIV Cortex - the core piece of technology at EMOTIV which brings the brain computer interface to consumer.

The intended audience is anyone with some programming skills who wants to develop a third party application that interacts with an EMOTIV headset.

The Cortex API is built on JSON and WebSockets, making it easy to access from a variety of programming languages and platforms.

System requirements and supported platforms

Learn more about .

Supported headsets

Currently, Cortex supports the following headsets:

USB dongle refers to the USB receiver that comes with EPOC+. If you need an additional receiver, you can purchase it from the EMOTIV.

Virtual Brainwear

In addition to physical EMOTIV headsets, users can create virtual headsets (a “Virtual Brainwear®”) using the EMOTIV Launcher, which emulates device states and data streams for development purposes.

Important caveat: Records captured using a virtual headset are local to that machine and will not be synced to another device or transferred between machines.

For more details on creating and using virtual devices, see “”

Prerequisites

Create an EmotivID

As with other EMOTIV services, you are required to have an EmotivID account. You can create an ID on .

License

If you’re ready to start developing with EMOTIV’s Cortex SDK, one of your first steps is registering your Cortex App ID. Whether you’re working with consumer devices like the Insight or MN8, or exploring options with professional-grade hardware such as the EPOC X or EPOC Flex, this guide will walk you through how to get started with consumer devices.

Understanding Cortex API Access Levels

EMOTIV’s Cortex SDK supports multiple EEG and behavioral data streams. These are grouped into Basic (BCI API) and Premium categories:

Basic (BCI API) Includes:

• Mental Commands API

• Facial Expression API

• Frequency Band API

• Motion Data API

Premium API Includes:

• Raw EEG API

• High-resolution Performance Metrics (2 Hz)

Consumer devices (Insight, MN8) will allow access to all data streams through our Developer SDK and API. You can register here to get started: . Professional devices (EPOC X and EPOC Flex) include free access to the Basic BCI API. To access the Premium API, however, a premium Developer API license is required. If you don't have a valid Developer API license, please submit your SDK application and specify the level of data stream you wish to access with your professional device. Our support team will then guide you on the appropriate licensing option to get started.

Create a Cortex App

To learn how to register your Cortex App ID and begin development, please refer to .

Client ID and Client Secret

Once you register your Cortex App ID, you will receive a Client ID and Client Secret, which serve as unique identifiers for your software application. These will be used as input parameters for some authentication Cortex API calls.

The "Client ID" and "Client Secret" similar to a username and password, are automatically generated by EMOTIV for each version of your software application.

The Cortex Examples

To help you getting started with your application, EMOTIV provides basic examples in various programming languages. There are open source and hosted by Github at

If you have difficulty with the Cortex API, you can also on this Github repository.

Next Step

If you are upgrading your application from Cortex 1.x to Cortex 2.x, then please be aware that the Cortex API has significantly changed. Please read the for details.

If you are new to the Cortex API, then please start with .

This method returns information about the Cortex service, like its version and build number.

Parameters

This method has no parameter.

Result

The result is an object with these fields:

Example

This method is to generate a Cortex access token. Most of the methods of the Cortex API require this token as a parameter.

Application can specify the license key and the amount of sessions to be debited from the license and use them locally.

Cortex token

The token is linked to your application. It cannot be used with another application. The token is also linked to the EmotivID of the current user. It cannot be used with another EmotivID. So if the user logs out in , and then logs in with another EmotivID, your application must call this API again to get a new token.

After you finish the authentication process, your application should start headset scanning to search for EMOTIV headsets, using the method controlDevice with "refresh" command, then use the method queryHeadsets to get the discovered headsets.

If the headset is not connected to Cortex yet, then you must call controlDevice with "connect" command.

See also Headset object for details.

Check if your application has been granted access rights or not in EMOTIV Launcher.

Parameters

Result

The result is an object containing a boolean value "accessGranted" and a message.

If accessGranted is false, then your application should call If accessGranted is true, then no action is required

Examples

This method returns basic information about the current user.

Parameters

Result

The result is an object containing basic information about the user.

Examples

Get the current logged in user.

Parameters

This method has no parameter.

Result

The result is an array of objects, each object describes a logged in user. If no user is logged in, then the result is an empty array.

Please note that currently, Cortex is a single user system. Only one user can login at a time, so the result contains at most one object.

The user object includes these fields:

If currentOSUId is equal to loggedInOSUId, then the user is already logged in and can work with Cortex. If currentOSUId is different from loggedInOSUId, then a user is logged into Cortex, but from a different OS account. So the user of the current OS account cannot work with Cortex, and must check EMOTIV Launcher.

Examples

No user is logged in

A user is logged in from the current OS account

A user is logged in from another OS account

The application is connected to Cortex that belongs to the OS account 501/jsnow. But someone has already logged in to Cortex from OS account 502/astark with the EmotivID aria.stark. So, the application cannot work with Cortex.

This method uses a Cortex token to generate a new Cortex token. You can use this method to extend the expiration date of a token.

See authorize for details.

Parameters

Result

The result is an object containing a field cortexToken.

Example

This method returns information about the license currently used by your application.

Parameters

Result

The result is an object containing a license object and the isOnline flag.

Example

This method lets you set the headband position of an EPOC X headset.

The headband position is important to interpret the motion data coming from the headset. The motion sensor is located in the headband. So Cortex uses the headband position to know the orientation of the motion sensor.

When you Cortex saves the current headband position into the record. So you should set the position before starting the record.

This method was added in Cortex 2.4

This method lets you synchronize the monotonic clock of your application with the monotonic clock of Cortex. It is an important step if you want to inject markers with a high precision.

Cortex uses a different clock for each headset and it initializes this clock when the headset is connected by Bluetooth or USB dongle. This means that:

• You must call “syncWithHeadsetClock” after the headset is connected, not before.

• You must provide a headset id.

• If the headset is disconnected and connected again, then you must call this method again.

The simplest solution is to call this method just before .

Use Case

Cortex sets the timestamps of each EEG sample using the of the computer. It is more reliable than using the system clock, because the system clock is subject to unpredictable variations, notably because of the synchronization.

When you to a record, Cortex uses the parameter "time" of your request to associate the marker with the EEG sample that has the closest timestamp. So if you want to have accurate markers, you should set the time of your markers using the monotonic clock, not the system clock.

Most programing languages provide a function to get a monotonic time. But in general, the point of origin of this time is undefined. So you need to synchronize the monotonic clock of your application with the monotonic clock used by Cortex. This is the purpose of this Cortex API method.

Parameters

This method takes 3 parameters:

Result

The result is a JSON object with these fields:

To synchronize your clock, you must add the “adjustment” to your monotonic times. If the “adjustment” is positive, then it means your clock is late compared to the Cortex clock. If the “adjustment” is negative, then your clock is ahead of the Cortex clock.

Example

This method is to connect or disconnect a headset. It can also refresh the list of available Bluetooth headsets returned by queryHeadsets.

Please note that connecting and disconnecting a headset can take a few seconds.

Before you call createSession on a headset, make sure that Cortex is connected to this headset. You can use queryHeadsets to check the connection status of the headset.

Parameters

Headset Scanning Flow

The app must call controlDevice with "refresh" command to start headset scanning. The timeout of scanning is around 20s. When the scanning finishes, Cortex will send a to the app. When received this warning, if the app still want to scan for headsets, simply call controlDevice with "refresh" command again.

Please note that headset scanning can affect to data stream quality if headset scanning is running at the same time with data stream subscription, so we recommend app developers to design the app so that we only run headset scanning when necessary.

EPOC Flex mapping

The mappings parameter is only to connect an EPOC Flex headset. Use this parameter to tell Cortex how you setup the EEG sensors of your EPOC Flex headset.

The keys for this object must be chosen from this list: "CMS", "DRL", "LA", "LB", "LC", "LD", "LE", "LF", "LG", "LH", "LJ", "LK", "LL", "LM", "LN", "LO", "LP", "LQ", "RA", "RB", "RC", "RD", "RE", "RF", "RG", "RH", "RJ", "RK", "RL", "RM", "RN", "RO", "RP", "RQ".

The keys "CMS" and "DRL" are required.

The values are sensor locations from the international 10-20 system: "Cz", "FCz", "Fz", "Afz", "Fpz", "Fp1", "AF3", "AF7", "F9", "F7", "F5", "F3", "F1", "FC1", "C1", "C3", "FC3", "FC5", "FT7", "FT9", "T7", "C5", "TP9", "TP7", "CP5", "CP3", "CP1", "P1", "P3", "P5", "P7", "P9", "PO9", "PO7", "PO3", "O1", "O9", "CPz", "Pz", "POz", "Oz", "Iz", "O10", "O2", "PO4", "PO8", "PO10", "P10", "P8", "P6", "P4", "P2", "CP2", "CP4", "CP6", "TP8", "TP10", "C6", "T8", "FT10", "FT8", "FC6", "FC4", "C4", "C2", "FC2", "F2", "F4", "F6", "F8", "F10", "AF8", "AF4", "Fp2".

Special EEG sensor mapping for EPOC Flex

By default, the streams "met", "com" and "fac" are not available for EPOC Flex. It is because Cortex doesn't implement the detections (performance metrics, mental command, facial expression) for EPOC Flex.

However, you can configure your EPOC Flex to simulate an EPOC X headset. In that case, Cortex runs the detections that are designed for EPOC X.

All you have to do is to use a sensor mapping that includes all the 14 EEG sensors of an EPOC X headset: AF3, F7, F3, FC5, T7, P7, O1, O2, P8, T8, FC6, F4, F8, AF4. In addition, you should use P3 and P4 as references CMS and DRL. Please see the EPOC X for the complete EPOC X configuration.

Your mapping can also include sensors that are not present on an EPOC X. Cortex will not use these additional sensors to run the detections, but you can use them to collect more EEG data.

There are two methods for creating the mapping for EPOC Flex:

1. Using the EMOTIV Launcher, which can be accessed .

2. Using the configMapping API, available .

Example of special EEG sensor mapping:

This feature was added in Cortex 2.7.1

Connection Type

You can use this parameter together with the command "connect", to force Cortex to use the specified connection type. For example, an EPOC+ headset can be connected by dongle or by Bluetooth. If both connections are available on your computer then you may want to set connectionType to "dongle" so you don't accidentally connect the headset with Bluetooth.

Result

The result is an object containing these fields:

When the command is "connect", then the result of this method just tells you that the connection is in progress. You must wait for a warning object with to know that the connection is successful. If the connection fails then you will receive a warning with .

Another way to check if the headset is connected or not is to call and then check the status of the headset.

Examples

Refresh the list of headsets

Use the refresh command to start searching for new Bluetooth headsets.

Then you will receive a when scanning is finished.

Connect an Insight headset

Then you will receive a warning with code 104 if the connection is successful:

Connect an Epoc Flex headset

Disconnect a headset

This method lets you change the settings of an EPOC+ or EPOC X headset.

You can configure the EEG sample rate, EEG resolution, motion data sample rate, and motion data resolution. You can check the current settings of a headset using the method queryHeadsets.

This method is for EPOC+ and EPOC X headsets only. There are no configuration settings for other EMOTIV headsets.

Please note that updating the configuration of a headset can take a few seconds.

Parameters

The setting parameter must be an object with these fields:

Result

The result is an object containing these fields:

In Cortex 2.3.0 and earlier, you just need to check the result of the method. If the method doesn't return any error, then it means that the update is successful.

However, since Cortex 2.4.0, the result of the method just tells you that the update is in progress. You must wait for a warning object with to know if the update is successful or not.

If your configuration is not compatible with a Bluetooth connection then you will receive a warning with . Your configuration will work fine with a USB dongle. To use the headset with a Bluetooth connection, you must set the EEG rate to 128Hz and disable the motion sensors.

Examples

Set the EEG rate to 256 hertz (16 bits) and the motion rate to 64 hertz (16bits)

Set the EPOC+ headset in EPOC mode, EEG rate at 128 hertz (14 bits) and disable the motion sensors.

The configMapping API manages EEG channel mapping configurations for a EPOC Flex headset. This API allows you to create, get, read, update and delete mapping configurations.

To connect to an EPOC Flex headset, you must input a specific EEG channel mapping or the name of an existing mapping for the current Emotiv user.

Parameters

Status create

Create a new sensor mapping for EPOC Flex. The configuration will be added to list EEG sensor mapping configuration of current emotiv user, can be synced to other machine. Requires: cortexToken, status="create", name, and mappings.

Example

Status get

Retrieve all mapping configurations for the current Emotiv user. Requires: cortexToken, status="get".

Example

Status read

Read the details of a specific configuration. Requires: cortexToken, status="read", uuid.

Example

Status update

To update an existing mapping configuration. Requires: cortexToken, status, and uuid.

The name and mappings are optional parameters:

• If name is included, the configuration name will be updated.

• If mappings is included, the mappings will be updated.

• If both are included, both fields will be updated.

Example

Status delete

Delete a mapping configuration. Requires: cortexToken, status="delete", uuid.

Example

On Windows and MacOS, the Cortex service is a background process that communicates with the EMOTIV headsets and the EMOTIV cloud. It is also a WebSocket server that uses the JSON-RPC protocol.

WebSocket

Communicate with the Cortex API using the WebSocket Secure protocol.

Create a WebSocket client and connect to localhost on the port 6868, using the wss protocol.

Any WebSocket client should work in any programming language. You can even use a web browser plugin or an .

Please note that Cortex only supports the WebSocket Secure (wss) protocol. It doesn't support the plain WebSocket (ws) protocol without encryption.

Cortex security certificate

The Cortex web socket server uses a self-signed certificate. When you install Emotiv softwares, the installer has already installed the Emotiv Root CA file and ask the system to trust it, so most of the time, your application don't need to configure anything else. However, for some programming languagues or for remote connections to Pi, you must configure a custom Certificate Authorities (CA) to trust Cortex websocket connection.

For example, on Android, you must configure the application like or if you use python, you can configure the application like .

Here is .

Remote connections

Since 2.7.1 release, we support remote connections to Cortex running on Raspberry Pi device. It requires some steps:

• Grant the permissions to a desktop machine before an app on that machine can connect to the Cortex web socket server on Raspberry Pi device, using tool.

• Connect using the IP address:

  • Only applied if the IP address of your Raspberry Pi device is in the below range:

JSON-RPC

After you have successfully opened the WebSocket connection, communicate with Cortex using the protocol.

Call methods, with or without parameters, and Cortex sends back a result or an error.

Call an API method by sending a JSON object with these fields:

The response from Cortex is a JSON object with these fields:

Here is a simple fictional example:

Please read the for details.

Test API request and response

You can try with the most simple API of Cortex: .

Next step

The rest of this documentation will show you what methods are available, what parameters they take, and how to use these methods.

But first, you should start with the .

A session is an object that makes the link between your application and an EMOTIV headset. When the user wants to work with a headset, your application should create a session first. Then you can:

• subscribe to the data stream of the headset

• create a record and add markers

• use

Your application can open only one session at a time with a given headset. But it can open multiple sessions with multiple headsets.

Session lifetime

A session is created by and closed by .

A session is linked to an application. All the sessions of an application are automatically closed when the application is disconnected from the Cortex service. A session is also closed if the headset is disconnected.

A session is a temporary in-memory object, it is not persistent. After a session is closed, it is destroyed by Cortex. If you want to create a persistent object, please inside your session. See for details.

Session activation

When you create a session, you can activate it or leave as is.

If the session is not activated, then it doesn't use the license of the user. You cannot subscribe to the EEG stream and you are limited to the low resolution performance metrics. You can neither create a nor .

If the session is activated, then it uses the license of the user. Depending on the license scope of the license, you can subscribe to the EEG stream or high resolution performance metrics. If the license has a session quota, then this session will be debited from this quota.

Use and check the field status to know if a session was activated or not.

Some methods of the API return one or more headset objects, for example queryHeadsets. A session object also includes a headset object.

Description

A headset object include these fields:

Status

When you want to work with a headset, it is important to check its status.

Settings

The settings object include these fields:

For an Epoc+ headset, the mode can be "EPOC" or "EPOCPLUS", depending on its configuration. See for details. For an Insight or Epoc headset, the mode is always "EPOC". For an Epoc Flex headset, the mode is always "EPOCFLEX".

Flex Mapping

Currently, the flexMappings object contains a single field. It may include more fields in the future.

Examples

Insight

Epoc+

Virtual MN8

Discover details about headsets connected to your device via USB dongle, USB cable, or Bluetooth or virtual headsets enabled through the EMOTIV Launcher. Additionally, search for a specific headset using its ID or apply a wildcard for partial matches.

Parameters

For the parameter id, you can use these wildcards:

Result

The result is an array of , or an empty array if no headset matches the request.

Examples

Query all the headsets

If no headset matches your request, then the result is an empty array.

Query a headset by its id

Query all the Insight headsets

A session is the link between your application and a headset.

You must create a session before you call subscribe to receive data from a headset. See createSession.

Description

A session object includes these fields:

Status

The status is linked to the license. If the session is activated, it will be debited from the quota of the user's license.

Examples

A session with an Epoc+ headset. It is not activated. We subscribed to the performance metrics and motion data.