AWS Robotics Blog

Introducing Batch Simulation API for AWS RoboMaker

There are many benefits of using simulation in robot application development. One, a company may have a new product idea and wants to design, test and iterate on a set of prototypes before investing in physical hardware. Two, once you have a physical robot created, developers may not have access to expensive or large physical robots at their desk for active development. Three, if developers do have access to a physical robot, it can be difficult to keep the configuration consistent across the team and ensure code can be easily integrated without friction. Four, once developers are ready to test their code, there are a virtually endless number of real-world scenarios and locations that robots would encounter.

This is where simulation can add-value, accelerate development and improve code quality. Simulation is quite beneficial when developers are building and testing robots that will operate on far off locations, in dangerous situations or even different planets, where the physical test environments are simply not available. In addition, developers may want to run the robot application for 10,000 hours to test code and identify bugs. In simulation, you can speed up the clock time to ensure your code is durable and see how the application may impact hardware longevity. Automating tests like these in simulation and running them consistently and routinely as part of a CI/CD pipeline can significantly speed up your software release lifecycle by reducing the number of bugs introduced and improve quality, safety and readiness of your code. Finally, developers could use batch simulations to train machine learning models. By speeding up clock time and running many simulations in parallel with horizontally scalable compute in AWS, you can train ML models faster and cheaper than if you were to capture physical data.

AWS RoboMaker provides a fully managed robotics simulation service that can be used to run ROS and ROS2 applications in simulation and automatically scales the underlying infrastructure based on the complexity of the simulation. Creating simulation jobs in batch to support the use cases above is easier than ever with the release of a new AWS RoboMaker Batch Simulation API. This feature enables customers to easily create large-scale batch simulation jobs with a simple API call. In this blog, we will introduce the new API and how to use it.

Batch Simulation with AWS RoboMaker

To get started, let’s take a look at the input JSON file that you would use to define a batch of simulation jobs. In the below example, we will use the CloudWatch Robot Monitoring Sample Application and launch a set of simulations each with different environment variables.

{
	"batchPolicy": {
		"timeoutInSeconds": 800,
		"maxConcurrency": 2
	},
	"createSimulationJobRequests": [{
			"failureBehavior": "Fail",
			"iamRole": "string",
			"maxJobDurationInSeconds": 600,
			"outputLocation": {
				"s3Bucket": "<S3_BUCKET_NAME>",
				"s3Prefix": "logs"
			},
			"robotApplications": [{
				"application": "<ROBOT_APPLICATION_ARN>",
				"applicationVersion": "1",
				"launchConfig": {
					"launchFile": "rotate.launch",
					"packageName": "hello_world_robot",
					"environmentVariables": {
						"ROS_AWS_REGION": "us-west-2"
					}
				}
			}],
			"simulationApplications": [{
				"application": "<SIMULATION_APPLICATION_ARN>",
				"applicationVersion": "1",
				"launchConfig": {
					"launchFile": "empty_world.launch",
					"packageName": "hello_world_simulation",
					"environmentVariables": {
						"ROS_AWS_REGION": "us-west-2",
						"TURTLEBOT3_MODEL": "waffle_pi",
						"NAVIGATION_SUCCESS_COUNT": "1",
						"SIMULATION_WORLD": "small_house",
						"SIM_TIMEOUT_SECONDS": "600"
					}
				}
			}],
			"tags": {
				"myJobTagKey": "myJobTagValue"
			}
		},
		{
			"failureBehavior": "Fail",
			"iamRole": "string",
			"maxJobDurationInSeconds": 600,
			"outputLocation": {
				"s3Bucket": "<S3_BUCKET_NAME>",
				"s3Prefix": "logs"
			},
			"robotApplications": [{
				"application": "<ROBOT_APPLICATION_ARN>",
				"applicationVersion": "1",
				"launchConfig": {
					"launchFile": "rotate.launch",
					"packageName": "hello_world_robot",
					"environmentVariables": {
						"ROS_AWS_REGION": "us-west-2"
					}
				}
			}],
			"simulationApplications": [{
				"application": "<SIMULATION_APPLICATION_ARN>",
				"applicationVersion": "1",
				"launchConfig": {
					"launchFile": "empty_world.launch",
					"packageName": "hello_world_simulation",
					"environmentVariables": {
						"ROS_AWS_REGION": "us-west-2",
						"TURTLEBOT3_MODEL": "waffle_pi",
						"NAVIGATION_SUCCESS_COUNT": "1",
						"SIMULATION_WORLD": "bookstore",
						"SIM_TIMEOUT_SECONDS": "600"
					}
				}
			}],
			"tags": {
				"myJobTagKey": "myJobTagValue"
			}
		}
	],
	"tags": {
		"myBatchTagKey": "myBatchTagValue"
	}
}
 
       
 
       

The first block is the batch policy. In this section, you would define the parameters for the batch job. It includes the following:

  • timeoutInSeconds: Maximum amount of time to run all batch simulation jobs to a terminal state.
  • maxConcurrency: The number of simulations jobs to run in parallel from the simulation job batch. The default limit for concurrent simulation jobs in AWS RoboMaker is 10. If you need to run more than 10 concurrent simulation jobs, you can request an increase in this limit.

The second block contains an array of job requests. Here is where you define the simulation jobs to run. Each item in the array will launch a seperate simulation job. The format expects the same structure as the input parameters for the single CreateSimulationJob request. This includes:

  • maxJobDurationTimeout: Amount of time this single simulation job will run before being terminated.
  • iamRole: The IAM role that the simulation job can assume. You would need to attach appropriate IAM policies to this role if the simulation job accesses AWS resources such as S3, CloudWatch, etc.
  • failureBehaviour: If the application or underlying system encounters a failure, you can choose to immediately terminate the job or keep it running for troubleshooting.
  • robotApplications: The set of robot applications that you would like to launch in this simulation job. These applications would usually contain no simulation assets and contain the codebase that is intended to run on the physical robot.
    • application: The robot application Amazon Resource Name (ARN) to use in the simulation. When creating a new robot application, you would define where the code artifact is stored in S3 as well as the architecture and ROS/ROS2 release to use.
    • launchConfig: The launch file and package name to invoke when the simulation job starts.
      • packageName: The ROS package name for your application.
      • launchFile: The ROS launch file that you will use to start your application.
    • environmentVariables: Any environment variables to use in the application. This is a great way to parameterize simulations for different scenarios.
    • portForwardingConfig: Some applications require ports to be open on the underlying host for communication with other simulation jobs or back-end systems running outside of AWS RoboMaker simulation. To learn more about how to configure ports, click here.
    • tags: A set of key-value pairs that can be used to identify and annotate the individual simulation job.
  • simulationApplications: The set of simulation applications that you would like to launch in this simulation job. These applications would contain all of the simulation assets (for example, 3D model assets like the URDF file and Gazebo world files) as well as the scenarios and test applications that you want to run in simulation. It requires the same parameters as the above robot applications.

The final tags block enables you to define a separate set of key-value pairs to use with the simulation job batch resource.

Launching a Simulation Job Batch

To launch a batch of simulation jobs, you can use the AWS CLI or the AWS SDK. First, copy the above JSON and save it as “batchSimulationLaunch.json”. Before getting started below, ensure that you have the AWS CLI installed and the IAM user credentials have access to create RoboMaker simulations. Next, in order to easily create a sample robot and simulation application, we are going to launch the Robot Monitoring Sample Application and create the resource with the AWS RoboMaker Console.

  1. Open the AWS Console and then open AWS RoboMaker.
  2. Click on Sample Applications under the Resources tab.
  3. Click the radio box for Robot Monitoring. Click Launch simulation job. Now, the robot and simulation application supporting assets will be created and a single simulation job will launch. In this process:
    • The required AWS infrastructure (S3 bucket, IAM role with the required permissions to allow the application(s) access to publish to CloudWatch and other AWS services) are created.
    • The ROS1 sample application is already built and bundled on your behalf using colcon (a build and bundling tool for ROS applications). If you want to see the application code in GitHub, click here. To learn more about building and bundling applications for AWS RoboMaker using colcon, click here.
    • The bundle files are copied and staged in AWS S3 (tar files with both the dependencies and the built ROS packages) into an S3 bucket.
    • The robot and simulation applications are created in AWS RoboMaker, referencing the tar files in the S3 bucket from above.
  4. Once this is complete, click back to the AWS RoboMaker console and under Development, click Robot Application. Find the robot application that was created by the process above and open it. Copy the ARN and replace the <ROBOT_APPLICATION_ARN> in each of the robotApplications section of the batchSimulationLaunch.json file that you created from the template above.
  5. Do the same exercise for the Simulation Application, this time replacing the <SIMULATION_APPLICATION_ARN> in each of the simulationApplications section of the batchSimulationLaunch.json file.
  6. Save the batchSimulationLaunch.json file.
  7. Run the following CLI command:
    aws robomaker start-simulation-job-batch --cli-input-json file://batchSimulationLaunch.json
  8. Return to the AWS RoboMaker Console and click Simulation job batches under Simulations. You should see your batch of simulation jobs preparing to launch.
  9. To get the current status of the batch job, including the failed, pending and created requests, you can run the following CLI describe command using the ARN of the batch job that was created:
    aws robomaker describe-simulation-job-batch --batch <YOUR_BATCH_JOB_ARN>

Cancelling a Simulation Job Batch

Once a simulation job batch is running, you can easily cancel the job by following these steps:

  1. In the left navigation pane, choose Simulations, then choose Simulation job batches.
  2. Select the Id of the simulation job batch you want to cancel.
  3. In the Simulation job batch detail page, under Batch actions, choose Cancel batch.
  4. In the Cancel simulation job batch page, select Cancel.

If you want to cancel the job programmatically or through the AWS CLI, you can run this command:
aws robomaker cancel-simulation-job-batch --batch <YOUR_SIMULATION_JOB_BATCH_ARN>

In addition to these above approaches, you can also cancel and tag any individual job from within your application by using a local ROS service proxy for AWS RoboMaker Simulation.

import rospy
import rostest
import time
import os
import unittest

from robomaker_simulation_msgs.msg import Tag
from robomaker_simulation_msgs.srv import Cancel, AddTags

class SimulationUtils():
    """
    A set of utilities to use in AWS RoboMaker simulation.
    """
    def cancel_job(self):
        rospy.wait_for_service("/robomaker/job/cancel")
        requestCancel = rospy.ServiceProxy("/robomaker/job/cancel", Cancel)
        response = requestCancel()
        if response.success:
            self.is_cancelled = True
            rospy.loginfo("Successfully requested cancel job")
            self.set_tag(name=self.test_name + "_Time_Elapsed_End", value= str(time.time()).split(".", 1)[0])
        else:
            rospy.logerr("Cancel request failed: %s", response.message)

    def set_tag(self, name, value):
        rospy.wait_for_service("/robomaker/job/add_tags")
        requestAddTags = rospy.ServiceProxy("/robomaker/job/add_tags", AddTags)
        tags = ([Tag(key=name, value=value)])
        response = requestAddTags(tags)
    if response.success:
        rospy.loginfo("Successfully added tags: %s", tags)
    else:
        rospy.logerr("Add tags request failed for tags (%s): %s", tags, response.message)

Cloning Simulation Job Batches

Once you have configured and ran a simulation job batch with the CreateSimulationJobBatch API, you can easily clone the batch job for future use. The robot and simulation application ARNs that you defined in your above JSON file will reference the latest code stored in S3. If you are using batch simulations as part of a CI/CD workflow, when the new code is built and bundled, you can conveniently clone the previous batch job to run regression tests. Secondly, if a single scenario failed in the test, instead of running all of the simulation jobs again, you could simply clone and run the single simulation job where the test failed. Finally, if you are using batch simulations to run ML training jobs, you can run a new set of training jobs by simply cloning the previous batch. To clone your simulation job batches:

  1. In the left navigation pane, choose Simulations, then choose Simulation job batches
  2. Select the Id of the simulation job batch you want to clone.
  3. To clone the entire batch, in the Simulation job batch detail page, under Batch actions, choose Clone batch.
  4. To clone specific simulation job requests from the batch, under Simulation job requests, check the simulation job requests you want to clone, then select Request actions and choose Clone request.
  5. In the Clone simulation job batch page, select Submit.

Summary

In this blog article we discussed how using simulation can enable robot application developers to reduce the number of bugs introduced and increase the velocity and number of production-ready features released. We highlighted a new feature, a Batch Simulation API for AWS RoboMaker, that will make it easier to launch batch simulation jobs and test many real-world scenarios or run many training jobs in parallel. We hope this new capability will help you and your development teams improve  your test coverage, speed up your software release cycle and more easily get new exciting features out to your customers.

Happy Building!