Cortex API
Search…
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"}

Remote connections

Since 2.7.1 release, we support remote connections to Cortex running on Raspberry Pi device. It requires some steps:
  • Grant the permissions to a desktop machine before an app on that machine can connect to the Cortex web socket server on Raspberry Pi device, using cortexaccess tool.
  • Connect using the IP address:
    • Only applied if the IP address of your Raspberry Pi device is in the below range:
      • 10.[0-1].[0-2].[0-255]
      • 172.[16-17].[0-2].[0-255]
      • 192.168.[0-5].[0-255]
    • Create a WebSocket client and connect to<IP address of Raspberry Pi device>
      on the port 6868, using the wss protocol.
  • Connect using the DNS name:
    • Can be applied for any value of IP address of your Raspberry Pi device.
    • Add this line into the host file of the desktop machine:<IP address of Raspberry Pi device> emotiv-cortex.remote
    • Create a WebSocket client and connect to emotiv-cortex.remote on the port 6868, using the wss protocol.
Please note that websocket server on Raspberry Pi accepts only 1 remote connection at a time (not counting the remote connection from EMOTIVApp).

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
1
{
2
"id": 1,
3
"jsonrpc": "2.0",
4
"method": "area",
5
"params": {
6
"width": 6,
7
"length": 7
8
}
9
}
Copied!
1
{
2
"id": 1,
3
"jsonrpc": "2.0",
4
"result": 42
5
}
Copied!
Please read the JSON-RPC 2.0 specification for details.

Next step

The rest of this documentation will show you what methods are available, what parameters they take, and how to use these methods.
But first, you should start with the overview of the API flow.