arrow-left

Only this pageAll pages
gitbookPowered by GitBook
1 of 75

Cortex API V4

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Overview of API flow

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.

Authentication

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 Launcherarrow-up-right. 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.

requestAccess
controlDevice
queryHeadsets
controlDevice
authorize
createSession

Offline support

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".

hashtag
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.

hashtag
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.

circle-info

The softLimitTime will be at least 1 month later from the time the app calls API. The hardLimitTime is 7 days after softLimitTime.

requestAccess

Request user approval for the current application through EMOTIV Launcherarrow-up-right.

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.

circle-check

Any application that connects to Cortex must call this API to request approval from the user through .

triangle-exclamation

Most of the methods of the API will fail if the user didn't approve your application.

hashtag
Parameters

hashtag
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.

hashtag
Examples

hashtag
Application was already approved

hashtag
Application is not approved yet, or declined

Getting Started

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.

hashtag
System requirements and supported platforms

Learn more about .

hashtag
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.

circle-info

Currently, it is not possible to use a Flex or a MN8 headset with Cortex on Raspberry Pi.

hashtag
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 “”

hashtag
Prerequisites

hashtag
Create an EmotivID

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

hashtag
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.

hashtag
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.

hashtag
Create a Cortex App

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

hashtag
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.

hashtag
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.

hashtag
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 .

getCortexInfo

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

hashtag
Parameters

This method has no parameter.

hashtag
Result

The result is an object with these fields:

hashtag
Example

authorize

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.

hashtag
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.

authorize
authorize

Name

Type

Description

buildDate

string (date time)

The date and time the Cortex binary was built

buildNumber

string

The internal build number

version

string

The version of Cortex. It should have the format "2.y.z"

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getCortexInfo"
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "buildDate":"2019-05-29T14:09:19",
        "buildNumber":"25cf08bd",
        "version":"2.0.0"
    }
}

Headsets

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.

Name

Type

Required

Description

clientId

string

yes

The client id of your Cortex application

clientSecret

string

yes

The client secret of your Cortex application

Name

Type

Description

accessGranted

boolean

True, if the user has already approved your application False, if the user declined your application, or didn't approve it yet

message

string

EMOTIV Launcherarrow-up-right
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "requestAccess",
    "params": {
        "clientId": "xxx",
        "clientSecret": "xxx"
    }
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "accessGranted":true,
        "message":"The User has granted access right to this application."
    }
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "requestAccess",
    "params": {
        "clientId": "xxx",
        "clientSecret": "xxx"
    }
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "accessGranted":false,
        "message":"The User has not granted access right to this application. Please use Emotiv App to proceed."
    }
}

USB dongle, BLE 4.0

Insight

All

USB dongle, BLE 4.0

All

BLE 4.0

All

BLE 4.0

All

nRF dongle with BLE 5, BLE 5.x

Low-resolution Performance Metrics (0.1 Hz)

Model

Firmware

Connection

EPOC

All

USB dongle

EPOC+arrow-up-right

All

USB dongle, BLE 4.0

EPOC Xarrow-up-right

All

USB dongle, BLE 4.0

Bluetooth® 5.0 will be available with upcoming software and firmware updates

EPOC Flexarrow-up-right

the system requirements and support platforms for Cortexarrow-up-right
storearrow-up-right
Devices - Setting up virtual Brainwear®arrow-up-right
www.emotiv.comarrow-up-right
https://www.emotiv.com/pages/developerarrow-up-right
herearrow-up-right
this guidearrow-up-right
https://github.com/Emotiv/cortex-v2-examplearrow-up-right
open an issuearrow-up-right
release notes
Connecting to the Cortex API

All

Your application can save the Cortex token and reuse it later, within 2 days. Note that it is the responsibility of the application to secure the token.

triangle-exclamation

The Cortex token must remain secret. Do NOT share it. It is your responsibility to keep it secure.

Once having Cortex token, the app can work offline with Cortex.

hashtag
EULA not accepted warning

If the user has not accepted the EULA, then a warning message will be included in the response as well. The user must accept the EULA through EMOTIV Launcher.

circle-info

Before you call this method, the user must approve your application in EMOTIV Launcherarrow-up-right. See requestAccess for details.

hashtag
Parameters

Name

Type

Required

Description

clientId

string

yes

The client id of your Cortex application.

clientSecret

string

yes

The client secret of your Cortex application.

license

hashtag
Result

The result is an object containing a field cortexToken. It may also include a field warning, if the user didn't accept the EULA.

Name

Type

Description

cortexToken

string

The Cortex token of the user

warning

object

Contains a message and the URL to accept the EULA

hashtag
Examples

EMOTIV Launcherarrow-up-right

hasAccessRight

Check if your application has been granted access rights or not in EMOTIV Launcherarrow-up-right.

circle-check

Any application that connects to Cortex must request approval from the user through EMOTIV Launcherarrow-up-right. See requestAccess for details.

hashtag
Parameters

hashtag
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

hashtag
Examples

getUserInformation

This method returns basic information about the current user.

hashtag
Parameters

Name

Type

Required

Description

hashtag
Result

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

hashtag
Examples

getUserLogin

Get the current logged in user.

circle-check

There is no login or logout API in Cortex. Instead, users are required to login through the EMOTIV Launcherarrow-up-right.

hashtag
Parameters

This method has no parameter.

hashtag
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.

hashtag
Examples

hashtag
No user is logged in

hashtag
A user is logged in from the current OS account

hashtag
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.

generateNewToken

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.

hashtag
Parameters

Name

hashtag
Result

The result is an object containing a field cortexToken.

hashtag
Example

getLicenseInfo

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

hashtag
Parameters

Name

Type

Required

Description

hashtag
Result

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

hashtag
Example

updateHeadsetCustomInfo

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

hashtag

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "authorize",
    "params": {
        "clientId": "xxx",
        "clientSecret": "xxx"
    }
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "cortexToken":"xxx",
        "warning": {
            "code": 6,
            "message": "...",
            "licenseUrl": "https://..."
        }
    }
}

string

no

A license id. In most cases, you don't need to specify the license id. Cortex will find the appropriate license based on the client id.

debit

number

no

Number of sessions to debit from the license, so that it can be spent locally without having to authorize again. You need to debit the license only if you want to activate a session. The default value is zero.

Name

Type

Required

Description

clientId

string

yes

The client id of your Cortex application

clientSecret

string

yes

The client secret of your Cortex application

Name

Type

Description

accessGranted

boolean

True, if the user has already approved your application False, if the user declined your application, or didn't approve it yet

message

string

requestAccess
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "hasAccessRight",
    "params": {
        "clientId": "xxx",
        "clientSecret": "xxx"
    }
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "accessGranted":true,
        "message":"The User has granted access right to this application."
    }
}

Type

Required

Description

cortexToken

string

yes

A token returned by authorize

clientId

string

yes

The client id of your Cortex application

clientSecret

string

yes

The client secret of your Cortex application

Name

Type

Description

cortexToken

string

The new Cortex token of the user

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "generateNewToken",
    "params": {
        "cortexToken": "xxx",
        "clientId": "...",
        "clientSecret": "..."
    }
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "cortexToken": "yyy"
    }
}

An object that contain information about the EULA agreement

cortexToken

string

yes

A token returned by authorize

Name

Type

Description

username

string

The EmotivID of the user

firstName

string

The first name of the user

lastName

string

The last name of the user

licenseAgreement

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getUserInformation",
    "params": {
        "cortexToken": "xxx"
    }
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "username": "jon.snow",
        "firstName": "Jon",
        "lastName": "Snow",
        "licenseAgreement": {
            "accepted": true,
            "licenseUrl": "https://..."
        }
    }
}

object

The id of the OS account used to login in EMOTIV Launcher

loggedInOSUsername

string

The user name for loggedInOSUId

lastLoginTime

string (ISO datetime)

When this user logged in for the last time.

This field was added in Cortex 2.3.0

Name

Type

Description

username

string

The EmotivID of the user

currentOSUId

string

The id of the current OS account

currentOSUsername

string

The user name for currentOSUId

loggedInOSUId

string

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getUserLogin"
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": []
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getUserLogin"
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [{
        "currentOSUId":"501",
        "currentOSUsername":"jsnow",
        "lastLoginTime": "2019-11-28T12:09:17.300+07:00",
        "loggedInOSUId":"501",
        "loggedInOSUsername":"jsnow",
        "username":"jon.snow"
    }]
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getUserLogin"
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [{
        "currentOSUId":"501",
        "currentOSUsername":"jsnow",
        "lastLoginTime": "2019-11-28T12:09:17.300+07:00",
        "loggedInOSUId":"502",
        "loggedInOSUsername":"astark",
        "username":"aria.stark"
    }]
}
Parameters

Name

Type

Required

Description

cortexToken

string

yes

A token returned by .

headsetId

string

yes

A headset id returned by .

headbandPosition

hashtag
Result

The result is an object containing these fields:

Name

Type

Description

headsetId

string

The headset id used in the request.

customName

string

The custom name of the headset.

headbandPosition

string

The position of the headband. Can be "back" or "top".

hashtag
Examples

start a record

cortexToken

string

yes

A token returned by authorize

Name

Type

Description

license

object

An object containing all the information about the current license

isOnline

boolean

True, if Cortex was able to get the license information from the EMOTIV cloud

False, if Cortex got the license information for its local cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getLicenseInfo",
    "params": {
        "cortexToken": "xxx"
    }
}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "isOnline":true,
        "license":{
            "applications":["com.emotiv.emotivpro"],
            "billingFrom":"2018-08-23T07:00:00.000+07:00",
            "billingTo":"2019-09-23T07:00:00.000+07:00",
            "deviceInfo":{
                "deviceLimit":15,
                "devicesPerSeat":3,
                "sessionLimit":{"day":null,"month":null,"year"
            },
            "expired":false,
            "extenderLimit":30,
            "hardLimitTime":"2019-07-01T06:59:59.999+07:00",
            "isCommercial":false,
            "licenseId":"xxx",
            "licenseName":"PRO license",
            "localQuota":0,
            "maxDebit":null,
            "scopes":["eeg","pm"],
            "seatCount":5,
            "sessionCount":0,
            "softLimitTime":"2019-06-24T06:59:59.999+07:00",
            "totalDebit":0,
            "totalRegisteredDevices":1,
            "validFrom":"2018-08-23T07:00:00.000+07:00",
            "validTo":"2019-09-24T06:59:59.999+07:00"
        }
    }
}
Insight 2.0arrow-up-right
MN8arrow-up-right

syncWithHeadsetClock

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 .

hashtag
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.

hashtag
Parameters

This method takes 3 parameters:

Name
Type
Required
Description

hashtag
Result

The result is a JSON object with these fields:

Name
Type
Description

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.

hashtag
Example

controlDevice

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.

circle-info

This method is not available on iOS. On iOS the user must connect and disconnect the headset in EMOTIV App.

hashtag
Parameters

hashtag
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.

hashtag
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".

hashtag
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

hashtag
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.

hashtag
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.

hashtag
Examples

hashtag
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.

hashtag
Connect an Insight headset

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

hashtag
Connect an Epoc Flex headset

hashtag
Disconnect a headset

updateHeadset

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.

circle-info

The user must connect the headset to the computer by using a USB cable before calling this method. You can't configure the headset through a wireless connection. You can use to check how the headset is connected.

hashtag
Parameters

The setting parameter must be an object with these fields:

circle-info

A motion rate of zero means that the motion sensors are disabled.

hashtag
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.

hashtag
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.

configMapping

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.

hashtag
Parameters

hashtag
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

hashtag
Status get

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

Example

hashtag
Status read

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

Example

hashtag
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

hashtag
Status delete

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

Example

Connecting to the Cortex API

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 WebSocketarrow-up-right server that uses the JSON-RPCarrow-up-right protocol.

hashtag
WebSocket

Communicate with the Cortex API using the WebSocket Securearrow-up-right 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.

circle-info

To try the Cortex API, open a secure WebSocket connection to wss://localhost:6868 and send the message {"id":1,"jsonrpc":"2.0","method":"getCortexInfo"}

hashtag
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 .

hashtag
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:

circle-info

Please note that websocket server on Raspberry Pi accepts only 1 remote connection at a time (not counting the remote connection from EMOTIVApp).

hashtag
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.

hashtag
Test API request and response

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

hashtag
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 .

Sessions

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.

hashtag
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.

hashtag
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.

Headset object

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

hashtag
Description

A headset object include these fields:

Name

hashtag
Status

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

hashtag
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".

circle-info

A motion rate of zero means that the motion sensors are disabled.

hashtag
Flex Mapping

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

hashtag
Examples

hashtag
Insight

hashtag
Epoc+

hashtag
Virtual MN8

queryHeadsets

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.

hashtag
Parameters

Name

Type

Required

For the parameter id, you can use these wildcards:

hashtag
Result

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

hashtag
Examples

hashtag
Query all the headsets

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

hashtag
Query a headset by its id

hashtag
Query all the Insight headsets

Session object

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.

hashtag
Description

A session object includes these fields:

hashtag
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.

hashtag
Examples

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "updateHeadsetCustomInfo",
  "params": {
    "cortexToken": "xxx",
    "headbandPosition": "top",
    "headsetId": "EPOCX-12345678"
  }
}
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "customName": "Epoc 1",
    "headbandPosition": "top",
    "headsetId": "EPOCX-12345678",
    "message": "Update headset customized information successfully."
  }
}
:
null
}
BCI
createSession
updateSession
create a record
Records
record
markers
querySessions

string

yes

Must be "back" or "top".

authorize
queryHeadsets

yes

The system time of your application. It must be the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970 UTC.

You should get this time right before you call this API.

headset

string

yes

The headset id.

Use queryHeadset to list available headsets.

monotonicTime

number

yes

The monotonic time of your application. The unit is in seconds. The origin can be anything.

You should get this time right before you call this API.

systemTime

headset

string

The headset id.

adjustment

number

The difference between the monotonic clock of your application and the monotonic clock of the headset.

The unit is in seconds.

creating a record
monotonic clockarrow-up-right
NTParrow-up-right
add a marker

number

yes

An object containing the setting to apply. See below.

yes

The motion sample rate, in hertz.

If the mode is "EPOC", then the motion rate must be 0.

If the mode is "EPOCPLUS", then the motion rate can be 0, 32, 64 or 128.

Name

Type

Required

Description

cortexToken

string

yes

A token returned by authorize.

headset

string

yes

A headset id returned by queryHeadsets.

setting

Name

Type

Required

Description

mode

string

yes

Must be "EPOC" or "EPOCPLUS".

In "EPOC" mode, the EEG resolution is 14 bits.

In "EPOCPLUS" mode, the EEG and motion resolutions are 16 bits.

eegRate

number

yes

The EEG sample rate, in hertz. If the mode is "EPOC", then the EEG rate must be 128.

If the mode is "EPOCPLUS", then the EEG rate can be 128 or 256.

memsRate

Name

Type

Description

headsetId

string

The headset id you set in the parameters.

message

string

A success message.

queryHeadsets
code 110 or 111
code 112

object

number

  • 10.[0-1].[0-2].[0-255]

  • 172.[16-17].[0-2].[0-255]

  • 192.168.[0-5].[0-255]

  • Create a WebSocket client and connect to<IP address of Raspberry Pi device>

    on the port 6868, using the wss protocol.

  • Connect using the DNS name:

    • Can be applied for any value of IP address of your Raspberry Pi device.

    • Add this line into the host file of the desktop machine:<IP address of Raspberry Pi device> emotiv-cortex.remote

    • Create a WebSocket client and connect to emotiv-cortex.remote on the port 6868, using the wss protocol.

  • no

    The parameters of the method, if it has any

    id

    number or string

    no

    The id of this request. Cortex will include this id into the response message, so you can can match the response with the request

    The id you included in the request

    Name

    Type

    Required

    Description

    jsonrpc

    string

    yes

    Must be "2.0"

    method

    string

    yes

    The name of the API method you want to call

    params

    Name

    Type

    Description

    jsonrpc

    string

    Is always "2.0"

    result

    any

    If the method is successful, contains the result of the method. The type depends on the method

    error

    object

    If the method failed, contains an error code and an error message

    id

    online clientarrow-up-right
    thisarrow-up-right
    thisarrow-up-right
    the link to the Emotiv Root CA filearrow-up-right
    cortexaccess
    JSON-RPC 2.0arrow-up-right
    JSON-RPC 2.0 specificationarrow-up-right
    getCortexInfo
    overview of the API flow

    object

    number or string

    The motion data sample rate, in hertz.

    memsRes

    number

    The motion data resolution, in bits.

    Type

    Description

    id

    string

    The id of this headset.

    status

    string

    Can be "discovered", "connecting", or "connected".

    connectedBy

    string

    Can be "bluetooth", "dongle", "usb cable", or "extender".

    dongle

    string

    The version of the dongle firmware.

    firmware

    string

    The version of the headset firmware.

    motionSensors

    array of strings

    The names of the motion sensors of this headset.

    sensors

    array of strings

    The names of the EEG sensors of this headset. Use the international 10-20 system.

    settings

    object

    An object containing the configuration of the EEG and motion data of this headset.

    flexMappings

    object

    If the headset is an EPOC Flex, then this field is an object containing information about the mapping of the EEG channels.

    headbandPosition

    string

    If the headset is an EPOC X, then this field tells you the position of the headband of this headset. Can be "back" or "top". If the headset is not an EPOC X, then this field is null. See updateHeadsetCustomInfo for details.

    This field was added in Cortex 2.4

    customName

    string

    The custom name of the headset. The user can set it in EMOTIV Launcher.

    This field was added in Cortex 2.4

    isVirtual

    boolean

    True if the headset is a virtual Brainwear. False otherwise.

    Status

    Description

    discovered

    Cortex has detected the headset, but it is not connected. You cannot create a session for a discovered headset. You can call controlDevice to connect the headset.

    connecting

    Cortex is trying to connect to this headset. This can take a few seconds.

    connected

    Cortex is connected to and receives data from this headset. You can call createSession and start working with this headset.

    You can call controlDevice to disconnect the headset.

    Name

    Type

    Description

    mode

    string

    Can be "EPOC", "EPOCPLUS", or "EPOCFLEX"

    eegRate

    number

    The EEG sample rate, in hertz.

    eegRes

    number

    The EEG resolution, in bits.

    memsRate

    Name

    Type

    Description

    mappings

    object

    Describe which EEG channel is mapped to which physical connector of EPOC Flex device. The keys are the names of the connectors, the values are the names of the EEG channels.

    Example: { "CMS": "TP8", "DRL": "P6", "RM": "TP10", "RN": "P4", "RO": "P8" }

    updateHeadset

    number

    Description

    id

    string

    No

    A headset id or a wildcard

    includeFlexMappings

    boolean

    No

    Set this parameter to true to include the mapping of each EPOC FLEX headset in the result headset object.

    Wildcard

    Filter

    INSIGHT-*

    All Insight headsets

    EPOC-*

    All Epoc headsets

    EPOCPLUS-*

    All Epoc Plus headsets

    headset objects
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "queryHeadsets"
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": [
            {
                "connectedBy": "dongle",
                "customName": "",
                "dongle": "6ff",
                "firmware": "625",
                "id": "EPOCPLUS-3B9AXXXX",
                "motionSensors": [
                    "GYROX",
                    "GYROY",
                    "GYROZ",
                    "ACCX",
                    "ACCY",
                    "ACCZ",
                    "MAGX",
                    "MAGY",
                    "MAGZ"
                ],
                "sensors": [
                    "AF3",
                    "F7",
                    "F3",
                    "FC5",
                    "T7",
                    "P7",
                    "O1",
                    "O2",
                    "P8",
                    "T8",
                    "FC6",
                    "F4",
                    "F8",
                    "AF4"
                ],
                "settings": {
                    "eegRate": 256,
                    "eegRes": 16,
                    "memsRate": 64,
                    "memsRes": 16,
                    "mode": "EPOCPLUS"
                },
                "status": "connected"
            }
        ]
    }

    Name

    Type

    Description

    id

    string

    The id of this session.

    status

    string

    Can be "opened", "activated", or "closed".

    owner

    string

    The EmotivID of the user.

    license

    string

    The id of the license used by this session. Or an empty string if the session wasn't activated.

    appId

    string

    The application id of your Cortex app.

    started

    string (ISO datetime)

    When this session was created.

    stopped

    string (ISO datetime)

    When this session was closed.

    streams

    array of strings

    The data streams you subscribed to. See subscribe.

    recordIds

    array of strings

    The ids of all the records created by this session. See createRecord.

    recording

    boolean

    True if a record is currently in progress for this session. False otherwise.

    headset

    object

    A headset object. It contains information about the headset linked to this session.

    Status

    Description

    opened

    The session was created with createSession, but it doesn't use a license. You can activate or close this session with updateSession.

    activated

    The session was activated with a license. You can close this session with updateSession.

    closed

    This session is closed, you cannot use it anymore.

    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "syncWithHeadsetClock",
      "params": {
        "headset": "INSIGHT-587XX4BB",
        "monotonicTime": 321.445,
        "systemTime": 1629978090.302
      }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": {
        "adjustment": 1629977768.86108,
        "headset": "INSIGHT-587XX4BB"
      }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "updateHeadset",
        "params": {
            "cortexToken": "xxx",
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "setting": {
                "mode": "EPOCPLUS",
                "eegRate": 256,
                "memsRate": 64
            }
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "message": "..."
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "updateHeadset",
        "params": {
            "cortexToken": "xxx",
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "setting": {
                "mode": "EPOC",
                "eegRate": 128,
                "memsRate": 0
            }
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "message": "..."
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "area",
        "params": {
            "width": 6,
            "length": 7
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": 42
    }
    {
      "id": "INSIGHT-AAAA0000",
      "status": "connected",
      "connectedBy": "dongle",
      "customName": "",
      "dongle": "6ff",
      "firmware": "930",
      "motionSensors": [
        "Q0",
        "Q1",
        "Q2",
        "Q3",
        "ACCX",
        "ACCY",
        "ACCZ",
        "MAGX",
        "MAGY",
        "MAGZ"
      ],
      "sensors": [
        "AF3",
        "T7",
        "Pz",
        "T8",
        "AF4"
      ],
      "settings": {
        "eegRate": 128,
        "eegRes": 14,
        "memsRate": 64,
        "memsRes": 14,
        "mode": "INSIGHT"
      },
      "isVirtual": false
    }
    {
        "id": "EPOCPLUS-3B9AXXXX",
        "status": "connected",
        "connectedBy": "dongle",
        "customName": "",
        "dongle": "6ff",
        "firmware": "625",
        "motionSensors": [
            "GYROX",
            "GYROY",
            "GYROZ",
            "ACCX",
            "ACCY",
            "ACCZ",
            "MAGX",
            "MAGY",
            "MAGZ"
        ],
        "sensors": [
            "AF3",
            "F7",
            "F3",
            "FC5",
            "T7",
            "P7",
            "O1",
            "O2",
            "P8",
            "T8",
            "FC6",
            "F4",
            "F8",
            "AF4"
        ],
        "settings": {
            "eegRate": 256,
            "eegRes": 16,
            "memsRate": 64,
            "memsRes": 16,
            "mode": "EPOCPLUS"
        },
        "isVirtual": false
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": [
        {
          "connectedBy": "bluetooth",
          "customName": "virtual mn8",
          "dfuTypes": ["dfuNone"],
          "dongle": "0",
          "firmware": "23",
          "firmwareDisplay": "0x23",
          "headbandPosition": null,
          "id": "MN8-2DC3C2D9",
          "isDfuMode": false,
          "isVirtual": true,
          "motionSensors": ["Q0", "Q1", "Q2", "Q3"],
          "sensors": ["T7", "T8"],
          "settings": {
            "eegRate": 128,
            "eegRes": 14,
            "memsRate": 6,
            "memsRes": 10,
            "mode": "MN8"
          },
          "status": "connected",
          "virtualHeadsetId": "2dc3c2d9-cfe1-461b-983b-f187437b91e0"
        }
      ]
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "queryHeadsets"
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": []
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "queryHeadsets",
        "params": {
            "id": "EPOCPLUS-3B9AXXXX"
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": [
            {
                "connectedBy": "dongle",
                "customName": "",
                "dongle": "6ff",
                "firmware": "625",
                "id": "EPOCPLUS-3B9AXXXX",
                "motionSensors": [
                    "GYROX",
                    "GYROY",
                    "GYROZ",
                    "ACCX",
                    "ACCY",
                    "ACCZ",
                    "MAGX",
                    "MAGY",
                    "MAGZ"
                ],
                "sensors": [
                    "AF3",
                    "F7",
                    "F3",
                    "FC5",
                    "T7",
                    "P7",
                    "O1",
                    "O2",
                    "P8",
                    "T8",
                    "FC6",
                    "F4",
                    "F8",
                    "AF4"
                ],
                "settings": {
                    "eegRate": 256,
                    "eegRes": 16,
                    "memsRate": 64,
                    "memsRes": 16,
                    "mode": "EPOCPLUS"
                },
                "status": "connected"
            }
        ]
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "queryHeadsets",
        "params": {
            "id": "INSIGHT-*"
        }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": [
        {
          "id": "INSIGHT-AAAA0000",
          "status": "connected",
          "connectedBy": "dongle",
          "customName": "",
          "dongle": "6ff",
          "firmware": "930",
          "headbandPosition": null,
          "motionSensors": [
            "Q0",
            "Q1",
            "Q2",
            "Q3",
            "ACCX",
            "ACCY",
            "ACCZ",
            "MAGX",
            "MAGY",
            "MAGZ"
          ],
          "sensors": [
            "AF3",
            "T7",
            "Pz",
            "T8",
            "AF4"
          ],
          "settings": {
            "eegRate": 128,
            "eegRes": 14,
            "memsRate": 64,
            "memsRes": 14,
            "mode": "INSIGHT"
          }
        }
      ]
    }
    {
        "id": "8bfc26de-754b-4c1f-9771-acfd1a7da02c",
        "status": "opened",
        "owner": "jon.snow",
        "license": "",
        "appId": "com.jon.snow.winterfell-app",
        "started": "2019-05-29T14:18:45.108+07:00",
        "stopped": "",
        "headset": {
            "status": "connected"
            "connectedBy": "dongle",
            "customName": "",
            "dongle": "6ff",
            "firmware": "625",
            "id": "EPOCPLUS-3B9AXXXX",
            "motionSensors": [
                "GYROX",
                "GYROY",
                "GYROZ",
                "ACCX",
                "ACCY",
                "ACCZ",
                "MAGX",
                "MAGY",
                "MAGZ"
            ],
            "sensors": [
                "AF3",
                "F7",
                "F3",
                "FC5",
                "T7",
                "P7",
                "O1",
                "O2",
                "P8",
                "T8",
                "FC6",
                "F4",
                "F8",
                "AF4"
            ],
            "settings": {
                "eegRate": 256,
                "eegRes": 16,
                "memsRate": 64,
                "memsRes": 16,
                "mode": "EPOCPLUS"
            }
        },
        "recordIds": [],
        "recording": false,
        "streams": ["met","mot"]
    }

    no

    The EEG sensor mapping of the EPOC Flex headset that you want to connect.

    If the command is not "connect", or if the headset is not an EPOC Flex, then you should omit this parameter.

    connectionType

    string

    no

    If the command is "connect" or "disconnect" then this parameter can be "dongle", "bluetooth" or "usb cable", or you can omit it. If the command is "refresh" then you should omit this parameter.

    This parameter was added in Cortex 2.2.1

    flexConfigName

    string

    no

    Specify the EEG sensor mapping name for the EPOC Flex headset you wish to connect. This can be retrieved using . If you provide this parameter, the mappings parameter will be ignored.

    Name

    Type

    Required

    Description

    command

    string

    yes

    The command must be "connect", "disconnect" or "refresh".

    headset

    string

    no

    The id of the headset that you want to connect or disconnect. The headset id is returned by queryHeadsets.

    If the command is "refresh", then you should omit this parameter.

    mappings

    Name

    Type

    Description

    command

    string

    The command that you set in the request

    message

    string

    A success message

    warning with code 142
    user manualarrow-up-right
    here
    code 104
    code 100, 101, 102 or 113
    queryHeadsets
    warning with code 142

    object

    string

    No

    Name of the configuration (required for create ).

    mappings

    object

    No

    Key-value pairs define EEG sensor mapping (required for create; optional for update). More details are available .

    Name

    Type

    Required

    Description

    cortexToken

    string

    Yes

    A valid Cortex token from a successful authentication.

    status

    string

    Yes

    Action to perform: create, get, read, update, or delete.

    uuid

    string

    No

    Unique ID of a mapping configuration (required for read, delete).

    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "configMapping",
        "params": {
          "cortexToken": "xxx",
          "mappings": {
            "CMS": "TP9",
            "DRL": "TP10",
            "RD": "T8",
            "RE": "F4",
            "RF": "F8",
            "RG": "AF4"
          },
          "name": "config1",
          "status": "create"
        }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": {
        "message": "Create flex mapping config successful",
        "value": {
          "label": {},
          "mappings": {
            "CMS": "TP9",
            "DRL": "TP10",
            "RD": "T8",
            "RE": "F4",
            "RF": "F8",
            "RG": "AF4"
          },
          "name": "config1",
          "uuid": "4416dc1b-3a7c-4d20-9ec6-aacdb9930071"
        }
      }
    }

    name

    querySessions

    This method returns the list of the sessions created by the current application. You can create a session with createSession.

    circle-check

    New in 2.0: Sessions are now temporary in-memory objects. So this methods only returns the current sessions, not your past sessions. See Sessions for details.

    hashtag
    Parameters

    hashtag
    Result

    The result is an array of .

    hashtag
    Example

    subscribe

    This method is to subscribe to one or more data streams. You can call unsubscribe to cancel a subscription. After you successfully subscribe to a stream, Cortex will keep sending you data sample objects.

    See Data Subscription for details.

    hashtag
    Parameters

    The parameter streams must contain one or more values, chosen from this list: "eeg", "mot", "dev", "eq", "pow", "met", "com", "fac", "sys". See for details.

    circle-info

    To subscribe to the "eeg" stream, you must have a paid license and the session.

    hashtag
    Result

    The result is an object that includes these fields:

    In case of success, you get an object with these fields:

    Please note that the field cols is especially important. This field tells you which values you will get in the data stream, and in which order. See for details.

    In case of failure, you get an object with these fields:

    hashtag
    Examples

    Subscribe successfully to motion and performance metrics.

    Subscribe successfully to performance metrics, but fail to subscribe to raw EEG.

    updateSession

    This method is to activate or close a session. See Sessions for details.

    hashtag
    Parameters

    Name

    Type

    Required

    Description

    hashtag
    Result

    The result is a representing the updated session.

    hashtag
    Examples

    hashtag
    Activate a session

    hashtag
    Close a session

    deleteRecord

    This method is to delete one or more records.

    The records will be deleted from the local computer, but also from the EMOTIV account of the user in the cloud, and from any computer where the user is logged in.

    Your application cannot delete a record that was created by another application.

    triangle-exclamation

    Deleting a record is irreversible. There is no way to recover a deleted record.

    hashtag
    Parameters

    hashtag
    Result

    The result is an object that includes these fields:

    In case of success, you get an object with these fields:

    In case of failure, you get an object with these fields:

    hashtag
    Examples

    Deleting two records, including one that has an invalid id.

    Data sample object

    After you successfully subscribe to a data stream, Cortex will keep sending you data sample objects. See Data Subscription for details.

    A data sample object contains these fields:

    Name

    Type

    Description

    <stream>

    array

    The name of this field is the name of the data stream, for example "eeg", "met", "com"...

    This array contains the values of a data sample. The type and meaning of each value depend on the stream.

    sid

    To interpret the values in the <stream> array, you must check the field cols from the result of the method.

    hashtag
    How to interpret the values

    Suppose you want to get the mental command stream. You successfully subscribe to the stream "com", and you receive this response:

    The important part is the field cols:

    So, the labels for the mental command samples are "act" (action) and "pow" (power), in this order. Then you will receive some mental command samples. They look like this:

    The values in the array com match the labels in the array cols. So "push" is the value for "act" , and 0.376 is the value for "pow".

    Below is the description of the labels used in each data stream.

    hashtag
    EEG

    The stream "eeg" uses these labels:

    The maker objects include these fields:

    Example for an INSIGHT:

    Example for an EPOC+ or EPOC X:

    hashtag
    Motion

    The stream "mot" uses these labels:

    Depending on the headset, the labels for the gyroscope will be GYROX, GYROY, GYROZ or the quaternions. You will never get both these labels.

    Example for a newer INSIGHT:

    Example for an older INSIGHT:

    To understand the meaning of motion data, you can refer .

    hashtag
    Device information

    The stream "dev" uses these labels:

    Example with INSIGHT:

    Example with EPOC+ or EPOC X:

    hashtag
    EEG Quality

    Please read this to understand the difference between the contact quality and the EEG quality.

    The stream "eq" uses these labels:

    This stream was added in Cortex 2.7.0

    Example with INSIGHT:

    hashtag
    Band power

    This stream gives you the power of the EEG data. The values are absolute, the unit is uV^2 / Hz. Each sample is calculated based on the last 2 seconds of EEG data.

    The labels of the stream "pow" use the format "SENSOR/BAND", when SENSOR is the name of the EEG sensor and BAND is the name of the band power. Cortex provides these bands:

    • theta (4-8Hz)

    • alpha (8-12Hz)

    • betaL (low beta, 12-16Hz)

    So the low beta for AF3 has the label "AF3/betaL". The gamma for Pz has the label "Pz/gamma".

    Example with INSIGHT:

    Example with EPOC+ or EPOC X:

    hashtag
    Performance metric

    Each performance metric is a decimal number between 0 and 1. Zero means "low power", 1 means "high power". So for example, a value of 0.1 for "eng" means that the user is not engaged, a value of 1.0 means the user is very engaged. If the detection cannot run because of a poor EEG signal quality then the value is null.

    For each performance metrics, the flag isActive is true if the detection of this metrics is running properly. It is false if the detection cannot run. This can happen if the EEG signal from the headset is of poor quality. This flag was added in Cortex 2.2.1

    The "met" stream labels vary depending on the headset type, as shown in the tables below:

    hashtag
    The "met" Stream Labels of MN8

    hashtag
    Example

    hashtag
    The "met" Stream Labels of EPOC / INSIGHT / FLEX - (with EPOC config only)

    hashtag
    Example

    To understand the meaning of each performance metrics, you can refer .

    hashtag
    Mental command

    The stream "com" uses these labels:

    hashtag
    Facial expression

    The stream "fac" uses these labels:

    Use the method to get the possible actions.

    hashtag
    System events

    The stream "sys" is used for the of the mental command and facial expression. It uses these labels:

    For example, just after you start a training for the mental command detection, you receive a system event like this:

    Records

    After you opened a session with a headset, you can create a record. A record is a permanent object to store data from an EMOTIV headset. You can associate a subject to a record. You can add one or more markers to a record.

    Unlike a session, a record is a permanent object. It is stored on the hard drive and then can be synchronized to the EMOTIV cloud. The opt-out configuration can let you decide if the records of a user are uploaded to the cloud or not.

    hashtag
    Record lifetime

    First, you must with a headset. Then you call to start a new record. When the record is in progress, you can add to this record. You stop a record with .

    The record is linked to the session, so if you close the session, or if your application is disconnected from the Cortex service, then Cortex will automatically close the record.

    After you stop the record you can export its data to a CSV or EDF file using .

    Data Subscription

    After you opened a session with a headset, you can subscribe to one or more data streams.

    Each data stream gives you real time access to data from the headset (EEG, motion...) or data calculated by Cortex (band powers, mental command...)

    After you successfully subscribe to a data stream, Cortex will keep sending you data sample objects.

    A subscription is linked to a session. All the subscriptions of a session are automatically cancelled when the session is closed. You can call unsubscribe to cancel a subscription.

    The available data streams depend on the license of the user, and the model and settings of the headset. For an EPOC Flex, it also depends on the EEG sensor mapping.

    hashtag
    Data streams

    Each data stream is identified by its name: "eeg", "mot", "dev", "eq", "pow", "met", "com", "fac", "sys".

    hashtag
    Data streams availability

    Depending on the license and the model of the headset, some streams may be available or not, and may send at a different rate.

    unsubscribe

    This method is to cancel a subscription that was previously created by the subscribe method.

    hashtag
    Parameters

    Name

    Type

    Required

    Description

    The parameter streams must contain one or more values, chosen from this list: "eeg", "mot", "dev", "pow", "met", "com", "fac", "sys". See for details.

    hashtag
    Result

    The result is an object that includes these fields:

    In case of success, you get an object with these fields:

    In case of failure, you get an object with these fields:

    hashtag
    Examples

    Unsubscribe successfully from the performance metrics and motion streams.

    createSession

    This method is to open a session with an EMOTIV headset.

    To open a session with a headset, the status of the headset must be "connected". If the status is "discovered", then you must call controlDevice to connect the headset. You cannot open a session with a headset connected by a USB cable. You can use queryHeadsets to check the status and connection type of the headset.

    You can use updateSession to activate or close a session.

    See Sessions for details.

    circle-info

    Make sure the headset has the status "connected" before you call this method. Use to check the status of the headset.

    hashtag
    Parameters

    If the status is "open", then the session won't be activated. You can activate the session later by calling .

    hashtag
    Result

    The result is a representing the created session.

    hashtag
    Examples

    Open a session.

    Open a session and activate it.

    configOptOut

    This method is to configure the opt-out feature for the records. This feature lets you decide if the records created by your application on the local machine are uploaded to the EMOTIV cloud or not.

    If the opt-out is on (ie the parameter newOptOut is true) then the records created on this machine will not be uploaded to the cloud. If the opt-out is off (ie the parameter newOptOut is false) then the records created on this machine will be uploaded to the cloud.

    Please note that changing the opt-out configuration has no effect on the records previously created on the local computer. It only affects the records created after the change. Changing the opt-out configuration is not retroactive.

    The opt-out configuration is linked to your application. Changing the configuration only affects the records created by your application. This has no effect on the records created by other applications.

    The opt-out configuration is also linked to the EmotivID of the user. The opt-out can be turned on or off for each EmotivID. It is off by default.

    You can check the field localOnly of a to know if this record will stay on the local machine, or if it will be uploaded to the EMOTIV cloud.

    Some don't let you change the opt-out configuration and force the opt-out to be always on or always off. See the possible configurations below for details.

    This method was added in Cortex 2.2.1

    hashtag
    Parameters

    hashtag
    Result

    The result is an object describing the current opt-out configuration. It includes these fields:

    hashtag
    Possible Configurations

    Here is an overview of the possible configurations:

    hashtag
    Examples

    hashtag
    Get the current configuration

    hashtag
    Change the configuration

    exportRecord

    This method is to export one or more records to EDF or CSV files.

    You can export the raw EEG data, the motion data, the performance metrics and the band powers. The available data streams depend on the license of the record. You can check the field licenceScope in the Record object to know which data streams are available.

    By default, you can only export the records that were created by your application. If you want to export a record that was created by another application (e.g. Emotiv PROarrow-up-right or EMOTIV LABSarrow-up-right) then you must provide the license id of this application in the parameter licenseIds.

    In order to export a record created by EMOTIV LABSarrow-up-right, the current Cortex user must be the owner of the LABS experiment.

    You must before you can export it. If you want to export a record immediately after you stop it then you must wait for the before you try to export.

    The format of the exported files is described in .

    This method was added in Cortex 2.1.1 to all desktop versions of Cortex. It was added to iOS and Android in Cortex 2.7.0

    hashtag
    Parameters

    hashtag
    Data streams

    The parameter streamTypes must contain one or more values, chosen from this list: "EEG", "MOTION", "PM", "BP". If the format is "EDF" then only "EEG" and "MOTION" are available.

    hashtag
    Format and version

    Depending on the parameters format and version Cortex will create different files.

    hashtag
    Format EDF, no version

    This format is identical to the one used in Cortex 1.x

    • 1 EDF file for the EEG and CQ data

    • 1 EDF file for the motion data

    • 1 JSON file for the markers

    Format EDFPLUS/BDFPLUS, no version (available since Cortex version 3.7.5)

    • 1 EDF+/BDF+ file for the EEG, CQ and Motion data

    • 1 JSON file for the markers

    • 1 CSV file for the markers if the parameter includeMarkerExtraInfos is true

    hashtag
    Format CSV, version V1

    This format is identical to the one used in Cortex 1.x

    • 1 CSV file for the EEG and CQ data

    • 1 CSV file for the band powers

    • 1 CSV file for the motion data

    hashtag
    Format CSV, version V2

    This format is the new format of Cortex 2.x

    • 1 CSV file for all the data streams (EEG, CQ, band powers, motion, PM)

    • 1 JSON file for the markers

    • 1 CSV file for the markers if the parameter includeMarkerExtraInfos is true

    hashtag
    Result

    The result is an object that includes these fields:

    In case of success, you get an object with these fields:

    In case of failure, you get an object with these fields:

    hashtag
    Examples

    hashtag
    EDF

    hashtag
    CSV V1

    hashtag
    CSV V2

    stopRecord

    This method is to stop a record that was previously started by createRecord. This will set the end date time of the record to the current date time.

    hashtag
    Parameters

    Name

    Type

    Required

    A record is linked to a session. So to close a record, you need to provide the session id.

    hashtag
    Result

    The result is an object containing these fields:

    hashtag
    Example

    requestToDownloadRecordData

    This method is to ask Cortex to download the EEG/motion/CQ/detections data of a record from the EMOTIV cloud.

    hashtag
    Use case

    Suppose that the user has installed Cortex on 2 computers, named computer A and computer B. On computer A, the user creates a record, and Cortex uploads this record to the EMOTIV cloud.

    Then, on computer B, Cortex automatically downloads the metadata of this record, ie its name, description, start time, end time, etc... So this record is visible when you call methods like queryRecord or getRecordInfos.

    But Cortex doesn't automatically download the actual data of the record, ie the EEG, motion, CQ, the results of the detections, etc... So you cannot this record. To download the actual data, you must call the method "requestToDownloadRecordData".

    hashtag
    Parameters

    Name
    Type
    Required
    Description

    hashtag
    Result

    The result is an object with 2 fields:

    Name
    Type
    Description

    Each object in the success array include these fields:

    Name
    Type
    Description

    Each object in the failure array include these fields:

    Name
    Type
    Description

    hashtag
    Example

    createRecord

    This method is to create a new record.

    circle-info

    You must create and activate a session before you call this method. See createSession for details.

    hashtag
    Parameters

    hashtag
    Result

    The result is an object containing two fields:

    hashtag
    Examples

    updateRecord

    This method is to update a record. You can update its title, description and its tags.

    Your application cannot update a record that was created by another application.

    hashtag
    Parameters

    Name

    hashtag
    Result

    The result is a .

    hashtag
    Examples

    Update the tags and the description.

    Marker object

    A marker object includes these fields:

    updateMarker

    This method is to update a marker that was previously created by .

    This method set the end date time of a marker, turning an "instance" marker into an "interval" marker. You can also update the extras object.

    The marker must belong to a record that is still in progress. You cannot update the marker if the record is already stopped.

    hashtag
    Parameters

    getRecordInfos

    This method returns a list of records, selected by their id.

    hashtag
    Parameters

    injectMarker

    This method is to create an "instance" marker to the current record of a session. Then you can call to turn this marker into an "interval" marker.

    circle-info

    You must call before you call this method.

    hashtag

    Markers

    A marker is to mark a point in time, or a period of time, inside a .

    Markers are always linked to a record, so you must start a record before you add a marker. You can't add nor update a marker after the record is stopped. You can associate some data to each marker, like a value and a label.

    There are two types of markers:

    • An instance marker is to mark a point in time. You call to create the marker at a specific timestamp.

    queryRecords

    This method returns a list of records owned by the current user. By default, you only get the records created by your application. To query the records from another application, you must filter by the license id of this application.

    hashtag
    Parameters

    {
        "CMS": "P3",
        "DRL": "P4",
        "LA": "FC5",
        "LB": "O1",
        "LC": "P7",
        "LD": "T7",
        "LE": "F3",
        "LF": "F7",
        "LG": "AF3",
        "RA": "FC6",
        "RB": "O2",
        "RC": "P8",
        "RD": "T8",
        "RE": "F4",
        "RF": "F8",
        "RG": "AF4"
     }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "controlDevice",
        "params": {
            "command": "refresh"
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": {
            "command": "refresh",
            "message": "..."
        }
    }
    {
        "jsonrpc": "2.0",
        "warning": {
            "code": 142,
            "message": {
                "behavior": "Headset discovering complete."
            }
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "controlDevice",
        "params": {
            "command": "connect",
            "headset": "INSIGHT-12341234"
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": {
            "command": "connect",
            "message": "Start connecting to headset INSIGHT-12341234"
        }
    }
    {
        "jsonrpc": "2.0",
        "warning": {
            "code": 104,
            "message": {
                "headsetId": "INSIGHT-12341234",
                "behavior": "The headset is connected"
            }
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "controlDevice",
        "params": {
            "command": "connect",
            "headset": "EPOCFLEX-12341234",
            "mappings": {
                "CMS": "F3",
                "DRL": "F5",
                "LA": "AF3",
                "LB": "AF7",
                "RA": "P8"
            }
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": {
            "command": "connect",
            "message": "..."
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "method": "controlDevice",
        "params": {
            "command": "disconnect",
            "headset": "EPOCFLEX-12341234"
        }
    }
    {
        "id": 1,
        "jsonrpc": "2.0",
        "result": {
            "command": "disconnect",
            "message": "..."
        }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "configMapping",
      "params": {
        "cortexToken": "xxx",
        "status": "get"
      }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": {
        "message": "Get flex mapping config successful",
        "value": {
          "config": [
            {
              "label": {},
              "mappings": {
                "CMS": "TP10",
                "DRL": "TP9",
                "LA" : "C3",
                "LB" : "T7",
              },
              "name": "Default Configuration",
              "uuid": "f4296b2d-d6e7-45cf-9569-7bc2a1bd56e4"
            },
            {
              "label": {},
              "mappings": {
                "CMS": "TP9",
                "DRL": "TP10",
                "RF" : "F8",
                "RG" : "AF4"
              },
              "name": "config2",
              "uuid": "764adb97-a710-4d95-977a-dea5b682aa04"
            }
          ],
          "updated": "2025-10-08T06:16:30.521+07:00",
          "version": "2018-05-08"
        }
      }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "configMapping",
      "params": {
        "cortexToken": "xxx",
        "status": "read",
        "uuid": "764adb97-a710-4d95-977a-dea5b682aa04"
      }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": {
        "message": "Read flex mapping config successful",
        "value": {
          "label": {},
          "mappings": {
            "CMS": "TP9",
            "DRL": "TP10",
            "RF" : "F8",
            "RG" : "AF4"
          },
          "name": "config2",
          "uuid": "764adb97-a710-4d95-977a-dea5b682aa04"
        }
      }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "configMapping",
      "params": {
        "cortexToken": "xxx",
        "status": "update",
        "uuid": "764adb97-a710-4d95-977a-dea5b682aa04",
        "name": "new config"
      }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": {
        "message": "Update flex mapping config successful",
        "value": {
          "label": {},
          "mappings": {
            "CMS": "TP9",
            "DRL": "TP10",
            "RF" : "F8",
            "RG" : "AF4"
          },
          "name": "new config",
          "uuid": "764adb97-a710-4d95-977a-dea5b682aa04"
        }
      }
    }
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "configMapping",
      "params": {
        "cortexToken": "xxx",
        "status": "delete",
        "uuid": "effa621f-49d6-4c46-95f3-28f43813a6e9"
      }
    }
    {
      "id": 3373617,
      "jsonrpc": "2.0",
      "result": {
        "message": "Delete flex mapping config successful",
        "uuid": "effa621f-49d6-4c46-95f3-28f43813a6e9"
      }
    }