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

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

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

The configMapping API manages EEG channel mapping configurations for a EPOC Flex headset. This API allows you to create, get, read, update and delete mapping configurations.

To connect to an EPOC Flex headset, you must input a specific EEG channel mapping or the name of an existing mapping for the current Emotiv user.

Parameters

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.

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 to know if the update is successful or not.

If your configuration is not compatible with a Bluetooth connection then you will receive a warning with . Your configuration will work fine with a USB dongle. To use the headset with a Bluetooth connection, you must set the EEG rate to 128Hz and disable the motion sensors.

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.

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

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

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

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

Special EEG sensor mapping for EPOC Flex

By default, the streams "met", "com" and "fac" are not available for EPOC Flex. It is because Cortex doesn't implement the detections (performance metrics, mental command, facial expression) for EPOC Flex.

However, you can configure your EPOC Flex to simulate an EPOC X headset. In that case, Cortex runs the detections that are designed for EPOC X.

All you have to do is to use a sensor mapping that includes all the 14 EEG sensors of an EPOC X headset: AF3, F7, F3, FC5, T7, P7, O1, O2, P8, T8, FC6, F4, F8, AF4. In addition, you should use P3 and P4 as references CMS and DRL. Please see the EPOC X for the complete EPOC X configuration.

Your mapping can also include sensors that are not present on an EPOC X. Cortex will not use these additional sensors to run the detections, but you can use them to collect more EEG data.

There are two methods for creating the mapping for EPOC Flex:

1. Using the EMOTIV Launcher, which can be accessed .

2. Using the configMapping API, available .

Example of special EEG sensor mapping:

This feature was added in Cortex 2.7.1

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

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 .

Use Case

Cortex sets the timestamps of each EEG sample using the of the computer. It is more reliable than using the system clock, because the system clock is subject to unpredictable variations, notably because of the synchronization.

When you to a record, Cortex uses the parameter "time" of your request to associate the marker with the EEG sample that has the closest timestamp. So if you want to have accurate markers, you should set the time of your markers using the monotonic clock, not the system clock.

Most programing languages provide a function to get a monotonic time. But in general, the point of origin of this time is undefined. So you need to synchronize the monotonic clock of your application with the monotonic clock used by Cortex. This is the purpose of this Cortex API method.

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

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

Epoc+

Virtual MN8