Connecting to the Cortex API
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"}The Cortex web socket server uses a self-signed certificate. When you install Emotiv softwares, the installer has already installed the Emotiv Root CA file and ask the system to trust it, so most of the time, your application don't need to configure anything else. However, for some programming languagues or for remote connections to Pi, you must configure a custom Certificate Authorities (CA) to trust Cortex websocket connection.
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).
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
}
The rest of this documentation will show you what methods are available, what parameters they take, and how to use these methods.
Last modified 6d ago