Skip to content

Cloudsim Submission

Jump to bottom
Angela Maio edited this page Jun 30, 2023 · 13 revisions

Note: This tutorial is now deprecated, as the SubT Virtual Portal is no longer open for simulation submissions

This tutorial describes how to submit a Docker image to the Portal for practice, qualifications, or competition event.

Docker images are required. Registered teams can utilize a private Docker repository, or other Docker repositories, such as Dockerhub. Please contact [email protected] for access to a private Docker repository.

Important note about Dockerhub

It is possible to use docker images hosted on Dockerhub, however we do not recommend this. Dockerhub has introduced rate limits starting on November 2nd, 2020. These rate limits could prevent Cloudsim from pulling your solution. We recommend using a private Docker repository, available to teams upon request, which is hosted on AWS instead of Dockerhub. Contact [email protected] for access to a private Docker repository.

Instructions

  1. Make sure you have registered on the Portal.

  2. Create and test your Docker image. This docker image must contain your solution, and your solution must run automatically. There are numerous resources online that describe how to install, setup, and use Docker. If you want a good starting point, please look at this tutorial.

  3. Upload your Docker image to a repository. The following instructions assume you are using a provided AWS ECR based repository.

    Make sure you have installed the AWS CLI tool, and configured it with your team's credentials. These credentials will be provided to you. If you don't have credentials, then please contact us at [email protected].

    Use the provided subt_docker.bash script to tag and upload your docker image. Usage of this script is

     $ ./install/share/subt_ign/scripts/subt_docker.bash <team_name> <local_docker_image> <local_tag> <upstream_tag>

 team_name: This is the name of your team. This is also the name of your Docker repository.

 local_tag: This is the tag associated with your docker image. A common tag is 'latest'.

 upstream_tag: This is the tag you want associated with your image when uploaded to the repository. This will let you version your docker images.

    For example, if your team name is foo, you have a docker image called solution_bar:latest, and you want to version this image with the name virtual_stix:

    subt_docker.bash foo solution_bar latest virtual_stix

    This script will log you into docker, tag your image, and push the image to your repository. The final output of the script is the URL of your Docker image. Use this URL when "Uploading a Simulation" on the Portal.

  4. At this stage, you have two options for submitting your solution. The first options utilizes a web interface. The second option utilizes a REST API.

Web Interface Submission

  1. Log into the Portal and navigate to the Compete page.

  2. Click on the "Upload a Submission" button.

  3. Give your submission a name. This name is just for bookkeeping, and must contain only alpha-numeric characters.

  4. Choose the event/scenario for your submission using the dropdown box.

  5. Select if your submission is private or public. If it's public, anyone will be able to access its visualization.

  6. Add robots to your team.

    1. Each robot must have a unique name. The name must have only alpha-numeric characters.

    2. Specify the URL of your Docker image for the robot. This can the URL provided from the subt_docker.bash script, or from another source such as DockerHub. Here is an example URL: 138467776890.dkr.ecr.us-east-1.amazonaws.com/osrf_subt_redteam:subt_seed

    3. Choose the robot type from the dropdown box.

    4. Click the Add button, and continue adding more robots until you have built your entire team.

  7. Click Submit

  8. You should now see a new entry in the "Submissions" card. This entry will receive status updates as the simulation instance runs.

  9. Once the simulation instance completes, you can download the log files using the download button located at the far right of the simulation entry.

REST Interface Submission

A competitor can submit a solution through a REST interface. This option bypasses the web UI, and allows a competitor to programmatically submit a solution. Cloudsim needs a user authentication mechanism, which is normally provided by the web UI when a user logs in. Personal access tokens provide this authentication method. The rest of this section will walk through the process of creating a personal access token and submitting a solution.

  1. Create a personal access token.

    1. Log into the Portal.
    2. Select your username in the upper right, and choose the Settings option.
    3. On the Settings page, select the Access Tokens tab.
    4. Enter a name for your new token. The name is used as a label for your token.
    5. Click Create Token.
    6. A dialog window will appear with your new token. Copy this token now. You will not have access to the token again. This is done for security reasons.
    7. This token can be used for authentication purposes.

  2. Submit a solution using curl and your personal access token.

    curl -k -X POST --url <CLOUDSIM_URL> -F name="SUBMISSION_NAME" -F owner="TEAM_NAME" -F private="PRIVATE" -F circuit="CIRCUIT_EVENT" -F robot_name="ROBOT_NAME" -F robot_type="ROBOT_CONFIG" -F robot_image="ROBOT_IMAGE" -F marsupial="PARENT_NAME:CHILD_NAME" --header "Private-Token: ACCESS_TOKEN"
    • SUBMISSION_NAME: This is the name of your submission. This is equivalent to the Name field on the web interface.
    • TEAM_NAME: This is the name of your team. This is equivalent to the "Owner" field on the web interface.
    • PRIVATE: A boolean indicating if the submission is private (true) or public (false). This form field is optional: Submissions are private by default.
    • CIRCUIT_EVENT: This is the name of the scenario, and is equivalent to the Scenario field on the web interface. The possible values include:
      • "Virtual Stix"
      • "Tunnel Circuit"
      • "Tunnel Practice 1"
      • "Tunnel Practice 2"
      • "Tunnel Practice 3"
      • "Simple Tunnel 1"
      • "Simple Tunnel 2"
      • "Simple Tunnel 3"
      • "Urban Qualification"
      • "Urban Simple 1"
      • "Urban Simple 2"
      • "Urban Simple 3"
      • "Urban Practice 1"
      • "Urban Practice 2"
      • "Urban Practice 3"
      • "Urban Circuit"
      • "Urban Circuit World 1"
      • "Urban Circuit World 2"
      • "Urban Circuit World 3"
      • "Urban Circuit World 4"
      • "Urban Circuit World 5"
      • "Urban Circuit World 6"
      • "Urban Circuit World 7"
      • "Urban Circuit World 8"
      • "Cave Simple 1"
      • "Cave Simple 2"
      • "Cave Simple 3"
      • "Cave Qualification"
      • "Cave Practice 1"
      • "Cave Practice 2"
      • "Cave Practice 3"
    • ROBOT_NAME: Name of your first robot. This is equivalent to the Robot Name field on the web interface.
    • ROBOT_TYPE: Sensor configuration for your first robot. This is equivalent to the Robot Type field of the web interface.
    • ROBOT_IMAGE: Docker image URI. This is equivalent to the Docker Image URL on the web interface.
    • MARSUPIAL: The names of the parent and child robots, separated by a colon, that form a marsupial vehicle.

    The ROBOT_NAME, ROBOT_CONFIG, and ROBOT_IMAGE fields can be repeated multiple times, once for each robot in your team.

    Example Submission

    curl -k -X POST --url <CLOUDSIM_URL> -F name="MyUrbanQualSubmission" -F owner="OSRF SubT RedTeam" -F circuit="Urban Qualification" -F robot_name="X1" -F robot_type="X1_SENSOR_CONFIG_6" -F robot_image="138467776890.dkr.ecr.us-east-1.amazonaws.com/osrf_subt_redteam:subt_seed" -F robot_name="X2" -F robot_type="X3_SENSOR_CONFIG_6" -F robot_image="138467776890.dkr.ecr.us-east-1.amazonaws.com/osrf_subt_redteam:subt_seed" -F marsupial="X1:X2" --header "Private-Token: abcde.efghijk"

Troubleshooting

  1. The cloudsim bridge instance runs the ROS_MASTER, refer to the cloudsim architecture. While you can create a multi-master setup, chances are you should not run your own ROS master.

  2. The /subt/start and /subt/finish ROS service calls are optional, refer to the API documentation.

  3. Use the docker compose guide to re-create the cloudsim setup on your local computer.

  4. Your docker images must run forever (not exit). Use the Dockerfile Entrypoint to execute your solution.

  5. Gazebo state information and server console messages are logged on the Ignition Gazebo instance. ROS console messages are captured in the Bridge Container on each Robot instance. Additionally, a rosbag of the /rosout_agg topic is captured in the Bridge Container in a file called rosout_agg.bag. All of these log files are available for download following a successful simulation run.

Helper Scripts

If you are using the provided Docker repository, then you can make use of the following scripts.

List available images

To list all the images that you have uploaded to your repository:

$ ./install/share/subt_ign/scripts/subt_docker_list.bash <team_name>

Pay attention to the imageTag field, which should be used when submitting a cloud simulation solution. Use the subt_docker_uri.bash script to convert an imageTag to a full URI.

Construct Image URI

To convert an image tag to a full URI, which can be used when submitting a cloud simulation solution:

$ ./install/share/subt_ign/scripts/subt_docker_list.bash <team_name> <image_tag>

The <image_tag> can be acquired from the subt_docker_list.bash script.

Clone this wiki locally