Remote control#
The Open Ephys HTTP Server enables remote control of the GUI via a RESTful API. Immediately upon launching, the GUI starts an HTTP server on port 37497 (EPHYS on a phone keypad). You can confirm that the server is running by pointing a web browser to http://localhost:37497/api/processors. If you’re using a different computer, substitute localhost with the IP address of the machine running the GUI. This should display a JSON string with information about the current signal chain.
The HTTP server can be disabled or re-enabled via the File menu.
The following sections document the various remote control commands that are available. Python examples based on the requests library, while Matlab examples use the webread and webwrite functions.
Start/stop acquisition and recording#
URL |
|
Querying the GUI’s acquisition/recording status uses an HTTP GET request at the /api/status endpoint.
Python Example:
r = requests.get("http://localhost:37497/api/status")
Matlab Example:
out = webread('http://localhost:37497/api/status')
This returns a JSON string (accessible via r.json() in Python) containing information about the current mode of the GUI, which can take the following values:
IDLE- the GUI is not acquiring dataACQUIRE- the GUI is acquiring data, but not recordingRECORD- the GUI is acquiring and recording data
To set the GUI’s status, use an HTTP PUT request.
Python Example:
r = requests.put(
"http://localhost:37497/api/status",
json={"mode" : "ACQUIRE"})
Matlab Example:
url = 'http://localhost:37497/api/status'
out = webwrite(url, struct('mode','ACQUIRE'),
weboptions('RequestMethod','put','MediaType','application/json'))
Note
The signal chain must contain at least one Record Node in order for the RECORD command to work.
Get/set recording configuration#
URL |
|
Information related to recording can be queried and updated using the /api/recording endpoint. Sending a GET request to this endpoint will return a JSON string with information about the recording directory as well as the details of each record node.
Python Example:
r = requests.get("http://localhost:37497/api/recording")
Matlab Example:
out = webread('http://localhost:37497/api/recording')
This will return a JSON string with the following structure:
{
'parent_directory' : '/Users/neuroscientist/Documents/OpenEphys',
'base_text' : 'AUTO',
'prepend_text' : 'NONE',
'append_text' : 'AUTO',
'record_nodes' : [
{
'node_id' : 102,
'parent_directory' : '/Users/neuroscientist/Documents/OpenEphys',
'record_engine' : 'BINARY',
'experiment_number' : 1,
'recording_number' : 3,
'is_synchronized' : true
}, ...
]
}
To update the default location for storing data, use an HTTP PUT request to set the parent_directory field.
Python Example:
r = requests.put(
"http://localhost:37497/api/recording",
json={"parent_directory" : "/Users/neuroscientist/Documents/Data"})
Matlab Example:
url = 'http://localhost:37497/api/recording'
out = webwrite(url, struct('parent_directory','/Users/neuroscientist/Documents/Data'),
weboptions('RequestMethod','put','MediaType','application/json'))
Note that this new directory will be applied only to future Record Nodes, not Record Nodes that are already present in the signal chain.
To change the recording directory for a specific Record Node, the Record Node’s ID must be appended to the address.
Python Example:
r = requests.put(
"http://localhost:37497/api/recording/102",
json={"parent_directory" : "/Users/neuroscientist/Documents/Data"})
Matlab Example:
url = 'http://localhost:37497/api/recording/102'
out = webwrite(url, struct('parent_directory','/Users/neuroscientist/Documents/Data'),
weboptions('RequestMethod','put','MediaType','application/json'))
To use custom base text for the next recording directory (in place of the auto-generated date string), use the following commands:
Python Example:
r = requests.put(
"http://localhost:37497/api/recording",
json={"base_text" : "new_directory_name"})
Matlab Example:
url = 'http://localhost:37497/api/recording'
out = webwrite(url, struct('base_text','new_directory_name'),
weboptions('RequestMethod','put','MediaType','application/json'))
The same endpoint can be used to set the recording directory prepend_text and append_text as well.
Get information about the signal chain#
URL |
|
Sending a GET request to the /api/processors endpoint will return a JSON string with information about available processors and their parameters. Information about Record Nodes is accessed separately, via the /api/recording endpoint.
Python Example:
r = requests.get("http://localhost:37497/api/processors")
Matlab Example:
out = webread('http://localhost:37497/api/processors')
will return a string with the following structure:
{
"processors" : [
{
"id" : 100,
"name" : "File Reader",
"parameters" : [ ],
"predecessor" : null,
"streams" : [
{
"channel_count" : 16,
"name" : "example_data",
"parameters" : [ ],
"sample_rate" : 40000.0,
"source_id" : 100
}
]
},
{
"id" : 101,
"name" : "Bandpass Filter",
"parameters" : [ ],
"predecessor" : 100,
"streams": [
{
"channel_count" : 16,
"name" : "example_data",
"sample_rate" : 40000.0,
"source_id" : 100
"parameters" : [
{
"name" : "enable_stream",
"type" : "Boolean",
"value" : "true"
},
{
"name" : "high_cut",
"type" : "Float",
"value" : "6000"
},
{
"name" : "low_cut",
"type" : "Float",
"value" : "300"},
{
"name" : "Channels",
"type" : "Mask Channels",
"value" : ""
}
],
}
]
}
}
Appending the 3-digit processor ID to the endpoint (e.g., /api/processors/101) will return information about one processor at a time.
Send a configuration message to a specific processor#
URL |
|
Certain processors can respond to custom configuration messages that modify their state prior to starting acquisition. For example, the following command will change the reference setting on a Neuropixels probe connected to slot 3, port 1, and dock 1:
Python Example:
r = requests.put(
"http://localhost:37497/api/processors/100/config",
json={"text" : "NP REFERENCE 3 1 1 TIP"})
Matlab Example:
url = 'http://localhost:37497/api/processors/100/config'
out = webwrite(url, struct('text','NP REFERENCE 3 1 1 TIP'),
weboptions('RequestMethod','put','MediaType','application/json'))
Broadcast a message to all processors#
URL |
|
Broadcast messages are relayed to all processors while acquisition is active. These messages will be ignored unless a plugin has implemented the handleBroadcastMessage() method, and knows how to respond to the specific message that was sent. For example, the following command will trigger a 100 ms pulse on digital output line 1 of the Open Ephys Acquisition Board:
Python Example:
r = requests.put(
"http://localhost:37497/api/message",
json={"text" : "ACQBOARD TRIGGER 1 100"})
Matlab Example:
url = 'http://localhost:37497/api/message'
out = webwrite(url, struct('text','ACQBOARD TRIGGER 1 100'),
weboptions('RequestMethod','put','MediaType','application/json'))
Tip
Broadcast messages are saved by all Record Nodes, so these messages can be used to mark different epochs within a given recording.
Close the GUI remotely#
URL |
|
To shut down the GUI, send the quit command to the /api/window endpoint:
Python Example:
r = requests.put(
"http://localhost:37497/api/window",
json={"command" : "quit"})
Matlab Example:
url = 'http://localhost:37497/api/window'
out = webwrite(url, struct('command','quit'),
weboptions('RequestMethod','put','MediaType','application/json'))