1 of 73

Cortex API

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.

End Of Life

Support for the previous generation EMOTIV SDK Community Edition version 3.5, and EMOTIV Cortex v1.x, has reached the end of life on 31st December 2020.

Developers should migrate their applications to work with our new Emotiv Cortex V2, which is described in this document and can be downloaded from our website.

System requirements and supported platforms

Learn more about the system requirements and support platforms for Cortex.

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

Currently, it is not possible to use a MN8 headset with Cortex on Linux Ubuntu.

Prerequisites

Create an EmotivID

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

License

With a valid EmotivID, you have access to the basic data streams, including:

Motion Data
Mental Commands
Facial Expressions
Performance Metrics (low-resolution, 0.1Hz)
Frequency Bands
Contact Quality
Battery Level

A paid subscription will be required for data streams such as:

EEG Data
Performance Metrics (high-resolution, 2Hz)

A Developer API license is required to access the Raw EEG API and the High-resolution Performance metrics API. Please complete the SDK application form, and our customer support team will respond as soon as possible with assistance and licensing options.

Visit https://www.emotiv.com/developer/ for more details. If you have questions about the licensing plans please contact the EMOTIV Customer Support.

Create a Cortex App

Create the application ID and generate the corresponding client ID and client secret for your application in order to grant access to Cortex API.

Login to www.emotiv.com.
Go to My Account Dashboard (https://www.emotiv.com/my-account/).
Select Cortex Apps.
Read the Developers EULA carefully and click Accept only if you agree to all the terms and conditions. You cannot develop an application that works with Cortex if you do not agree to all of the terms.
Enter the name of your new application - an application ID will be generated automatically in the form of com.{your-username}.{application-name}. Note that the app ID string must contain only alphanumeric characters (A-Z, a-z, 0-9), hyphens (-), and periods (.).
(If you have purchased a subscription to the EEG Data API) Decide whether your application requires access to the EEG Data stream. If so, understand that your application will only be available to you until you contact EMOTIV for a deployment license. If your application does not require EEG data then you are entitled to share it with up to 10,000 users before contacting EMOTIV for a deployment license.
(If you have purchased a subscription to the EEG Data API and decided that your application would require access to the EEG Data stream), tick "My App requires EEG access". If you forget this, your application cannot subscribe to EEG stream data later.
Click Register Application. A client ID and a client secret will be presented to you. Copy them to somewhere safe immediately as the client secret will ONLY BE SHOWN ONCE ON THIS SCREEN FOR SECURITY. If you lost it, you will have to generate a new application ID later.
(If you have purchased a subscription to the EEG Data API and decided that your application would require access to the EEG Data stream), make sure you submit this form https://account.emotiv.com/cortex-sdk-application-form/ with necessary information. If you don't submit this form, your applications don't have permission to use the license later.

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 https://github.com/Emotiv/cortex-v2-example

If you have difficulty with the Cortex API, you can also open an issue 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 release notes for details.

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

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 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 online client.

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

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

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 this or if you use python, you can configure the application like this.

Here is the link to the Emotiv Root CA file.

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 cortexaccess tool.
Connect using the IP address:
- Only applied if the IP address of your Raspberry Pi device is in the below range:
  - 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.

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

JSON-RPC

After you have successfully opened the WebSocket connection, communicate with Cortex using the JSON-RPC 2.0 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:

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "area",
    "params": {
        "width": 6,
        "length": 7
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": 42
}

Please read the JSON-RPC 2.0 specification for details.

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 overview of the API flow.

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

getCortexInfo

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

{
    "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"
    }
}

getUserLogin

Get the current logged in user.

There is no login or logout API in Cortex. Instead, users are required to login through the EMOTIV Launcher.

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getUserLogin"
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": []
}

A user is logged in from the current OS account

{
    "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"
    }]
}

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.

{
    "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"
    }]
}

requestAccess

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.

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

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

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

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

Application is not approved yet, or declined

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

hasAccessRight

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

Any application that connects to Cortex must request approval from the user through . See for details.

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

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.

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.

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.

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.

Before you call this method, the user must approve your application in . See for details.

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

Parameters

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.

Examples

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 for details.

Parameters

Result

The result is an object containing a field cortexToken.

Example

getUserInformation

This method returns basic information about the current user.

Parameters

Result

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

Examples

getLicenseInfo

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

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.

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.

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

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 warning with code 142 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".

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 code 104 to know that the connection is successful. If the connection fails then you will receive a warning with code 100, 101, 102 or 113.

Another way to check if the headset is connected or not is to call queryHeadsets 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.

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "controlDevice",
    "params": {
        "command": "refresh"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "command": "refresh",
        "message": "..."
    }
}

Then you will receive a warning with code 142 when scanning is finished.

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 142,
        "message": {
            "behavior": "Headset discovering complete."
        }
    }
}

Connect an Insight headset

{
    "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"
    }
}

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

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 104,
        "message": {
            "headsetId": "INSIGHT-12341234",
            "behavior": "The headset is connected"
        }
    }
}

Connect an Epoc Flex headset

{
    "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": "..."
    }
}

Disconnect a headset

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "controlDevice",
    "params": {
        "command": "disconnect",
        "headset": "EPOCFLEX-12341234"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "command": "disconnect",
        "message": "..."
    }
}

queryHeadsets

Shows details of any headsets connected to the device via USB dongle, USB cable, or Bluetooth. You can query a specific headset by its id, or you can specify a wildcard for partial matching.

Parameters

For the parameter id, you can use these wildcards:

Result

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

Examples

Query all the headsets

{
    "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"
        }
    ]
}

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "queryHeadsets"
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": []
}

Query a headset by its id

{
    "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"
        }
    ]
}

Query all the Insight headsets

{
    "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"
      }
    }
  ]
}

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.

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 queryHeadsets to check how the headset is connected.

Parameters

The setting parameter must be an object with these fields:

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

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 code 110 or 111 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 code 112. 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)

{
    "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": "..."
    }
}

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

{
    "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": "..."
    }
}

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 start a record 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

Parameters

Result

The result is an object containing these fields:

Examples

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

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 creating a record.

Use Case

Cortex sets the timestamps of each EEG sample using the monotonic clock 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 NTP synchronization.

When you add a marker 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:

Name

Type

Required

Description

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

{
  "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"
  }
}

Headset object

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 updateHeadset for details. For an Insight or Epoc headset, the mode is always "EPOC". For an Epoc Flex headset, the mode is always "EPOCFLEX".

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

Flex Mapping

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

Examples

Insight

{
  "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"
  }
}

Epoc+

{
    "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"
    }
}

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:

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

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:

{
    "id":8,
    "jsonrpc":"2.0",
    "result":{
        "failure":[],
        "success":[{
            "cols":["act","pow"],
            "sid":"7f899d66-442b-4bf4-9752-ed06d57b72c3",
            "streamName":"com"
        }]
    }
}

The important part is the field cols:

["act","pow"]

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:

{
    "com": ["push", 0.376],
    "sid": "7f899d66-442b-4bf4-9752-ed06d57b72c3",
    "time": 1559900743.3318
}

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.

EEG

The stream "eeg" uses these labels:

The maker objects include these fields:

Example for an INSIGHT:

[
  "COUNTER",
  "INTERPOLATED",
  "AF3","T7","Pz","T8","AF4",
  "RAW_CQ",
  "MARKER_HARDWARE",
  "MARKERS"
]

{
  "eeg": [
    8,
    0,
    4202.051, 4235.385, 4146.667, 4210.769, 4108.718,
    0,
    0,
    []
  ],
  "sid": "8bbc58bd-0ab1-404e-b472-dac1322dbe5b",
  "time": 1590402103.9016
}

Example for an EPOC+ or EPOC X:

[
    "COUNTER",
    "INTERPOLATED",
    "AF3","F7","F3","FC5","T7","P7","O1","O2","P8","T8","FC6","F4","F8","AF4",
    "RAW_CQ",
    "MARKER_HARDWARE",
    "MARKERS"
]

{
    "eeg":[
        14,
        0,
        4161.41,4212.051,4135,4161.538,4195,4184.103,4182,
        0,
        0, 
        [{
            "applicationId": "com.emotiv.emotivpro",
            "isStop": false,
            "label": "Blink eye while relaxing",
            "markerId": "cc577d88-f404-482a-9629-3e08a0dbcc02",
            "port": "KeyStroke",
            "recordId": "f3c76112-9b7f-43ab-a906-5c15dc4dd55e",
            "value": 22
        }]
    ],
    "sid":"01e1e0f1-4416-436f-8f9d-5bf21e2e4784",
    "time":1559902873.8976
}

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:

[
  "COUNTER_MEMS","INTERPOLATED_MEMS",
  "Q0","Q1","Q2","Q3",
  "ACCX","ACCY","ACCZ",
  "MAGX","MAGY","MAGZ"
]

{
  "mot": [
    48,
    0,
    0.735341, 0.255615, 0.627441, -0.015869,
    0.948257, -0.354986, -0.083497,
    -44.656766, -86.970985, 23.221568
  ],
  "sid": "da18712c-a292-46b7-a5a0-1bd64a3dc6f3",
  "time": 1590402244.8242
}

Example for an older INSIGHT:

[
    "COUNTER_MEMS","INTERPOLATED_MEMS",
    "GYROX","GYROY","GYROZ",
    "ACCX","ACCY","ACCZ",
    "MAGX","MAGY","MAGZ"
]

{
    "mot":[
        14,0,
        8206,8187,8181,
        4235,8668,8128,
        8294,8237,7938
    ],
    "sid":"462c4d75-113f-4664-a443-3aaa02c178d0",
    "time":1559902927.7428
}

Device information

The stream "dev" uses these labels:

Example with INSIGHT:

[
  "Battery",
  "Signal",
  ["AF3","T7","Pz","T8","AF4","OVERALL"],
  "BatteryPercent"
]

{
  "dev": [
    3,
    1,
    [4,1,1,2,4,25],
    74
  ],
  "sid": "edcb9287-f6d5-4c22-9b3f-783d72750f24",
  "time": 1590403053.5002
}

Example with EPOC+ or EPOC X:

[
    "Battery","Signal",
    ["AF3","F7","F3","FC5","T7","P7","O1","O2","P8","T8","FC6","F4","F8","AF4","OVERALL"],
    "BatteryPercent"
]

{
    "dev":[
        4,2,
        [2,0,1,0,1,0,0,4,0,1,0,1,0,1,24],
        98
    ],
    "sid":"d02af7d5-2bc0-46f4-8804-026a42ad7841",
    "time":1559903194.6721
}

EEG Quality

Please read this page 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:

[
  "batteryPercent",
  "overall",
  "sampleRateQuality",
  "AF3","T7","Pz","T8","AF4"
]

{
  "eq": [
    78,
    25,
    1.0,
    4,1,1,2,4
  ],
  "sid": "edcb9287-f6d5-4c22-9b3f-783d72750f24",
  "time": 1590403053.5002
}

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)
betaH (high beta, 16-25Hz)
gamma (25-45Hz)

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

Example with INSIGHT:

[
    "AF3/theta","AF3/alpha","AF3/betaL","AF3/betaH","AF3/gamma",
    "T7/theta","T7/alpha","T7/betaL","T7/betaH","T7/gamma",
    "Pz/theta","Pz/alpha","Pz/betaL","Pz/betaH","Pz/gamma",
    "T8/theta","T8/alpha","T8/betaL","T8/betaH","T8/gamma",
    "AF4/theta","AF4/alpha","AF4/betaL","AF4/betaH","AF4/gamma"
]

{
  "pow": [
    1.246,0.706,0.566,1.065,0.602,
    10.293,4.374,11.638,351.767,40.273,
    50.159,4.585,0.467,1.481,3.764,
    9.861,3.139,2.094,3.342,4.452,
    75.652,1.972,2.932,2.555,7.005
  ],
  "sid": "ff0245d1-9531-424c-9f6d-9f736f465516",
  "time": 1590403491.0307
}

Example with EPOC+ or EPOC X:

[
    "AF3/theta","AF3/alpha","AF3/betaL","AF3/betaH","AF3/gamma",
    "F7/theta","F7/alpha","F7/betaL","F7/betaH","F7/gamma",
    "F3/theta","F3/alpha","F3/betaL","F3/betaH","F3/gamma",
    "FC5/theta","FC5/alpha","FC5/betaL","FC5/betaH","FC5/gamma",
    "T7/theta","T7/alpha","T7/betaL","T7/betaH","T7/gamma",
    "P7/theta","P7/alpha","P7/betaL","P7/betaH","P7/gamma",
    "O1/theta","O1/alpha","O1/betaL","O1/betaH","O1/gamma",
    "O2/theta","O2/alpha","O2/betaL","O2/betaH","O2/gamma",
    "P8/theta","P8/alpha","P8/betaL","P8/betaH","P8/gamma",
    "T8/theta","T8/alpha","T8/betaL","T8/betaH","T8/gamma",
    "FC6/theta","FC6/alpha","FC6/betaL","FC6/betaH","FC6/gamma",
    "F4/theta","F4/alpha","F4/betaL","F4/betaH","F4/gamma",
    "F8/theta","F8/alpha","F8/betaL","F8/betaH","F8/gamma",
    "AF4/theta","AF4/alpha","AF4/betaL","AF4/betaH","AF4/gamma"
]

{
    "pow":[
        0.225,0.213,0.537,0.19,0.34,
        0.511,0.808,1.706,0.839,0.416,
        ...
        0.92,0.469,1.657,1.443,0.912,
        2.675,0.824,0.951,0.303,0.881
    ],
    "sid":"f581b2bb-c043-4a00-8737-1e8e09a9a81b",
    "time":1559902987.133
}

Performance metric

The stream "met" uses these labels:

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

[
    "eng.isActive","eng",
    "exc.isActive","exc","lex",
    "str.isActive","str",
    "rel.isActive","rel",
    "int.isActive","int",
    "foc.isActive","foc"
]

{
    "met":[false,null,false,null,null,false,null,true,0.266589,false,null,true,0.098421],
    "sid":"6a68b92a-cb1f-4062-bf1f-74424fbae065",
    "time":1559903137.1741
}

Mental command

The stream "com" uses these labels:

["act","pow"]

{
    "com":["pull",0.564],
    "sid":"79cc669b-af2e-465a-bdc2-0e9bd4aebe80",
    "time":1559903099.348
}

Facial expression

The stream "fac" uses these labels:

Use the method getDetectionInfo to get the possible actions.

["eyeAct","uAct","uPow","lAct","lPow"]

{
    "fac":["neutral","neutral",0,"clench",0.0576],
    "sid":"a4f69c56-9769-4a4d-950c-490eb5ebe372",
    "time":1559903035.2961
}

System events

The stream "sys" is used for the training 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:

["event","msg"]

{
    "sid":"c7e7b527-2b2e-4ec6-8c74-cf16aae8540b",
    "sys":["mentalCommand","MC_Started"],
    "time":1559903035.2961
}

Error Codes

Here is a list of the error codes that the Cortex API can return. This list is not exhaustive (yet) and will be updated in the future.

-32700 Parse Error

The message you sent to Cortex is not a valid JSON object. This is a bug is your application.

-32600 Invalid Request

The message you sent to Cortex is a valid JSON object but it doesn't contain the expected fields. This a bug is your application. Please check Connecting to the Cortex API

-32601 Method Not Found

You sent a request with an invalid method name. This a bug is your application. Please check this documentation to see which methods are available.

-32602 Invalid Parameters

You sent a request to call a valid method, but the parameters are wrong. It can be because:

You didn't provide a required parameter
You provided a parameters with an invalid name
The name of parameter is correct but the value is invalid

This is a bug in your application. Please check the documentation of the method.

-32603 Internal Error

An unexpected error happened in Cortex while processing your request. This is probably a bug in Cortex. If the problem persists, please contact the EMOTIV customer support.

-32000 Server Internal Error

An unexpected error happened in the EMOTIV cloud while processing your request. It can be a temporary failure of the EMOTIV servers, like when the servers are in maintenance. Or it can be a bug in Cortex. If the problem persists, please contact the EMOTIV customer support.

-32002 Invalid License ID

The EMOTIV cloud cannot find the license of the user. When you call the method authorize, please make sure that you provide a valid license ID, or no license parameter at all. If the problem persists, then the owner of the license must contact the EMOTIV customer support.

-32003 Internet Connection Error

Cortex must connect to the EMOTIV cloud to process your request, but the connection failed. Please make sure that you computer has a working internet connection.

-32004 Headset Unavailable

You sent a request to perform an action on a specific headset, but Cortex cannot find this headset. Some possible reasons for this error:

You provided an invalid headset ID in your request
The headset was disconnected (maybe it is out of range of your computer)
The headset was switched off

-32005 A session already exists with this headset

You called the method createSession for a specific headset, but your application already has a session for this headset. This is a bug in your application. You cannot create 2 sessions for the same headset at the same time. You must close the existing session before creating a new one.

-32006 No license to activate a session

You called createSession or updateSession with the parameter "status" set to "active", but your license doesn't authorize you to activate a session. You have a paid EMOTIV license to activate a session. If you already have such a license but the problem still persists, then contact the EMOTIV customer support. You should also read the prerequisite.

-32007 The session doesn't exist

You included a session ID in the parameters of your request, but Cortex cannot find this session. It can be because you session ID is invalid or because the session is already closed.

Many methods can return this error: updateSession, subscribe, unsubscribe, createRecord, injectMarker, training, etc...

-32012 The session must be activated

You called a method that requires an active session, but the current session is inactive. It can happen if you call createRecord on an inactive session.

-32014 Invalid Cortex token

You included a Cortex token in the parameters of your request, but this token is invalid. This is a bug in your application. When a method requires a Cortex token, please make sure that your token comes from the result of the method authorize.

-32015 The Cortex token has expired

Your Cortex token has expired. You must call the method authorize again to get a new token. The Cortex token is valid for 48 hours.

-32016 Invalid stream

You called the methods subscribe or unsubscribe with an invalid stream. The stream can be invalid for one of these reasons:

The name of the stream is incorrect. Check Data Subscription for the list of the available streams.
The stream is not available for this headset. For example, the motion data of an EPOC X headset can be disable.
The stream is "eeg" but the license doesn't allow you to access this stream. You can check the license with getLicenseInfo

-32017 Record already started

You called createRecord for a specific session, but your application already started a record for the same session. You cannot create 2 records for the same session at the same time.

-32019 Session limit has been reached

You tried to activate a session (with createSession or updateSession) but the "localQuota" of the license is zero. You can check the "localQuota" by calling the method getLicenseInfo. Every time you activate a session, the local quota of the license is reduced by 1.

To solve this error, you must increase the local quota of the license. Call authorize with the parameter "debit". For example, you can call authorize with a "debit" of 10, and this will increase the local quota by 10. Then you will be able to create and activate 10 sessions on this computer.

-32020 The headset must be connected with a USB cable

You called updateHeadset but the headset is connected to the computer via Bluetooth or a USB dongle. Instead, the user should connect the headset with a USB cable.

-32021 Invalid client credentials

Your request includes an invalid client ID or an invalid client secret.

-32022 Device limit has been reached

The license was used on too many devices (eg computer, tablet, phone...) The license has a device limit. You can check it by calling the method getLicenseInfo. If you want to increase the limit or transfer the license from 1 device to another, then please contact the EMOTIV customer support.

-32024 The license has expired

The license of the user has expired. You can check the license with getLicenseInfo. After the license is renewed, your application must call authorize to get a new token.

-32027 Cannot use this license

You called authorize with a valid license ID but your application doesn't have the permission to use this license.

-32029 License hard limit has been reached

When the computer is offline, you can use the license for a limited period of time. The end of this period is the "hard limit" of the license. You can check it with getLicenseInfo. After the "hard limit" has been reached, Cortex must connect to the EMOTIV cloud to validate the license again. To solve this problem, the computer must have an internet connection and then you must call authorize.

-32031 Invalid profile name

You sent a request to perform an action on a specific training profile, but Cortex cannot find this profile.

-32033 No user

Cortex cannot process your request because no user is logged in. You must ask the user to log in in EMOTIV Launcher.

-32034 The Cortex token is for another user

Your request includes a Cortex token that was created for a specific user, but the current user is a different one. In that case, that must call authorize again and get a new token. You can check the current user with getUserLogin.

-32037 Cannot train this action

You called training for an action that cannot be trained.

-32044 Profile already loaded on another headset

You tried to load a training profile for a specific headset, but this profile is already loaded for another headset. You cannot load the same profile on 2 different headset at the same time.

-32045 No profile loaded for this headset

You tried to unload a training profile from a headset, but no profile was loaded for this headset.

-32046 Profile loaded by another application

You tried to perform an operation (eg setupProfile, training...) on a training profile, but this profile was loaded by another application. An application can only access a profile that loaded by itself. You can call getCurrentProfile to check if your application loaded the profile of a headset or not.

-32102 Not approved in EMOTIV Launcher

The user didn't approved your application yet. The user must open EMOTIV Launcher and approve your application.

-32104 Failed to connect or disconnect the headset

Cortex failed to communicate with the headset. Maybe the wireless connection between the headset and the computer was interrupted. Your application should try again. You can also call queryHeadsets to check the status of the headset.

-32106 The user account is not active

The EMOTIV ID of the user is inactive. The user must contact the EMOTIV customer support. You can call getUserLogin or getUserInformation to check the current user.

-32108 Cloud token error

The EMOTIV cloud refused the user credentials provided by Cortex. The user must logout and login again.

-32109 Cortex token error

There is something wrong with the Cortex token. Your application must call authorize to get a new Cortex token.

-32110 Must be online to use this license

Your license cannot work when you are offline. You must be connected to the internet at all time to use this license. You can call getLicenseInfo to check the current license.

-32112 The session is already active

You tried to activate a session that is already active. You can call querySessions to check the status of your sessions.

-32113 Invalid record ID

You are trying to access a record that doesn't exist, or the record exist but you don't have the permission to access it.

-32114 No record in progress

You are trying to inject a marker or to stop a record but no record is is progress.

-32115 The time of the marker is too far in the past

You are trying to inject a marker but its time is too far in the past. You should inject your markers in real time, at the moment the event you want to mark happens.

-32116 The time of the marker is too far in the future

You are trying to inject a marker but its time is too far in the future. You should inject your markers in real time, at the moment the event you want to mark happens.

-32117 Marker not found

You called updateMarker with an invalid marker id.

-32118 The profile name already exists

You are trying to create or rename a training profile, but another profile with the same name already exists.

-32119 The marker is already stopped

You are trying to update a marker that was already updated before.

-32123 Corrupted database

The local Cortex database is corrupted. Please contact the EMOTIV customer support.

-32124 Subject not found

You are trying to update or delete a subject that doesn't exist. Or you are trying to create a record with an invalid subject.

-32125 Subject already exists

You are trying to create a subject, but another subject with the same name already exists.

-32127 Profile already loaded for this headset

You are trying to load a training profile for a headset, but a profile was already loaded for this headset before. You must unload the current profile before loading a new one.

-32129 Invalid record title

You are trying to create or update a record, but the record title is invalid. The title must be 200 characters long or less.

-32137 Cannot open output file

You are trying to export a record but Cortex cannot open the output CSV or EDF file.

-32138 Stream not supported for export

You are trying to export a record but one of the data streams you requested is not available.

Warning Objects

In addition to method responses and data samples, Cortex can send a third type of message, called warnings.

These warnings inform your application about important events, like when the user logs in or out, or when a training profile is loaded or unloaded for a headset.

Description

A warning object contain these fields:

The warning object has 2 fields:

Warning Codes

The possible codes are:

Examples

0 - Data stream unsubscribed

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 0,
        "message": {
            "behavior": "Cortex has stopped all the subscriptions of session 866b8437-2380-4392-9a35-3d5957eaf95d.",
            "sessionId": "866b8437-2380-4392-9a35-3d5957eaf95d"
        }
    }
}

1 - Session closed

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 1,
        "message": {
            "behavior": "Cortex has closed the session 866b8437-2380-4392-9a35-3d5957eaf95d.",
            "sessionId": "866b8437-2380-4392-9a35-3d5957eaf95d"
        }
    }
}

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 2,
        "message": "User jon.snow has already logged in to Cortex."
    }
}

3 - User logout

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 3,
        "message": "User jon.snow has already logged out from Cortex."
    }
}

9 - App access granted

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 9,
        "message": "The access right to the cortex-examples has been granted"
    }
}

10 - App access declined

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 10,
        "message": "The access right to the cortex-examples has been rejected"
    }
}

13 - Profile loaded

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 13,
        "message": {
            "behavior": "Profile is loaded",
            "headset": "INSIGHT-12341234",
            "profile": "foo"
        }
    }
}

14 - 15 - Profile unloaded

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 14,
        "message": {
            "behavior": "Profile is unloaded",
            "headset": "INSIGHT-12341234",
            "profile": "foo"
        }
    }
}

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 15,
        "message": {
            "behavior": "Cortex has unloaded the profile",
            "headset": "INSIGHT-12341234",
            "profile": "foo"
        }
    }
}

17 - EULA accepted

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 17,
        "message": "User jon.snow has accepted the EULA via EMOTIV App"
    }
}

19 - 20 - Disk space

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 19,
        "message": {
            "behavior": "The available disk space is low.",
            "rootPath": "/",
            "volumeName": "MAC"
        }
    }
}

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 20,
        "message": {
            "behavior": "The available disk space is critically low. Cortex will disconnect all the headsets.",
            "rootPath": "C",
            "volumeName": "Windows"
        }
    }
}

21 - 22 - Opt-out configuration changed

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 21,
        "message": {
            "currOptOut": true,
            "forceOptOut": false,
            "message": "User has changed the Opt-out configuration.",
            "optOutAvail": true
        }
    }
}

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 22,
        "message": {
            "currOptOut": true,
            "forceOptOut": false,
            "message": "The Opt-out configuration has been automatically changed due to change in license.",
            "optOutAvail": true
        }
    }
}

100 - 101 - 102 - 113 - Failed to connect to a headset

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 100,
        "message": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "behavior": "Headset cannot be connected. Please try again."
        }
    }
}

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 101,
        "message": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "behavior": "Headset cannot be connected. Please try again."
        }
    }
}

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 102,
        "message": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "behavior": "Headset cannot be connected due to connection timeout."
        }
    }
}

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 113,
        "message": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "behavior": "Please disable motion data and set EEG rate to 128Hz in headset configuration when using Bluetooth connection, or use USB dongle."
        }
    }
}

103 - Headset disconnected

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 103,
        "message": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "behavior": "Headset has been disconnected due to connection timeout."
        }
    }
}

104 - Headset connected

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 104,
        "message": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "behavior": "The headset is connected"
        }
    }
}

110 - Headset update successful

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 110,
        "message": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "behavior": "Headset configuration is updated."
        }
    }
}

111 - Headset update failed

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 111,
        "message": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "behavior": "Headset configuration update failed."
        }
    }
}

112 - Headset configuration cannot work with Bluetooth

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 112,
        "message": {
            "headsetId": "EPOCPLUS-3B9AXXXX",
            "behavior": "This headset configuration cannot work with BTLE on this platform."
        }
    }
}