Running a simulation

To get started running a simulation, use the following AWS CLI commands to describe your applications. These commands provide output that you can examine to confirm you're ready to proceed to creating a simulation job.

The following command retrieves data associated with your robot application.

aws robomaker describe-robot-application --application YOUR-ROBOT-APP-ARN

The output for describe-robot-application contains the following data.

{
   "arn": "YOUR-ROBOT-APP-ARN",
   "name": "YOUR-ROBOT-APP-NAME",
 
 ... # Removed extra data for clarity
 
   "robotSoftwareSuite": {
       "name": "General"
   },
 
 ... # Removed extra data for clarity
 
   "environment": {
       "uri": "YOUR-ROBOT-APP-ECR-URI"
   }
}

The next command retrieves the data associated with your simulation application.

aws robomaker describe-simulation-application --application YOUR-SIM-APP-ARN

The output for the describe-simulation-application contains the following data.

{
   "arn": "YOUR-SIM-APP-ARN",
   "name": "YOUR-SIM-APP-NAME",
 
 ... # Removed extra data for clarity
 
   "simulationSoftwareSuite": {
       "name": "SimulationRuntime"
   },
   "robotSoftwareSuite": {
       "name": "General"
   },

 ... # Removed extra data for clarity

   "environment": {
       "uri": "YOUR-SIM-APP-ECR-URI"
   }
}

Save the returned values for YOUR-ROBOT-APP-ARN and YOUR-SIM-APP-ARN. You need them both to submit your simulation job. If you need to import WorldForge assets into your simulation job, use the DataSource API. This allows you to import world assets from the Amazon S3 output directory of the world export job into a destination of your choosing within your simulation job container. For more information, see Using exported worlds in simulation.

To submit your simulation job, create a JSON file in your working directory named create_simulation_job.json. Copy, paste, and edit the strings identified by red italic text to contain YOUR-IAM-ROLE-ARN, YOUR-ROBOT-APP-ARN, and YOUR-SIM-APP-ARN. The roslaunch command, TurtleBot environment variable, and tool settings below are specific to the hello world sample application. You must update these settings to your own custom values depending on the needs of your simulation job. For more information, see the CreateSimulationJob API.

{
   "maxJobDurationInSeconds": 3600,
   "iamRole": "IAM-ROLE-ARN",
   "robotApplications": [
       {
           "application": "YOUR-ROBOT-APP-ARN",
           "applicationVersion": "$LATEST",
           "launchConfig": {
               "environmentVariables": {
                   "ROS_IP": "ROBOMAKER_ROBOT_APP_IP",
                   "ROS_MASTER_URI": "http://ROBOMAKER_ROBOT_APP_IP:11311",
                   "GAZEBO_MASTER_URI": "http://ROBOMAKER_SIM_APP_IP:11345"
               },
               "streamUI": false,
               "command": [
                   "/bin/bash", "-c", "roslaunch hello_world_robot rotate.launch"
               ]
           },
           "tools": [
               {
                   "streamUI": true,
                   "name": "robot-terminal",
                   "command": "/entrypoint.sh && xfce4-terminal",
                   "streamOutputToCloudWatch": true,
                   "exitBehavior": "RESTART"
               }
           ]
       }
   ],
   "simulationApplications": [
       {
           "application": "YOUR-SIM-APP-ARN",
           "launchConfig": {
               "environmentVariables": {
                 "ROS_IP": "ROBOMAKER_SIM_APP_IP",
                 "ROS_MASTER_URI": "http://ROBOMAKER_ROBOT_APP_IP:11311",
                 "GAZEBO_MASTER_URI": "http://ROBOMAKER_SIM_APP_IP:11345",
                 "TURTLEBOT3_MODEL":"waffle_pi"
               },
               "streamUI": true,
               "command": [
                   "/bin/bash", "-c", "roslaunch hello_world_simulation empty_world.launch --wait"
               ]
           },
           "tools": [
               {
                   "streamUI": true,
                   "name": "gzclient",
                   "command": "/entrypoint.sh && gzclient",
                   "streamOutputToCloudWatch": true,
                   "exitBehavior": "RESTART"
               }
           ]
       }
   ]
}

Note

Take special note of the ROS_ and GAZEBO_ specific environment variable settings in the launchConfig object in the robot and simulation application. The ROBOMAKER_* string values and port numbers are required to enable your robot application container to communicate with your simulation application container.

Once you have confirmed your job settings, you can submit the job using the following command.

aws robomaker create-simulation-job --cli-input-json file://create_simulation_job.json

To confirm that your simulation is running in AWS RoboMaker, visit the Simulation Jobs page within the AWS RoboMaker console. Look for your running job and choose it to view the details and to launch any associated tools. Congratulations, your simulation job is now running in AWS RoboMaker!