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

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 warning with code 142 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:

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

Refresh the list of headsets

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

Request

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "controlDevice",
    "params": {
        "command": "refresh"
    }
}

Response

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "command": "refresh",
        "message": "..."
    }
}

Then you will receive a warning with code 142 when scanning is finished.

{
    "jsonrpc": "2.0",
    "warning": {
        "code": 142,
        "message": {
            "behavior": "Headset discovering complete."
        }
    }
}

Connect an Insight headset

Request

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "controlDevice",
    "params": {
        "command": "connect",
        "headset": "INSIGHT-12341234"
    }
}

Response

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

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

Response

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "command": "connect",
        "message": "..."
    }
}

Disconnect a headset

Request

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "controlDevice",
    "params": {
        "command": "disconnect",
        "headset": "EPOCFLEX-12341234"
    }
}

Response

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "command": "disconnect",
        "message": "..."
    }
}