The most flexible way to interact with motion planning at the ROS level is through the GetMotionPlan and ComputePlanningBenchmark services. This is also the most complex way, so if you are looking for something simple that just moves e.g., the arm, to a specified pose or joint state, please see the MoveGroup action. For C++ interfaces, plase see the planninginterface section".

The ROS services for motion planning share most of the request part of the service: the MotionPlanRequest message.

The MotionPlanRequest Message

The content of this message may look intimidating, but most of its fields are optional:

• group_name This is the name of the group to plan for. This member is required and must be a group name defined in the SRDF.
• start_state This is the state to assume the robot starts at. This member does not need to be specified. Joint values that are not set in this message are assumed to be the same as the robot's current state (as specified by the PlanningScene visible to the planner).
• goal_constraints Instead of defining a goal state, goals are specified in a more generic fashion: in terms of constraints. Constraints can be very specific, to defining a bounding box in the joint space of the robot such that only one goal state is included, to being very generic, where a link of the robot (e.g., the end-effector) is required to move to some specified volume of the space. There can be multiple goal constraints specified. Each goal constraint is considered a possible goal. The planner will try to find a path that reaches a state that satisfies at least one of the specified goal constraints. However, all the sub-constraints specified withing a Constraints message must be satisfied. The goal constraints are mandatory, in the sense that some form of goal definition needs to exist, in order for a plan to be initiated.
• path_constraints These are optional constraints that are to be imposed along the solution path. All the states along the solution path must satisfy these constraints. This includes the specified start state, so the caller should make sure that the robot is currently at a state that satisfies the path constraints. This can be easily achieved for example by executing a plan that has the desired path constraints as goal constraints.
• planner_id Usually planning libraries that are used include multiple motion planning algorithms. If the optional planner_id is specified, the library will use the planning algorithm identified by the specified planner_id.
• workspace_parameters When planning for mobile robots, where there are no implicit limits for some of the degrees of freedom (e.g., position in plane or space), the workspace parameters define a bounding box -- a volume that limits the space in which the robot can plan and operate. This is an axis aligned representation, for efficiency reasons. If the volume for planning needs to be restricted to more complex shapes, a PositionConstraint can be used as a path constraint.
• num_planning_attempts Normally, when one motion plan is needed, one motion plan is computed. However, for algorithms that use randomization in their execution, it is likely that different planner executions will produce different solutions. Setting this parameter to a value above 1 has the effect of running that many additional motion plans (perhaps in parallel), and obtaining multiple solutions. The shortest solution is then reported by the planner as the final result.
• allowed_planning_time Each planner execution needs a time limit; this parameter defaults to 1 if not specified, and indicates the number of seconds allowed to plan.

The GetMotionPlan service

The request to this service is simply a motion planning request as described above. The result includes the following members:

• trajectory These are the points along the solution path. Only joints for the group planned for are included.
• trajectory_start The computed thajectory does not include all robot joints; as such, the trajectory is not complete, since we do not know the values for the links that were not included in planning. For this reason, the full robot state is included. This state is usually the robot's current state (as in the planning scene set for planning), but with values specified by the start_state overwritten.
• planning_time This is the amount of time the planner took to compute the motion plan
• error_code The status code reported after planning.

The ComputePlanningBenchmark service

This service is used for computing benchmarks for various motion planners

(i'm still changing this service after the discussion on Mar 15; will finish this section later)