DRC/UserGuide


 * 1) DRCSim User Guide

DRCSim is a collection of models, environments, plugins, and tools that customize the Gazebo simulator for use in the DARPA Robotics Challenge (DRC). Gazebo contains general simulation capabilities and DRCSim includes the robots, objects, and code that are specific to the DRC. DRCSim is versioned and released independently of Gazebo. Releases are recorded in the change log and future plans are recorded in the roadmap.


 * 1) Installation

Full installation instructions

Quickstart for binary installation on Ubuntu 12.04 (precise):

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu precise main" > /etc/apt/sources.list.d/ros-latest.list' sudo sh -c 'echo "deb http://packages.osrfoundation.org/drc/ubuntu precise main" > /etc/apt/sources.list.d/drc-latest.list' wget http://packages.ros.org/ros.key -O - | sudo apt-key add - wget http://packages.osrfoundation.org/drc.key -O - | sudo apt-key add - sudo apt-get update sudo apt-get install drcsim

Note that the first four steps are only needed the first time you install; after that, the `apt-get` calls are sufficient.


 * 1) Setup

Before using DRCSim, you should configure your shell with the provided shell setup file

source /usr/share/drcsim/setup.sh

You must load this setup file in every shell from which you're using DRCSim. You may find it convenient to add the `source` line to your default shell configuration (e.g., `~/.bashrc`). No noise added.
 * 1) Starting and stopping DRCSim

It's easiest to launch DRCSim using roslaunch. DRCSim includes several roslaunch files that bring up the simulator in various configurations (see below for details on each launch file).


 * 1) Environment variables

The following environment variables affect the operation of DRCSim:


 * `VRC_CHEATS_ENABLED`: if this variable is set to `1`, then the development aids (aka cheats) listed below in the ROS API are enabled. Otherwise (including if the variable is not set to anything), the development aids are not enabled.
 * [ROS environment variables](http://ros.org/wiki/ROS/EnvironmentVariables)
 * [Gazebo environment variables](http://gazebosim.org/user_guide/started__components__env.html)


 * 1) Starting

To bring up the default DRCSim configuration (Atlas robot with no hands in an empty world):

roslaunch atlas_utils atlas.launch


 * 1) Stopping

To stop the DRCSim after having launched it with `roslaunch`, press Ctrl-C in the terminal where you executed the `roslaunch` command. Shutting down can take several seconds; wait until you see that `roslaunch` has exited and returned to your shell prompt.

It's important to stop DRCSim in this way, by killing `roslaunch`. If you stop it in other ways (e.g., existing from the Gazebo GUI), you might leave other processes running that can cause problems with future simulation sessions.


 * 1) Launch files

Listed below are `roslaunch` files with which users are recommended to experiment.

Unless noted otherwise, the simulation will start with gravity disabled for 10 seconds to allow the controllers to initialize; after that gravity is enabled and the robot is standing on the ground with full dynamics.


 * 1) Launch file arguments

Unless otherwise noted, each launch file accepts the following roslaunch arguments:


 * `gzname` : which executable to invoke when running Gazebo. The default is `gazebo`, which brings up both the server and the GUI client.  Other valid values are: `gzserver`, which brings up only the server (no GUI client; useful for running on remote machines and for testing) and `gzclient`, which only brings up the GUI client (rarely useful).
 * `gzworld`: which `.world` file to pass to Gazebo on startup. The default varies with each launch file.  For example, the default world for `atlas_sandia_hands.launch` is `atlas_sandia_hands.world`.  This option is useful when you want the ROS configuration defined in a launch file but want to override the world file that's used.

E.g., to run the robot with Sandia hands without the client GUI (e.g., on a cloud machine):

roslaunch atlas_utils atlas_sandia_hands.launch gzname:=gzserver


 * 1) General-purpose launch files

* Robot: Atlas with no hands * Environment: empty world (just ground plane)
 * `atlas_utils/launch/atlas.launch`. This is the default configuration, useful for experimenting with the robot on its own.

* Robot: Atlas with Sandia hands * Environment: empty world (just ground plane)
 * `atlas_utils/launch/atlas_sandia_hands.launch`. This is a simple environment that includes Atlas with the Sandia Hands.

* Robot: Atlas with Sandia hands * Environment: ground plane with drivable DRC Vehicle and firehose standpipe. * Tutorials: Using the VRC Plugin to tele-operate the DRC Vehicle,  Using the VRC Plugin with Atlas and the DRC Vehicle
 * `atlas_utils/launch/atlas_drc_vehicle_fire_hose.launch`. This environment includes Atlas, a drivable DRC Vehicle, and the standpipe for a firehose.

* Robot: Atlas with no hands * Environment: ground plane with drivable golf cart and firehose standpipe. * Tutorials: Using the VRC Plugin to tele-operate the Golf Cart,  Using the VRC Plugin with Atlas and the Golf Cart
 * `atlas_utils/launch/atlas_golf_cart_fire_hose.launch`. This environment includes Atlas, a drivable golf cart, and the standpipe for a firehose.

* Robot: Atlas with no hands * Environment: heightmap-based terrain, controllable golf cart, large building (power plant), hose and standpipe.
 * `atlas_utils/launch/drc_sim_v0.launch`. This contains a first draft of some elements of the VRC.  None of these elements are final, but may be useful for experiments.


 * 1) VRC Qualification launch files

* Robot: Atlas with Sandia hands. * Environment: Starting pen followed by a series of gates to walk through, progressing from flat ground to steps, ramps, and small obstacles. (UNDER CONSTRUCTION) * Robot: Atlas with Sandia hands. * Environment: Table with cordless drill that is to be moved into a bin. * Note: The robot's hip joint is pinned to the world, removing the need to balance.
 * `atlas_utils/launch/qual_task_1.launch`. The environment that will be used for VRC Qualification Task 1: walking.
 * `atlas_utils/launch/qual_task_2.launch`. The environment that will be used for VRC Qualification Task 2: manipulation.

* Robot: Atlas with Sandia hands. * Environment: ??
 * `atlas_utils/launch/qual_task_3.launch`. The environment that will be used for VRC Qualification Task 3: ??.

* Robot: Atlas with Sandia hands. * Environment: ??
 * `atlas_utils/launch/qual_task_4.launch`. The environment that will be used for VRC Qualification Task 4: ??.


 * 1) VRC launch files

* Robot: Atlas with Sandia hands. * Environment: Starting pen followed by utility vehicle that must be driven along a road.
 * `atlas_utils/launch/vrc_task_1.launch`. An environment of the type that will be used for VRC Task 1: driving.

* Robot: Atlas with Sandia hands. * Environment: Starting pen followed by a series of gates to walk through, progressing from flat ground increasingly challenging terrain.
 * `atlas_utils/launch/vrc_task_2.launch`. An environment of the type that will be used for VRC Task 2: walking.

* Robot: Atlas with Sandia hands. * Environment: Table with a hose that is to be connected to a spigot.
 * `atlas_utils/launch/vrc_task_3.launch`. An environment of the type that will be used for VRC Task 3: manipulation.


 * 1) ROS APIs

The DRC Simulation exposes a set of ROS APIs for users to develop with. Doxygen documentation can be found in the [DRCSim API page](http://gazebosim.org/drc/api/).


 * 1) Published topics

The following data are published by the DRC Simulator.

Notes:

* [1] The physical Multisense-SL device has some limitations regarding how many streams of data it can provide simultaneously due to available network bandwidth. drcsim does not implement the corresponding logic to provide matching behavior. If you want to ensure that your code will transfer directly to hardware, you should live within the constraints of the hardware when working in simulation. Having said that, it is likely that drcsim will provide smaller images, at a lower frame rate than the physical device because of CPU limitations in stereo processing (the physical device does stereo in an FPGA and so does not suffer from this limitation).


 * 1) Subscribed topics

The following commands are subscribed by the DRC Simulator.


 * 1) ROS Services

The following ROS services are subscribed to by the DRC Simulator.

/atlas/get_joint_damping atlas_msgs/GetJointDamping New in DRCSim 2.6.0. Get viscous joint damping coefficients for Atlas. Resulting array of damping_coefficients has 28 elements, one per joint, and the order of joints can be found in atlas_msgs/AtlasState

/atlas/atlas_filters atlas_msgs/AtlasFilters New in DRCSim 2.6.0. Control position and/or velocity filtering (implemented in a plugin running inside simulation at 1KHz).

Multisense-SL sensor head

/multisense_sl/camera/(various) See stereo_image_proc Various dynamic_reconfigure services are provided to allow configuration of stereo image processing. For more details on the various parameters and services offered by the stereo_image_proc, please see stereo_image_proc documentation.

Sandia hands

/sandia_hands/set_joint_damping atlas_msgs/SetJointDamping Set viscous joint damping coefficients for both robot's left hand (l_hand) and right hand (r_hand). The first 24 of the 28 element-long input array damping_coefficients are used, one per joint, and the order of joints can be found here. Joint damping coefficients can be in the range of 1.0 Nms/rad to 30.0 Nms/rad.

/sandia_hands/get_joint_damping atlas_msgs/GetJointDamping Get viscous joint damping coefficients for both robot's left hand (l_hand) and right hand (r_hand). The first 24 of the 28 element-long damping_coefficients will be filled, one per joint, and the order of joints can be found here.

/sandia_hands/l_hand/simple_grasp /sandia_hands/r_hand/simple_grasp sandia_hand_msgs/SimpleGraspSrv Command simple grasps to left hand (l_hand) and right hand (r_hand). Valid values for the name field are: "cylindrical", "spherical", and "prismatic". No guarantees are provided about the capabilities of these grasps.

Development aids (not available during competition)

/gazebo/pause_physics std_msgs/Empty Pauses Gazebo.

/gazebo/unpause_physics std_msgs/Empty Unpauses Gazebo.

/gazebo/reset_simulation std_msgs/Empty Resets simulation.

/gazebo/reset_models std_msgs/Empty Resets model poses in Gazebo.


 * 1) Controllers
 * Note: Under construction, details may change drastically in the next few iterations.**


 * 1) Atlas Per-Joint Servo Controllers

At the lowest level, on every simulation update at 1kHz, joint torque is computed based on the following formula:

effort_commanded = k_effort * (  kp_position     * ( position - measured_position )       +   ki_position     * 1/s * ( position - measured_position ) +   kd_position     * s * ( position - measured_position ) +   kp_velocity     * ( velocity - measured_velocity )     +   effort ) + (1 - k_effort) * effort_bdi_controller

Note that the `kp_velocity` term is subject to special treatment that is detailed in the following section.


 * 1) High Bandwidth Joint Velocity Implicit Damping via kp_velocity

A high bandwidth viscous damping mechanism is provided to mitigate the noise in joint velocity measurements. The viscous damping coefficient at each Atlas joint can be set by the `kp_velocity` gain in the AtlasCommand message and is passed to the ODE solver as an implicit damping coefficient, which improves controller stability. The `kp_velocity` gain will be truncated to the range specified in [ROS service section](http://gazebosim.org/w/index.php?title=DRC/UserGuide#ROS_Services). Further details on the implementation can be seen in the source code [AtlasPlugin.cpp:2360-2436](https://bitbucket.org/osrf/drcsim/src/aec75e352ee235254441b5cb9b870a7c67bc68d1/ros/atlas_msgs/AtlasPlugin.cpp?at=drcsim_2.6#cl-2360).


 * 1) Boston Dynamics Atlas Simulation Behavior Library (AtlasSimInterface)

The AtlasSimInterface library populates the feed-forward force command (`effort_bdi_controller`) in the per-joint controllers. See [Controller ROS API section](http://gazebosim.org/wiki/DRC/UserGuide#Controller_ROS_API) for hooks to call into the behavior library.

Updates regarding release state and available behaviors will be detailed in the [ChangeLog](http://gazebosim.org/wiki/DRC/Change_log) and [RoadMap](http://gazebosim.org/wiki/DRC/Roadmap).

There is some initial [API documentation](http://gazebosim.org/drc/api/atlas_interface/index.html) for the underlying behavior library. The ROS interface is a pretty thin wrapper around the C++ library API.


 * 1) AtlasSimInterface Behaviors

Behaviors are controller states that govern which joints are controller-governed, and which are user-governed. The neck joint, unless otherwise stated, is user-controlled.

Behavior changes are controlled by publishing to the 'atlas_sim_interface_command' topic, or are controlled automatically. Examples of automatic changes include switching to Freeze when the robot starts to fall or reverting to stand if enough steps weren't provided in the walk behavior. Sometimes, a requested behavior will not be possible as determined by the controller and will be ignored.

* **User**: All joints controlled by performer (through the per-joint servo controllers). * **Stand**: Statically stable stand. This is the "hub" mode, entry and termination into other behaviors. * **Walk**: Dynamically stable walking using approximate step locations. * **Step**: Slow walking with precise step locations, statically stable between steps. * **Manipulate**: Statically stable stand, but with upper body joints available for performer control to enable tool use and environment interaction. * **Freeze**: For falling, when other behaviors have no chance of working. * **StandPrep**: Initialization behavior for entering Stand.

Below is the behavior transition diagram:




 * 1) Stand

Stand is a statically stable stand, and the robot will attempt to maintain balance in light of small pushes, inclines, or other applied forces.

The Stand behavior is the central behavior, and all behavior transitions, except to User and Freeze, occur through Stand. To enter stand, the robot must be mostly upright with no appreciable linear or angular velocity. For simulation startup, StandPrep puts the robot into a suitable configuration.


 * 1) Walk

Walk is a dynamic walking behavior that is robust to small ground height and slope disturbances.

A walk command in the 'Command' message requires four steps specified in 'walk_params.step_queue' with the following:

* step_index: Which step in the Walk this step data is for. * foot_index: Which foot (0 for left, 1 for right). Will switch to Stand mode if two consecutive steps specify the same foot. * duration: How long the step should take. * pose: Where to put the foot, in Atlas world frame. Only yaw is used from the orientation quaternion.

The controller requires a queue of four steps to execute a stable walk. As few as two steps may be used, but it will be less stable and may switch to a Stand behavior. The step_queue can be re-specified while the current queue is executed, but it may result in instability. The next four steps needed of a longer trajectory can be determined by observing the 'walk_feedback.next_step_index_needed' field of the 'atlas_sim_interface_state' topic.

Once a foot has been lifted, the step pose cannot be changed. The Walk behavior will do its best to follow the step data, but it may have to modify steps to fit within constraints, or maintain stability. Observing the 'walk_feedback.step_queue_saturated' in the 'atlas_sim_interface_state' can provide insight into whether a trajectory should be replanned.


 * 1) Step

Step is a quasi-static walking behavior that will realize better foot placement accuracy than walk, but is still subject to kinematic constraints.

A step command is specified in the 'step_params.desired_step' of the 'Command' message. If the controller modifies a step to meet constraints, feedback will be provided in the 'step_feedback.desired_step_saturated' of the 'State' message.

The Step behavior has two states that are specified in 'step_feedback.status_flags' of the 'State' message. The step_data in 'desired_step' can be changed when it enters the STEP_SUBSTATE_SWAYING sub-state.


 * 1) Manipulate

Manipulate is similar to stand, except it makes more joints available for user control. The user must set the pelvis orientation, height, and position relative to the center of the feet. The user can control the movement of the back and upper body joints. The controller will be robust to added masses likely to occur during manipulation situations.

Extreme, or quick moves can overwhelm the controller's ability to maintain stability. It is also recommended that the feet be placed with step commands into strong, and stable positions.


 * 1) Freeze

Behaviors automatically enter the Freeze state when it is determined that the robot has entered an unrecoverable state. It prevents the controller from becoming unstable.


 * 1) StandPrep

StandPrep is a special case behavior that assumes the robot is in a 'harnessed' state. It moves the joints into a position that is suitable for stand when gravity is turned on.

Foot points indicated by [foot_pos_est](https://bitbucket.org/osrf/drcsim/src/e7323d090b95fbadcc96c1402b57f9251adc901a/ros/atlas_msgs/msg/AtlasSimInterfaceState.msg?at=default#cl-38) are offset `(0.06 0.0 -0.085) meters (x y z)` in the foot frame for both left/right feet. This value is subject to change (though we have no plans to do so at the moment.)
 * 1) Foot Reference Frames


 * 1) Controller ROS API

The ROS API provides four key topics that are expected to be used in controlling the Atlas robot:

* [`/atlas/atlas_state`](https://bitbucket.org/osrf/drcsim/src/default/ros/atlas_msgs/msg/AtlasState.msg?at=default): This topic provides the user with the current state of all joints, IMU and force torque sensors. * [`/atlas/atlas_command`](https://bitbucket.org/osrf/drcsim/src/default/ros/atlas_msgs/msg/AtlasCommand.msg?at=default): This topic provides set-points and gains for a set of low-level PID controllers that operate on a per-joint basis. (This is a slight extension to `/atlas/joint_command` with addition of PID coefficients, see the message documentation for the control law that is implemented). Users are expected to write higher-level behavior as ROS nodes that command these per-joint controllers to achieve coordinate motion such as balancing and walking. * [`/atlas/atlas_sim_interface_command`](https://bitbucket.org/osrf/drcsim/src/default/ros/atlas_msgs/msg/AtlasSimInterfaceCommand.msg?at=default): The AtlasSimInterface Behavior Library control command can be issued over this ROS topic. * [`/atlas/atlas_sim_interface_state`](https://bitbucket.org/osrf/drcsim/src/default/ros/atlas_msgs/msg/AtlasSimInterfaceState.msg?at=default): Example high-level behavior control can be seen in [this tutorial](http://gazebosim.org/wiki/Tutorials/drcsim/2.4/keyboard_teleop), which utilizes an underlying [demo actionlib server](https://bitbucket.org/osrf/drcsim/src/default/ros/atlas_msgs/actionlib_server.cpp?at=default) that closes the loop on `/atlas/atlas_sim_interface_command` and `/atlas/atlas_sim_interface_state`.


 * 1) Controller Blending

Parameter `k_effort` can be used to switch / blend controller torques from `AtlasCommand` and `AtlasSimInterfaceCommand`. Please see the [Control Mode Switching Tutorial](http://gazebosim.org/wiki/Tutorials/drcsim/2.4/control_mode_switching) for more details on how to switch between servo control mode and AtlasSimInterface Behavior Library control mode.


 * 1) Update Rates

Regarding update rates, we currently expect that:


 * the simulation timestep will be 0.001s (1ms);
 * the update rate for the per-joint controllers running inside Gazebo (the sink for the `/atlas/joint_commands` topic) will be 1KHz (i.e., they will update every simulation timestep); and
 * users will be able to write controllers external to simulation, as ROS nodes, that interact with the per-joint controllers at 200Hz-500Hz (we will narrow this range as we can with performance data).


 * 1) Control Strategies

Regarding control strategies:


 * to implement conventional PID control, set the commanded effort to zero;
 * to implement torque control, set the PID gains to zero (and presumably set the commanded effort to non-zero); and
 * to mix PID control and torque control, command non-zero PID gains and non-zero effort (the resulting torques will be summed).

Control of the Sandia hands is expected to be similar to control of Atlas. Any expected differences will be documented here.
 * 1) Sandia hands


 * 1) Qualifications


 * 1) Extra instructions for late Qualification

IMPORTANT: For teams doing qualifying runs on or after May 17th, 2013, extra steps are required to get your system configured to use the right versions of software and models (the released versions have been updated in preparation for Practice and Competition).

1. Installation: download and manually install specific versions of the code (assuming here that you're working on 64-bit Ubuntu 12.04 (Precise)):

# Install with apt-get to resolve dependencies, then uninstall sudo apt-get update sudo apt-get install -y drcsim sudo apt-get remove -y drcsim gazebo osrf-common sandia-hand # Download specific versions wget http://gazebosim.org/assets/distributions/osrf-common_1.0.6-1~precise_amd64.deb wget http://gazebosim.org/assets/distributions/sandia-hand_5.1.13-1~precise_amd64.deb wget http://gazebosim.org/assets/distributions/gazebo_1.7.3-1~precise_amd64.deb wget http://gazebosim.org/assets/distributions/drcsim_2.5.2-1~precise_amd64.deb # Manually install with dpkg sudo dpkg -i gazebo_1.7.3-1~precise_amd64.deb sudo dpkg -i osrf-common_1.0.6-1~precise_amd64.deb sudo dpkg -i sandia-hand_5.1.13-1~precise_amd64.deb sudo dpkg -i drcsim_2.5.2-1~precise_amd64.deb # Remove any cached models rm -rf ~/.gazebo/models

1. Configuration: point Gazebo at the archived version of the online model database (*do this in every shell you use*):

# Usual setup . /usr/share/drcsim/setup.sh       # Use a special archive of models export GAZEBO_MODEL_DATABASE_URI=http://gazebosim.org/models_vrc_quals/


 * 1) Software Versions


 * Gazebo** 1.7.3


 * DRC Sim** 2.5.2


 * Sandia Hands** 5.1.13


 * OSRF Common** 1.0.6

CloudSim is not used for Qualification.


 * 1) Creating a Qualification Submission


 * 1) Step 1: Record the operator and display videos

Record the operator and display videos following the procedure detailed in the Video Guide.


 * 1) Step 2: Start a Qualification Task


 * Important:** Data is stored in `/tmp/qual_task_{n}`, where {n} is the number of the Qualification task. Old data will be overwritten. Make sure to backup your data between runs.

Launch one of the Qualification tasks using a ROS launch file.


 * 1) Step 3: Perform the Run

Using some combination of teleoperation and autonomy, achieve the task. When you're happy with the run, move onto the next step. The simulation will not stop automatically on task completion.


 * 1) Step 4: Stop a Qualification Task

1. Stop logging

gzlog stop

The simulation will be paused while the buffered log data is flushed and written to the log file. This can take a very long time. In our testing, it can take about as long as the time required for the simulation itself. Once the log file is finished writing, the simulation will resume.

2. **Wait until the last line in the `state.log` file is ``**. This can be verified with:

$ tail -n 1 -f /tmp/qual_task_1/state.log $

3. Quit Simulation using ctrl-c

Verify the existence of two files upon completion of a Qualification task.
 * 1) Step 5: Verify the output

1. A Gazebo state log file, called `state.log` should exist in `/tmp/qual_task_{n}/`, where {n} is the number of the Qualification task. 2. A Qualification score file, called `score.log` should exist in `/tmp/qual_task_{n}/`, where {n} is the number of the Qualification task.


 * 1) Step 6: Validate the output

1. Replay the Gazebo state log file. This will make sure that the data is valid.

gazebo -p /tmp/qual_task_{n}/state.log

2. Inspect the score log file by opening it in your favorite editor.

gedit /tmp/qual_task_{n}/score.log

The contents will contain a header that describes the data. Make sure the data is correct.


 * 1) Step 7: Create a zip file for log submission

Run the `mkqual.bash` script with three command line arguments:

1. The number of the Qualification task: 1, 2, 3 or 4 2. The Gazebo state log file: `/tmp/qual_task_{n}/state.log` 3. The score log file: `/tmp/qual_task_{n}/score.log`

Example:

mkqual.bash 1 /tmp/qual_task_1/state.log /tmp/qual_task_1/score.log

Note that this script may take 5 minutes / 100 MB in state.log.

A new file will be created in your current directory called `vrc_qual_{n}.zip`.

Unzipping this log file should produce the `state.log` and `score.log` files.


 * 1) Step 8: Upload the zip log file to the VRC Portal

Log into the VRC Portal, and submit your log file.

Only the most recent zip file for each qualification task will be kept.

It is a good idea to download the file that was just uploaded and replay the contained log data. This will verify that the upload was successful.


 * 1) Step 9: Upload the videos to the VRC Portal

Create a single file `vrc_video_q{n}.zip`, where `n` is the number of the Qualification task (1, 2, 3 or 4). The zip file should contain the operator and screen videos following the naming convention described in the Video Guide.

Example:

zip vrc_video_q1.zip 2013_04_30_13_31_C001_OCS_Walk_1.mp4 2013_04_30_13_31_C001_OP_Walk_1.mts

Go to the VRC 2013 Videos tab of your VRC Portal team's page, and upload your video.

Only the most recent zip video for each qualification task will be kept.


 * 1) Practice

For instructions on using your cloud-hosted constellation during Practice, see the CloudSim VRC User Guide.