Enable the platform¶

The first thing to explain is how to enable the platform. A machine become the platform when you install the main rcm platform agent, i.e. the rcm master (look at the Installation & Administration Guide to see how to do that). Being the platform means that this machine (or master, as we call it) will be the center of all the user will create in its robotic world: we are speaking of simulated robots for now because we still don’t have added physical robot in that world but can be physical robot or machines that works as robots in the platform; machines working as robots only means that you run the rcm robot agent into them: in any case we’ll see later how to add robot to the platform. At this point the platform is enabled and you can see that calling the web services exposed by the master:

~$ curl http://public_ip_master

The response is a simple html page remembering that rcm is responding and so is up and running. The web server runs only in the master so you can check only the master installation in this way, but you know that a minimal configuration of the platform is available. You can have a look at what you have in your platform contacting platform_instance and see that your platform doesn’t have robot for now:

~$ curl http://public_ip_master/platform_instance/read

The response is a json formatted response with the list of robots available in the platform so you have an empty list for now.

Add robots¶

Now that your platform is available you can add the robots: these could be physical robots, physical computers or virtual machines, but the important thing is that they have to run the rcm robot agent. Before that an rcm agent would be recognized by the platform you have to do the provisioning of the robot; you have to tell the platform the name of your robot and what will be its role, what it can do: we call this service logic (see Create brains to better understand the concept and how to create a service logic). You’ll provide a new robot calling platform_instance in the rcm master instance:

~$ curl -H 'Content-Type: application/json' -d '{"pi_name":"name_r","pi_service_logic":"name_s_l"}' http://public_ip_master/platform_instance/provisioning

You can do this before or after running the machine with the rcm robot agent but only when this operation will be done the robot will be available on the platform and can be used. The name of the robot must be unique because this will be the identifier for the robot and all the components generated for that robot; the service logic is mandatory too otherwise the provisioning fails. The response provides the result of the operation but in any case you can see the new platform situation calling platform_instance in the rcm master instance:

~$ curl http://public_ip_master/platform_instance/read

This time you could see the newly added robot in the no more empty list of available robots. In this case you can see the state of the rcm robot and verify if it’s up and running:

• connected is true when you switch on your provisioned robot. The agent on the robot has contacted the master to advertise its presence in the platform and the master agent recognise him as one the the robot provisioned by the user
• paired is true when the robot is associated with a server (as its brain) and its role is defined (the service logic used for the robot at provisioning time is running)

Create brains¶

In this section will speak about service logic, its meaning and how to create a new service logic. Often the robot is a machine less computationally equipped but that needs more power that he has in order to do all what he has to do. The robot is associated with an additional brain at the boot time (after the installation of the rcm robot agent and the robot provisioning) and and has a role in the platform which means what he can do in the platform: this is defined by the service logic. In terms of robotic world the logic units are tied with the underlying ROS and can be of two types:

• Node a process that perform computation and does one of the task of what the user want to let the robot do. Every task can involve more other nodes as sub task: to find more information about ROS nodes see the documentation. We define this underlying component as service node and can be accessed in the service logic as one of the two types of service items
• Launcher a sort of aggregator, something that provide a common starting point for nodes in the ROS point of view. We define this as service launcher and can be accessed in the service logic as one of the two types of service items

The service logic provides a context in which the underlying elements can run and live to give the feature or brain the robot needs. There are many service items already available through the full installation of the underlying layer but are not listed through the platform in the fiware version: you can see them looking in the ROS environment or documentation to see what the installation deploys into the machine.

The service logic is composed by 3 parts:

• name the name that identifies the service logic into the platform
• context the environment in which the elements of the service logic run and live. We call them service spaces and are a sort of containers in which the service items work. This is not configurable but every service logic instance and so every robot create and use one service space identified by the same name used to identify the rcm robot
• list of service items the elements that define the behaviour of the robot and in terms of ROS point of view what is launched in the service logic context

~$ curl -H 'Content-Type: application/json' -d '{"slg_name":"name_s",...}' http://public_ip_master/service_logic/provisioning

~$ curl http://public_ip_master/service_logic/read
~$ curl http://public_ip_master/service_logic/read?slg_name=name_s_l

~$ curl -H 'Content-Type: application/json' -d '{"slg_name":"name_s"}' http://public_ip_master/service_logic/r_provisioning

Give the brain a body¶

When you finished to design the brain for your robot you have to provide a body to that brain and you do that when you do the provisioning of the robot. All that you set to run in the service logic will be launched where you asked when the robot is switched on after the robot provisioning. You can check if all went well looking at platform_instance in the rcm master instance:

~$ curl http://public_ip_master/platform_instance/read

The service logic was good and the provisioning went well if the paired field becomes true. This change of state require some time so wait before considering the operation a failure. Even in the case of robot as it happens in service logic case, if you want to change something about the robot you have to remove the robot and provide again with the new values. If you change the name you have to change the name in the configuration file of the rcm robot to match the name you newly provide. In order to remove the robot you can call platform_instance in the rcm master instance:

~$ curl -H 'Content-Type: application/json' -d '{"pi_name":"name_r"}' http://public_ip_master/platform_instance/r_provisioning

Connecting to the Fiware world¶

In order to understand and provide the connection to the fiware world you have to know that this link is done through firos and you need to put that part in your custom service logic to do it. During the master installation the wizard ask you if you want to enter the fiware world and install the firos package (see Installation & Administration Guide). If you require that, firos, rcm_driver and robotics_msgs will be deployed in the ROS workspace used by the rcm platform to run the underlying nodes and launchers. You can see those 3 elements as service nodes needed to exchange information between the robotic world and fiware world. Rcm platform speaks to rcm_driver to tell firos what’s happening in the rcm platform and firos communicates those information to the fiware context broker. Rcm_driver speaks to firos in the ROS environment using the language specified in robotics_msgs. All this explanation is intended to let you know that if you want to connect with fiware in your custom made service logic you have to put those 3 nodes in it. Moreover those 3 service nodes are deployed in the master and are available only there, so when you create your service logic you must tell it to run them on the server side. If you do that when you turn on your robots they are notified in fiware world and and an entity of each robot will be automatically available there.

Robots in context broker¶

Firos will perform a mapping between ROS and context broker following these rules:

• Each robot will be an entity, its type will be ROBOT and its id the name of the robot.
• The topics from the robot will be translated into attributes, its type will be the type of the topic and the name will be a slightly modified version of the name of the topic.
• Each topic will have a timestamp named firostimestamp.
• If you want to send a command from context broker to a robot, you must list the name of the attribute to be sent into the value of the attribute COMMAND (type COMMAND).

{
    "type": "COMMAND",
    "name": "COMMAND",
    "value": [
        "pose"
    ]
}

"name_of_the_robot": {
    "publisher": ["list_of_topics_to_be_received_from_context_broker"],
    "subscriber": ["list_of_topics_to_be_sent_to_context_broker"],
}

"turtle\\w+": {
    "publisher": ["cmd_vel"],
    "subscriber": ["pose"]
},
"robot\\w+": {
    "publisher": ["cmd_vel.*teleop", ".*move_base/goal", ".*move_base/cancel"],
    "subscriber": [".*move_base/result"]
}

"turtle1": {
    "descriptions": [
        "http://wiki.ros.org/ROS/Tutorials/UsingRxconsoleRoslaunch",
        "http://wiki.ros.org/ROS/Tutorials/UnderstandingNodes"
    ]
}

{
    "type": "DescriptionData",
    "name": "descriptions",
    "value": "http://wiki.ros.org/ROS/Tutorials/UsingRxconsoleRoslaunch||http://wiki.ros.org/ROS/Tutorials/UnderstandingNodes"
},

Requirements¶

RCM and firos must have the following software installed:

• Ubuntu 14.04 LTS/12.04 LTS (other versions are not tested)
• Python 2.7
• ROS Indigo/Groovy (other versions are not tested)

In addition, the master must have OpenVPN server and Sqlite in order to install rcm master and the robot must have OpenVPN client in order to install rcm robot. Firos need Nodejs 0.10 but is not mandatory and can be configured to not use the additional features that requires it.

Python and sqlite should be already available in the Ubuntu OS but in any case for all the software requirements refer to the products pages to find out how to download, install and configure them. In addition to the instruction provided by the products you have to take care of a couple of things regarding RCM:

• rcm master internally runs a web server to expose the RDAPI. This web server is forced to use the network interface called ‘eth0’ so make sure that this is the main network interface accessible by the user on the master.
• rcm instances, as agents of the platform, need to deal each other and to do so they use the VPN provided by OpenVPN server installed on the master. They are forced to use the network interface called ‘tun0’ so make sure to configure properly the OpenVPN server and clients to use this network interface. Moreover remember to emit the certificates for all the OpenVPN clients using the OpenVPN server on the master in order to use the same VPN for all the platform.

Distribution¶

Starting from the source code you can create the distribution packages needed to install all the components of Robotics; the main tool to do this is the python script create_robotics_pkg found in the scripts folder. The following are all the options you can have with the tool:

• without options: this is the more completed distribution package because contains the rcm master agent and all the packages needed for the communication in fiware (firos, rcm_driver and robotics_msgs). It creates robotics.zip with the root folder called rcm_platform_master
• master: this is the distribution package with only the rcm master agent. It creates rcm_platform_master.zip with the root folder called rcm_platform_master but the packages needed for the communication in fiware must be created and installed separately
• robot: this is the distribution package with only the rcm robot agent. It creates rcm_platform_robot.zip with the root folder called rcm_platform_robot
• firos: this is the distribution package with only firos. It creates firos.zip with the root folder called firos
• rcm_driver: this is the distribution package with only rcm_driver. It creates rcm_driver.zip with the root folder called rcm. This is a driver component to let the platform communicate with firos through ROS
• robotics_msgs: this is the distribution package with only robotics_msgs. It creates robotics_msgs.zip with the root folder called robotics_msgs. This is the component providing the intercommunication language for firos and rcm_driver through ROS

~/rcm_platform_master$ ./create_robotics_pkg

Installation¶

As we saw in the previous section the distribution packages are provided in compressed files. In this section we will see their structure and how to use them to install Robotics. The robotics.zip and rcm_platform_master.zip are substantially the same thing as internal structure:

rcm_platform_master/
        rcm_platform/
                __init__.py
                rcmp_command.py
                rcmp_event.py
                rcmp_ext_connector.py
                rcmp_inter_communication.py
                rcmp_ms.py
                rcmp_node.py
                rcmp_platform_command.py
                rcmp_robotics_data.py
                rcmp_service_command.py
                rcmp_wd.py
        ros/
                rosconsole.config
        install.sh
        sub_inst.sh
        uninstall.sh
        sub_uninst.sh
        rcmpd
        rcmp_n

The only difference between the two packages is that the robotics.zip in the root folder has firos.zip, rcm_driver.zip, and robotics_msgs.zip too. These are the distribution packages of the other components used to complete the Robotics and are embedded into the main package.

The rcm_platform_robot.zip shares the same structure of the previous two but loses the two python modules related to the web server and the database that are only available in the rcm master agent:

rcm_platform_robot/
        rcm_platform/
                __init__.py
                rcmp_command.py
                rcmp_event.py
                rcmp_inter_communication.py
                rcmp_ms.py
                rcmp_node.py
                rcmp_platform_command.py
                rcmp_service_command.py
                rcmp_wd.py
        ros/
                rosconsole.config
        install.sh
        sub_inst.sh
        uninstall.sh
        sub_uninst.sh
        rcmpd
        rcmp_n

The other three packages shares the same structure of typical ROS nodes implemented in python with the root folder named with the package name used in ROS environment and the main python entry point named with what is the type of the node in ROS context. Usually the entry point and all the python modules goes in the scripts folder; configuration files are managed internally by the node so the provider decides where put them. Special folders containing the syntax of messages exchanged by the nodes are in ‘srv’ or ‘msg’ folder, depending on the type of messages that can be exchanged (more detailed and clear explanation can be found on ROS documentation).

Firos:

firos/
        config/
        scripts/
                include/
                        ...
                core.py
                ...
        CMakeLists.txt
        License.txt
        package.xml
        README.md

rcm_driver:

rcm/
        scripts/
                rcm_driver.py
        CMakeLists.txt
        LICENSE.txt
        package.xml
        README.md

robotics_msgs:

robotics_msgs/
        msg/
                CB_Event.msg
                Robot_Event.msg
        srv/
                FIROS_info.srv
        CMakeLists.txt
        LICENSE.txt
        package.xml
        README.md

The rcm agent packages contain the scripts for installing and uninstalling all the packages: this is because during the installation process the scripts create the folder used by RCM to manage the ROS nodes and so all the other components of Robotics. In any case you can install all the other components manually simply extracting the content of the distribution packages into rcmp_ws/src folder (this folder is already available only if you have already installed the rcm platform part).

For what concern the installation of robotics.zip, rcm_platform_master.zip or rcm_platform_robot.zip you have to extract the content of the selected component and run the install.sh found under the root folder:

~/rcm_platform_master$ ./install.sh

The procedure installs the package dependences and places all the needed files in the right places: some of these steps require the administration permission so after the first steps it will be asked you the sudo password. The installer provides a step by step configuration process and can be used as a wizard to perform changes in the RCM configuration files. At the end of the process it will ask if it has to start the ‘rcm daemon’. You can also change directly the available configuration files or create them from scratch. If you don’t let the installer start the rcm daemon or you have manually changed the configuration files, you have to start or restart the rcm daemon as follow:

~$ sudo service rcmpd start

or

~$ sudo service rcmpd restart

Configuration¶

The configuration process prompts some questions to the user, proposing available responses within brackets in case of selection queries and showing a default response within square brackets (used in case the user presses only Enter key):

~/rcm_platform_master$ ./install
The workspace rcmp_ws already exists: do you wanna replace it ([Y]es/no)?

As said before we have two kinds of agents in the platform so different questions are proposed in the two cases. Rcm master doesn’t have the standard configuration file init.cfg but uses a hidden file .init.cfg that looks the same but with only the list of ports opened for inbound communication; this instance directly controls the robotics data so further creates and uses the sqlite database file named robotics_data.db. Rcm robot uses the standard configuration file and needs a name for the platform instance and the ip address where to find rcm master too.

Don’t forget that the list of ports for inbound communication should be configured only if we need ports available from outside the VPN so you have to open the ports on the NAT and firewall to make them available to the platform. Moreover for what concern the name and the ip address configured on the rcm robots is important to remember that the ip address of the master must be the one in the VPN (network interface ‘tun0’ is used by the instances to communicate each other) and the name of the robot must match the one provided during the provisioning phase (once the rcm master is installed and running exposes RDAPI: to add robots to the platform you have to call the provisioning web service and provide the name there will be used for the robot). For more information about the provisioning process you can see the User & Programmer Guide.

# This is a template for the configuration file for an RCM platform node.
# Remember that only robots and virtual machines must have this file specified and that must be renamed
# with the name init.cfg.

[main]

# the name for the instance (rcm platform node)
# name=instance_name

# specify a list of ports that are previously opened for inbound communication
# inbound_open_ports=10100, 10101, 10102, 10103

# specify the type of the instance (rcm platform node) in case the system we are running on is a robot;
# used as flag to distinguish a robot from a vm instance (the master doesn't have this configuration file so
# it is already different)
# robot=yes

# the ip of the master rcm platform node
# ip_master=10.xx.yy.1

# init.cfg

[main]
name=robot1
robot=yes
ip_master=10.11.12.1

# .init.cfg

[main]
inbound_open_ports=10100, 10101, 10102, 10103

Uninstallation¶

The distribution package of all the rcm platforms provides the tool for uninstalling Robotics. Enter into distribution folder or if no more available take the zip file and extract the content. Run the uninstall.sh script to uninstall all the components of Robotics:

~/rcm_platform_pkg$ ./uninstall.sh

this command removes all the files associated with RCM except the package dependences.

Sanity check procedures¶

In order to see if the installation went well you can check if the rcm master or rcm robot is running:

~$ sudo service rcmpd status
/usr/local/bin/rcmp_n is running

This is not an exhaustive test because this tells you only that the daemon is up and running, but doesn’t know if all the internal steps have started correctly to consider the platform up and running.

~$ curl http://public_ip_master
<html><body>Welcome to the RCM platform node server!</body></html>

~$ curl http://public_ip_master/platform_instance/read
{"reason": [], "result": "OK"}

~$ rostopic pub -1 s1 std_msgs/String "data: 'test'"  __ns:=end_end_test

~$ (curl contextbroker_ip:1026/v1/queryContext -s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -d @- | python -mjson.tool) <<EOF
{
        "entities": [
                {
                        "type": "ROBOT",
                        "isPattern": "true",
                        "id": "end_end_test"
                }
        ],
        "attributes": [
                "s1"
        ]
}
EOF

{
        "contextResponses": [
                {
                        "contextElement": {
                                "attributes": [
                                        {
                                                "name": "s1",
                                                "type": "std_msgs.msg.String",
                                                "value": "{%27firosstamp%27: 1443020619.58971, %27data%27: %27test%27}"
                                        }
                                ],
                                "id": "end_end_test",
                                "isPattern": "false",
                                "type": "ROBOT"
                        },
                        "statusCode": {
                                "code": "200",
                                "reasonPhrase": "OK"
                        }
                }
        ]
}

rostopic echo /end_end_test/p1

~$ (curl contextbroker_ip:1026/v1/updateContext -s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -d @- | python -mjson.tool) <<EOF
{
          "contextElements": [
                  {
                          "type": "ROBOT",
                          "isPattern": "false",
                          "id": "end_end_test",
                          "attributes": [
                          {
                                  "name": "p1",
                                  "type": "std_msgs.msg.String",
                                  "value": "{%27data%27: %27`echo $RANDOM`%27}"
                          },
                          {
                                  "name": "COMMAND",
                                  "type": "COMMAND",
                                  "value": ["p1"]
                          }
                          ]
                  }
          ],
          "updateAction": "APPEND"
}
EOF

data: random_number
---

~$ ps aux | grep rcmp_n
root 1353 0.1 0.3 223740 19876 ? Rl 08:53 0:41 /usr/bin/python /usr/local/bin/rcmp_n
root 2000 0.0 0.2 150016 16968 ? R 08:53 0:06 /usr/bin/python /usr/local/bin/rcmp_n

~$ ps aux | grep firos
user    6576  0.1  0.4 513748 18184 pts/10   Sl+  15:38   0:02 python firos_path/scripts/core.py

~$ ps aux | grep firos
user    6576  0.1  0.4 513748 18184 pts/10   Sl+  15:38   0:02 python firos_path/scripts/core.py
user    6615  0.0  1.8 853320 69308 pts/10   Sl+  15:38   0:00 node firos_path/scripts/mapserver.js 10101 9090

~$ ps aux | grep ros

~$ netstat -lptu
tcp 0 0 10.82.99.1:9999 *:* LISTEN -
tcp 0 0 192.168.2.74:http *:* LISTEN -

tcp 0 0 *:10100 *:* LISTEN -
tcp 0 0 *:10101 *:* LISTEN -

/opt/rcm-platform$ sqlite3 robotics_data.db

Diagnosis procedures¶

RCM platform provides logging feature to investigate in case of problems; you can find the log files in the folder named /opt/rcm-platform/log. The logger used provides information about what happening in the platform and when the max dimension of the file called rcmp.log is reached it rolls over appending a number after the old version of the file used so you can see what happened before. Only 5 files are written before overwrite the first. To more advanced log features relative to the service nodes (included firos) you can see the ROS documentation about the log.