Copyright © 2015 by Telecom Italia, Consoft Sistemi
RDAPI is a set of REST APIs (which return JSON responses) allowing FIWARE developers to integrate robotic services to IoT ones in a simple way.
This is a work in progress and is changing on a daily basis. First major release 4 will be released by the end of September 2015
This specification is licensed under the FIWARE Open Specification License.
The resources abstracted by RDAPI and needed by FIWARE are described below.
A service logic identifies the set of ROS functions (i.e. ROS nodes and/or launchers) needed to perform a specific service, like e.g. "assisted teleoperation" or "path planning". For each ROS function is also indicated where it has to be started (Server o Robot side).
Returns the list of provisioned service logics.
The following is the response structure:
result: OK if the requested information can be returned, otherwise ERROR with motivation in the reason field.
reason: if result is OK - an array of provisioned service logics, for each element:
Returns the list of ROS nodes and/or launchers associated to the service logic.
The following is the response structure:
result: OK if response can be returned, otherwise ERROR with motivation in the reason field.
reason: if result is OK - an object containing:
This action allows you to read the indicated service logic information.
ParametersBefore using a service logic, it has to be inserted into the platform by using the provisioning API.
The following is the request structure:
slg_name: name of the service logic to provide
sn_list: list of ROS nodes to start, for each element:
sl_list: list of ROS launchers to start, for each element:
The following is the response structure:
result: OK if the requested action can be executed, otherwise ERROR with motivation in the reason field.
reason: additional information
You may provide your own service logic into platform using this action. It takes a JSON object containing the unique name of the service logic and two list related to the ROS nodes and ROS launchers associated to the service logic.
If a service logic is no longer used, it can be deleted from platform by using the rollback provisioning API.
The following is the request structure:
The following is the response structure:
result: OK if the requested action can be executed, otherwise ERROR with motivation in the reason field.
reason: additional information
You may remove your own service logic from platform using this action. It takes a JSON object containing the unique name of the service logic.
The MASTER instance and the set of Robot instances provisioned in the platform.
Returns the list of provisioned Robot instances.
The following is the response structure:
result: OK if the requested information can be returned, otherwise ERROR with motivation in the reason field.
reason: if result is OK - an array of provisioned Robot instances, for each element:
Before using a robot, the related Robot instance has to be inserted into the platform by using the provisioning API.
The following is the request structure:
pi_name: name of the Robot instance to provide
pi_service_logic: name of the service logic to associate with the robot
The following is the response structure:
result: OK if the requested action can be executed, otherwise ERROR with motivation in the reason field.
reason: additional information
You may provide your own robot into platform using this action. It takes a JSON object containing the unique name of the Robot instance and the name of the associated service logic.
If a robot is no longer used, the related Robot instance can be deleted from platform by using the rollback provisioning API.
The following is the request structure:
The following is the response structure:
result: OK if the requested action can be executed, otherwise ERROR with motivation in the reason field.
reason: additional information
You may remove your own robot from platform using this action. It takes a JSON object containing the unique name of the robot instance.
A Service Space (also called "Robot Clone") is a ROS container hosting the service logic associated to a provisioned Robot instance.
It has a unique name within the platform (i.e. the same name of the managed robot) and traverses two platform instances:
Server-side (i.e. the "remote brain"), which is the MASTER instance
Robot-side (i.e. the "local brain"), which is a Robot instance: a real robot, a simulated robot or a gateway which manages a real robot
Each Service Space is:
Automatically created by the platform when the related robot connects to it and automatically deleted when the robot disconnects to it.
After the creation, the service logic associated to the related robot is started and it is stopped before the deletion
Returns the list of ROS nodes and/or launchers that are started in the Service Space and information related to FIROS to be reachable by the Context Broker.
The following is the response structure:
result: OK if response can be returned, otherwise ERROR with motivation in the reason field.
reason: if result is OK - an object containing:
This action allows you to read the indicated Service Space.
ParametersHeaders
Content-Type: application/jsonBody
{
"result": "OK",
"reason": [
{
"slg_name": "service_logic1",
},
{
"slg_name": "service_logic2",
}
]
}
Headers
Content-Type: application/jsonBody
{
"result": "OK",
"reason": {
"ss_side": "S",
"sn_list":
[
{
"sn_package": "node1_pkg",
"sn_type": "node1_type",
"sn_side": "S",
"sn_name": "node1_name",
"sn_params": "node1_params"
},
...,
{
"sn_package": "driver1_pkg",
"sn_type": "driver1_type",
"sn_side": "R",
"sn_name": "driver1_name",
"sn_params": "driver1_params"
}
],
"sl_list":
[
{
"sl_package": "launcher1_pkg",
"sl_file_launcher": "launcher1_file",
"sl_side": "S",
"sl_name": "launcher1_name",
"sl_params": "launcher1_params"
}
]
}
}
Headers
Content-Type: application/jsonBody
{
"slg_name": "service_logic1",
"sn_list":
[
{
"sn_package": "node1_pkg",
"sn_type": "node1_type",
"sn_name": "node1_name",
"sn_params": "node1_params",
"sn_side": "S"
},
...,
{
"sn_package": "driver1_pkg",
"sn_type": "driver1_type",
"sn_name": "driver1_name",
"sn_params": "driver1_params",
"sn_side": "R"
}
],
"sl_list":
[
{
"sl_package": "launcher1_pkg",
"sl_file_launcher": "launcher1_file",
"sl_name": "launcher1_name",
"sl_params": "launcher1_params",
"sl_side": "S"
}
]
}
Headers
Content-Type: application/jsonBody
{
"result": "OK",
"reason": "The service logic with name 'service_logic1' has been provisioned correctly"
}
Headers
Content-Type: application/jsonBody
{
"slg_name": "service_logic1",
}
Headers
Content-Type: application/jsonBody
{
"result": "OK"
"reason": "The provisioning of the service logic with name 'service_logic1' has been rolled back completely",
}
Headers
Content-Type: application/jsonBody
{
"result": "OK",
"reason": [
{
"pi_name": "robot1",
"service_logic": "service_logic1",
"connected": true,
"paired": true
}
]
}
Headers
Content-Type: application/jsonBody
{
"pi_name": "robot1",
"pi_service_logic": "service_logic1"
}
Headers
Content-Type: application/jsonBody
{
"result": "OK",
"reason": "The platform node instance with name 'robot1' has been provisioned correctly"
}
Headers
Content-Type: application/jsonBody
{
"pi_name": "robot1",
}
Headers
Content-Type: application/jsonBody
{
"result": "OK"
"reason": "The provisioning of the platform node instance with name 'robot1' has been rolled back completely",
}
Headers
Content-Type: application/jsonBody
{
"result": "OK",
"reason": {
"r_nodes":
[
{
"sn_package": "node1_pkg",
"sn_type": "node1_type",
"sn_name": "node1_name",
"i_name": "master"
},
...,
{
"sn_package": "driver1_pkg",
"sn_type": "driver1_type",
"sn_name": "driver1_name",
"i_name": "robot1"
}
],
"r_launchers":
[
{
"sl_package": "launcher1_pkg",
"sl_file_launcher": "launcher1_file",
"sl_name": "launcher1_name",
"associated_r_nodes": ["node1", ..., "nodeN"],
"i_name": "master"
}
],
"inbound_port": "10100",
"public_ip": "..."
}
}
The editors would like to express their gratitude to the following people who actively contributed to this specification: Gianmario Bollano, Pierangelo Garino