Only released in EOL distros:   electric fuerte groovy

Overview (e-turtle)

A number of changes have been made to the planning_environment. Details to follow, but much of the information on diamondback no longer holds.

Overview (diamondback)

The planning_environment is a library/ROS node that allows users to instantiate robot models and collision models based on data from the parameter server with minimal user input. Additionally, state information for both robot models and collision environments can be monitored.

Planning_environment constructs a model of the robot through the URDF and will update the current state of the robot using joint information. Planning_environment will also listen to range sensor data, constructing a collision space to be used for checking collision between the robot and the environment. Other objects can be added to the collision space as well.

The primary purpose of the planning environment is to allow for checking whether states and trajectories are safe or unsafe due to violating constraints, joint limits, or causing the robot to collide with itself of the environment. The primary interface to the planning_environment is through the environment_server which is a ROS node providing all the topic and service functionality.

The ROS API for this node is explained in detail below.

ROS API

API stability

• The ROS API is REVIEWED but UNSTABLE
• The C++ API is UNREVIEWED and UNSTABLE

Services offered

Utility services

These are the services that planning environment offers for performing utility functions like figuring out all the joints in a group.

get_joints_in_group (planning_environment_msgs/GetJointsInGroup)

• This service gives access to the joints in a group as specified in the robot_description_planning/groups. E.g., the group right_arm contains the joints: r_shoulder_pan_joint r_shoulder_lift_joint r_upper_arm_roll_joint r_elbow_flex_joint r_forearm_roll_joint r_wrist_flex_joint r_wrist_roll_joint

get_robot_state (planning_environment_msgs/GetRobotState)

• This service provides the complete state of the robot as a motion_planning_msgs/RobotState message. This message contains information about the joint positions of all the (real) joints on the robot.

Monitoring configuration services

These are the services that allows for configuring the monitoring behavior in the planning environment.

set_constraints (planning_environment_msgs/SetConstraints)

• This service allows configuration of goals and constraints for monitoring.

Monitoring/Checking services

These are the services that the planning environment provides to checks plans, check whether goal states have been reached, and for monitoring trajectories.

get_environment_safety (planning_environment_msgs/GetEnvironmentSafety)

• This service checks whether is the environment is safe for operation. This service could be used, for example, to warn if state messages have not been received from the robot recently or if sensor messages are outdated, making the environment unsafe for operation.

get_execution_safety (planning_environment_msgs/GetExecutionSafety)

• This services provides checking of trajectories as provided by motion_planning_msgs/JointTrajectory are safe.

get_trajectory_validity (planning_environment_msgs/GetJointTrajectoryValidity)

• Allows checking if the specified plan is valid, i.e. whether it satisfies the goal and path constraints AND is not in collision at any point along the path.

Collision space information

Services for getting information about the current state of the collision space.

~/get_objects_in_collision_map (planning_environment_msgs/GetObjectsInCollisionMap)

• Returns a list of objects and attached objects currently in the collision space.

~/get_current_allowed_collision_matrix (planning_environment_msgs/GetAllowedCollisionMatrix)

• Returns the current matrix of whether collision checks will be performed for different pairs of links, attached objects, and objects.

~/set_allowed_collisions (planning_environment_msgs/SetAllowedCollisions)

• (FOR TESTING/DEBUGGING PURPOSES ONLY) Sets the default collision matrix until reverted. Better practice is to use allowed collision operations in each call.

~/revert_allowed_collisions (std_srvs/Empty)

• (FOR TESTING/DEBUGGING PURPOSES ONLY) Reverts the default collision matrix when set.

Parameter configuration

~robot_description (string, default: "robot_description")

• The name of the ROS parameter that contains the string representation of the URDF for the robot.

~allow_valid_collisions (bool, default: false)

• If true and allowable contact regions exist, collisions inside the allowed contact regions will be ignored.

~collision_map_safety_timeout (double, default: 0.0)

• If > 0.0 seconds, the node will expect the collision map to be published regularly within this interval of time. If the node has not received a collision map within the interval it will declare all states and trajectories unsafe.

~joint_states_safety_timeout (double, default: 0.0 (seconds))

• If > 0.0 seconds, the node will expect the joint states to be published more frequently than this safety timeout. If the node has not received joint states within the interval it will declare all states and trajectories unsafe.

~group (string, default: "")

• Sets the group name of joints to monitor. See YAML configuration for more information on groups.

~global_frame (string, default: "")

• If the global frame is specified to be the empty string, the root frame in which all monitoring will take place is the root link of the robot ("base_link" for the robot). Otherwise, this parameter can be set to a fixed frame in the world (e.g. "odom_combined", "map")

~tf_safety_timeout (double, default: 0.0 (seconds))

• The expected interval between TF updates. If global_frame is set to a valid fixed frame (and not to its default of an empty string), THEN if the node has not received TF updates within this interval it will declare all states and trajectories unsafe.

~contacts_to_compute_for_display (int, default: 1)

• If no allowed collisions are set as part of a state or trajectory safety query, then this parameter sets the number of contacts that will be broadcast for display. The minimum value is 1.

~contacts_to_compute_for_allowable_contacts_test (int, default: 10)

• If allowable contacts are set as part of a state or trajectory safety query, this parameter specifies the number of contacts that will be checked for violating allowed contacts. If all checked contacts occur within the allowable contact region, contact is not reported.

~use_collision_map (bool, default: true)

• If true, collision map information is expected and used in the collision space.

~velocity_history_size (int, default: 20)

• The velocity history is used to determine whether or not the robot is moving. If the sum of joint velocities is less than .001 when summed over the velocity history, and the environment server is monitoring a trajectory where the robot should be moving, it will declare the trajectory failed.

<robot_description_name>_planning/groups (XmlRpc::TypeArray, default: <empty>)

• Contains an array of named sets of joints and links. For more information see YAML configuration. Note that <robot_description_name> will be replaced with either robot_description or whatever value has been remapped for robot_description.

<robot_description_name>_collision/robot_padd (double, default: .01)

• The value for a padding to add around the collision bodies associated with all links in the collision space. Note that <robot_description_name> will be replaced with either robot_description or whatever value has been remapped for robot_description.

<robot_description_name>_collision/robot_scale (double, default: 1.0)

• The value for the scale for each collision associated with each link in the collision space. Note that <robot_description_name> will be replaced with either robot_description or whatever value has been remapped for robot_description.

<robot_description_name>_collision/default_collision_operations (XmlRpc::TypeArray, default: <empty>)

• A list of collision operation for enabling and disabling self collision checks between robot links. For more information see YAML configuration. Note that <robot_description_name> will be replaced with either robot_description or whatever value has been remapped for robot_description

~object_padd (double, default: 0.02)

• The padding to use for the known objects when clearing the point cloud

~pointcloud_padd (double, default: 0.02)

• Additional padding to be used when collision checking against pointclouds (the padding around the robot links defined in <robot_description_name>_collision/robot_padd will still be used)

~joint_state_cache_allowed_difference (double, default: 0.25)

• Maximum allowed past/future time difference between a requested timestamp and the cached joint states. Requests outside the cache timestamp limits and within the time difference allowed by this parameter will return the closest cache limit (no extrapolation).

~bounding_planes (string, default: 0 0 1 -0.01)

• Collision environment bounding planes. It consists of a sequence of plane equations specified as "a1 b1 c1 d1 a2 b2 c2 d2 ..." where each plane is defined by the equation ax+by+cz+d=0

ROS topics

Published Topics

environment_server_collision_markers (visualization_msgs/Marker)

• if the show_collisions and compute_contacts parameters are set to true, visualization markers marking points of detected collision will be published. The naming convention for the markers is that a marker will have a namespace indicating the first link or attached body that is in contact followed by a "+", and then the link, object, or attached body that is also in collision. An arbitrary sequenced number will be passed as the id number.

allowed_contact_regions_array (visualization_msgs/MarkerArray)

• This is a visual representation of the allowed contacts regions. The allowed contacts regions are regions in space where certain links of the robot may be allowed to touch objects.

Subscribed Topics

collision_map (mapping_msgs/CollisionMap)

• This is the topic on which the server listens for collision map information. If expected duration for this topic is set greater than 0.0 (see ROS params above), the node will wait for this topic to be published.

collision_map_update (mapping_msgs/CollisionMap)

• This is the topic on which the server listens for incremental collision map information. Incremental information could be published, e.g., by using single laser scans.

Tutorials

Tutorials for this package are available in the motion_planning_environment stack tutorials.