-
Notifications
You must be signed in to change notification settings - Fork 1
Home
There exist a number of rigid body dynamics "engines", many of which are targeted toward particular applications. These engines consist of a number of components (integration scheme, collision detection approach, approximations for speed, constraint solver, and constraint stabilization approach, among others) that results in a holistic system.
For just one example, consider modifications by Open Source Robotics Foundation (OSRF) to Open Dynamics Engine (ODE) to facilitate running DARPA's Virtual Robotics Challenge in real time: ODE's default time stepping integration scheme, combined with the discrete collision detection approach, results in interpenetration. OSRF computes friction forces and then "teleports" the bodies apart using the computed interpenetration depth. Essentially every simulator (including Bullet, DART, RPI-Sim, and Moby) deals with simulation issues in its own way.
These differences make it difficult for users to select and tune a dynamics engine and make it difficult for researchers to assess and improve dynamics engines. REVEAL hopes to change this status quo by providing a repository of benchmark scenarios- all involving contact- toward accomplishing the following:
- Detecting and tracking bugs in dynamics: we aim for closed form and simplified numerical benchmarks (using equations of motion derived in different ways) that can give trusted results.
- Showing users how to tune parameters for a particular dynamics engine to maximize performance (some combination of accuracy, stability, speed)
- Identify potential areas of improvement for an individual engine or all engines
- Inform the community of users (through readily interpretable results) the simulators that are highly suited for particular applications
Unlike past benchmarks, we attempt to put the "burden" of parameter tuning on users (though we also plan to use some automated tuning with random parameters to help collect data); both users and simulation developers can record an evaluation under particular parameterizations of an engine and versions of an engine (the evaluator selects the label for the evaluation). User credentials will allow the collected data to be peer reviewed: if evaluations do not match, community members can attempt to rerun the experiments under the same parameterizations and flag unreproducible results for removal. The user credentials will also allow the community to assign weight to results by credibility: users that run experiments carefully (by recording all pertinent parameters) will naturally attain greater credibility (and vice versa). We expect that the community would give a simulation developer particular credibility.
Reveal is composed of four principle components: client, server, data service, and web visualization service. All four components can be installed onto a single machine or installed on separate systems. The client allows a user to create experiments, run simulations, and automatically submits solutions to the server. The server services client requests, interacts with the data service, and analyzes client solutions. The data service responds to transaction requests by the server and maintains the repository of all Reveal data. The web service provides a means to visualize the data stored by the data service through a browser interface. The client and server are included in the reveal repository as C++ projects, the data service is a mongodb based database, and the web service is a python project maintained in a separate repository.
Reveal is maintained in four separate repositories whose contents work in conjunction with one another to support simulator evaluation. The principle repository is reveal which provides the system foundation and client/server applications. Two additional repositories are required to execute the applications, reveal_sims and reveal_packages. reveal_sims contains the interfaces for supported simulators and reveal_packages contains the scenarios and analyzers available. The repositories reveal, reveal_sims, and reveal_packages are all required in order to execute Reveal applications. These components are segregated for developmental and future distribution purposes. The final component is reveal_site which contains the web-site for viewing and plotting Reveal data.
- Reveal Client and Server
- reveal_messages
- reveal_core
- reveal_sim_gazebo
- Reveal Server
- reveal_db
- reveal_analytics
- reveal_messages
- protobuf 2.4.1 (default version for Ubuntu 12.04)
- reveal_core
- zeromq 4.0.3 (or later)
- boost (tested against version 1.46.1)
- tinyxml
- reveal_sim_gazebo
- gazebo 4.0.1
- reveal_db
- mongodb c++ driver (branch 26compat)
- reveal_analytics
- Ravelin
Warning: Reveal has currently only been validated against mongo version 2.6. Mongo has progressed several steps since this version and the current version distributed by Debian may not be compatible with the 2.6 interface. Until otherwise noted, please build and install mongo v2.6 from source rather than install mongo from apt-get.
Note: The prefix specified in the following instructions is purely optional. If you choose to specify a prefix, you should install mongo to /opt/mongo. If you choose not to specify a prefix, mongo will be installed to the default system path, i.e. most likely /usr/local/; otherwise, the Reveal cmake system may not find the mongo libraries. Also, the installation command specifies (by omission) a 32-bit installation which is adequate for testing purposes. For long term database deployment 64-bit will be necessary.
- Download mongo branch v2.6
- Build and install mongo. Refer to the Build Mongo From Source document for detailed instructions.
sudo scons core --prefix=/opt/mongo install - Create a mongo user, e.g. mongodb, to limit access rights. Refer to the Install MongoDB on Linux document for detailed instructions on creating a user and starting mongo.
- Create a directory for the database itself, e.g. /data/db, and give the mongo user ownership.
- If the prefix was set in step 2, export that path including the bin subfolder, e.g. /opt/mongo/bin, to the system PATH variable in the mongo user bash script.
- Create a mongo configuration script for the mongo user. MongoDB has various security vulnerabilities that are exposed by default. A configuration script will minimize those vulnerabilities. Refer to the Security Management and Practices document for details. Below is a sample Mongo configuration file that handles the most prominent security vulnerabilities.
# mongod.conf
# Where to store the data.
# Note: if you run mongodb as a non-root user (recommended) you may
# need to create and set permissions for this and any log directory manually,
dbpath=/data/db
# Where to log
logpath=/var/log/mongodb/mongod.log
quiet=true
logappend=true
# Port to listen on
port = 27017
# Listen to local interface only. Comment out to listen on all interfaces.
bind_ip=127.0.0.1
nounixsocket=true
# Disable the HTTP interface (Defaults to localhost:28017).
nohttpinterface=true
rest=false
Note: The note on the prefix in the previous section applies here as well. If a prefix was specified for installing the database itself, use the same prefix installing the driver.
Make sure to install the mongo driver on the system the server is installed to. The driver allows the server to communicate with the database host whether the database is hosted on the local system or a remote system. Reveal server will not build if the mongo driver headers are not on the server system.
- Download mongo-cxx-driver branch 26compat
- Build and install the driver
sudo scons --full --use-system-boost --prefix=/opt/mongo --sharedclient install-mongoclient
For a full installation clone reveal, reveal_sims, and reveal_packages repositories onto your local system. The build products from reveal will be installed to the system while reveal_sims and reveal_packages will be utilized on the system in the location specified by the environment and will therefore require appropriate access rights. Your home directory is a recommended location for these repositories and is used in in all following examples.
To clone, use the following commands:
git clone https://github.com/PositronicsLab/reveal.git
git clone https://github.com/PositronicsLab/reveal_sims.git
git clone https://github.com/PositronicsLab/reveal_packages.git
To install the core Reveal system and applications from the console, navigate to the reveal directory, create a build directory in the directory, change to the build directory, and use cmake and make to build and install the system. The following commands demonstrate making and installing from the reveal directory:
mkdir build
cd build
cmake ..
make
sudo make install
Note: The reveal build system will allow a choice to install client only, server only, or the full system. By default, the full system is built and installed. To limit an installation, disable either INSTALL_REVEAL_SERVER or INSTALL_REVEAL_CLIENT in the cmake configuration.
Refer to the Reveal Site Wiki for installation instructions on installing and running the Visualization service.
Reveal uses a number of environment variables to determine locations. A setup file is written with these environment variables and their default values during configuration, build and installation to the reveal build directory. The same file is also installed to a system directory (typcally /usr/local/share/reveal). The following is a sample of the setup file containing default values
export REVEAL_SAMPLES_URI=http://localhost:20700
export REVEAL_SAMPLES_DATABASE_NAME=reveal_samples
export REVEAL_DATABASE_URI=http://localhost:27017
export REVEAL_MONITOR_PORT=20702
export REVEAL_PACKAGES_PATH=$HOME/reveal_packages
export REVEAL_SIMS_PATH=$HOME/reveal_sims
export REVEAL_BIN_SEARCH_PATH=/usr/local/bin:/usr/bin
export REVEAL_LIB_SEARCH_PATH=/usr/local/lib:/usr/lib
Before running a Reveal connected process, source the setup file in each console that runs a Reveal process.
REVEAL_SAMPLES_URI specifies the location of the Reveal samples server and the port on which it accepts connections. For a samples server instance, only the port will be observed and the port will define which port the server will open to listen on. For a samples client instance, the host and port will be used when building a connection string.
REVEAL_SAMPLES_DATABASE_NAME specifies the database with which the samples server should interact. A database of the same name must have been created within the mongo instance for the server to connect (refer to Database Configuration for details). For client-end systems, this variable is unused.
REVEAL_DATABASE_URI specifies the location of the Reveal database and the port on which it accepts connections. On the database-end server, the specified port must match the mongo configuration. On the server-end system, the host and port specify the connection string the server will use to connect to the Reveal database. On a client-end system, this environment variable is irrelevant.
REVEAL_MONITOR_PORT specifies the local port on which the Reveal client communicates with a simulator. The monitor port is an inprocess port for intercommunication between simulator and client. Commands to control the simulator are broadcast from the client to the simulator and simulation state is broadcast from the simulator to the client on this port. This variable is only relevant on client-end systems.
REVEAL_PACKAGES_PATH specifies the local directory where packages are installed. On a server-end system, this variable is used to locate locally installed analyzers. On a client-end system, this variable specifies the directory where the pre-downloaded packages which contain the scenario definitions and configurations are maintained.
REVEAL_SIMS_PATH specifies the local directory where simulator interfaces for Reveal are installed. On a server-end system, this variable is not currently in use (although, it may be if automatic distribution is supported in the future). On a client-end system, this variable specifies the directory in which the pre-downloaded simulator interfaces are maintained.
REVEAL_BIN_SEARCH_PATH specifies locations where Reveal is to search for installed simulator binaries. The value is a compound path following the same specification as the PATH environment variable. This variable allows Reveal to detect a simulator installed to a nonstandard path; however, the build configurations of individual experiments may still not find the simulator in a nonstandard path.
REVEAL_LIB_SEARCH_PATH specifies locations where Reveal is to search for installed simulator libraries. The value is a compound path following the same specification as the PATH environment variable. This variable allows Reveal to detect a simulator installed to a nonstandard path; however, the build configurations of individual experiments may still not find the simulator in a nonstandard path.
The following environment variables are not currently in use but are included in the setup file. They are intended for future expansion:
REVEAL_ANALYTICS_DATABASE_NAME
REVEAL_ANALYTICS_URI
REVEAL_ANALYZER_PORT
Before running the Reveal server, you must first set up the database, so first refer to the Data Service Installation documentation for installation and configuration information on the backend service.
A utility has been provided that will automatically set up the Reveal database assuming that the backend service is running on the local system. This utility will delete any existing Reveal database and will then build a new database with a compatible schema. It can be used to purge an existing database if necessary. Once Reveal has been successfully installed, at the command line source the setup.sh file and execute the following command:
reveal_db_config
The utility will issue a series of commands that will individually report 'OK' and will overall report 'Success' if the the database is ready for use.
Once the data service is ready, refer to Populating the Database for generating an initial data set.
The database is initially empty; however, Reveal experimentation requires model data to be available. To populate the database, data must be imported using a utility or in the case of a full installation data may be directly inserted. The import utility allows a set of text files to be read into the database while direct insertion issues transactions to the database during simulation.
The reveal_sims interfaces provide a set of helper functions to translate Gazebo data structures into Reveal compatible data structures. As a general rule, controllers should only require linking to the interface in order to export data into a Reveal compatible format. In order to use the data export methods provided, the reveal_sims_gazebo interface must be built before running the scenario in standalone Gazebo.
The reveal_sims_gazebo interface can be built automatically by Reveal even though the initial database is empty. Launch an instance of both the server and client according to the instructions. The client will still step through the necessary steps to build the interface once the simulator is selected from the Simulator menu. Select Gazebo from the menu and allow the system to progress through building the interface. Once the client presents an empty Scenario menu, use Ctrl-C to terminate the client. The interface can now be specified when building and running an example Gazebo scenario.
Scenario data can be imported into the database in two ways, via direct insert or export/import utilities. Direct insertion requires that a package is linked against the reveal database, so the reveal database library must be present (and the underlying service must be running) and the scenario must be run in the simulator outside of Reveal. The export/import utilities use a combination of xml and flat files to allow the generation of data on a remote system or from real-world experiments and then a transfer of data to the data host for import.
The example industrial_arm scenario package supports both direct insert and export/import approaches. The industrial_arm package will only generate data if the DATA_GENERATION cmake variable is ON. If DATA_GENERATION is enabled gazebo_arm_plugin.cpp will generate a set of four files named with the unique scenario identifier and extensions defining the data contained in the file. This set of files can be imported through the test application test-db-importer located in the test/db/ directory. If DATA_GENERATION is enabled then an additional cmake variable DB_DIRECT_INSERT will be available. If DB_DIRECT_INSERT is ON, gazebo_arm_plugin.cpp will link against the reveal database library and the controller will insert data directly into the database forgoing the need to import files in a separate step. Enabling both DATA_GENERATION and DB_DIRECT_INSERT is the easiest way to seed the database with an initial dataset.
Reveal uses a set of environment variables. To facilitate setting up the environment, a setup.sh file was created in the reveal build directory when reveal was built. In any instructions referring to the setup.sh file, the setup.sh file generated into the reveal build directory is assumed.
These instructions assume that the previous instructions for building reveal were followed strictly and that the reveal build directory is a subdirectory of the reveal project directory located in your home directory. The paths to the reveal_sim include directory and build directory must be specified as cmake parameters, so update these paths if the installation of these components is to non-standard locations. To create an initial dataset and populate the database, open a console in the reveal project directory and issue the following commands:
cd packages/industrial_arm/shared
mkdir build
cd build
cmake -DDATA_GENERATION=ON -DDB_DIRECT_INSERT=ON -DREVEAL_SIM_INCLUDE=$HOME/reveal_sims/reveal/sim/gazebo -DREVEAL_SIM_LIBRARY=$HOME/reveal_sims/reveal/sim/gazebo/build/libreveal_sim_gazebo.so ..
make
source $HOME/reveal/build/setup.sh
export GAZEBO_PLUGIN_PATH=$PWD:$GAZEBO_PLUGIN_PATH
export GAZEBO_MODEL_PATH=$PWD/models/sdf:$GAZEBO_MODEL_PATH
gazebo gazebo/gazebo.world
The simulation uses a sampling rate of 0.001s and will run 16 virtual seconds. After the prescribed duration, the simulation will automatically exit. For each timestep, the simulation will create a model solution and a trial and will directly insert these records into the database.
The gazebo.world configuration file can also run the scenario without any Reveal relationship by building the package with DATA_GENERATION off. Executing Gazebo using gazebo.world with DATA_GENERATION off will run the scenario in Gazebo as a normal Gazebo simulation.
The reveal.world configuration file requires Reveal and cannot properly execute outside the Reveal framework. reveal.world is intended to be automatically called by and only by the Reveal client.
manifest.xml defines the set of build products for a given simulator. It is read by reveal when the package is built automatically by the client.
Data export generates a number of files containing the scenario data. Each time the export process is run, a set of four files prefixed by the unique identifier generated for the scenario will be written to the directory. The files will have the extensions scenario, analyzer, solutions, and trials. It is recommended to move (or delete) these files from the directory before running Reveal as the directory is copied to a temporary location for experimentation and the presence of large files will slow the client down when it prepares an experiment.
The file with the scenario extension contains the xml scenario definition and defines the column layout of the flat files matching the file name with the trials and solutions extensions.
The file with the analyzer extension contains the xml analyzer definition.
The trials and solutions files are flat files that contain the sampling data for the experiment where trials contains the state and commands to be issued for a given timestep and solutions contains the state after an integration step is computed.
The models directory contains sdf and urdf directories which contain model definitions in respective formats and are used by the simulation.
To run the server, in a separate console instance source the setup.sh file from the reveal build directory and issue the following command:
reveal_samples_server
If the database has been seeded with sample data, the server should build any registered analyzers first. Registration of analyzers is based on the relative path written into the analyzer database record. The analyzer path is relative to the path specified by the REVEAL_PACKAGE_PATH environment variable. Once any installed analyzers are ready, the server will then enter its main loop and will report that it is listening to indicate that it is ready.
To run the client, in a separate console instance source the setup.sh file in the reveal build directory and issue the following command:
reveal_samples_client
The Reveal client will begin by connecting to the Reveal server.
If the client connects to the server, the user is prompted to choose whether or not to log-in. Reveal supports both registered and anonymous access. In either case, a session will be created to differentiate one access from all others. In the default configuration there will be no users registered in the database, so it is advised to choose NOT to log in for testing. Once the log-in prompt is answered, the client will request authorization from the server.
If authorization is granted, the client will present a menu of the set of scenarios available. Currently there is one sample scenario available, 'grasping a block with an industrial arm', assuming you have followed the instructions under Populating the Database.
After selecting a scenario the client will allow the user to design the experiment. The experimental design consists of selecting a dynamics engine (for Gazebo), setting the time step, setting how many intermediate trials to ignore, and tuning the scenario parameters.
Gazebo currently supports four dynamics engines: ODE, Bullet, DART, and SimBody. When designing a Gazebo experimental configuration, Reveal will prompt the user to select which of these dynamics engines to use. Note: Development has focused primarily on ODE and testing has indicated issues in the interfaces for other dynamics engines which will require additional testing with the current version of Gazebo.
After selecting dynamics, the user is allowed to configure the other Reveal dedicated experimental parameters, 'time step' and 'the number of trials to ignore before resetting to trial state'.
The 'sampling rate' is the rate model data was gathered and 'time step' is the desired integration step size for the current experiment. If the sampling rate is less than or equal to the time step, the client will take one step, submit its solution, and request a new trial from the server matching the virtual time of the solution. If the sampling rate is greater than the time step, the client will take a number of steps up to the time of the next available solution and will then submit its solution and request a new trial from the server matching the virtual time of the solution. Note: The time step must be some factor of the sampling rate.
The 'number of trials to ignore' option allows an experiment to evolve and show divergence over a number of available trial samples. If zero is entered, then every time the client submits a solution, the client will request a trial from the server and then reset simulator state to the received model trial state. If a number greater than zero is entered, the client will submit a solution on the interval prescribed by the 'time step'/'sampling rate' formula but the client will continue to step using the current simulator state until it has ignored the number of trials specified at which point the client will reset simulator state to the most recently received model trial state. This parameter allows a simulation to evolve from a trial and diverge farther from solution data than might otherwise be noticable if the simulation were to be reset each and every trial.
The next prompt will ask the user whether or not they would like to tune the experiment. Currently, either selection will cause the client to begin simulation; however, tuning can be accomplished simply be editing the package directly. This prompt is primarily a reminder for future determination of how the system will interactively support tuning. Several ideas have been discussed including users submitting a document describing tuning and building an interactive, programmatic tuning interface. The first requires the honor system and the second requires extensive development.
After following the prompts, the client copies the package source into a temporary directory, compiles the package and launches the simulation. Once the simulation has completed, the client should prompt the user to choose whether or not to run another experiment. Note: Detecting the signal for simulator termination is somewhat erratic and this menu appears very reliably sometimes and sometimes very irregularly. If the reveal client reports the following:
AL lib: (WW) alcCloseDevice: Releasing context 0xa0add18
The experiment has completed and it is safe to use Ctrl-C to terminate the process with no side effects.