If you upgrade from EmotivBCI before v3.6.5, you should notice that we change the format of training profiles so that the existing training profile (i.e. created before v3.6.5) will not be fully supported. We call them readonly profiles which can only run at a live mode and cannot run on training mode.

These readonly training profiles only support headsets with 14 EEG channels (i.e. EPOC X and Flex with EPOC X config mapping).

You can use the Cortex API to develop a brain–computer interface (BCI), using facial expressions, mental commands, or both.

To get the results of the facial expression detection and the mental command detection, you must subscribe to the data streams "fac" and "com" respectively.

To use the mental command detection, you must load a training profile that contains training data for at least one action. For the facial expression detection, the training is optional.

Profile

A profile is a persistent object that stores training data for the facial expression and mental command detections. A profile belongs to a user and is synchronized to the EMOTIV cloud.

You can use queryProfile to list the profiles of the current user. Use setupProfile to manage the profiles, and also to load or unload a profile for a headset. You can use training to add training data to a profile.

Before v3.6.5, a profile can be loaded for both Epoc/Flex and Insight. Since v3.6.5, a profile can only be loaded for Epoc/Flex or Insight since their EEG channels are different. If you upgrade from version before 3.6.5, the existing profiles will become readonly. See Readonly training profile.

Training workflow

The training works that same for the mental command detection and the facial expression detection. However, they don't use the same actions, events or controls. So you should call getDetectionInfo to know what actions, controls and events you can use for each detection.

Before you start a training, you must subscribe to the data stream "sys" to receive the training events from Cortex. Then you can follow these steps:

1. Start the training by calling training with the action you want to train and the control "start".

2. On the "sys" stream, you receive the event "started".

3. After a few seconds, you receive one of these two events:

   1. Event "succeeded", the training is a success. Now you must accept it or reject it.

   2. Event "failed", the data collected during the training is of poor quality, you must start over from the beginning.

4. Call training with the control "accept" to add the training to the profile. Or you can use the control "reject" to reject this training, and then you must start over from the beginning.

5. Cortex sends the event "completed" to confirm that the training was successfully completed.

6. You should save the profile to persist this training. If you unload the profile without saving, then the training is lost.

After step 2, but before step 3, you can send the control "reset" to cancel the training.

The following chart illustrates the flow of BCI training with corresponding request for each step:

Getting live actions

The following chart illustrates the streaming of Mental Commands data in live:

This method returns the list of all the training profiles of the user.

Parameters

Result

The result is an array of objects , or an empty array if the user has no profile. Each object includes these fields:

Example

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "queryProfile",
    "params": {
        "cortexToken": "xxx"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "uuid":"xxx"
            "name":"Profile A",
            "readOnly":false,
            "eegChannels":["AF3","T7","Pz","T8","AF4"]
        },
        {
            "uuid":"yyy"
            "name":"Profile B",
            "readOnly":true,
            "eegChannels":["AF3","F7","F3","FC5","T7","P7","O1","O2","P8","T8","FC6","F4","F8","AF4"]
        }
    ]
}

This method returns useful information about the mental command training or the facial expression training.

Parameters

Result

The result is an object containing information about the detection you specified in the parameters.

Examples

Mental command

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getDetectionInfo",
    "params": {
        "detection": "mentalCommand"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "actions": [
            "neutral",
            "push",
            "pull",
            "lift",
            "drop",
            "left",
            "right",
            "rotateLeft",
            "rotateRight",
            "rotateClockwise",
            "rotateCounterClockwise",
            "rotateForwards",
            "rotateReverse",
            "disappear"
        ],
        "controls": [
            "start",
            "accept",
            "reject",
            "erase",
            "reset"
        ],
        "events": [
            "MC_Started",
            "MC_Succeeded",
            "MC_Failed",
            "MC_Completed",
            "MC_DataErased",
            "MC_Rejected",
            "MC_Reset",
            "MC_AutoSamplingNeutralCompleted",
            "MC_SignatureUpdated"
        ],
        "signature": []
    }
}

Facial expression

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getDetectionInfo",
    "params": {
        "detection": "facialExpression"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "actions": [
            "neutral",
            "blink",
            "winkL",
            "winkR",
            "horiEye",
            "surprise",
            "frown",
            "smile",
            "clench",
            "laugh",
            "smirkLeft",
            "smirkRight"
        ],
        "controls": [
            "start",
            "accept",
            "reject",
            "erase",
            "reset"
        ],
        "events": [
            "FE_Started",
            "FE_Succeeded",
            "FE_Failed",
            "FE_Completed",
            "FE_DataErased",
            "FE_Rejected",
            "FE_Reset"
        ],
        "signature": [
            "universal",
            "trained"
        ]
    }
}

This method returns the training profile that is currently loaded for a specific headset.

Parameters

Result

The result is an object containing these fields:

Examples

This method loads an empty profile for a headset. You can use this method to quickly load a profile, without having to create a profile with .

Parameters

Result

The result is an object containing these fields:

Examples

This method is to control the training of the mental command and facial expression detections. Before you start a training, you should to the "sys" data stream.

See for details.

Parameters

status

To get the available status for a detection, call , and check the field controls of the result object. Or you can check this list:

action

However, note that for the facial expression detection, only these actions can be trained: "neutral", "surprise", "frown", "smile", "clench".

Result

The result is an object containing these fields:

Examples

Start a training

Start a mental command training for the action "push".

Accept a training

Accept a successful training for the action "push".

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.

Parameters

Depending on the status, this method has different effects, and uses different parameters.

Status create

Create a new profile. It can be an empty profile, or a copy of a loaded profile.

Status load

Load an existing profile for a specific headset. If a profile is already loaded, then you must unload it first.

Status unload

Unload the profile of a specific headset. After the unload, this headset will use a default empty profile. You should set the parameter profile to an empty string. You cannot unload a profile that was loaded by another application.

Status save

Save the profile used by a headset. You can save it with a new name, so it creates a new profile. Or you can save it with the same name, ie the name you used to load it. You cannot save a profile that was loaded by another application.

Status rename

Rename an existing profile.

Status delete

Delete an existing profile. If this profile is loaded for a headset, then it is automatically unloaded. You cannot delete a profile that is currently loaded by another application.

Result

The result is an object containing these fields:

Examples

Create a new empty profile

Load a profile for a headset

Save a profile