On Windows and MacOS, the Cortex service is a background process that communicates with the EMOTIV headsets and the EMOTIV cloud. It is also a WebSocket server that uses the JSON-RPC protocol.
WebSocket
Communicate with the Cortex API using the WebSocket Secure protocol.
Create a WebSocket client and connect to localhost on the port 6868, using the wss protocol.
Any WebSocket client should work in any programming language. You can even use a web browser plugin or an .
Please note that Cortex only supports the WebSocket Secure (wss) protocol. It doesn't support the plain WebSocket (ws) protocol without encryption.
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 or if you use python, you can configure the application like .
Here is .
Remote connections
Since 2.7.1 release, we support remote connections to Cortex running on Raspberry Pi device. It requires some steps:
Grant the permissions to a desktop machine before an app on that machine can connect to the Cortex web socket server on Raspberry Pi device, using tool.
Connect using the IP address:
Only applied if the IP address of your Raspberry Pi device is in the below range:
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 protocol.
Call methods, with or without parameters, and Cortex sends back a result or an error.
Call an API method by sending a JSON object with these fields:
The response from Cortex is a JSON object with these fields:
Here is a simple fictional example:
Please read the for details.
Test API request and response
You can try with the most simple API of Cortex: .
Next step
The rest of this documentation will show you what methods are available, what parameters they take, and how to use these methods.
But first, you should start with the .
10.[0-1].[0-2].[0-255]
172.[16-17].[0-2].[0-255]
192.168.[0-5].[0-255]
Create a WebSocket client and connect to<IP address of Raspberry Pi device>
on the port 6868, using the wss protocol.
Connect using the DNS name:
Can be applied for any value of IP address of your Raspberry Pi device.
Add this line into the host file of the desktop machine:<IP address of Raspberry Pi device> emotiv-cortex.remote
Create a WebSocket client and connect to emotiv-cortex.remote on the port 6868, using the wss protocol.
no
The parameters of the method, if it has any
id
number or string
no
The id of this request.
Cortex will include this id into the response message, so you can can match the response with the request
The id you included in the request
Name
Type
Required
Description
jsonrpc
string
yes
Must be "2.0"
method
string
yes
The name of the API method you want to call
params
Name
Type
Description
jsonrpc
string
Is always "2.0"
result
any
If the method is successful, contains the result of the method.
The type depends on the method
error
object
If the method failed, contains an error code and an error message
Once the app authenticates with the Cortex successfully, it can use the Cortex token to stay offline while working with Cortex for a period of time (see soft limit, hard limit below).
Here is the recommended flow to work offline with Cortex:
Step 1: Follow this API flow to get Cortex token the first time. This flow requires the Internet connection. A Cortex token will be available for 48 hours.
Step 2: When the Cortex token is expired, call generateNewToken API to generate another token. This API doesn't require the Internet connection.
Step 3: Check soft limit, hard limit of the current license via getLicenseInfo API and warn the users to be online.
In the license information, there are 2 fields "softLimitTime" and "hardLimitTime".
softLimitTime
This is the reasonable time to warn users that the app will not be able to use offline soon. The app can still work offline until hardLimitTime.
hardLimitTime
This is the time that the app will be no longer to use offline. The app must call API with the Internet connection to be able to continue working with Cortex.
The softLimitTime will be at least 1 month later from the time the app calls API. The hardLimitTime is 7 days after softLimitTime.
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.
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.
Currently, it is not possible to use a Flex or a MN8 headset with Cortex on Raspberry Pi.
Virtual Brainwear
In addition to physical EMOTIV headsets, users can create virtual headsets (a “Virtual Brainwear®”) using the EMOTIV Launcher, which emulates device states and data streams for development purposes.
Important caveat: Records captured using a virtual headset are local to that machine and will not be synced to another device or transferred between machines.
For more details on creating and using virtual devices, see “”
Prerequisites
Create an EmotivID
As with other EMOTIV services, you are required to have an EmotivID account. You can create an ID on .
License
If you’re ready to start developing with EMOTIV’s Cortex SDK, one of your first steps is registering your Cortex App ID. Whether you’re working with consumer devices like the Insight or MN8, or exploring options with professional-grade hardware such as the EPOC X or EPOC Flex, this guide will walk you through how to get started with consumer devices.
Understanding Cortex API Access Levels
EMOTIV’s Cortex SDK supports multiple EEG and behavioral data streams. These are grouped into Basic (BCI API) and Premium categories:
Basic (BCI API) Includes:
Mental Commands API
Facial Expression API
Frequency Band API
Motion Data API
Premium API Includes:
Raw EEG API
High-resolution Performance Metrics (2 Hz)
Consumer devices (Insight, MN8) will allow access to all data streams through our Developer SDK and API. You can register here to get started: .
Professional devices (EPOC X and EPOC Flex) include free access to the Basic BCI API. To access the Premium API, however, a premium Developer API license is required. If you don't have a valid Developer API license, please submit your SDK application and specify the level of data stream you wish to access with your professional device. Our support team will then guide you on the appropriate licensing option to get started.
Create a Cortex App
To learn how to register your Cortex App ID and begin development, please refer to .
Client ID and Client Secret
Once you register your Cortex App ID, you will receive a Client ID and Client Secret, which serve as unique identifiers for your software application. These will be used as input parameters for some authentication Cortex API calls.
The "Client ID" and "Client Secret" similar to a username and password, are automatically generated by EMOTIV for each version of your software application.
The Cortex Examples
To help you getting started with your application, EMOTIV provides basic examples in various programming languages. There are open source and hosted by Github at
If you have difficulty with the Cortex API, you can also on this Github repository.
Next Step
If you are upgrading your application from Cortex 1.x to Cortex 2.x, then please be aware that the Cortex API has significantly changed. Please read the for details.
If you are new to the Cortex API, then please start with .
Overview of API flow
There are a few steps to prepare before you can get the data streaming out from Cortex web socket server:
First you have to login to the EMOTIV Launcher with your EmotivID.
Make sure that you are using the correct application ID, client ID and client secret that you generated from the Account dashboard on Emotiv website in your application (see here).
Call the API from your app to Cortex, and accept via the EMOTIV Launcher.
After access is granted, connect your EMOTIV brainwear headset via the USB dongle or Bluetooth.
Call the API with "refresh" command to start the headset scanning.
Call the API to list the available headsets.
Call the API with "connect" command to connect to the desire headset.
Call the API to get a Cortex token for subsequence requests.
Call the API to open up a new session and be ready for BCI data streaming.
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
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.
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 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
A user is logged in from the current OS account
A user is logged in from another OS account
The application is connected to Cortex that belongs to the OS account 501/jsnow. But someone has already logged in to Cortex from OS account 502/astark with the EmotivID aria.stark. So, the application cannot work with Cortex.
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.
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.
This method returns basic information about the current user.
Parameters
Name
Type
Required
Description
Result
The result is an object containing basic information about the user.
Examples
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 .
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
Application is not approved yet, or declined
getLicenseInfo
This method returns information about the license currently used by your application.
Parameters
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 .
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.
Headset object
Some methods of the API return one or more headset objects, for example . A also includes a headset object.
Description
A headset object include these fields:
An object that contain information about the EULA agreement
{
"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."
}
}
cortexToken
string
yes
A token returned by
Result
The result is an object containing a license object and the isOnline flag.
Name
Type
Description
license
object
An object containing all the information about the current license
isOnline
boolean
True, if Cortex was able to get the license information from the EMOTIV cloud
False, if Cortex got the license information for its local cache
Example
{"id": 1,"
{"id": 1,"
Name
Type
Required
Description
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
Name
Type
Required
Description
cortexToken
string
yes
A token returned by .
headset
string
yes
A headset id returned by .
setting
The setting parameter must be an object with these fields:
Name
Type
Required
Description
mode
string
yes
Must be "EPOC" or "EPOCPLUS".
In "EPOC" mode, the EEG resolution is 14 bits.
In "EPOCPLUS" mode, the EEG and motion resolutions are 16 bits.
eegRate
number
yes
The EEG sample rate, in hertz.
If the mode is "EPOC", then the EEG rate must be 128.
If the mode is "EPOCPLUS", then the EEG rate can be 128 or 256.
memsRate
A motion rate of zero means that the motion sensors are disabled.
Result
The result is an object containing these fields:
Name
Type
Description
headsetId
string
The headset id you set in the parameters.
message
string
A success message.
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)
Set the EPOC+ headset in EPOC mode, EEG rate at 128 hertz (14 bits) and disable the motion sensors.
Can be "discovered", "connecting", or "connected".
connectedBy
string
Can be "bluetooth", "dongle", "usb cable", or "extender".
dongle
string
The version of the dongle firmware.
firmware
string
The version of the headset firmware.
motionSensors
array of strings
The names of the motion sensors of this headset.
sensors
array of strings
The names of the EEG sensors of this headset. Use the international 10-20 system.
settings
object
An object containing the configuration of the EEG and motion data of this headset.
flexMappings
object
If the headset is an EPOC Flex, then this field is an object containing information about the mapping of the EEG channels.
headbandPosition
string
If the headset is an EPOC X, then this field tells you the position of the headband of this headset. Can be "back" or "top".
If the headset is not an EPOC X, then this field is null.
See for details.
This field was added in Cortex 2.4
customName
string
The custom name of the headset. The user can set it in EMOTIV Launcher.
This field was added in Cortex 2.4
isVirtual
boolean
True if the headset is a virtual Brainwear. False otherwise.
Status
When you want to work with a headset, it is important to check its status.
Status
Description
discovered
Cortex has detected the headset, but it is not connected. You cannot create a session for a discovered headset.
You can call to connect the headset.
connecting
Cortex is trying to connect to this headset. This can take a few seconds.
connected
Cortex is connected to and receives data from this headset. You can call and start working with this headset.
You can call to disconnect the headset.
Settings
The settings object include these fields:
Name
Type
Description
mode
string
Can be "EPOC", "EPOCPLUS", or "EPOCFLEX"
eegRate
number
The EEG sample rate, in hertz.
eegRes
number
The EEG resolution, in bits.
memsRate
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.
Name
Type
Description
mappings
object
Describe which EEG channel is mapped to which physical connector of EPOC Flex device. The keys are the names of the connectors, the values are the names of the EEG channels.
Discover details about headsets connected to your device via USB dongle, USB cable, or Bluetooth or virtual headsets enabled through the EMOTIV Launcher. Additionally, search for a specific headset using its ID or apply a wildcard for partial matches.
Parameters
Name
Type
Required
For the parameter id, you can use these wildcards:
Result
The result is an array of , or an empty array if no headset matches the request.
Examples
Query all the headsets
If no headset matches your request, then the result is an empty array.
Query a headset by its id
Query all the Insight headsets
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.
Cortex token
The token is linked to your application. It cannot be used with another application. The token is also linked to the EmotivID of the current user. It cannot be used with another EmotivID. So if the user logs out in 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.
The Cortex token must remain secret. Do NOT share it. It is your responsibility to keep it secure.
Once having Cortex token, the app can .
EULA not accepted warning
If the user has not accepted the EULA, then a warning message will be included in the response as well. The user must accept the EULA through EMOTIV Launcher.
Before you call this method, the user must approve your application in . See for details.
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
Sessions
A session is an object that makes the link between your application and an EMOTIV headset. When the user wants to work with a headset, your application should create a session first.
Then you can:
Your application can open only one session at a time with a given headset. But it can open multiple sessions with multiple headsets.
Session lifetime
A session is created by and closed by .
A session is linked to an application. All the sessions of an application are automatically closed when the application is disconnected from the Cortex service. A session is also closed if the headset is disconnected.
A session is a temporary in-memory object, it is not persistent. After a session is closed, it is destroyed by Cortex. If you want to create a persistent object, please inside your session.
See for details.
Session activation
When you create a session, you can activate it or leave as is.
If the session is not activated, then it doesn't use the license of the user. You cannot subscribe to the EEG stream and you are limited to the low resolution performance metrics. You can neither create a nor .
If the session is activated, then it uses the license of the user. Depending on the license scope of the license, you can subscribe to the EEG stream or high resolution performance metrics. If the license has a session quota, then this session will be debited from this quota.
Use and check the field status to know if a session was activated or not.
updateHeadsetCustomInfo
This method lets you set the headband position of an EPOC X headset.
The headband position is important to interpret the motion data coming from the headset. The motion sensor is located in the headband. So Cortex uses the headband position to know the orientation of the motion sensor.
When you Cortex saves the current headband position into the record. So you should set the position before starting the record.
This method was added in Cortex 2.4
configMapping
The configMapping API manages EEGchannel mapping configurations for a EPOC Flex headset. This API allows you to create, get, read, update and delete mapping configurations.
To connect to an EPOC Flex headset, you must input a specific EEG channel mapping or the name of an existing mapping for the current Emotiv user.
Parameters
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 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.
controlDevice
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.
This method is not available on iOS.
On iOS the user must connect and disconnect the headset in EMOTIV App.
A license id. In most cases, you don't need to specify the license id. Cortex will find the appropriate license based on the client id.
debit
number
no
Number of sessions to debit from the license, so that it can be spent locally without having to authorize again. You need to debit the license only if you want to .
The default value is zero.
A valid Cortex token from a successful authentication.
status
string
Yes
Action to perform: create, get, read, update, or delete.
uuid
string
No
Unique ID of a mapping configuration (required for read, delete).
Status create
Create a new sensor mapping for EPOC Flex. The configuration will be added to list EEG sensor mapping configuration of current emotiv user, can be synced to other machine.
Requires: cortexToken, status="create", name, and mappings.
Example
{"id": 1,"
{"id": 1,"
Status get
Retrieve all mapping configurations for the current Emotiv user.
Requires: cortexToken, status="get".
Example
Status read
Read the details of a specific configuration.
Requires: cortexToken, status="read", uuid.
Example
Status update
To update an existing mapping configuration.
Requires: cortexToken, status, and uuid.
The name and mappings are optional parameters:
If name is included, the configuration name will be updated.
If mappings is included, the mappings will be updated.
If both are included, both fields will be updated.
Example
Status delete
Delete a mapping configuration.
Requires: cortexToken, status="delete", uuid.
Example
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
headset
string
yes
The headset id.
Use to list available headsets.
monotonicTime
number
yes
The monotonic time of your application. The unit is in seconds. The origin can be anything.
You should get this time right before you call this API.
systemTime
Result
The result is a JSON object with these fields:
Name
Type
Description
headset
string
The headset id.
adjustment
number
The difference between the monotonic clock of your application and the monotonic clock of the headset.
The unit is in seconds.
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.
The command must be "connect", "disconnect" or "refresh".
headset
string
no
The id of the headset that you want to connect or disconnect. The headset id is returned by .
If the command is "refresh", then you should omit this parameter.
mappings
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".
By default, the streams "met", "com" and "fac" are not available for EPOC Flex. It is because Cortex doesn't implement the detections (performance metrics, mental command, facial expression) for EPOC Flex.
However, you can configure your EPOC Flex to simulate an EPOC X headset. In that case, Cortex runs the detections that are designed for EPOC X.
All you have to do is to use a sensor mapping that includes all the 14 EEG sensors of an EPOC X headset: AF3, F7, F3, FC5, T7, P7, O1, O2, P8, T8, FC6, F4, F8, AF4.
In addition, you should use P3 and P4 as references CMS and DRL. Please see the EPOC X user manual for the complete EPOC X configuration.
Your mapping can also include sensors that are not present on an EPOC X. Cortex will not use these additional sensors to run the detections, but you can use them to collect more EEG data.
There are two methods for creating the mapping for EPOC Flex:
Using the EMOTIV Launcher, which can be accessed .
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:
Name
Type
Description
command
string
The command that you set in the request
message
string
A success message
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.
This method returns the list of the sessions created by the current application. You can create a session with createSession.
New in 2.0: Sessions are now temporary in-memory objects. So this methods only returns the current sessions, not your past sessions. See Sessions for details.
Parameters
Result
The result is an array of .
Example
updateSession
This method is to activate or close a session. See Sessions for details.
Parameters
Name
Type
Required
Description
Result
The result is a representing the updated session.
Examples
Activate a session
Close a session
createSession
This method is to open a session with an EMOTIV headset.
To open a session with a headset, the status of the headset must be "connected". If the status is "discovered", then you must call controlDevice to connect the headset. You cannot open a session with a headset connected by a USB cable. You can use queryHeadsets to check the status and connection type of the headset.
You can use updateSession to activate or close a session.
Make sure the headset has the status "connected" before you call this method. Use to check the status of the headset.
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.
Data Subscription
After you opened a session with a headset, you can subscribe to one or more data streams.
Each data stream gives you real time access to data from the headset (EEG, motion...) or data calculated by Cortex (band powers, mental command...)
After you successfully subscribe to a data stream, Cortex will keep sending you data sample objects.
A subscription is linked to a session. All the subscriptions of a session are automatically cancelled when the session is closed. You can call unsubscribe to cancel a subscription.
The available data streams depend on the license of the user, and the model and settings of the headset. For an EPOC Flex, it also depends on the EEG sensor mapping.
Data streams
Each data stream is identified by its name: "eeg", "mot", "dev", "eq", "pow", "met", "com", "fac", "sys".
Data streams availability
Depending on the license and the model of the headset, some streams may be available or not, and may send at a different rate.
subscribe
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
Session object
A session is the link between your application and a headset.
You must create a session before you call to receive data from a headset. See .
Description
A session object includes these fields:
Data sample object
After you successfully to a data stream, Cortex will keep sending you data sample objects. See for details.
A data sample object contains these fields:
unsubscribe
This method is to cancel a subscription that was previously created by the method.
Parameters
deleteRecord
This method is to delete one or more records.
The records will be deleted from the local computer, but also from the EMOTIV account of the user in the cloud, and from any computer where the user is logged in.
Your application cannot delete a record that was created by another application.
Deleting a record is irreversible. There is no way to recover a deleted record.
The parameter streams must contain one or more values, chosen from this list: "eeg", "mot", "dev", "eq", "pow", "met", "com", "fac", "sys". See Data Subscription for details.
To subscribe to the "eeg" stream, you must have a paid license and activate the session.
Result
The result is an object that includes these fields:
Name
Type
Description
success
array of objects
For each stream you successfully subscribed to, this array contains an object that describe the data structure of this stream.
failure
array of objects
For each stream you failed to subscribed to, this array contains an object that describes the error.
In case of success, you get an object with these fields:
Name
Type
Description
streamName
string
The name of the stream.
cols
array of strings
The labels of the columns that are part of this stream.
sid
string
The session id.
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 Data sample object for details.
In case of failure, you get an object with these fields:
Name
Type
Description
streamName
string
The name of the stream.
code
number
The error code.
message
string
The error message.
Examples
Subscribe successfully to motion and performance metrics.
Subscribe successfully to performance metrics, but fail to subscribe to raw EEG.
The session id used to subscribe to this data stream.
time
number
The timestamp of this sample. It is the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970 UTC.
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:
The important part is the field cols:
So, the labels for the mental command samples are "act" (action) and "pow" (power), in this order.
Then you will receive some mental command samples. They look like this:
The values in the array com match the labels in the array cols. So "push" is the value for "act" , and 0.376 is the value for "pow".
Below is the description of the labels used in each data stream.
EEG
The stream "eeg" uses these labels:
Label
Type
Description
COUNTER
number
Increment by 1 for each sample, reset to zero every second.
INTERPOLATED
number
0 if this sample was received from the headset.
1 if this sample was interpolated by Cortex.
<EEG sensors>
number
For each EEG sensor, you get 1 value in microvolt.
RAW_CQ
The maker objects include these fields:
Name
Type
Description
applicationId
string
The id of the application that created this marker.
recordId
string
The id of the record this marker belongs to.
markerId
string
The id of this marker.
value
Example for an INSIGHT:
Example for an EPOC+ or EPOC X:
Motion
The stream "mot" uses these labels:
Label
Type
Description
COUNTER_MEMS
number
Increment by 1 for each sample, reset to zero every second.
INTERPOLATED_MEMS
number
0 if this sample was received from the headset.
1 if this sample was interpolated by Cortex.
ACCX, ACCY, ACCZ
number
X, Y, Z axis of the accelerometer.
MAGX, MAGY, MAGZ
Depending on the headset, the labels for the gyroscope will be GYROX, GYROY, GYROZ or the quaternions. You will never get both these labels.
Example for a newer INSIGHT:
Example for an older INSIGHT:
To understand the meaning of motion data, you can refer .
Device information
The stream "dev" uses these labels:
Label
Type
Description
Battery
number
The battery level of the headset, from 0 to 4.
Signal
number
The strength of the wireless signal received from the headset, from 0 to 1.
<EEG sensors>
number
The contact quality of each EEG sensor, from 0 to 4.
There is an additional label "OVERALL" at the end of the array. The overall contact quality is a value from 0 to 100 that is calculated from the contact quality of all the EEG sensors.
The label OVERALL was added in Cortex 2.4
BatteryPercent
Example with INSIGHT:
Example with EPOC+ or EPOC X:
EEG Quality
Please read this page to understand the difference between the contact quality and the EEG quality.
The stream "eq" uses these labels:
Label
Type
Description
batteryPercent
number
The battery level of the headset, from 0 to 100.
overall
number
A value from 0 to 100 that is calculated from the EEG quality of all the EEG sensors.
sampleRateQuality
number
A float value from 0 to 1 that evaluates the actual sample rate of the EEG data coming from the headset.
If the wireless connection between the headset and the computer is perfect (no data loss) then the sample rate quality is 1. If X percent of the EEG samples were lost over the last 2 seconds, then the SRQ is (100 - X) / 100.
If we lost more than 300 ms of data over the last 2 seconds, then the SRQ takes the special value -1.
<EEG sensors>
This stream was added in Cortex 2.7.0
Example with INSIGHT:
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:
Example with EPOC+ or EPOC X:
Performance metric
Each performance metric is a decimal number between 0 and 1. Zero means "low power", 1 means "high power". So for example, a value of 0.1 for "eng" means that the user is not engaged, a value of 1.0 means the user is very engaged.
If the detection cannot run because of a poor EEG signal quality then the value is null.
For each performance metrics, the flag isActive is true if the detection of this metrics is running properly. It is false if the detection cannot run. This can happen if the EEG signal from the headset is of poor quality.
This flag was added in Cortex 2.2.1
The "met" stream labels vary depending on the headset type, as shown in the tables below:
The "met" Stream Labels of MN8
Label
Type
Description
cognitiveStress
number
Cognitive Stress measures the mental strain caused by challenging tasks or environments.
attention
number
Attention measures sustained focus on a single task.
cognitiveStress.isActive
boolean
Active flag for cognitiveStress
attention.isActive
Example
The "met" Stream Labels of EPOC / INSIGHT / FLEX - (with EPOC config only)
Label
Type
Description
eng
number
Engagement measures immersion in an activity.
exc
number
Excitement measures the intensity of reactions to stimuli or environments.
lex
number
Long term excitement. It is calculated from the excitement values of the last minute.
str
Example
To understand the meaning of each performance metrics, you can refer .
Mental command
The stream "com" uses these labels:
Label
Type
Description
act
string
A mental command action. Use the method to get the possible actions.
pow
number
The power of the action. It is a decimal number between 0 and 1, zero means "low power", 1 means "high power".
Facial expression
The stream "fac" uses these labels:
Label
Type
Description
eyeAct
string
The action of the eyes.
uAct
string
The upper face action.
uPow
number
Power of the upper face action. Zero means "low power", 1 means "high power".
The parameter streams must contain one or more values, chosen from this list: "eeg", "mot", "dev", "pow", "met", "com", "fac", "sys". See Data Subscription for details.
Result
The result is an object that includes these fields:
Name
Type
Description
success
array of objects
For each stream you successfully unsubscribed to, this array contains an object with the name of the stream.
failure
array of objects
For each stream you failed to unsubscribed to, this array contains an object that describes the error.
In case of success, you get an object with these fields:
Name
Type
Description
streamName
string
The name of the stream.
In case of failure, you get an object with these fields:
Name
Type
Description
streamName
string
The name of the stream.
code
number
The error code.
message
string
The error message.
Examples
Unsubscribe successfully from the performance metrics and motion streams.
The result is an object that includes these fields:
Name
Type
Description
success
array of objects
For each record you successfully deleted, this array contains an object that includes the record id.
failure
array of objects
For each record that couldn't be deleted, this array contains an object that describes the error.
In case of success, you get an object with these fields:
Name
Type
Description
recordId
string
The id of the record that was successfully deleted.
In case of failure, you get an object with these fields:
Name
Type
Description
recordId
string
The id of the record that couldn't be deleted.
code
number
The error code.
message
string
The error message.
Examples
Deleting two records, including one that has an invalid id.
object
no
The EEG sensor mapping of the EPOC Flex headset that you want to connect.
If the command is not "connect", or if the headset is not an EPOC Flex, then you should omit this parameter.
connectionType
string
no
If the command is "connect" or "disconnect" then this parameter can be "dongle", "bluetooth" or "usb cable", or you can omit it.
If the command is "refresh" then you should omit this parameter.
This parameter was added in Cortex 2.2.1
flexConfigName
string
no
Specify the EEG sensor mapping name for the EPOC Flex headset you wish to connect. This can be retrieved using configMapping. If you provide this parameter, the mappings parameter will be ignored.
This method is to export one or more records to EDF or CSV files.
You can export the raw EEG data, the motion data, the performance metrics and the band powers. The available data streams depend on the license of the record. You can check the field licenceScope in the Record object to know which data streams are available.
By default, you can only export the records that were created by your application. If you want to export a record that was created by another application (e.g. Emotiv PRO or EMOTIV LABS) then you must provide the license id of this application in the parameter licenseIds.
In order to export a record created by EMOTIV LABS, the current Cortex user must be the owner of the LABS experiment.
You must before you can export it. If you want to export a record immediately after you stop it then you must wait for the before you try to export.
The format of the exported files is described in .
This method was added in Cortex 2.1.1 to all desktop versions of Cortex. It was added to iOS and Android in Cortex 2.7.0
Parameters
Data streams
The parameter streamTypes must contain one or more values, chosen from this list: "EEG", "MOTION", "PM", "BP". If the format is "EDF" then only "EEG" and "MOTION" are available.
Format and version
Depending on the parameters format and version Cortex will create different files.
Format EDF, no version
This format is identical to the one used in Cortex 1.x
1 EDF file for the EEG and CQ data
1 EDF file for the motion data
1 JSON file for the markers
Format EDFPLUS/BDFPLUS, no version (available since Cortex version 3.7.5)
1 EDF+/BDF+ file for the EEG, CQ and Motion data
1 JSON file for the markers
1 CSV file for the markers if the parameter includeMarkerExtraInfos is true
Format CSV, version V1
This format is identical to the one used in Cortex 1.x
1 CSV file for the EEG and CQ data
1 CSV file for the band powers
1 CSV file for the motion data
Format CSV, version V2
This format is the new format of Cortex 2.x
1 CSV file for all the data streams (EEG, CQ, band powers, motion, PM)
1 JSON file for the markers
1 CSV file for the markers if the parameter includeMarkerExtraInfos is true
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
EDF
CSV V1
CSV V2
createRecord
This method is to create a new record.
You must create and activate a session before you call this method. See createSession for details.
Parameters
Result
The result is an object containing two fields:
Examples
updateRecord
This method is to update a record. You can update its title, description and its tags.
Your application cannot update a record that was created by another application.
Parameters
Name
Result
The result is a .
Examples
Update the tags and the description.
queryRecords
This method returns a list of records owned by the current user. By default, you only get the records created by your application. To query the records from another application, you must filter by the license id of this application.
Parameters
Name
Type
Required
Depending on the query, this method may return a lot of records. To avoid performance issues, you should always set an offset and a limit.
query
The query object can contain one or more of these fields:
orderBy
The orderBy parameters is an array of objects, similar to the orderBy clause of a SQL request.
Each object must have a single attribute. The key of the attribute is the name of record's field you want to order by. The value of the attribute must be "ASC" or "DESC", to order is ascending or descending order.
For example, to order the records by their start date, in descending order, you must use the object {"startDatetime":"DESC"}. To sort the records by title, in alphabetical order, you must use {"title":"ASC"}.
You can order the records by these fields: title, description, startDatetime, modifiedDatetime, duration, subjectName, applicationId.
The option to order by applicationId was added in Cortex 2.5.0
limit and offset
These parameters are to implement pagination. It useful if you want to display the records in a UI. You must order the results to use these parameters.
First you should call this method with an offset of zero, and a limit of X. In the response, check the value of count. If count is greater than the limit, then you should call this method again with an offset of X. And then with an offset of 2*X, 3*X... until you get all the records for your query.
Result
The result is an object that includes these fields:
Examples
Get the 10 most recent records created by EmotivPRO.
Get some records using a keyword.
Records
After you opened a session with a headset, you can create a record. A record is a permanent object to store data from an EMOTIV headset. You can associate a subject to a record. You can add one or more markers to a record.
Unlike a session, a record is a permanent object. It is stored on the hard drive and then can be synchronized to the EMOTIV cloud. The opt-out configuration can let you decide if the records of a user are uploaded to the cloud or not.
Record lifetime
First, you must with a headset. Then you call to start a new record. When the record is in progress, you can add to this record. You stop a record with .
The record is linked to the session, so if you close the session, or if your application is disconnected from the Cortex service, then Cortex will automatically close the record.
After you stop the record you can export its data to a CSV or EDF file using .
configOptOut
This method is to configure the opt-out feature for the records. This feature lets you decide if the records created by your application on the local machine are uploaded to the EMOTIV cloud or not.
If the opt-out is on (ie the parameter newOptOut is true) then the records created on this machine will not be uploaded to the cloud. If the opt-out is off (ie the parameter newOptOut is false) then the records created on this machine will be uploaded to the cloud.
Please note that changing the opt-out configuration has no effect on the records previously created on the local computer. It only affects the records created after the change. Changing the opt-out configuration is not retroactive.
The opt-out configuration is linked to your application. Changing the configuration only affects the records created by your application. This has no effect on the records created by other applications.
The opt-out configuration is also linked to the EmotivID of the user. The opt-out can be turned on or off for each EmotivID. It is off by default.
You can check the field localOnly of a to know if this record will stay on the local machine, or if it will be uploaded to the EMOTIV cloud.
Some don't let you change the opt-out configuration and force the opt-out to be always on or always off. See the possible configurations below for details.
This method was added in Cortex 2.2.1
Parameters
Result
The result is an object describing the current opt-out configuration. It includes these fields:
Possible Configurations
Here is an overview of the possible configurations:
Examples
Get the current configuration
Change the configuration
Marker object
A marker object includes these fields:
getRecordInfos
This method returns a list of records, selected by their id.
Parameters
requestToDownloadRecordData
This method is to ask Cortex to download the EEG/motion/CQ/detections data of a record from the EMOTIV cloud.
Use case
Suppose that the user has installed Cortex on 2 computers, named computer A and computer B. On computer A, the user creates a record, and Cortex uploads this record to the EMOTIV cloud.
Then, on computer B, Cortex automatically downloads the metadata of this record, ie its name, description, start time, end time, etc... So this record is visible when you call methods like or
Record object
Some methods of the API return one or more record objects, for example .
Description
A record object includes these fields:
Markers
A marker is to mark a point in time, or a period of time, inside a .
Markers are always linked to a record, so you must start a record before you add a marker. You can't add nor update a marker after the record is stopped. You can associate some data to each marker, like a value and a label.
There are two types of markers:
An instance marker is to mark a point in time. You call to create the marker at a specific timestamp.
An interval marker is to mark a period of time, with a beginning and an end. First you create an instance marker with injectMarker. This sets the beginning of the interval. Then you call updateMarker to set the end of the interval, turning the instance marker into an interval marker.
{"id": 1,"jsonrpc": "2.0","method": "updateRecord","params": {"cortexToken":"xxx","record":"d8fe7658-71f1-4cd6-bb5d-f6775b03438f","description":"My best record ever.","tags": ["best","snow","direwolf"]}}
{"id": 1,"jsonrpc": "2.0","result": {"applicationId":"com.jon.snow.winterfell-app","applicationVersion":"1.0","description":"My best record ever.","endDatetime":"2019-06-06T11:42:23.436191+07:00","experimentId":0,"licenseId":"xxx","licenseScope": ["pm","eeg"],"ownerId":"76c3468a-d9c0-428d-81b4-bdac5d63860e","startDatetime":"2019-06-06T11:41:53.088632+07:00","tags": ["best","snow","direwolf"],"title":"Cortex Examples C++","uuid":"d8fe7658-71f1-4cd6-bb5d-f6775b03438f"}}
Subjects
A subject represents a human being who is the subject of a record, ie the person wearing the headset during the record. A subject is a permanent object. It is stored on the hard drive and then synchronized to the EMOTIV cloud.
To associate a subject to a record, you must create the subject first, by calling createSubject. Then you must specify the subject name when you call createRecord. A subject is identified by his/her name.
You can call querySubjects to list the subjects already created for the current user.
An object with fields "from" and "to" to filter the records by their start date time.
modifiedDatetime
object
An object with fields "from" and "to" to filter the records by their modification date time.
duration
object
An object with fields "from" and "to" to filter the records by their duration.
The maximum number of records that this method should return. A limit of zero means no maximum.
offset
number
no
The number of record that this method should skip before returning the result.
If the limit is zero, then Cortex will ignore this parameter.
includeMarkers
boolean
no
If true then the record objects in the result will include the markers linked to each record. The default value is false because a record may have a large number of markers.
This parameter was added in Cortex 2.1
includeSyncStatusInfo
boolean
no
If true then the record object in the result will include the field "syncStatus". This field tells you if the record was uploaded to the EMOTIV cloud or not.
The default value is false.
This parameter was added in Cortex 2.6.3
Name
Type
Description
licenseId
string
Set this parameter to filter the records by their license.
applicationId
string
If you set the licenseId, then you can set this parameter to further filter the records by application.
keyword
string
Set this parameter to filter the records by title, description, or subject name.
If the status is "set" then you must set this parameter to true or false, in order to turn the opt-out feature on or off.
If the status is "get" then you should omit this parameter.
A text message.
Always false
The records will always be uploaded to the cloud. You cannot change the configuration.
false
true
Always false
The records will always be uploaded to the cloud. You cannot change the configuration.
Must be "get" or "set".
Use "get" to read the current configuration of the opt-out feature.
Use "set" to turn the opt-out on or off.
newOptOut
Name
Type
Description
optOutAvail
boolean
If false then the opt-out is always off.
The value of this field depends on the current license. Some license force you to upload the records to the cloud.
forceOptOut
boolean
If true (and optOutAvail is also true) then the opt-out is always on.
The value of this field depends on the current license. Some license don't let you upload the records to the cloud.
currOptOut
boolean
The current configuration of the opt-out.
If this value is true, then the records created by your application won't be uploaded to the cloud. If this value is false, then they will.
message
optOutAvail
forceOptOut
currOptOut
Description
true
false
Variable, false by default
By default, currOptOut is false and the records created by your application will be uploaded to the cloud.
You can change the opt-out configuration for each EmotivID.
true
true
Always true
The records will never be uploaded to the cloud. You cannot change the configuration.
The path of a local folder. Cortex will write the exported files in that folder. You must create this folder before you call this method. Cortex will return an error if the folder doesn't exist.
On iOS, this parameter doesn't exist. Cortex exports the data to the "Documents" folder of the current application.
streamTypes
array of strings
yes
List of the data streams you want to export.
format
string
yes
The format of the exported files. Must be "EDF", "EDFPLUS", "BDFPLUS" or "CSV".
version
string
no
If the format is "EDF", then you must omit this parameter.
If the format is "CSV", then this parameter must be "V1" or "V2".
licenseIds
array of strings
no
The default value is an empty list, which means that you can only export the records created by your application.
You can provide the license ID of other applications in order to export the records created by these applications.
This parameter was added in Cortex 2.6.3
includeDemographics
boolean
no
If true then the exported JSON file will include the demographic data of the user. It is only for the records created by .
The default value is false.
This parameter was added in Cortex 2.6.3
includeSurvey
boolean
no
If true then the exported JSON file will include the survey data of the record. It is only for the records created by .
The default value is false.
This parameter was added in Cortex 2.6.3
From Cortex 3.5.0, survey data will be exported in a separate CSV file (along with JSON file).
includeMarkerExtraInfos
boolean
no
If true then the markers of the records will be exported to a CSV file. This file is compatible with .
The default value is false.
This parameter was added in Cortex 2.6.3
includeDeprecatedPM
boolean
no
If true then deprecated performance metrics (i.e. Focus) will be exported.
The default value is false.
This parameter was added in Cortex 3.5.6
Export the band powers of each EEG sensor.
1 CSV file for the markers if the parameter includeMarkerExtraInfos is true
1 CSV file for the performance metrics
1 JSON file for the markers
1 CSV file for the markers if the parameter includeMarkerExtraInfos is true
An array of record ids. These are the ids of the records you want to export.
folder
Stream
Description
EEG
Export the raw EEG data, the contact quality of each EEG sensor, and the markers.
The license scope of the record must contain the scope "eeg".
MOTION
Export the motion data.
PM
Export the results of the performance metric detection.
If the license scope of the record contains the scope "pm" then Cortex will export the high resolution performance metrics, at 2 hertz. Otherwise Cortex will export the low resolution data, at 0.1 hertz.
MC
Export the results of the mental command detection.
FE
Export the results of the facial expression detection.
Name
Type
Description
success
array of objects
For each record you successfully exported, this array contains an object that includes the record id.
failure
array of objects
For each record that couldn't be exported, this array contains an object that describes the error.
Name
Type
Description
recordId
string
The id of the record that was successfully exported.
The title of the record. Must be 200 characters or less.
description
string
no
The description of the record.
subjectName
string
no
The name of a subject created by . The subject is the person wearing the headset during the record. If you omit this field, then Cortex assumes that the is using the headset.
tags
array of strings
no
A list of tags you can associate to this record.
You can use to search the records by tags.
experimentId
number (integer)
no
An experiment id you can associate to this record. If you omit this parameter then the experimentId of the record will be zero.
The port of the marker, ie where the marker comes from.
Examples: "Software", "Serial", etc...
startDatetime
string (ISO date time)
The timestamp you set in .
endDatetime
string (ISO date time)
The timestamp you set in .
If you didn't call this method, then endDatetime is equal to startDatetime.
extras
object
Can be any extra information you want to associate with this marker.
Examples
An instance marker:
An interval marker:
Name
Type
Description
uuid
string
The id of the marker.
type
string
Can be "interval" or "instance".
value
string or number
string
yes
A token returned by .
recordIds
array of strings
yes
A list of records id.
Result
The result is an array of record objects, including the markers of each record.
Examples
{"id": 1,"
{"id": 1,"
Name
Type
Required
Description
cortexToken
.
But Cortex doesn't automatically download the actual data of the record, ie the EEG, motion, CQ, the results of the detections, etc... So you cannot export this record. To download the actual data, you must call the method "requestToDownloadRecordData".
Parameters
Name
Type
Required
Description
cortexToken
string
yes
A token returned by .
recordIds
array of strings
yes
A list of record ids.
Result
The result is an object with 2 fields:
Name
Type
Description
success
array of objects
List of the records that Cortex will start to download.
failure
array of objects
List of the records that Cortex will not download.
Each object in the success array include these fields:
Name
Type
Description
recordId
string
The id of a record that was added to the Cortex download queue.
Cortex will now start the download.
Each object in the failure array include these fields:
The id of the user this record belongs to. It is a GUID, it is not the EmotivID of the user.
applicationId
string
The id of the application that created this record.
applicationVersion
string
The version of the application that created this record.
title
string
The title of this record.
description
string
The description of this record.
tags
array of strings
The tags associated to this record.
experimentId
number (integer)
The experiment id associated to this record.
startDatetime
string (ISO datetime)
When this record was created.
endDatetime
string (ISO datetime)
When this record was stopped.
licenseId
string
The id of the license used by this record.
licenseScope
array of strings
List of the data streams the license has access to.
The scope "eeg" gives access to the raw EEG data.
The scope "pm" gives access to the 2 hertz performance metrics.
subject
object
This object has a single field "subjectName".
It is the subject name used to create this record. You can use to get more information about the subject. If the record was created without a subject name, then the field "subjectName" contains the EmotivID of the user.
localOnly
boolean
If true then this record will not be uploaded to the EMOTIV cloud.
If false then it will be uploaded.
headbandPosition
string
If the headset is an EPOC X, then this field tells you the position of the headband of this headset during this record. Can be "back" or "top".
If the headset is not an EPOC X, then this field is null.
See for details.
This field was added in Cortex 2.4
Depending on how you get the record, it may contains an additional field for the markers:
Name
Type
Description
markers
array of objects
A list of . The markers added to this record.
syncStatus
Record object returned from getRecordInfos has an additional field syncStatus:
Name
Type
Description
syncStatus
object
contain information of sync status (status field) and/or uploading/downloading progress (percent field).
Available values for status:
"pending": the record is waiting for being downloaded.
"downloading": the record's data is being downloaded. Check progress in percent field.
"downloaded": the record's data is on both the Emotiv Cloud and the local machine.
"notDownloaded": the record's data is on the Emotiv Cloud and not on the local machine.
"failedEncryption", "failedDownload": sync status of the record if fails.
"notUploaded": the record is not uploaded to the Emotiv Cloud yet.
"uploading": the record is being uploaded to the Emotiv Cloud. Check progress in percent field.
"uploaded": the record is on both the Emotiv Cloud and the local machine.
"failedAccessFile", "failedDecryption", "failedUpload": sync status of the record whose uploading fails. Cortex will try uploading again.
"neverUploaded": The record will never be uploaded to the Emotiv Cloud. The record is created with virtual headsets in this case.
For example:
A record is created but waiting for being uploaded to the Emotiv Cloud:
A record is waiting for downloaded from the Emotiv Cloud:
A record is created and is uploading to the Emotiv Cloud:
This method is to update a marker that was previously created by injectMarker.
This method set the end date time of a marker, turning an "instance" marker into an "interval" marker. You can also update the extras object.
The marker must belong to a record that is still in progress. You cannot update the marker if the record is already stopped.
Parameters
Result
The result is an object containing these fields:
Examples
updateSubject
This method is to update an existing subject.
This method was added in Cortex 2.1
Parameters
Name
Type
A subject is identified by his/her name, so you must provide the name of the subject you want to update. Then you can set one or more of the not required fields to update their value.
Result
The result is a representing the updated subject.
Examples
Update the date of birth of a subject.
injectMarker
This method is to create an "instance" marker to the current record of a session. Then you can call updateMarker to turn this marker into an "interval" marker.
You must call createRecord before you call this method.
Parameters
Result
The result is an object containing these fields:
Examples
stopRecord
This method is to stop a record that was previously started by createRecord. This will set the end date time of the record to the current date time.
Parameters
Name
Type
Required
A record is linked to a session. So to close a record, you need to provide the session id.
The result is an array of objects. Each object contain these fields:
Example
deleteSubjects
This method is to delete one or more subjects.
Deleting a subject is irreversible. There is no way to recover a deleted subject.
This method was added in Cortex 2.1
Parameters
A subject is identified by his/her name, so you must provide the name of the subjects you want to delete.
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
.
Subject object
A subject represents a human being who is the subject of a (ie an experiment).
Description
A subject object includes these fields:
getCurrentProfile
This method returns the training profile that is currently loaded for a specific headset.
Parameters
BCI
You can use the Cortex API to develop a brain–computer interface (BCI), using facial expressions, mental commands, or both.
Before you start programming your own BCI, it is strongly recommended that you use to get familiar with the main BCI features of Cortex.
You should also check out the .
getDetectionInfo
This method returns useful information about the mental command training or the facial expression training.
Parameters
setupProfile
This method is to manage the training profiles of the user.
You create, rename or delete a profile. You can load and unload a profile for a headset if the EEG channels of this headset is supported by this training profile. And you can save a profile after the user completed a , or after you changed the of the profile.
Before you load or unload a profile, you can call to know if a profile is currently loaded, and if it was loaded by your application.
queryProfile
This method returns the list of all the training profiles of the user.