Contents
Overview
Controller for differential drive wheel systems. Control is in the form of a velocity command, that is split then sent on the two wheels of a differential drive wheel base. Odometry is computed from the feedback from the hardware, and published.
Velocity commands
The controller works with a velocity twist from which it extracts the x component of the linear velocity and the z component of the angular velocity. Velocities on other components are ignored.
Hardware interface type
The controller works with wheel joints through a velocity interface.
Other features
Realtimesafe implementation.
 Odometry publishing
 Taskspace velocity, acceleration and jerk limits
 Automatic stop after command timeout
Mathematical Background
The illustration on the right shows a sketch of a differential drive wheeled robot. In this sketch, the following notation applies.
 linear velocity (Velocity Command, see chapter 1.1)
 angular velocity by which the robot rotates (Velocity Command, see chapter 1.1)
and  global coordinate system
and  locale body coordinate system
 angle of robot with respect to global coordinate system
 radius of the wheels
 width of the vehicle
 instantaneous center of rotation
,  ground contact speed of left and right wheel
,  angular velocity of left and right wheel
Using the kinematic model (see here), the diff_drive_controller calculates the left and right angular velocity to:
and
.
Robots



ROS API
Description
The controller main input is a geometry_msgs::Twist topic in the namespace of the controller.
Subscribed Topics
cmd_vel (geometry_msgs/Twist) Velocity command.
Published Topics
odom (nav_msgs/Odometry) Odometry computed from the hardware feedback.
 Transform from odom to base_footprint
 Available when "publish_cmd" parameter is set to True. It is the Twist after limiters have been applied on the controller input.
Parameters
left_wheel (string  string[...]) Left wheel joint name or list of joint names
 Right wheel joint name or list of joint names
 Diagonal of the covariance matrix for odometry pose publishing
 Diagonal of the covariance matrix for odometry twist publishing
 Frequency (in Hz) at which the odometry is published. Used for both tf and odom
 Multiplier applied to the wheel separation parameter. This is used to account for a difference between the robot model and a real robot.
 Multiplier applied to the wheel radius parameter. This is used to account for a difference between the robot model and a real robot.
 Allowed period (in s) allowed between two successive velocity commands. After this delay, a zero speed command will be sent to the wheels.
 Base frame_id, which is used to fill in the child_frame_id of the Odometry messages and TF.
 Whether the controller should limit linear speed or not.
 Maximum linear velocity (in m/s)
 Minimum linear velocity (in m/s). Setting this to 0.0 will disable backwards motion. When unspecified, max_velocity is used.
 Whether the controller should limit linear acceleration or not.
 Maximum linear acceleration (in m/s^2)
 Minimum linear acceleration (in m/s^2). When unspecified, max_acceleration is used.
 Whether the controller should limit linear jerk or not.
 Maximum linear jerk (in m/s^3).
 Whether the controller should limit angular velocity or not.
 Maximum angular velocity (in rad/s)
 Minimum angular velocity (in rad/s). Setting this to 0.0 will disable counterclockwise rotation. When unspecified, max_velocity is used.
 Whether the controller should limit angular acceleration or not.
 Maximum angular acceleration (in rad/s^2)
 Minimum angular acceleration (in rad/s^2). When unspecified, max_acceleration is used.
 Whether the controller should limit angular jerk or not.
 Maximum angular jerk (in m/s^3).
 Publish to TF directly or not
 The distance of the left and right wheel(s). The diff_drive_controller will attempt to read the value from the URDF if this parameter is not specified
 Radius of the wheels. It is expected they all have the same size. The diff_drive_controller will attempt to read the value from the URDF if this parameter is not specified.
 Name of frame to publish odometry in.
 Publish the velocity command to be executed. It is to monitor the effect of limiters on the controller input.
 Setting this to true will allow more than one publisher on the input topic, ~/cmd_vel. Setting this to false will cause the controller to brake if there is more than one publisher on ~/cmd_vel.
 The number of velocity samples to average together to compute the odometry twist.linear.x and twist.angular.z velocities
Controller configuration examples
Minimal description
mobile_base_controller: type: "diff_drive_controller/DiffDriveController" left_wheel: 'wheel_left_joint' right_wheel: 'wheel_right_joint' pose_covariance_diagonal: [0.001, 0.001, 1000000.0, 1000000.0, 1000000.0, 1000.0] twist_covariance_diagonal: [0.001, 0.001, 1000000.0, 1000000.0, 1000000.0, 1000.0]
Complete description
mobile_base_controller: type : "diff_drive_controller/DiffDriveController" left_wheel : 'wheel_left_joint' right_wheel : 'wheel_right_joint' publish_rate: 50.0 # default: 50 pose_covariance_diagonal : [0.001, 0.001, 1000000.0, 1000000.0, 1000000.0, 1000.0] twist_covariance_diagonal: [0.001, 0.001, 1000000.0, 1000000.0, 1000000.0, 1000.0] # Wheel separation and diameter. These are both optional. # diff_drive_controller will attempt to read either one or both from the # URDF if not specified as a parameter wheel_separation : 1.0 wheel_radius : 0.3 # Wheel separation and radius multipliers wheel_separation_multiplier: 1.0 # default: 1.0 wheel_radius_multiplier : 1.0 # default: 1.0 # Velocity commands timeout [s], default 0.5 cmd_vel_timeout: 0.25 # Base frame_id base_frame_id: base_footprint #default: base_link # Velocity and acceleration limits # Whenever a min_* is unspecified, default to max_* linear: x: has_velocity_limits : true max_velocity : 1.0 # m/s min_velocity : 0.5 # m/s has_acceleration_limits: true max_acceleration : 0.8 # m/s^2 min_acceleration : 0.4 # m/s^2 has_jerk_limits : true max_jerk : 5.0 # m/s^3 angular: z: has_velocity_limits : true max_velocity : 1.7 # rad/s has_acceleration_limits: true max_acceleration : 1.5 # rad/s^2 has_jerk_limits : true max_jerk : 2.5 # rad/s^3
Skid steer
The diff_drive_controller allows for skid steer driving with the geometry_msgs/Twist command interface however it doesn't support direct skid commands.
The current implementation allows you to register multiple wheels per side and will average those wheel positions in its odometry calculations. For more info read the code and issue.
Multiple wheels per side example from Jackal.
jackal_velocity_controller: type: "diff_drive_controller/DiffDriveController" left_wheel: ['front_left_wheel', 'rear_left_wheel'] right_wheel: ['front_right_wheel', 'rear_right_wheel'] publish_rate: 50 pose_covariance_diagonal: [0.001, 0.001, 1000000.0, 1000000.0, 1000000.0, 0.03] twist_covariance_diagonal: [0.001, 0.001, 0.001, 1000000.0, 1000000.0, 0.03] cmd_vel_timeout: 0.25 # Odometry fused with IMU is published by robot_localization, so # no need to publish a TF based on encoders alone. enable_odom_tf: false # Wheel separation and radius multipliers wheel_separation_multiplier: 1.5 # default: 1.0 wheel_radius_multiplier : 1.0 # default: 1.0 # Velocity and acceleration limits # Whenever a min_* is unspecified, default to max_* linear: x: has_velocity_limits : true max_velocity : 2.0 # m/s has_acceleration_limits: true max_acceleration : 20.0 # m/s^2 angular: z: has_velocity_limits : true max_velocity : 4.0 # rad/s has_acceleration_limits: true max_acceleration : 25.0 # rad/s^2
Further reading
In addition to the robots addressed in chapter 2, tutorials for the application of the diff_drive_controller should be briefly mentioned.
A basic understanding of the implementation of ros_control and its interaction with the hardware_interface is explained in this post.
An overview of the diff_drive_controller and its integration into ros_control can be found in the DiffBot Base Package tutorial.
A detailed description of the specific execution and application of the diff_drive_controller can also be found in the DiffBot Base Package.
In the Jackal Robot, the diff_drive_controller is also applied, and the control commands ( and ) are being retrieved in the hardware_interface and forwarded to the corresponding drives.