After you successfully subscribe to a data stream, Cortex will keep sending you data sample objects. See Data Subscription for details.
A data sample object contains these fields:
To interpret the values in the <stream> array, you must check the field cols from the result of the subscribe method.
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.
The stream "eeg" uses these labels:
The maker objects include these fields:
Example for an INSIGHT:
Example for an EPOC+ or EPOC X:
The stream "mot" uses these labels:
Depending on the headset, the labels for the gyroscope will be GYROX, GYROY, GYROZ or the quaternions. You will never get both these labels.
Example for a newer INSIGHT:
Example for an older INSIGHT:
The stream "dev" uses these labels:
Example with INSIGHT:
Example with EPOC+ or EPOC X:
Please read this page to understand the difference between the contact quality and the EEG quality.
The stream "eq" uses these labels:
This stream was added in Cortex 2.7.0
Example with INSIGHT:
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:
The stream "met" uses these labels:
Each performance metric is a decimal number between 0 and 1. Zero means "low power", 1 means "high power". So for example, a value of 0.1 for "eng" means that the user is not engaged, a value of 1.0 means the user is very engaged. If the detection cannot run because of a poor EEG signal quality then the value is null.
For each performance metrics, the flag isActive is true if the detection of this metrics is running properly. It is false if the detection cannot run. This can happen if the EEG signal from the headset is of poor quality. This flag was added in Cortex 2.2.1
The stream "com" uses these labels:
The stream "fac" uses these labels:
Use the method getDetectionInfo to get the possible actions.
The stream "sys" is used for the training of the mental command and facial expression. It uses these labels:
For example, just after you start a training for the mental command detection, you receive a system event like this:
Name
Type
Description
<stream>
array
The name of this field is the name of the data stream, for example "eeg", "met", "com"...
This array contains the values of a data sample. The type and meaning of each value depend on the stream.
sid
string
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.
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
number
Raw value of the contact quality.
MARKER_HARDWARE
number
1 if a hardware marker was received for this EEG sample.
0 otherwise.
MARKERS
array of objects
An array of markers. It includes the markers sent by all the applications working with this headset.
This label was added in Cortex 2.1
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
string or number
The value of this marker, set by injectMarker.
label
string
The label of this marker, set by injectMarker.
port
string
The port of this marker, set by injectMarker.
isStop
boolean
False if this is an instance marker.
True if this marks the end of an interval marker.
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
number
X, Y, Z axis of the magnetometer.
Q0, Q1, Q2, Q3
number
Quaternions of the gyroscope (newer EMOTIV headsets)
GYROX, GYROY, GYROZ
number
X, Y, Z axis of the gyroscope (older EMOTIV headsets)
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
number
The battery level of the headset, from 0 to 100. It has the same purpose as the label "Battery", but it is more precise.
This label was added in Cortex 2.7
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>
number
The EEG quality of each EEG sensor, from 0 to 4.
Label
Type
Description
eng
number
Engagement
exc
number
Excitement
lex
number
Long term excitement. It is calculated from the excitement values of the last minute.
str
number
Stress / Frustration
rel
number
Relaxation
int
number
Interest / Affinity
foc
number
Focus
eng.isActive
boolean
Active flag for engagement.
exc.isActive
boolean
Active flag for excitement.
str.isActive
boolean
Active flag for stress / frustration.
rel.isActive
boolean
Active flag for relaxation.
int.isActive
boolean
Active flag for interest / affinity.
foc.isActive
boolean
Active flag for focus.
Label
Type
Description
act
string
A mental command action. Use the method getDetectionInfo 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".
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".
lAct
string
The lower face action.
lPow
number
Power of the lower face action. Zero means "low power", 1 means "high power".
Label
Type
Description
event
string
The name of the detection. Can be "mentalCommand" or "facialExpression"
msg
string
Depends on the detection. Use the method getDetectionInfo to get the possible values, check the field events in the result.
After you opened a session with a headset, you can subscribe to one or more data streams.
Each data steam 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.
Each data stream is identified by its name: "eeg", "mot", "dev", "eq", "pow", "met", "com", "fac", "sys".
Depending on the license and the model of the headset, some streams may be available or not, and may send data samples objects at a different rate.
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.
You must configure the EEG sensor mapping of your EPOC Flex when you call the method controlDevice.
This feature was added in Cortex 2.7.1
This method is to cancel a subscription that was previously created by the subscribe method.
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.
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:
Unsubscribe successfully from the performance metrics and motion streams.
This method is to subscribe to one or more data streams. You can call unsubscribe to cancel a subscription. After you successfully subscribe to a stream, Cortex will keep sending you data sample objects.
See Data Subscription for details.
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.
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 Data sample object for details.
In case of failure, you get an object with these fields:
Subscribe successfully to motion and performance metrics.
Subscribe successfully to performance metrics, but fail to subscribe to raw EEG.
Stream
Description
eeg
The raw EEG data from the headset.
mot
The motion data from the headset.
dev
The device data from the headset. It includes the battery level, the wireless signal strength, and the contact quality of each EEG sensor.
eq
The EEG quality of each EEG sensor.
Please read this page to understand the difference between the contact quality and the EEG quality.
pow
The band power of each EEG sensor. It includes the alpha, low beta, high beta, gamma, and theta bands.
met
The results of the performance metrics detection.
com
The results of the mental commands detection. You must load a profile to get meaningful results.
fac
The results of the facial expressions detection.
sys
The system events. These events are related to the training of the mental commands and facial expressions. See BCI for details.
Stream
Supported headsets
Sample rate in hertz
eeg
All, but requires a license
128 or 256, depends on the headset and its settings.
The license must contain the scope "eeg". You must activate the session before you subscribe.
Please check the documentation of your headset.
mot
All
Disabled, 32, 64, 128, depends on the headset and its settings.
6.4 hertz for MN8.
Please check the documentation of your headset.
dev
All
2
eq
All
2
pow
All
8
met
All EPOC Flex requires a special EEG sensor mapping
2 if the license contains the scope "pm" and you activate the session before you subscribe. 0.1 otherwise (1 sample every 10 seconds)
com
All EPOC Flex requires a special EEG sensor mapping
8
fac
All but MN8 EPOC Flex requires a special EEG sensor mapping
32
sys
All
No fixed rate, see BCI for details.
Name
Type
Required
Description
cortexToken
string
yes
A token returned by authorize.
session
string
yes
A session id returned by createSession.
streams
array of strings
yes
The data streams you want to unsubscribe to.
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.
Name
Type
Description
streamName
string
The name of the stream.
Name
Type
Description
streamName
string
The name of the stream.
code
number
The error code.
message
string
The error message.
Name
Type
Required
Description
cortexToken
string
yes
A token returned by authorize.
session
string
yes
A session id returned by createSession.
streams
array of strings
yes
The data streams you want to subscribe to.
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.
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.
Name
Type
Description
streamName
string
The name of the stream.
code
number
The error code.
message
string
The error message.