REST API

POST /simulation/clone-resources-files

Clone the resources files from the storage to the tmp folder

< json string exp_id

The experiment ID

Status Codes
GET /simulation/topics

Gets a list of topics available in the current simulation

GET /health/errors-last-24h

Get a nagios status regarding the number of errors that happened in the last 24 hours.

GET /health/errors

Get a nagios status regarding the number of errors that happened since the server started.

GET /simulation

Gets the list of simulations on this server.

> json int experimentID

> json int brainProcesses

> json int environmentConfiguration

> json string owner

The simulation owner (Unified Portal user name or ‘hbp-default’)

> json int reservation

> json string creationDate

Date of creation of this simulation

> json string creationUniqueID

> json string gzserverHost

Denotes where the gzserver will run once the simulation is started, local for localhost, lugano for a remote execution on the Lugano viz cluster.

> json string state

The current state of the simulation

> json int simulationID

The id of the simulation (needed for further REST calls)

Status Codes

  • 200 OK – Simulations retrieved successfully

POST /simulation

Creates a new simulation which is neither ‘initialized’ nor ‘started’.

< json int brainProcesses

Number of brain processes to use (overrides ExD Configuration)

< json string experimentID

The experiment ID of the experiment

> json string gzserverHost

The host where gzserver will be run: local for using the same machine of the backend, lugano to use a dedicated instance on the Lugano viz cluster

< json string reservation

the name of the cluster reservation subsequently used to allocate a job

< json string state

The initial state of the simulation

< json boolean private

Defines whether the simulation is based on a private experiment

< json string playbackPath

Path to simulation recording to play (optional)

< json string ctx-id

The context id of the collab if we are running a collab based simulation

> json string owner

The simulation owner (Unified Portal user name or ‘hbp-default’)

> json integer simulationID

The id of the simulation (needed for further REST calls)

> json string creationDate

Date of creation of this simulation

> json string creationUniqueID

The simulation unique creation ID that is used by the Frontend to identify this simulation

> json string profiler

indicates the profiler mode for the simulation: disabled, cle_step, cprofile

Status Codes
GET /version

Returns the versions of all NRP python packages.

> json string hbp_nrp_cle

> json string hbp_nrp_backend

> json string hbp_nrp_cleserver

> json string hbp_nrp_commons

> json string hbp_nrp_excontrol

Status Codes

  • 200 OK – Success. The versions were retrieved

PUT /simulation/(int: sim_id)/transfer-functions/(string: transfer_function_name)/activation/(string: activate)

Sets the activation state of the transfer function

Parameters

  • sim_id – The simulation ID

  • transfer_function_name – The name of the transfer function to be modified

  • activate – A boolean denoting the new desired activation status

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – The (de-)activation of the Transfer Function has failed

  • 200 OK – Success. The activation state of the TF has been successfully changed

PUT /simulation/(int: sim_id)/interaction/material_change

Change the material of a given visual. Currently, only the change of screen materials is implemented

Parameters

  • sim_id – The simulation ID

< json string visual_path

The path to the visual for which a change in material is requested

< json string material_name

The name of the material that will be applied

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – The parameters are invalid

  • 200 OK – Material applied successfully

PUT /simulation/(int: sim_id)/interaction/light

Raises a light event

Parameters

  • sim_id – The simulation ID

< json string name

The light to change

< json RGBADescription diffuse

the diffuse color

< json float attenuation_constant

the attenuation constant

< json float attenuation_linear

the attenuation linear

< json float attenuation_quadratic

the attenuation quadratic

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – The parameters are invalid

  • 200 OK – Successfully raised event

PUT /simulation/(int: sim_id)/convert-structured-tf-to-raw

Puts the structured transfer functions and returned raw function

Status Codes

  • 200 OK – Success. The transfer function was successfully converted

PUT /simulation/(int: sim_id)/convert-raw-tf-to-structured

Puts the raw transfer functions and returned structured function

Status Codes

  • 200 OK – Success. The transfer function was successfully converted

DELETE /simulation/(int: sim_id)/transfer-functions/(string: transfer_function_name)

Delete a transfer function

Parameters

  • sim_id – The simulation ID

  • transfer_function_name – The name of the transfer function to be deleted

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 200 OK – Success. The code was successfully patched

PUT /simulation/(int: sim_id)/transfer-functions/(string: transfer_function_name)

Applies user changes to transfer function code

Parameters

  • sim_id – The simulation ID

  • transfer_function_name – The name of the transfer function to be modified

< string data

The source code of the transfer function

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 403 Forbidden – Name already exists

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – The source code is invalid.

  • 200 OK – Success. The transfer function was successfully patched

GET /simulation/(int: sim_id)/transfer-functions

Gets all transfer functions (robot to neuron and neuron to robot) in a dictionary with string values.

Parameters

  • sim_id – The simulation ID

> json dict data

Dictionary containing all transfer functions (‘name’: ‘source’)

> json dict active

Dictionary containing a mask for active TFs (‘name’: ‘isActive’)

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to see the simulation changes.You can only see the simulations you own or those for which the experiment has been shared with you

  • 200 OK – Transfer functions retrieved successfully

POST /simulation/(int: sim_id)/transfer-functions

Adds a new transfer function

Parameters

  • sim_id – The simulation ID

< string data

The source code of the transfer function

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 403 Forbidden – Name already exists

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – The source code is invalid.

  • 200 OK – Success. The transfer function was successfully added

DELETE /simulation/(int: sim_id)/state-machines/(string: state_machine_name)

Delete a state machine

Parameters

  • sim_id – The simulation ID

  • state_machine_name – The name of the state machine to be deleted

Status Codes

  • 500 Internal Server Error – The query failed due to an internal server error

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 200 OK – The delete operation was successfully called. This does not imply that the state machine function was correctly deleted though.

PUT /simulation/(int: sim_id)/state-machines/(string: state_machine_name)

Applies user changes to state machine code. If the simulation is paused or started, it will be paused. A stopped, created or failed simulation will fail the request with error code 403

Parameters

  • sim_id – The simulation ID

  • state_machine_name – The name of the state machine to be modified

< json string data

The source code of the state machine

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – The source code is invalid.

  • 200 OK – Success. The code was successfully patched

POST /simulation/(int: sim_id)/extend_timeout

Extends the simulation timeout

Parameters

  • sim_id – The simulation id

Status Codes
GET /simulation/(int: sim_id)/state-machines

Get code of all state machines. This works in all simulation states except ‘created’, where it will deliver an empty dictionary.

Parameters

  • sim_id – The simulation ID

> json dict data

Dictionary containing all state machines (‘name’: ‘source’)

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to see the simulation changes.You can only see the simulations you own or those for which the experiment has been shared with you

  • 200 OK – Success. The state machines were returned

PUT /simulation/(int: sim_id)/populations

Set the populations of the brain in a simulation with the specified simulation id.

Parameters

  • sim_id – The simulation ID

< json dict brain_populations

A dictionary indexed by population names and containing neuron indices

< json string brain_type

Type of the brain file (‘h5’ or ‘py’)

< param brain_populations

Contents of the brain file. Encoding given in field data_type

< json string data_type

type of the data field (‘text’ or ‘base64’)

< json string change_population

indicates if it has to be changes in the transfer functions

> json string message

Error Message if there is a syntax error in the code

Status Codes

  • 404 Not Found – Error on server: environment variable: ‘NRP_MODELS_DIRECTORY’ or ‘NRP_EXPERIMENTS_DIRECTORY’ is empty

  • 200 OK – Success. The populations of the brain where successfully set

GET /simulation/(int: sim_id)/populations

Gets the neurons of the brain in a simulation with the specified simulation id.

Parameters

  • sim_id – The simulation ID

> json array Populations

array of population dictionaries. Each dict contains population name, neuron indices, neuron model, parameters and gids

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to see the simulation changes.You can only see the simulations you own or those for which the experiment has been shared with you

  • 200 OK – The neurons of the simulation with the given ID where successfully retrieved

GET /simulation/(int: sim_id)/resources

Gets simulation resource files of the experiment running for the simulation ID

Parameters

  • sim_id – The simulation ID

> json string resources

Resource files

Status Codes

  • 500 Internal Server Error – Error on server: environment variable: ‘NRP_MODELS_DIRECTORY’ or ‘NRP_EXPERIMENTS_DIRECTORY’ is empty

  • 404 Not Found – The experiment configuration file was not found. Or, The experiment BIBI file was not found.

  • 401 Unauthorized – Insufficient permissions to see the simulation changes.You can only see the simulations you own or those for which the experiment has been shared with you

  • 200 OK – Success. The simulation BIBI configuration files were retrieved

GET /simulation/(int: sim_id)/sdf_world

Returns the SDF file describing the world in which the simulation is carried out

> json string sdf

the SDF string describing the world excluding the robots involved

Status Codes

  • 500 Internal Server Error – ROS service not available

  • 401 Unauthorized – Insufficient permissions to see the simulation changes.You can only see the simulations you own or those for which the experiment has been shared with you

  • 400 Bad Request – A ROS error occurred

  • 200 OK – SDF file successfully returned

POST /simulation/(int: sim_id)/sdf_world

Save the current running experiment SDF back to the storage

Parameters

  • sim_id – The sim_id

  • context_id – The context_id of the experiment

Status Codes
GET /simulation/(int: sim_id)/recorder/(string: command)

Queries the simulation recorder for a value/status. See parameter description for supported query commands.

Parameters

  • sim_id – The simulation ID to command.

  • command – The command to query, supported: [is-recording]

Status Codes

  • 500 Internal Server Error – The query failed due to an internal server error

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to see the simulation changes.You can only see the simulations you own or those for which the experiment has been shared with you

  • 200 OK – Success. The query was issued and value returned.

POST /simulation/(int: sim_id)/recorder/(string: command)

Issue user commands to the simulator recorder. See parameter description for supported query commands.

Parameters

  • sim_id – The simulation ID to command.

  • command – The command to issue, supported: [start, stop, cancel, reset, save]

Status Codes

  • 500 Internal Server Error – The query failed due to an internal server error

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – The command is invalid/refused by recorder - see message returned.

  • 200 OK – Success. The command was issued.

DELETE /simulation/(int: sim_id)/robots/(string: robot_id)

Delete a robot from the simulation.

Parameters

  • sim_id – The simulation ID.

  • robot_id – The robot ID.

Status Codes
PUT /simulation/(int: sim_id)/robots/(string: robot_id)

Update initial pose of a robot

Parameters

  • sim_id – The simulation ID.

  • robot_id – The robot string ID.

Status Codes
POST /simulation/(int: sim_id)/robots/(string: robot_id)

Add a new robot to the simulation.

Parameters

  • sim_id – The simulation ID.

  • robot_id – The robot string ID.

Status Codes
GET /simulation/(int: sim_id)/robots

Gets the list of robots in the running simulation.

GET /simulation/(int: sim_id)/files/(string: resource_type)/(string: resource_path)

Download the file in the resource_path for the give resource_type

Parameters

  • sim_id – The ID of the simulation whose files shall be handled

  • resource_type – “robots”, “brains”, “environments”, “files”

  • resource_path – relative path the particular resource to be downloaded

PUT /simulation/(int: sim_id)/brain

Set brain file of the simulation specified with simulation ID. Depending on the type of brain file, it has to be transmitted as text or as base64

Parameters

  • sim_id – The simulation ID

< json string brain_type

Type of the brain file (‘h5’ or ‘py’)

< json string data_type

type of the data field (‘text’ or ‘base64’)

< json string data

Contents of the brain file. Encoding given in field data_type

< json dict brain_populations

A dictionary indexed by population names and containing neuron indices

> json string error_message

Error Message if there is a syntax error in the code

> json int error_line

Line of code, where error occurred

> json int error_column

Column, where error occurred (if available)

> json bool handle_population_change

a flag indicating if user wants to change transfer functions according to population changes.

Status Codes

  • 500 Internal Server Error – Error on server: environment variable: ‘NRP_MODELS_DIRECTORY’ or ‘NRP_EXPERIMENTS_DIRECTORY’ is empty

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – The source code is invalid.

  • 200 OK – The brain file was replaced.

GET /simulation/(int: sim_id)/brain

Get brain data of the simulation specified with simulation ID.

Parameters

  • sim_id – The simulation ID

> json string brain_type

Type of the brain file (‘h5’ or ‘py’)

> json string data_type

type of the data field (‘text’ or ‘base64’)

> json string data

Contents of the brain file. Encoding given in field data_type

> json dict brain_populations

A dictionary indexed by population names and containing neuron indices.

Status Codes

  • 500 Internal Server Error – Error on server: environment variable: ‘NRP_MODELS_DIRECTORY’ or ‘NRP_EXPERIMENTS_DIRECTORY’ is empty

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to see the simulation changes.You can only see the simulations you own or those for which the experiment has been shared with you

  • 200 OK – Success. The experiment brain file was retrieved

PUT /simulation/(int: sim_id)/state

Sets the simulation with the given name into a new state. Allowed values are: created, initialized, started, paused, stopped

Parameters

  • sim_id – The simulation id

< json string state

The state of the simulation to set

> json string state

The state of the simulation

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – The state transition is invalid

  • 200 OK – The state of the simulation with the given ID was successfully set

GET /simulation/(int: sim_id)/state

Gets the state of the simulation with the specified simulation id. Possible values are: created, initialized, started, paused, stopped

Parameters

  • sim_id – The simulation id

> json string state

The state of the simulation

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to see the simulation changes.You can only see the simulations you own or those for which the experiment has been shared with you

  • 200 OK – The state of the simulation with the given ID was successfully retrieved

PUT /simulation/(int: sim_id)/(string: experiment_id)/reset

Calls the CLE for resetting a given simulation to the last saved state in the storage.

Parameters

  • sim_id – The simulation ID.

  • experiment_id – The experiment ID

> json resetType

the reset type the user wants to be performed, details about possible values are given in GazeboRosPackages/src/cle_ros_msgs/srv/ResetSimulation.srv

Status Codes

  • 500 Internal Server Error – The query failed due to an internal server error

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to apply changes. Operation only allowed by simulation owner

  • 400 Bad Request – Invalid request, the JSON parameters are incorrect

  • 200 OK – The requested reset was performed successfully

GET /simulation/(int: sim_id)

Gets the simulation with the specified simulation id

Parameters

  • sim_id – The simulation id

> json string state

The current state of the simulation

> json integer simulationID

The id of the simulation (needed for further REST calls)

> json string environmentConfiguration

Path and name of the environment configuration file

> json string owner

The simulation owner (Unified Portal user id or ‘hbp-default’)

> json string creationDate

Date of creation of this simulation

> json string gzserverHost

Denotes where the simulation will run once started. Set to ‘local’ for localhost and ‘lugano’ for a dedicate machine on the Lugano viz cluster

> json string reservation

the name of the cluster reservation subsequently used to allocate a job

> json string experimentID

The experiment ID if the experiment is using the storage

> json integer brainProcesses

Number of brain processes to use (overrides ExD conf.)

> json string creationUniqueID

unique creation ID (used by Frontend to identify this sim.)

Status Codes

  • 404 Not Found – The simulation with the given ID was not found

  • 401 Unauthorized – Insufficient permissions to see the simulation changes.You can only see the simulations you own or those for which the experiment has been shared with you

  • 200 OK – The simulation with the given ID is successfully retrieved