Ignition Robotics project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
Ignition Robotics
Technical writer:
An Thai Le
Project name:
Ignition Physics tutorials and API documentation
Project length:
Standard length (3 months)

Project description

Motivation

Ignition Physics library enables flexible usage of the physics engines porting to the back-end of the Ignition Gazebo simulation. Many external physics engines can be adapted to the library as plugins consisting of different sets of features according to their capabilities and application contexts, in order to power gazebo simulation. However, the current stage of the library does not provide:

  • comprehensive tutorials on creating custom physics plugins that use custom physics engines to power simulation
  • coherent API documentation

This proposal aims to solve these issues for better project maintenance and guiding new contributors and users in a more principle manner. The details of the documentation process will be discussed in the next section and then followed by the milestone section for planning the time frame to complete the project. Finally, some notes about the current documentation are mentioned.

Description

This project has two main goals:

  • Create detailed tutorials on creating custom physics plugin interfacing with current library API.
  • Enhance current library API documentation for maintenance and collaboration purposes.

Currently, DART is the only support physics engine of this library. Hence, the tutorials will revolve around DART. These initial tutorials will be considered:

  1. Introduction: describes the high-level architecture of the Ignition Physics library, the supported physics engines, and the goals.
  2. Installation: guides the user to optionally install necessary physics engines depending on application contexts. This tutorial also demonstrates example configurations for each physics engine plugin for adapting a specific simulation.
  3. DART plugin usage: describes example usage of DART physics engine on Gazebo simulation. The tutorial consists of a sequence of executions and configurations to start this library as the back-end for Gazebo simulation on a specific example environment.
  4. Create custom plugin: guides new user or developer to create a custom plugin based on custom physics engine via some forms of config files (possibly class templates), and develop an interface between physics engine API and this library API. Some sanity checks can be noted at the end of the tutorial.
  5. Using multiple plugins on a simulation (need discussion): describes how to simultaneously use multiple plugins at runtime for an example simulation.

Further planning on tutorial structures, descriptions, and contents will be discussed in the community bonding period. It is indeed that the author of these tutorials must ensure the validity of the tutorial steps before merging to the repo.

For API documentation, it is possible to adapt to the Google C++ documentation style for this library. For instance, all classes must have a class level description. Furthermore, all public functions must be documented with a description, all their arguments, as well as possible return values and exceptions. It is beneficial that the most important classes (e.g. dartsim::RetrieveWorld, Feature, etc) will be documented first as an easier top-down approach. Further documentation style, important class identification will be discussed in the community bonding period.

Milestones

This section plans an initial time frame for completing the mentioned goals of the project. Time planning is as follows:

  • Aug 17 - Sep 13: Community bonding:

    1. Set up meetings for establishing project scopes and tutorial plannings as well as expectations from both the writer and mentors.
    2. Grasp the big picture of the Ignition Physics source code.

  • Sep 14 – Oct 31: Draft the mentioned tutorials with iterative refinements between mentors and the writer via meetings.

  • Nov 1 – Nov 30: Write API documentation for the most important classes and compile the documentation using Doxygen.

  • Dec 1 – Dec 5: Write the project report.

  • After GSoD 2020: I would like to stay connected with Ignition Robotics to further improve and maintain my works.

Final notes

It is essential to revise the current README.md on the front page of Ignition Physics, as the binary installation using apt-get does not work on Ubuntu 18.04. The source install section also needs revision because of incorrect formatting.