ADAMOS ROS Integration

Stuttgart Hackathon

This documentation explains how to connect ADAMOS to a ROS enabled device via the ROS webbridge (http://wiki.ros.org/rosbridge_suite).

The demos shown in this documentation have been developed for the purpose of the Stuttgart Hackathon 2018. They are designed to work with a Festo BionicCobot.

This documentation consits of four major parts:

  1. Before you start shows you how to get an ADAMOS tenant and developer tools
  2. ROS Agent shows you how to run the ADAMOS ROS agent
  3. Dashboarding shows you how to visualize the ROS measurements in ADAMOS
  4. Streaming Analyitcs shows you how to apply realtime analytics on ROS measurements

1. Before you start

Before you start to run the ROS agent to transfer measurements to ADAMOS you need an ADAMOS tenant and valid credentials.

We highly recommend you to register on the ADAMOS Partner Portal: http://partner.adamos.com. This will give you access to the Developer Center where you will find a large number of useful information, tutorials, documentation, etc.

Developer Center

Note: After registration you will not have immediate access to the Partner Portal until an ADAMOS staff member gives you the neccessary permissions. We will check new registrations frequently. Please ask the ADAMOS staff to get immediate access.

Get your tenant

Once registered for the ADAMOS Partner Portal, navigate to the Developer Center. Click the GET A DEVELOPMENT TENANT bubble and follow the link to Request free trial.

Fill out the trial request form. You tenant will be created immediately and you will receive an email to reset your password.

That's it. You now have an ADAMOS tenant and valid credentials. Remember your credentials, you will need them later.

Get your tools

To run the ADAMOS ROS Agent you need Python 3+ and a couple of modules to be installed on your local computer.

Please install Python 3: https://www.python.org/downloads/.

After that you can run the following commands in your terminal to install the required modules:

pip install requests
pip install uuid
pip install ws4py

To work with Apama Streaming Analytics we highly recomment the use of Software AG Designer, an Eclipse-based IDE that supports Apama EPL (Event Processing Language) and lets you run and test streaming rules on your local computer prior to deploying them to ADAMOS. To download Software AG Designer check the page in our Developer Center: Streaming Analyitcs IDE.

Note: Software AG Designer for Apama is only available for Windows.



2. ADAMOS ROS Agent

The ADAMOS ROS Agent will allow you to subscribe to measurements of a ROS enabled device and send them to the ADAMOS platform.

You will run the ADAMOS ROS Agent on your local computer to connect to a ROS enabled device (via LAN) and the ADAMOS platform (via WiFi). The ADAMOS ROS Agent then transforms incoming measurements and sends them to your tenant.

ADAMOS ROS Agent

Get the ADAMOS ROS Agent

The ADAMOS ROS Agent is available on GitHub.

Clone the following repository to get the complete code: https://github.com/ADAMOS-PUBLIC/ROS-Integration.

Configure the ADAMOS ROS Agent

Before you run the agent you need to supply your configuration. Open the run.py file with an editor of your choice.

Line 9-13 contains the following configuration paramters:

ADAMOS_URL = 'http://<tenant>.adamos-dev.com'   # URL of your ADAMOS tenant
ADAMOS_TENANT = '<tenant>'                      # Name of your ADAMOS tenant
ADAMOS_DEVICE_NAME = 'Cobot'                    # Name of the device that will be created in ADAMOS
ADAMOS_DEVICE_SERIAL = 'cobot-5428'             # Serial of the device (needed for bootstrap) 
ROS_IP = '192.168.4.4:9090'                     # IP and port of the ROS webbridge

Change the parameters accordingly.

Run the ADAMOS ROS Agent

Now you are ready to run the ADAMOS ROS Agent. Open up a terminal and run the agent:

python run.py

The agent will now start the bootstrap process. For more information how this process works, check: https://docs.adamos.com/guides/device-sdk/rest/#device-integration.

You now need to register the agent on your ADAMOS tenant.

  1. Log in to your ADAMOS tenant
  2. Using the application switcher on the upper right, select the "Device Management" application.
    App Switcher
  3. Navigate to "Registration" and click on "Register device"
  4. In the dialog select "General device registration"
    Device Registration
  5. Enter the serial of the agent as provided in the ADAMOS_DEVICE_SERIAL parameter of run.py and click Next.
  6. Click "Complete". The device registration is now waiting for a connection of your agent.
  7. After a couple of seconds a new "Accept"-button should appear. This also indicates that the ADAMOS ROS Agent has successfully connected to ADAMOS. Click the button to accept the registration. Device Registration Accept

The agent hac now been accepted and will create a new device on ADAMOS. Additionally the agent receives new device credentials that will be stored in credentials.txt. The next time you restart the agent it will not run the bootstrap process again as there is already a credentials.txt file. Remove the credentials.txt file to run the bootstrap process again (e.g. if you removed the device in ADAMOS).

Explore measurements

The agent will automatically connect to the ROS webbridge and subscribe to different topics. Whenever a new messages is sent by ROS the agent will read the values and transform it into an ADAMOS measurement or device update.

The agent subscribes to the following topics:

# Subscribe to ROS topic with (topic-name, interval-ms, callback)
rosClient.subscribe('/festo/cobotv1_1/festo_status', 2000, statusCallback)                          # extracts stiffness_factor, mode, p1, joint_names, joint_positions and sends a measurement and device update
rosClient.subscribe('/festo/cobotv1_1/base_to_cam_transform', 1000, transformCallback)              # extracts position (x,y,z) and orientation (x,y,z,w) and sends a measurement
rosClient.subscribe('/festo/cobotv1_1/cam_to_tcp_transform', 1000, transformCallback)               # extracts position (x,y,z) and orientation (x,y,z,w) and sends a measurement
rosClient.subscribe('/festo/cobotv1_1/base_to_tcp_transform', 1000, transformCallback)              # extracts position (x,y,z) and orientation (x,y,z,w) and sends a measurement
rosClient.subscribe('/festo/cobotv1_1/cobot_wrist_cam/image_raw/compressed', 2000, imageCallback)   # extracts the camera image and sends a device update

To explore the measurement go back to the "Device Management" application of you ADAMOS tenant 1. Select "All devices" 2. Select the newly created device 3. Click on "Measurements"

The platform automatically creates line charts for every measurement: Device Measurements

Extend the ADAMOS ROS Agent

You are free to extend the existing agent. Look at run.py if you wish to

ros.py and adamos.py should not have to be adjusted.



3. Dashboarding

ADAMOS comes with a Dashboarding solution named "Cockpit" that allows you to place graphical "widgets" to visualize data of your devices.

Let's set up a Dashboard to visualize the camera images on ADAMOS.

  1. Switch to the "Cockpit" application using the application switcher in the upper right corner.
  2. Select "GROUPS" from the left navigation
  3. Add a new group using the "Add group" button on the upper right.
    Add group
  4. Select the newly created group. Switch to the "Sub-assets" tab and click on "Assign devices".
    Assign device
  5. In the dialog choose your ROS device from the list and click on "Assign 1 device".
  6. Select the newly added device. Click on the large plus-button in the upper right and select "New dashboard".
    New Dashboard
  7. You can just click "Save" in the dialog or make some adjustments if you like.
  8. The newly created Dashboard will show up as a tab and is selected automatically.
  9. Add a widget by clicking on the "Add widget" button in the upper right.
  10. From the list select the HTML widget. Check the "Allow insecure use of elements and attributes" checkbox to allow inline CSS. Then paste the following code into the text field below:
<div style="padding: 20px 40px;">
<img alt="camera" src="data:image/jpg;base64,{{device.camera.data}}">
</div>

Widget Dialog 11. Click Save. The widget will be placed on your Dashboard and displays the camera image. You can resize or move the widget on the canvas.

Try out other widgets, e.g. the Data points graph to visualize measurements of your device.



4. Streaming Analytics

The ADAMOS platform integrates Apama, the market leading Streaming Analytics engine. It allows you to analyze measurements in realtime using EPL (event programming language). EPL is an easy to learn object-oriented scripting language.

If you cloned the GitHub repository https://github.com/ADAMOS-PUBLIC/ROS-Integration you will also find the file StatusMonitor.mon.

The file contains a complete Apama monitor that detects incoming status messages and checks whether the claw has changed its status (from OPENED to CLOSED or from CLOSED to OPENEND). If a status change is detected it automatically creates an Event in ADAMOS that shows the new status.

Deploy the Apama monitor

To run the Apama monitor you need to deploy it to ADAMOS.

Note: The Apama feature is not enabled by default on Trial tenants. Please ask the ADAMOS staff to enable Apama for your tenant.

  1. Switch to the "Administration" application using the application switcher in the upper right corner.
  2. Select "Own applications" from the left navigation (in the group APPLICATIONS).
  3. Click on "Add application" and select "Upload custom Apama rule" (Note: this will only show up if you have Apama enabled, ask the ADAMOS staff).
  4. Upload the StatusMonitor.mon.
    Apama Rule
  5. Click "Done". Your rule is now running in the platform.

Show the results

To show the results of the newly uploaded rule you need to submit a command to open or close the claw of the robot.

  1. In the Virtual Machine provided by Festo you can run the following command in a terminal:
rosservice call /festo/cobotv1_1/set_pressure "required_pressure: 
    sequence: 0
    p1: 0.0
    p2: 0.0
    weight: 0.0"

Info: p1: 0.0 = OPEN, p1: 1.0 = CLOSED

  1. Switch to the "Device Management" application using the application switcher in the upper right corner.
  2. Select your device from the "All devices" list.
  3. Navigate to "Events". A new event will automatically show up everytime the claw status changes. Device events