Cortex API
Search
K

controlDevice

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.
This method is not available on iOS. On iOS the user must connect and disconnect the headset in EMOTIV App.

Parameters

Name
Type
Required
Description
command
string
yes
The command must be "connect", "disconnect" or "refresh".
headset
string
no
The id of the headset that you want to connect or disconnect. The headset id is returned by queryHeadsets.
If the command is "refresh", then you should omit this parameter.
mappings
object
no
The EEG sensor mapping of the EPOC Flex headset that you want to connect.
If the command is not "connect", or if the headset is not an EPOC Flex, then you should omit this parameter.
connectionType
string
no
If the command is "connect" or "disconnect" then this parameter can be "dongle", "bluetooth" or "usb cable", or you can omit it. If the command is "refresh" then you should omit this parameter.
This parameter was added in Cortex 2.2.1

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:
Name
Type
Description
command
string
The command that you set in the request
message
string
A success message
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 code 104 to know that the connection is successful. If the connection fails then you will receive a warning with code 100, 101, 102 or 113.
Another way to check if the headset is connected or not is to call queryHeadsets and then check the status of the headset.

Examples

Connect an Insight headset

Request
Response
{
"id": 1,
"jsonrpc": "2.0",
"method": "controlDevice",
"params": {
"command": "connect",
"headset": "INSIGHT-12341234"
}
}
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"command": "connect",
"message": "Start connecting to headset INSIGHT-12341234"
}
}
Then you will receive a warning with code 104 if the connection is successful:
{
"jsonrpc": "2.0",
"warning": {
"code": 104,
"message": {
"headsetId": "INSIGHT-12341234",
"behavior": "The headset is connected"
}
}
}

Connect an Epoc Flex headset

Request
Response
{
"id": 1,
"jsonrpc": "2.0",
"method": "controlDevice",
"params": {
"command": "connect",
"headset": "EPOCFLEX-12341234",
"mappings": {
"CMS": "F3",
"DRL": "F5",
"LA": "AF3",
"LB": "AF7",
"RA": "P8"
}
}
}
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"command": "connect",
"message": "..."
}
}

Disconnect a headset

Request
Response
{
"id": 1,
"jsonrpc": "2.0",
"method": "controlDevice",
"params": {
"command": "disconnect",
"headset": "EPOCFLEX-12341234"
}
}
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"command": "disconnect",
"message": "..."
}
}

Refresh the list of headsets

Use the refresh command to search for new Bluetooth headsets.
Request
Response
{
"id": 1,
"jsonrpc": "2.0",
"method": "controlDevice",
"params": {
"command": "refresh"
}
}
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"command": "refresh",
"message": "..."
}
}