Using exported worlds in simulation

Simulation WorldForge can be used to create worlds for use with AWS RoboMaker. Once worlds have been created, they must be exported to use in simulations. You may also upload worlds to use in your simulation.

Exporting worlds offers the opportunity to use:

• Physics that are different from the default SDF physics

• Specialized lighting

• Custom models

This following sections provide more information about using generated worlds in your simulation.

Important

To learn more about how you are charged for AWS RoboMaker, see AWS RoboMaker pricing.

Using an exported world as a data source

With Simulation WorldForge, you can export worlds you can use in your ROS environment. The world you choose to export is copied to a single .zip file in an Amazon S3 bucket. This section describes how to use an exported world in an Amazon S3 bucket in a simulation job by giving instructions on how to adjust the launch file, then creating a simulation job either through the AWS Management Console or using the command line interface.

You must first update your simulation application launch file before using the AWS Management Console or AWS CLI to add a data source.

To update your simulation launch file:

1. Run the following launch commands:

   <launch>
     <!-- Always set GUI to false for AWS RoboMaker Simulation
     Use gui:=true on roslaunch command-line to run with gzclient.
     -->
     <arg name="gui" default="false"/>
        
     <include file="$(find aws_robomaker_worldforge_worlds)/launch/launch_world.launch">
     <arg name="gui" value="$(arg gui)"/>
     </include>
        
     <!-- Your other launch commands go here. -->
   </launch>
   

   You can spawn your robot at (0, 0, 0). The worlds Simulation WorldForge generates are guaranteed to have a 1 meter cylinder clear at (0, 0, 0).

2. Rebuild your image and push as normal. For more information, see Using images to develop AWS RoboMaker applications.

To add a data source

Follow the steps under one of the following tabs:

Using the console

1. Follow the procedure in Creating a world export job to export a world.

2. While creating a simulation job, add a new data source. Give the data source a meaningful name, such as WorldForge, used in the example.

3. Optionally, identify a destination directory into which to place the world.

   Note

   Do not use your workspace directory as the destination, as AWS RoboMaker overwrites the destination with dataSource files. Instead, you can specify a separate directory under the workspace such as your_workspace/src/aws_exported_world as the destination.

4. Choose Archive as the type. AWS RoboMaker unzips the world into the destination directory.

5. Choose Browse S3 and find the correct world-generated export.

6. Continue with creating the simulation job as normal.

Using the AWS CLI

Follow the procedure in Creating a world export job to export a world.

Assuming the workspace is located in the container at /home/simulation_ws, the following command extracts the world into the default destination directory:

aws robomaker create-simulation-job \
  --max-job-duration-in-seconds <time> \
  --iam-role <IAM role ARN> \
  --data-sources '[{
    "name": "WorldForge",
    "type": "Archive",
    "destination": "/home/simulation_ws/src/aws_exported_world",
    "s3Bucket": "worldforge-test",
    "s3Keys": ["aws-robomaker-worldforge-export-q376mqk4z7gm.zip"]
  }]' \
  --robot-applications <config> \
  --simulation-applications <config>

Using an exported world in ROS and Gazebo

As stated in the previous section, Simulation WorldForge exports your chosen world to a single .zip file. The .zip file includes all of the assets needed to modify and visualize the worlds using ROS and Gazebo. It includes the following important folders:

• The root folder, workspace_src, is the ROS workspace. It contains shared models, world data, and other information for the worlds. It is compatible with ROS 1 and ROS 2.

• Shared models is copied to workspace_src/src/aws_robomaker_worldforge_shared_models/models. For example, if the same chair is used in more than one world, it is placed in the shared model folder.

• World data is copied to workspace_src/src/aws_robomaker_worldforge_worlds/worlds/.

To update your simulation launch file:

1. Follow the procedure in Creating a world export job to export a world.

2. Unzip the world into an ROS workspace.

   cd MyApplication/simulation_ws
   unzip MyExportedWorld.zip
   

3. Build the world.

   rosdep install --from-paths src --ignore-src -r -y$ colcon build

4. Launch the world.

   source install/setup.sh
   roslaunch aws_robomaker_worldforge_worlds launch_world.launch gui:=true
   

To build and launch the world in a simulation job:

1. Follow the procedure in Creating a world export job to export a world.

2. Import the exported world into the workspace source package directory /home/simulation_ws/src/aws_exported_world using dataSource

3. Modify the LaunchConfig of simulation application.

   "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",
           "GAZEBO_MODEL_PATH":"@GAZEBO_MODEL_PATH:/home/simulation_ws/src/aws_exported_world/aws_robomaker_worldforge_pkgs/aws_robomaker_worldforge_shared_models/models"
       },
       "streamUI": true,
       "command": [
           "/bin/bash", "-c", "cd /home/simulation_ws && colcon build && source install/setup.sh && roslaunch hello_world_simulation worldforge_world.launch"
       ]
   },
   

Using an exported world with custom physics, lights, and models

If your simulation scenario requires customization, you can export and modify the world. For example, you can apply custom physics, different lighting effects, add custom models, or make other modifications.

After the world is exported, you need to modify the .world file to include the exported world model. The .world file uses SDF. For more information about SDF, see SDFormat.

To modify your .world file to include the exported world model:

1. Follow the procedure in Creating a world export job to export a world.

2. Copy the following code to your .world file. Make sure the world name matches the exported model name.

   <sdf version="1.6">
     <world name="generation_82856b0yq33y_world_16">
       <model name="WorldForge World">
         <include>
            <uri>model://generation_82856b0yq33y_world_16</uri>
         </include>
       </model>
       <!-- Your other <world> elements go here -->
     </world>
   </sdf>
   

3. Verify that your launch file includes the modified .world file. Use the updated launch file to launch your simulation.