Skip to content

Model Submission Process

Jump to bottom
Angela Maio edited this page Feb 17, 2021 · 9 revisions

This Wiki outlines the process for submitting a new vehicle model or sensor configuration to the SubT Tech Repo.

Preparing Models for Contribution

This section describes the directory structure and contents of vehicle models to be submitted by competitors and other organizations. The following flowchart outlines the process for vehicle model submission. This Wiki covers the Submits Pull Request to SubT Virtual Testbed Software Repository step. For Gazebo9 models, the Transitions URDF to SDF process is described in Model Migration from Gazebo9 to Ignition Gazebo. Models submitted to the SubT Tech Repo must be accompanied by validation data according to DARPA's Model Preparation Guide located at the SubT Challenge Resources page.

model-workflow.png

A model submission consists of a single ROS package with a name following the the pattern <organization_name>_<robot_name>_sensor_config_<#>. The corresponding command line variable name for the vehicle will be <ORGANIZATION_NAME>_<ROBOT_NAME>_SENSOR_CONFIG_<#>. The contents of the submission include:

  • An ignition-gazebo SDF model (See Model Migration from Gazebo9 to Ignition Gazebo to migrate from Gazebo9)
  • A URDF file derived from the ignition-gazebo SDF model
  • Resources (meshes, materials, etc) needed and shared by the ignition-gazebo SDF model and the URDF
  • A spawner.rb file that contains a spawn function that returns the SDF string for spawning the model into ignition-gazebo. This file will be included by the main SubT launch files to spawn the model. It is assumed that this file will reside in <package>/launch/
  • vehicle_topics.launch which launches the ROS-IGN bridge needed by the model. This launch file is to be used by spawner.rb
  • description.launch which sets the robot_description parameter of the robot from the URDF file. This launch file is also to be used by spawner.rb
  • A folder of thumbnails for displaying the model on the SubT Tech Repo. This helper script is useful for producing thumbnails.

Here's an example directory structure:

submitted_models
└── husky_migration_sensor_config_1
    ├── CMakeLists.txt
    ├── launch
    │   ├── description.launch
    │   ├── example.ign
    │   ├── spawner.rb
    │   └── vehicle_topics.launch
    ├── meshes
    │   ├── base_link.dae
    │   ├── bumper.dae
    │   ├── lms1xx_mount.dae
    │   ├── meshes.txt
    │   ├── sick-lms1xx.dae
    │   ├── top_chassis.dae
    │   ├── top_plate.dae
    │   ├── user_rail.dae
    │   └── wheel.dae
    ├── model.config
    ├── model.sdf
    ├── package.xml
    ├── thumbnails
    │   ├── 1.png
    │   ├── 2.png
    │   ├── 3.png
    │   ├── 4.png
    │   └── 5.png
    ├── urdf
    │   ├── husky_migration.orig.urdf
    │   └── robot_from_sdf.xacro
    └── worlds
        └── example.sdf

6 directories, 25 files

A team submission will be in the form of a PR to the SubT Tech Repo that adds a new directory to submitted_models. To launch a robot submitted by a team, the ROS package name is passed to robotConfigX parameter of the ign launch files.

The team_submission_example contains an example package called husky_migration_sensor_config_1. To test this robot, locally (before it becomes available on Fuel), teams can clone the repository by running git clone https://github.com/osrf/subt -b team_submission_example and running

ign launch -v 4 competition.ign robotName1:=alpha robotConfig1:=HUSKY_MIGRATION_SENSOR_CONFIG_1 localModel:=true

The localModel:=true is needed for local testing.

Once the PR is merged, the ignition-gazebo relevant files will be uploaded to Ignition Fuel.

Organizations can refer to the Submitting a Pull Request section of this guide for a step by step instructions on creating a model submission PR.

Adding a Custom Configuration to Existing Vehicles

Custom payload configurations can be submitted as pull requests using the vehicles already available on the SubT Tech Repo. Contributors are encouraged to compose new configurations of sensors (including sensor range, resolution, and noise parameters) tabulated at the SubT API. Submissions including new sensor parameters may be subject to additional requests for information such as representative sensor datasheets. Organizations should follow these steps to produce a new sensor configuration:

  1. Download the zipped vehicle model from Fuel and extract it. Rename the directory with the pattern <organization_name>_<robot_name>_sensor_config_1. The corresponding command line variable name for the vehicle will be <ORGANIZATION_NAME>_<ROBOT_NAME>_SENSOR_CONFIG_1.

  2. Add package.xml and CMakeLists.txt files to convert it into a ROS package

  3. Modify model.sdf to customize the payload configuration

  4. Generate a URDF from model.sdf following the steps in the Rviz visualization section of the Model Migration from Gazebo9 to Ignition Gazebo and place it in a new directory called urdf inside the package.

  5. Copy the launch directory from the husky_migration_sensor_config_1 example

  6. Update the package name and URDF path in launch/description.launch.

  7. Modify launch/spawner.rb by copying the corresponding function from competition.ign. For example, if modifying the X1 vehicle, copy the contents of spawnX1 from competition.ign and put the ignition relevant part in spawner and the ROS relevant parts in rosExecutables

  8. Modify launch/vehicle_topics.launch to include the necessary ROS-IGN bridges for the customized payload configuration. Use the SubT API for topic naming conventions. Make sure to include the following line <env name="IGN_TRANSPORT_TOPIC_STATISTICS" value="1"/>

  9. Test launch your model with the new sensor configuration to ensure it is working properly.

  10. Submit a pull request by following the steps in the next section of this wiki. Include a list of all sensors in your configuration, their parameters (range, resolution, FoV), and sensor topic names in the pull request description.

  11. Watch your pull request for comments and changes by the SubT Challenge Team. If your PR is accepted, SubT credit value and metadata will be assigned by DARPA and your configuration will be added to the SubT Tech Repo.

Please note the process for incorporating user-contributed sensor configurations is new and intended to help competitors - your cooperation and patience are appreciated.

Submitting a Pull Request

This section covers the step-by-step process to completing a pull-request submission to the SubT Virtual Testbed software repository. Before you submit a PR, please go through the Robot Model Checklist.

  1. Fork the public repository by clicking the Fork button at the top right on the subt repository home page.

  2. Name the forked repository. The recommended naming scheme is subt_<organization_name>_<robot_ name>. For this example, we will use subt_darpa_x1_sensor_config_1 as the repository name and darpa_x1_sensor_config_1 as the model directory/variable name.

  3. Clone your forked repository to your computer using your github username:
    git clone [email protected]<github_username>/subt_darpa_x1_sensor_config_1

  4. Move into your forked repository and check out your associated branch:
    cd subt_darpa_x1_sensor_config_1
    git branch submitted_models/darpa_x1_sensor_config_1

  5. Make a directory for your model in the submitted_models folder. The recommended naming convention is <organization_name>_<robot_name>_sensor_configuration_<configuration #>.
    cd subt_darpa_x1_sensor_config_1/submitted_models
    mkdir darpa_x1_sensor_config_1

  6. Add your files to the <organization_name>_<robot_name>_sensor_configuration_<configuration #> directory for your model submission inside of the submitted_models folder.

  7. Add and commit your changes:
    cd subt_darpa_x1_sensor_config_1/submitted_models
    git add darpa_x1_sensor_config_1/
    git commit -am "Model submission for X1 sensor configuration 1 from DARPA."

  8. Push your changes to your forked repository:
    git push origin submitted_models/darpa_x1_sensor_config_1

  9. Check your pushed branch on the forked repository (submitted_models/darpa_x1_sensor_config_1 is the example branch) and then initiate your pull request by clicking the Create button in the Pull request column.

  10. On New pull request, check to ensure the source branch is correct and that your pull request is being sent to the osrf/subt repository’s master branch. Ensure that the pull request’s title is “Model submission for <robot_name> sensor configuration # by <organization_name>.” Include comments in the description as necessary. When finished, click the Create pull request link.

  11. Check the status of your pull request periodically for feedback and action items prior to approval for merging into the subt repository.

Robot Model Checklist

Please verify your model using this checklist before submitting a PR.

Data streams are properly routed to ROS:

  • Sensor data streams are correctly routed to ROS topics
  • Robot moves as expected in response to velocity commands on cmd_vel topic
  • Topic naming conventions match the API
  • Optical frame publishers are added (see API on Sensors)
  • Static transform publishers are utilized for static links (see this PR)
  • Ground truth data is only routed to ROS topics when enableGroundTruth:=true (see API on Ground Truth)
  • If the robot includes active payload components (e.g., gimbal, droppable communication breadcrumbs, or marsupial child), the command topic(s) are routed to ROS

Mesh components are reasonable:

  • All parts have both visual and collision components and are attached to the vehicle (not floating)
  • All colliders and meshes align (i.e., mesh does not pierce or float above the ground plane -- typically occurs with wheels)
  • Sensors are correctly oriented and not obstructed by other parts of the model

Model features match the physical robot as listed in specifications.md:

  • Total mass in model.sdf matches physical robot mass
  • Battery model matches physical robot endurance duration (see Battery Model Tutorial)
  • Robot moves as expected in response to velocity and angular velocity commands, including adherence to velocity and acceleration limits
  • Sensor specifications in model.sdf match the listed sensor datasheets
  • If the robot includes an active or passive joint, the friction and angle limits are properly modeled and noted in specifications.md (for active joints, see API on Gimbals)
  • If the robot includes droppable communication breadcrumbs, the quantity is modeled and noted in specifications.md (see API on Breadcrumbs)
  • If the physical robot is capable of carrying another robot, the model includes marsupial deployment functionality and the parent and child models are submitted separately (see Marsupial Tutorial)
  • If the robot is wheeled, then the model should include a WheelSlip plugin in the spawner.rb script. See this example.
Clone this wiki locally