This method lets you synchronize the monotonic clock of your application with the monotonic clock of Cortex. It is an important step if you want to inject markers with a high precision.

Cortex uses a different clock for each headset and it initializes this clock when the headset is connected by Bluetooth or USB dongle. This means that:

• You must call “syncWithHeadsetClock” after the headset is connected, not before.

• You must provide a headset id.

• If the headset is disconnected and connected again, then you must call this method again.

The simplest solution is to call this method just before creating a record.

Use Case

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

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

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

Parameters

This method takes 3 parameters:

Result

The result is a JSON object with these fields:

To synchronize your clock, you must add the “adjustment” to your monotonic times. If the “adjustment” is positive, then it means your clock is late compared to the Cortex clock. If the “adjustment” is negative, then your clock is ahead of the Cortex clock.

Example

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "syncWithHeadsetClock",
  "params": {
    "headset": "INSIGHT-587XX4BB",
    "monotonicTime": 321.445,
    "systemTime": 1629978090.302
  }
}

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "adjustment": 1629977768.86108,
    "headset": "INSIGHT-587XX4BB"
  }
}

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

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

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

Parameters

Headset Scanning Flow

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

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

EPOC Flex mapping

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

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

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

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

Connection Type

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

Result

The result is an object containing these fields:

Examples

Refresh the list of headsets

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

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

After you finish the process, your application should start headset scanning to search for EMOTIV headsets, using the method with "refresh" command, then use the method to get the discovered headsets.

If the headset is not connected to Cortex yet, then you must call with "connect" command.

See also for details.

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

Parameters

Result

The result is an object containing these fields:

Examples

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:

Status

When you want to work with a headset, it is important to check its status.

Settings

The settings object include these fields:

Flex Mapping

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

Examples

Insight

Epoc+

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

Parameters

For the parameter id, you can use these wildcards:

Result

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

Examples

Query all the headsets

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "connectedBy": "dongle",
            "customName": "",
            "dongle": "6ff",
            "firmware": "625",
            "id": "EPOCPLUS-3B9AXXXX",
            "motionSensors": [
                "GYROX",
                "GYROY",
                "GYROZ",
                "ACCX",
                "ACCY",
                "ACCZ",
                "MAGX",
                "MAGY",
                "MAGZ"
            ],
            "sensors": [
                "AF3",
                "F7",
                "F3",
                "FC5",
                "T7",
                "P7",
                "O1",
                "O2",
                "P8",
                "T8",
                "FC6",
                "F4",
                "F8",
                "AF4"
            ],
            "settings": {
                "eegRate": 256,
                "eegRes": 16,
                "memsRate": 64,
                "memsRes": 16,
                "mode": "EPOCPLUS"
            },
            "status": "connected"
        }
    ]
}

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

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

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

Query a headset by its id

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "queryHeadsets",
    "params": {
        "id": "EPOCPLUS-3B9AXXXX"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "connectedBy": "dongle",
            "customName": "",
            "dongle": "6ff",
            "firmware": "625",
            "id": "EPOCPLUS-3B9AXXXX",
            "motionSensors": [
                "GYROX",
                "GYROY",
                "GYROZ",
                "ACCX",
                "ACCY",
                "ACCZ",
                "MAGX",
                "MAGY",
                "MAGZ"
            ],
            "sensors": [
                "AF3",
                "F7",
                "F3",
                "FC5",
                "T7",
                "P7",
                "O1",
                "O2",
                "P8",
                "T8",
                "FC6",
                "F4",
                "F8",
                "AF4"
            ],
            "settings": {
                "eegRate": 256,
                "eegRes": 16,
                "memsRate": 64,
                "memsRes": 16,
                "mode": "EPOCPLUS"
            },
            "status": "connected"
        }
    ]
}

Query all the Insight headsets

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "queryHeadsets",
    "params": {
        "id": "INSIGHT-*"
    }
}

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": [
    {
      "id": "INSIGHT-AAAA0000",
      "status": "connected",
      "connectedBy": "dongle",
      "customName": "",
      "dongle": "6ff",
      "firmware": "930",
      "headbandPosition": null,
      "motionSensors": [
        "Q0",
        "Q1",
        "Q2",
        "Q3",
        "ACCX",
        "ACCY",
        "ACCZ",
        "MAGX",
        "MAGY",
        "MAGZ"
      ],
      "sensors": [
        "AF3",
        "T7",
        "Pz",
        "T8",
        "AF4"
      ],
      "settings": {
        "eegRate": 128,
        "eegRes": 14,
        "memsRate": 64,
        "memsRes": 14,
        "mode": "INSIGHT"
      }
    }
  ]
}

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

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

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

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

Parameters

The setting parameter must be an object with these fields:

Result

The result is an object containing these fields:

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

However, since Cortex 2.4.0, the result of the method just tells you that the update is in progress. You must wait for a warning object with code 110 or 111 to know if the update is successful or not.

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

Examples

Set the EEG rate to 256 hertz (16 bits) and the motion rate to 64 hertz (16bits)

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "updateHeadset",
    "params": {
        "cortexToken": "xxx",
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "setting": {
            "mode": "EPOCPLUS",
            "eegRate": 256,
            "memsRate": 64
        }
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "message": "..."
    }
}

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "updateHeadset",
    "params": {
        "cortexToken": "xxx",
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "setting": {
            "mode": "EPOC",
            "eegRate": 128,
            "memsRate": 0
        }
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "message": "..."
    }
}