Quick Walkthrough

This tutorial will show you how to set up and run a variation of the ROS Turtlesim on rapyuta.io. This tutorial targets individuals who like to get their hands dirty and explore a wider variety of functionality found in the rapyuta.io platform.

In order to attain a deeper understanding of rapyuta.io it is highly recommended that the developer refer to the developer guide section for in-depth documentation on each topic and/or pick from one of the more nuanced sample walkthroughs that deal with individual concepts and topics.

Some of the packages used in this tutorial can be reused to control real robots such as Turtlebot.

Learning objectives

In this tutorial, you will learn how to add and deploy packages using rapyuta.io console. Specifically, you’ll learn how to:

  1. Source your packages from a public docker registry and a public git repository.
  2. Expose ROS topics, services, actions, and network endpoints as component-level interfaces and as package-level inbound interfaces.
  3. Create dependent deployments.
  4. Control a Turtlebot in simulation through a web browser.

Prerequisites

  1. You should have access to a computer with an internet connection. Ensure that the latest Google Chrome browser is installed on it.
  2. You should be familiar with the following tools:

Difficulty

Advanced

Estimated time

40 minutes

Software architecture

Turtlesim’s software consists of packages or modules. Each package has a specific purpose and contributes to the whole of Turtlesim. A modularized software is easy to maintain, share, and scale. A package contains interfaces that determine how it may interact with other packages. A deployment of a package may depend on deployments of other packages. Learn more about Turtlesim’s software architecture and constituent packages

Create the Turtle package

The Turtle package emulates the behavior of a Turtlebot through the Simulator. There may be multiple instances (deployments) of Turtle component, each representing a single robot entity. In a real-world implementation, the Turtle package would directly control a robot. Since this is a simulation, the dynamics of the Turtle’s behavior is obtained from the Simulator. Learn more about Turtle package.

To add Turtle package using rapyuta.io console, follow the steps:

  1. Click CATALOG > ADD NEW PACKAGE.
  2. You should provide information about the package such as the name of the package, its version, whether it is a singleton package and a short description.
    1. In the Package Name box, enter a name say Turtle
    2. In the Package Version box, specify a version for the package. Initially, the version is set to the default value 1.0.0
    3. Make sure Is singleton package is not selected.
    4. Ensure Is bindable package is selected.
    5. In the Description box, provide a summary of the package. For example, An emulation of Turtlebot
    6. Click NEXT.
  3. In the Component Name box, enter a name for the component such as turtle

    The name of a component must consist of alphabets [A-Z, a-z], digits [0-9], hyphen -, and an underscore _ character, and must not start with a digit.

  4. Select Cloud as the Component Runtime.
  5. Ensure Is ROS Component is selected.
  6. Set Replicas to run the component to number 1 (default value).
  7. In the Executable Name box, type in a name for the executable. For example, turtle_executable

    The name of an executable must consist of alphabets [A-Z, a-z], digits [0-9], hyphen -, and an underscore _ character, and must not start with a digit.

  8. Select Git for the Executable Type.
  9. In the Git repository box, enter the URL address of the git repository: https://github.com/rapyuta/io_tutorials
  10. In the Command to run in the docker container box, enter the command:

    roslaunch io_turtle turtle.launch
    

    Ensure you always execute the roslaunch command for explicitly starting the ROS Master. However, it’s not recommended to run the rosrun command because the ROS Master will fail to start, and thus, the deployment fails.

  11. Add /pose ROS topic with low QoS because there is no need to guarantee the delivery of each control message. Instead, it is essential to receive the most recent message at the expense of losing some information. Click Add ROS topic > enter /pose in the Name box > click Low for QoS.

  12. Add /sim/cmd_vel ROS topic with high QoS because you will expect the Turtle to react when given such a command. Click Add ROS topic > enter /sim/cmd_vel in the Name box > select High for QoS.

  13. To add a ROS action, click Add ROS action. In the Name box, enter /turtle_0/goto_action. Similarly, add another ROS action /turtle_1/goto_action

  14. Click NEXT > CONFIRM PACKAGE CREATION.

You can deploy multiple instances of the Turtle package. To deploy up to two instances of the package, you define two ROS actions. However, you may define as many ROS actions as you would want to, and also deploy them on many Turtles. The ROS actions are dynamically created when the Turtle registers with the Command Center. Each Turtle uses one of the defined actions.

Create User Interface package

The User Interface is an interactive, web-based visualization of the original ROS Turtlesim. You can visualize the state of the Turtles, pass control commands to the Turtles. A docker container encapsulates its application code and dependencies. It communicates with the Command Center through a WebSecureSocket. It is the only non-ROS package based on Nginix. Learn more about User Interface package.

To add User Interface package using the console, follow the instructions:

  1. Click CATALOG > ADD NEW PACKAGE.
  2. You should provide information about the package, such as the name of the package, its version, whether it is a singleton package, and a short description of the package.
    1. In the Package Name box, enter a name say User Interface
    2. In the Package Version box, specify a version for the package. Initially, the version is set to the default value 1.0.0
    3. Make sure Is singleton package is not selected.
    4. Ensure Is bindable package is selected.
    5. In the Description box, enter a summary of the package such as An interactive, web based version of ROS Turtlesim's user interface
    6. Click NEXT.
  3. In the Component Name box, enter a name for the component say user_interface

    The name of a component must consist of alphabets [A-Z, a-z], digits [0-9], hyphen -, and an underscore _ character, and must not start with a digit.

  4. Select Cloud for Component Runtime.
  5. Deselect Is ROS Component because User Interface is a non-ROS package.
  6. Set Replicas to run the component to number 1 (default value).
  7. In the Executable Name box, enter a name for the executable say uiexecutable

    The name of an executable must consist of alphabets [A-Z, a-z], digits [0-9], hyphen -, and an underscore _ character, and must not start with a digit.

  8. Select Docker for Executable Type.
  9. In the Docker image box, enter the address of the docker image that contains the application code. The address of the image is rrdockerhub/io_turtlesim_ui as the image is held in the public docker registry, DockerHub.
  10. The Command to run in the docker container remains empty because the docker image will automatically execute when you deploy the User Interface package.
  11. Deselect Run command from bash shell checkbox.
  12. Expose a communication endpoint to access User Interface as well as interact with the Turtles. To add an endpoint, follow the steps:
    1. Click Add endpoint.
    2. In the Endpoint Name box, enter a name say UserInterface
    3. Select Exposed externally.
    4. Click HTTPS/WSS for Protocol.
    5. The Port is set to the default value 443 for the HTTPS/WSS protocol.
    6. In the Target Port box, enter the value 8080 (default port for Nginix).
  13. Click NEXT > CONFIRM PACKAGE CREATION.

Create Simulator package

The Simulator package replicates the physical dynamics of 2D robots and their sensors. Learn more about Simulator package.

To add the Simulator package, follow the steps:

  1. Click CATALOG > ADD NEW PACKAGE.
  2. You must provide information about the package, such as the name of the package, its version, whether it is a singleton package, and a short description.
    1. In the Package Name box, type in the name for the package say Simulator
    2. In the Package Version box, enter the version of the package. The default value is set to 1.0.0
    3. Ensure Is singleton package is not selected.
    4. Ensure Is bindable package is selected.
    5. In the Description box, enter a short summary of the package such as Simulator simulates physical dynamics of 2D robots and their sensors
    6. Click NEXT.
  3. In the Component Name box, type in a name for the component, say simulator

    The name of a component must consist of alphabets [A-Z, a-z], digits [0-9], hyphen -, and an underscore _ character, and must not start with a digit.

  4. Select Cloud for Component Runtime.
  5. Ensure Is ROS Component is selected.
  6. Set the value of Replicas to run the component to number 1 (default value).
  7. In the Executable Name box, enter a name for the executable say simulator_executable

    The name of an executable must consist of alphabets [A-Z, a-z], digits [0-9], hyphen -, and an underscore _ character, and must not start with a digit.

  8. For the Executable type, click Git.
  9. In the Git Repository box, enter the URL address of the git repository, that is, https://github.com/rapyuta-robotics/io_tutorials
  10. In the Command to run in the docker container box, enter the command:

    roslaunch io_turtle_sim_env simulation.launch
    

    Ensure you always execute the roslaunch command for explicitly starting the ROS Master. However, it’s not recommended to run the rosrun command because the ROS Master will fail to start, and thus the deployment fails.

  11. To add /sim/pose ROS topic, click Add ROS topic. In the Name box, type in /sim/pose and select Low for QoS.

  12. To add another ROS topic, /sim/sensors, click Add ROS topic again. In the Name box, type in /sim/sensors and select Low for QoS.

    The value of QoS is set to Low because it is not necessary to guarantee the delivery of each topic. Instead, it is essential to receive the most recent message at the expense of losing some information.

  13. To add a ROS service, click Add ROS service. In the Name box, enter the name of the service /register_sim_turtle. Similarly, add another ROS service /teleport_turtle.

  14. Click NEXT.

  15. Since Simulator subscribes to the ROS topic /sim/cmd_vel published by Turtle, you must add /sim/cmd_vel as an INBOUND ROS INTERFACE topic. Click Add Topic > enter /sim/cmd_vel in the Name box.

  16. Click CONFIRM PACKAGE CREATION.

Create Command Center package

The Command Center is a node for registering Turtles, and a router for passing control commands and telemetry messages between User Interface and Turtles. Learn more about Command Center package.

To add Command Center package, follow the steps:

  1. Click CATALOG > ADD NEW PACKAGE.
  2. You must provide information about the package such as the name of the package, its version, whether it is a singleton package, and a short description.
    1. In the Package Name box, type in the name for the package say Command Center
    2. In the Package Version box, enter the version of the package. The default value is 1.0.0
    3. Ensure Is singleton package is not selected.
    4. Ensure Is bindable package is selected.
    5. In the Description box, enter a short description of the package such as Command Center is responsible for communication between User Interface and Turtle
    6. Click NEXT.
  3. In the Component Name box, enter a name for the component say command_center

    The name of a component must consist of alphabets [A-Z, a-z], digits [0-9], hyphen - and an underscore _ character, and must not start with a digit.

  4. Select Cloud for the Component Runtime.
  5. Ensure Is ROS Component is selected.
  6. Set the value of Replicas to run the component to number 1 (default value).
  7. In the Executable Name box, type in a name for the executable say ccexecutable

    The name of an executable must consist of alphabets [A-Z, a-z], digits [0-9], hyphen - and an underscore _ character, and must not start with a digit.

  8. For Executable type, click Git.
  9. In the Git Repository box, enter the URL address of the git repository: https://github.com/rapyuta-robotics/io_tutorials

  10. In the Command to run in the docker container box, enter the command:

    roslaunch io_turtle_command_center command_center.launch
    

    Ensure you always execute the roslaunch command for explicitly starting the ROS Master. However, it’s not recommended to run the rosrun command because the ROS Master will fail to start, and thus the deployment fails.

  11. You must expose a communication network endpoint for publicly accessing Command Center.

    1. Click Add endpoint.
    2. In the Endpoint Name box, enter WS_ROSBRIDGE
    3. Make Exposed externally checkbox is selected.
    4. Click HTTPS/WSS under Protocol.
    5. The value of Port is automatically set to 443 because the Protocol is HTTPS/WSS.
    6. In the Target Port box, type in 9090
  12. To add a ROS topic, click Add ROS topic > enter /cmd_vel in the Name box > click Low for QoS.

  13. To add a ROS service, click Add ROS service > enter /register_turtle in the Name box.

  14. The environment variables: WS_ADDR and WS_PORT, defined in the ROS launch file, determine the WebSecureSocket address and port. You can adjust their values as configuration parameters defined in the console during the process of deploying the command_center component. To add WS_ADDR as configuration parameter, follow the steps:

    1. Under CONFIGURATION PARAMETERS, click Add Parameter.
    2. In the Name box, enter WS_ADDR
    3. In the Default value box, type in 0.0.0.0
    4. In the Description box, type in WebSocket Address
    5. Ensure This parameter is exposed externally is not selected.
      Similarly, add WS_PORT configuration parameter. Set Name as WS_PORT and Default value to 9090, and describe it as WebSocket Port.
  15. Click NEXT to move to Additional Information page.

  16. The Command Center is responsible for coordination among the Turtles. The inbound ROS interfaces help recognize ROS topics, services, and actions broadcasted from the various Turtles’ deployments.

    1. To add /pose as an Inbound ROS topic, click Add Topic under INBOUND ROS INTERFACES > enter /pose in the Name box.
    2. To add /teleport_turtle as an Inbound ROS service, click Add Service under INBOUND ROS INTERFACES > enter /teleport_turtle in the Name box.
    3. To add /turtle_0/goto_action as Inbound ROS actions, click Add Action under INBOUND ROS INTERFACES > enter /turtle_0/goto_action in the Name box. Similarly, add another Inbound ROS action, /turtle_1/goto_action.
  17. Click CONFIRM PACKAGE CREATION.

Package build status

Each package takes about 5 minutes to build the source code into a running docker executable. You can view the build logs of a specific package, which helps in debugging failing builds.

A flickering yellow dot against the package name indicates that the Build Status:New.

A green dot against the package name indicates that the Build Status:Complete.

Deploy packages

In this tutorial, you have created four packages. They are:

  1. Turtle
  2. User Interface
  3. Simulator
  4. Command Center

You may click CATALOG to view all of the above packages in one place.

Since a deployment may depend on another deployment(s), you will initially deploy the package that is independent of other deployments, and you will work your way up the dependency chain.

ROS publisher subscriber describes the standard procedure for deploying a ROS package. In this tutorial, the Simulator deployment is independent of any other deployment. The Command Center deployment relies on that of Simulator, while the User Interface deployment is based on that of Command Center. Lastly, the Turtle deployment depends on deployments of both the Simulator and the Command Center.

The table summarises dependency relationships between all of the packages in Turtlesim tutorial.

Package Dependent Deployment(s)
Simulator None
Command Center Simulator
User Interface Command Center
Turtle Command Center, Simulator

The below diagram illustrates the dependencies among packages in Turtlesim tutorial.

Dependent deployment block diagram

Deploy Simulator package

To deploy the Simulator package whose deployment is independent of any other deployment, follow the steps:

  1. Click CATALOG > select Simulator package > click Deploy package.
  2. In the Name of the deployment box, type in a name for the deployment you are creating say SIMULATOR deployment
  3. Click CREATE DEPLOYMENT > Confirm.

You will be redirected to the deployment Details page where a green progress bar moves up to Succeeded along with Status:Running point indicating that the DEPLOYMENT PHASE has Succeeded, and the deployment STATUS is Running.

Deploy Command Center package

The Command Center deployment depends on the deployment of Simulator. That is the Simulator deployment is a dependent deployment of Command Center deployment. To deploy the Command Center package, follow the steps:

  1. click CATALOG > select COMMAND CENTER package > click Deploy package.
  2. In the Name of deployment box, enter a name for the deployment say COMMAND CENTER deployment
  3. Ensure that the value of WS_ADDR is 0.0.0.0 and WS_PORT is 9090
  4. Under DEPENDENT DEPLOYMENTS, click Add dependency > select the Simulator’s deployment ID from the dropdown list.
  5. Click CREATE DEPLOYMENT > Confirm.

You are redirected to the deployment’s Details page where a green progress bar moves up to Succeeded and Status:Running point indicating that the DEPLOYMENT PHASE has Succeeded, and the deployment STATUS is running. Since COMMAND CENTER deployment depends on SIMULATOR deployment, ensure that the dependent deployment’s STATUS is running as well.

Deploy User Interface package

When you deploy User Interface package (non-ROS package), ensure you add the Command Center deployment as a dependent deployment. That is a deployment of User Interface is based on that of Command Center.

The procedure to deploy the User Interface package is the same as deploying the Command Center package. However, provide a different name for the deployment say USER INTERFACE deployment To add a dependent deployment, click Add dependency and select the COMMAND CENTER deployment ID from the drop-down list. Click CREATE DEPLOYMENT > Confirm.

If the DEPLOYMENT PHASE is Succeeded and the STATUS is running for the dependent deployment as well, User Interface package is successfully deployed.

The NETWORK ENDPOINTS generates a URL on the deployment Details tab. Copy this specific URL (your URL address will be different from that shown in the screen capture), paste it in the web browser, and run it. You will view the Turtlesim’s user interface without any Turtles. However, if you do not see the Turtlesim user interface, try refreshing the web page for a couple of times.

Network Endpoint for User Interface package

Deploy Turtle package

The procedure for deploying the Turtle package is similar to that of any package whose deployment depends on another deployment. A deployment of Turtle depends on the running deployments of the Command Center and the Simulator, that is COMMAND CENTER deployment and SIMULATOR deployment. You may provide a name for the deployment say TURTLE deployment To add multiple dependent deployments, click Add dependency and select the desired deployment ID for each dependent deployment.

If the deployment fails, click Deprovision deployment; delete the corresponding package; create the package and deploy it again.

On the left navigation bar, click DEPLOYMENTS to view a list of four deployments that you created.

An illustration of the resultant dependency graph is:

Dependency graph of Turtlesim

Refresh the Turtlesim User Interface web page to view a single Turtle randomly placed in the environment.

Turtlesim simulation

Try moving the Turtle around using the command interface. If the Turtle behaves as you expect, you have successfully finished the tutorial.

You can deploy a second Turtle (in the same way as the first). You can now command two turtles simultaneously.

Cleaning up

A running deployment of a package consumes cloud resources. It is recommended to stop a running deployment when you do not need it. To deprovision (stop) a running deployment, follow the steps:

  1. On the left navigation bar, click DEPLOYMENTS.
  2. Click Deprovision against the running deployment ID you want to stop.

If the deployment is successfully deprovisioned, you will view a DEPLOYMENT STOPPED message and the corresponding deployment ID’s PHASE reads Deployment stopped.