In this section, you will find some advanced BCI features. Please read the section BCI first.

The methods in this section are to read and modify the attributes of a training profile. Changing these attributes affects the way the facial expression and mental command detections work. It can make an action easier to detect, or it can completely disable an action.

Profile name or session id

Most of the methods takes 2 optional parameters, a profile name and a session id.

You must set one of these 2 parameters, and omit the second parameter.

If you set the profile, then Cortex will read the attributes of a profile from the hard drive. You can only read the attributes, you cannot change them. The profile is read only.

If you set the session, then Cortex will read the attributes of a profile currently loaded in-memory. You can also change these attributes. The profile is in read-write mode. After you edited the attributes, you should save the profile to persist your changes.

There is a bug in Cortex 2.0.0. The parameter profile is required, even if you set the parameter session. So, to read/write attributes from a session, you should set the session to your session id and set profile to an empty string. Don't set it to null, don't omit it. This bug is fixed in Cortex version 2.1.0 and above.

This method returns the list of the trained actions of a profile. For each action, you also see how many times the user trained this action.

Parameters

You must set one of these 2 parameters: profile or session. Read this for details.

If you set the session, then this method reads information from the profile that is currently loaded for the headset of this session.

If you set profile then this method reads information from the hard drive. The values you get can be different from reading from the session, especially if the profile was load, edited, and not saved yet.

Result

The result is an object containing these fields:

The objects in trainedActions have 2 fields:

Examples

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getTrainedSignatureActions",
    "params": {
        "cortexToken": "xxx",
        "detection": "mentalCommand",
        "profile": "cortex-v2-example"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "totalTimesTraining": 12,
        "trainedActions": [
            {
                "action": "neutral",
                "times": 1
            },
            {
                "action": "push",
                "times": 1
            },
            {
                "action": "pull",
                "times": 1
            }
        ]
    }
}

This method returns the duration of a training. It is the approximate time needed by Cortex to decide if a training is a success or a failure. See BCI for details.

Parameters

Result

The result is an object containing these fields:

The time should be 8 seconds, for both mental command and facial expression.

Examples

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getTrainingTime",
    "params": {
        "cortexToken": "xxx",
        "detection": "mentalCommand",
        "session": "xxx"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "time": 8,
        "detection": "mentalCommand"
    }
}

This method can get or set the signature used by the facial expression detection.

The "universal" signature contains some generic parameters. It doesn't need (nor accept) any training. It is the default signature. Cortex uses it automatically when the profile doesn't contain any training.

The "trained" signature uses the training from the user. The profile must contain at least one training before you can switch to this signature.

Parameters

You must set one of these 2 parameters: profile or session. Read this for details.

Result

The result is an object containing these fields:

Examples

Get

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "facialExpressionSignatureType",
    "params": {
        "cortexToken": "xxx",
        "status": "get",
        "session": "xxx"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "currentSig": "universal",
        "availableSig": ["universal","trained"]
    }
}

Set

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "facialExpressionSignatureType",
    "params": {
        "cortexToken": "xxx",
        "status": "set",
        "session": "xxx",
        "signature": "trained"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "currentSig": "trained",
        "availableSig": ["universal","trained"]
    }
}

This method can get or set the threshold of a facial expression action for a specific profile.

Actions with a low threshold are less likely to be detected. Actions with a high threshold will be detected more often.

Parameters

You must set one of these 2 parameters: profile or session. Read this for details.

Result

If the status is "get", then the result is a number that is the current threshold of the action. If the status is "set", then the result is a string that is a success message.

Examples

Get

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "facialExpressionThreshold",
    "params": {
        "action": "blink",
        "cortexToken": "xxx",
        "session": "1d5d3655-d570-4731-9faf-967bc5440dc5",
        "status": "get"
    }
}

{
    "id":1,
    "jsonrpc":"2.0",
    "result":500
}

Set

{
    "id": 2323514,
    "jsonrpc": "2.0",
    "method": "facialExpressionThreshold",
    "params": {
        "action": "surprise",
        "cortexToken": "xxx",
        "session": "1d5d3655-d570-4731-9faf-967bc5440dc5",
        "status": "set",
        "value": 703
    }
}

{
    "id": 2323514,
    "jsonrpc": "2.0",
    "result": "success"
}

This method is to get or set the active actions for the mental command detection.

If an action is inactive, then the mental command detection won't detect it anymore. Deactivate an action do not erase its trainings from the profile.

Check out adding new commands and deactivating commands in our BCI app.

Parameters

You must set one of these 2 parameters: profile or session. Read this for details.

Result

If the status is "get", then the result is an array of strings that is the list of active actions.

If the status is "set", then the result is an object with these fields:

Examples

Get

{
    "id": 544314,
    "jsonrpc": "2.0",
    "method": "mentalCommandActiveAction",
    "params": {
        "cortexToken": "xxx",
        "profile": "cortex-v2-example",
        "status": "get"
    }
}

{
    "id": 544314,
    "jsonrpc": "2.0",
    "result": [
        "neutral",
        "push",
        "pull"
    ]
}

Set

{
    "id": 411114,
    "jsonrpc": "2.0",
    "method": "mentalCommandActiveAction",
    "params": {
        "actions": [
            "push"
        ],
        "cortexToken": "xxx",
        "session": "1d5d3655-d570-4731-9faf-967bc5440dc5",
        "status": "set"
    }
}

{
    "id": 411114,
    "jsonrpc": "2.0",
    "result": {
        "actions": [
            "push"
        ],
        "message": "Set MentalCommand active actions successfully"
    }
}

This method returns the brain map of a profile. The brain map is a graphic representation of the mental command training of the user. It indicates which actions are most distinct from each other and from the neutral state as measured by how often the training data is misclassified. The better training you do, the more separated the coordinates will be.

Check out the usage in our BCI app.

Parameters

You must set one of these 2 parameters: profile or session. Read this for details.

Result

The result is an array of objects. Each object is represents a trained actions and contains these fields:

Examples

{
    "id": 5891714,
    "jsonrpc": "2.0",
    "method": "mentalCommandBrainMap",
    "params": {
        "cortexToken": "xxx",
        "profile": "cortex-v2-example",
        "session": "1d5d3655-d570-4731-9faf-967bc5440dc5"
    }
}

{
    "id": 5891714,
    "jsonrpc": "2.0",
    "result": [
        {
            "action": "neutral",
            "coordinates": [0,0]
        },
        {
            "action": "push",
            "coordinates": [0.08947246481272716,0.1596770200887308]
        }
    ]
}

This method returns the skill rating of a mental command action, or the overall mental command skill rating. This is a measure of how often you can trigger the desired action as measured in the previous trainings. A higher rating indicates stronger ability to perform that action.

Parameters

You must set one of these 2 parameters: profile or session. Read this for details.

Result

The result is a number that is the requested skill rating.

Examples

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "mentalCommandGetSkillRating",
    "params": {
        "cortexToken": "xxx",
        "session": "xxx",
        "action": "push"
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": 0.25
}

This method returns the training threshold of the mental command detection. It also returns the score of the last mental command training.

The training threshold provides an indication of minimum threshold that you should target for when training the action, and it changes according to number of total actions that you have currently activated. Any training score above the threshold is very likely to improve your profile. Any training significantly below the threshold is likely to reduce the quality of your profile.

Check out the usage in our BCI app.

Parameters

You must set one of these 2 parameters: profile or session. Read this for details.

Result

The result is an object containing these fields:

Examples

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "currentThreshold": 0.83,
        "lastTrainingScore": 0.40
    }
}

This method get or set the sensitivity of the 4 active mental command actions.

Check out the usage in our BCI app.

Parameters

You must set one of these 2 parameters: profile or session. Read this for details.

The array values contains the sensitivity of each active actions. The order of the values must follow the order of the active actions, as returned by mentalCommandActiveAction.

Result

If the status is "get", then the result is an array of 4 numbers. If the status is "set", then the result is a success message.

Examples

Get

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "mentalCommandActionSensitivity",
    "params": {
        "cortexToken": "xxx",
        "profile": "cortex-v2-example",
        "status": "get"
    }
}

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

Set

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "mentalCommandActionSensitivity",
    "params": {
        "cortexToken": "xxx",
        "session": "1d5d3655-d570-4731-9faf-967bc5440dc5",
        "status": "set",
        "values": [5,7,5,5]
    }
}

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": "success"
}