-
Notifications
You must be signed in to change notification settings - Fork 1
Creating a Package Introduction
The following tutorial focuses on creating a new Reveal package or scenario with support for simulating the scenario in Gazebo. The tutorial will describe the package structure as well as the processes of defining a scenario, implementing controllers and analyzers, and importing data into the Reveal database.
Before beginning this tutorial, familiarize yourself with the information describing Reveal Installation and Configuration.
Reveal scenarios are encapsulated in individual packages. A Reveal package consists of the scenario definition, a set of simulator agnostic controllers, simulator specific interfaces bridging the agnositic controllers, and a set of analyzers designed to objectively assess simulation performance for the associated scenario. A scenario also requires a set of baseline model data to be used for comparative performance assessment.
The following section will describe the directory structure of a package. There are certain files and paths that are required for the package structure and others that are up to the package developer. Locations that are required will be noted in detail. In the file system frameworks presented below, vertical bars, i.e. |, denote a file or directory is a child of the parent listed at the top of skeleton, dashes, i.e. -, demark the level of nesting within a parent directory, directories will be denoted with a trailing slash, i.e. /, to more easily distinguish them from files, and angle brackets, i.e. <some-label> denotes a definable or predefined name for directories and a definable set of implementations for files depending on the context provided by its corresponding description.
A package is maintained in a directory structure relative to the REVEAL_PACKAGES_PATH environment variable which will be denoted as <root-package-path> in the following skeletons. Each package resides in its own subdirectory of the <root-package-path> and will be denoted as <package-directory>. The name of the <package-directory> is scenario designer definable and trivial but must be unique and should be somewhat descriptive of the scenario. Each package contains a scenario and an analyzers subdirectory. The scenario subdirectory contains all models, controllers, simulator interfaces, and data generators supporting the execution of the package in simulation. The analyzers subdirectory contains the set of all analyzer implementations defined for the package.
<root-package-path>/
|-<package-directory>/
|--scenario/
|--analyzers/
As stated above, the scenario subdirectory contains all the models, controllers, simulator interfaces, and data generators required to execute the simulation in Reveal and also contains the necessary configuration files to build the appropriate simulator-scenario interface at run time. In the root of the scenario subdirectory there must be a cmake build script, the agnostic controller implementation source code, a models subdirectory, and the set of simulation specific controller interfaces necessary to link the appropriate agnostic controller implementation to the simulator specific framework. Other subdirectories and files may also be written to this directory for various utilities, but these frameworks will vary across implementations.
scenario/
|-CMakeLists.txt
|-<agnostic-controller-implementations>
|-models/
|--sdf/
|---<sdf-model-definitions>
|--urdf/
|---<urdf-model-definitions>
|-<simulator-interfaces>/
Reveal uses cmake to build scenarios on demand. The CMakeLists.txt in the scenario directory primarily copies configurations into the build directory and redirects the build system to an appropriate simulator interface on demand during run time building.
All controllers are implemented such that they contain no references to simulator specific types or objects. This is to ensure that a package developer does not erroneously reinterpret controller implementations, that the same control code is executed on all simulators for a given simulation, and that evaluations share a common basis. In the skeleton listing above the set of all individual controller implentations is denoted by <agnostic-controller-implementations>. There may be open parameters for a given controller that may be subject to tuning, so which should be externalized variables in the controller and set by the simulator-scenario interface. The interface to control code is handled through maps that associate joint names as defined in the model configurations with corresponding state input and control output values. By conforming to this requirement, a controller need not have any knowledge of the simulator utilizing it. The controllers are placed into the scenario directory so as to be shared by all simulator-scenario interfaces.
The models directory contains the model definitions for the scenario. The models directory is contains sdf and urdf directories which contain model definitions matching the respective formats. Currently, sdf is the assumed model specification. urdf has been tested and can be easily supported if the limitations of the urdf format in simulation are resolved in the future. It is recommended that models defined for Reveal be prefixed by a reveal label so as to eliminate any name conflicts for simulators between models provided by their distributions and models in the packages.
Each package scenario must also provide the interface each supported simulator. As each new simulator is introduced to Reveal, the accompanying simulator interface for each scenario will be developed, tested, and incorporated into the package distribution. Currently, Reveal only supports Gazebo, so in lieu of the <simulator-interfaces> directory placeholder, a subdirectory name gazebo contains the gazebo interfaces required to link the Gazebo simulator to any agnostic controller implementations. The structure of the gazebo directory will be discussed in the next section. The skeleton of future simulator-interface directories is determined by the whoever develops the interface between Reveal and simulator, so the structure of individual simulator-interface directories will vary between simulators.
For a Gazebo supported package, the <simulator-interfaces> directory must be named gazebo. This directory must contain a CMakeLists.txt build script addressing any Gazebo requirements necessary to run the scenario, a reveal.world definition file defining the world configuration and parameters for the scenario, a manifest.xml file listing the build products that are produced by the build script, and the set of all Gazebo model plugins that act as simulator-scenario interfaces. This directory may also optionally contain other files such as a gazebo.world configuration file for testing the scenario directly in Gazebo without using Reveal.
scenario/
|-gazebo/
|--CMakeLists.txt
|--reveal.world
|--gazebo.world
|--manifest.xml
|--<gazebo-model-plugins>
The details of the gazebo directory is discussed more in detail in Developing a Controller.
Analyzers are post-processes that are run on the results of a Reveal experiment. Analyzers are scenario specific, so they are also defined in the corresponding package. There may be a one-to-many relationship between a scenario and analyzers, so the analyzers directory may contain a number of subdirectories containing different analytic implementations as represented by the <analyzer-directory> token below. Each analyzer requires a compatible build script and an implementation. There must be at least one analyzer included in a given package. Currently Reveal will only use one analyzer on a scenario, but enhancements can extend post-processing to execute multiple analyzers on a single experiment.
analyzers/
|-<analyzer-directory>/
|--CMakeLists.txt
|--<analyzer-implementation>
The name of the <analyzer-directory> is scenario designer definable and trivial but must be unique and should be somewhat descriptive of the analyzer metric.
The <analyzer-implementation> must implement the analytics plugin interface.
A practical example of analyzer development is discussed in more detail in Developing the Analyzer
The partitioned skeletons from the above sections are consolodated here to give a complete overview of the package file structure.
<root-package-path>
|-<package-directory>/
|--scenario/
|---CMakeLists.txt
|---<controller-implementations>
|---gazebo/
|----CMakeLists.txt
|----reveal.world
|----manifest.xml
|----<model-plugin-definitions>
|---models/
|----sdf/
|-----<sdf-model-definitions>
|----urdf/
|-----<urdf-model-definitions>
|--analyzers/
|---<analyzer-directory>/
|----CMakeLists.txt
|----<analyzer-implementation>
Continue with Developing a Controller.