Connecting to the Cortex API

On Windows and MacOS, the Cortex service is a background process that communicates with the EMOTIV headsets and the EMOTIV cloud. It is also a WebSocket server that uses the JSON-RPC protocol.

WebSocket

Communicate with the Cortex API using the WebSocket Secure protocol.

Create a WebSocket client and connect to localhost on the port 6868, using the wss protocol.

Any WebSocket client should work in any programming language. You can even use a web browser plugin or an online client.

Please note that Cortex only supports the WebSocket Secure (wss) protocol. It doesn't support the plain WebSocket (ws) protocol without encryption.

To try the Cortex API, open a secure WebSocket connection to wss://localhost:6868 and send the message {"id":1,"jsonrpc":"2.0","method":"getCortexInfo"}

JSON-RPC

After you have successfully opened the WebSocket connection, communicate with Cortex using the JSON-RPC 2.0 protocol.

Call methods, with or without parameters, and Cortex sends back a result or an error.

Call an API method by sending a JSON object with these fields:

Name

Type

Required

Description

jsonrpc

string

yes

Must be "2.0"

method

string

yes

The name of the API method you want to call

params

object

no

The parameters of the method, if it has any

id

number or string

no

The id of this request. Cortex will include this id into the response message, so you can can match the response with the request

The response from Cortex is a JSON object with these fields:

Name

Type

Description

jsonrpc

string

Is always "2.0"

result

any

If the method is successful, contains the result of the method. The type depends on the method

error

object

If the method failed, contains an error code and an error message

id

number or string

The id you included in the request

Here is a simple fictional example:

Request
Response
{
"id": 1,
"jsonrpc": "2.0",
"method": "area",
"params": {
"width": 6,
"length": 7
}
}
{
"id": 1,
"jsonrpc": "2.0",
"result": 42
}

Please read the JSON-RPC 2.0 specification for details.

Try it out!

To do a quick test, try to call the method getCortexInfo:

  1. Set the location field to wss://localhost:6868 and click Connect.

  2. Set the message field to {"id":1,"jsonrpc":"2.0","method":"getCortexInfo"} and click Send.

  3. You should get a response that looks like {"id":1,"jsonrpc":"2.0","result":{"version":"2.0.0"}}

Congratulations, you just called your first Cortex API method.

The rest of this documentation will show you what methods are available, what parameters they take, and how to use these methods.