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.

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.

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.

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

Get the current logged in user.

Parameters

This method has no parameter.

Result

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

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

The user object includes these fields:

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

Examples

No user is logged in

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

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

Parameters

Result

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

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

Examples

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

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.

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

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

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

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.

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

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

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

System requirements and supported platforms

Learn more about .

Supported headsets

Currently, Cortex supports the following headsets:

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

Prerequisites

Create an EmotivID

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

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 , and our customer support team will respond as soon as possible with assistance and licensing options.

Visit for more details. If you have questions about the licensing plans please contact the .

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.

1. Login to www.emotiv.com.

2. Go to My Account Dashboard ().

3. Select Cortex Apps.

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

5. 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 (.).

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

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

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

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

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

Next Step

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

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

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

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

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

Parameters

Headset Scanning Flow

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

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

EPOC Flex mapping

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

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

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

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

Connection Type

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

Result

The result is an object containing these fields:

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

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

Examples

Refresh the list of headsets

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

Then you will receive a when scanning is finished.

Connect an Insight headset

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

Connect an Epoc Flex headset

Disconnect a headset

Request user approval for the current application through .

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

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

Parameters

Result

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

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

Examples

Application was already approved

Application is not approved yet, or declined

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.

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 BCI

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

Session lifetime

A session is created by createSession and closed by updateSession.

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 create a record inside your session. See Records for details.

Session activation

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

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

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 querySessions and check the field status to know if a session was activated or not.

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:

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

This method returns basic information about the current user.

Parameters

Result

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

Examples

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

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 EMOTIV Launcher, 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.

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

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

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

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

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

See authorize for details.

Parameters

Result

The result is an object containing a field cortexToken.

Example

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "cortexToken": "yyy"
    }
}

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

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

Description

A session object includes these fields:

Status

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

Examples

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

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

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

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

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

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

Parameters

The setting parameter must be an object with these fields:

Result

The result is an object containing these fields:

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

However, since Cortex 2.4.0, the result of the method just tells you that the update is in progress. You must wait for a warning object with 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": "..."
    }
}

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

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

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

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

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

See for details.

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.

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:

Examples

Subscribe successfully to motion and performance metrics.

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

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

Parameters

Result

The result is an array of .

Example

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

Parameters

Result

The result is a representing the updated session.

Examples

Activate a session

Close a session

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 to connect the headset. You cannot open a session with a headset connected by a USB cable. You can use to check the status and connection type of the headset.

You can use to activate or close a session.

See for details.

Parameters

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

Result

The result is a representing the created session.

Examples

Open a session.

Open a session and activate it.

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

Parameters

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

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:

Examples

Unsubscribe successfully from the performance metrics and motion streams.

This method is to create a new record.

Parameters

Result

The result is an object containing two fields:

Examples