diff --git a/README.asciidoc b/README.asciidoc index 54127dc8c084b6f60918efe3f4c5434b1605fd38..a8ad9a566b2e545daa20a7b0976706532b9ec52f 100755 --- a/README.asciidoc +++ b/README.asciidoc @@ -1,61 +1,38 @@ -= diff_drive -- Differential-Drive Controller += mecanum_drive -- Mecanum-Drive Controller :imagesdir: ./images -This package implements ROS nodes to control and monitor a differential-drive robot. +This package implements ROS nodes to control and monitor a mecanum-drive robot. The package is intended as a lighter-weight solution than the ROS controller framework, albeit with lower performance since it is written in Python. If you need tight, real-time control, you may want -to look at link:http://wiki.ros.org/ros_controllers[ros_controllers], -a C++ package which includes a differential-drive controller that is integrated with -link:http://wiki.ros.org/ros_control[ros_control] and -link:http://wiki.ros.org/controller_manager[controller_manager]. Those controllers are designed -to integrate with hardware in the same process, rather than using topics. Instead, this package +to look at link:http://wiki.ros.org/ros_controllers[ros_controllers]. +Those controllers are designed to integrate with hardware in the same process, rather than using topics. Instead, this package expects to publish the desired motor speeds using standard ROS messages. == Supplied Nodes -* `diff_drive_controller` -- Converts from twist to wheel velocities for motors. -* `diff_drive_odometry` -- Publishes odometry from wheel encoder data. -* `diff_drive_go_to_goal` -- Moves the robot to a goal position. -* `diff_drive_mock_robot` -- Implements a mock differential drive robot, for testing. +* `mecanum_drive_controller` -- Converts from twist to wheel velocities for motors. +* `mecanum_drive_odometry` -- Publishes odometry from wheel encoder data. The nodes in this package are designed with these considerations: -* The node and hardware implementing differential drive should deal only in encoder ticks. +* The node and hardware implementing mecanum drive should deal only in encoder ticks. * Conversions to and from physical coordinates should happen within the nodes in this package. * This package should integrate cleanly with the navigation stack, perhaps with remappings. * Nodes should use standard topic and parameter names used by the navigation stack, but should allow remapping. -== Demo - -To see all the nodes in this package in action, you can launch a demo from ROS. There are no -dependencies other than the standard ROS packages. - - roslaunch diff_drive demo.launch - -This launches _rviz_ as part of the demo, and shows the robot position as a small coordinate system on -a 0.25m grid. In rviz you can move the robot by clicking the _2D Nav Goal_ button in the tools panel at the top. -Then click and drag within the grid to set the robot goal position and heading. The mock robot will move to -that new pose, which you can see by the movement of the robot axes. - -In the demo, both forward and backward movement is allowed, so if the goal position is behind the robot, -it will move backward. You can force the robot to move foward only by setting the parameter `~forwardMovementOnly` -to `true`. == ROS API -=== 1. diff_drive_controller +=== 1. mecanum_drive_controller Listens for desired linear and angular velocity, and publishes corresponding wheel velocities, in encoder ticks per second, required to achieve those velocities. ==== Published Topics -`~lwheel_desired_rate` (std_msgs/Int32):: -Desired left wheel rotation rate, in encoder ticks per second. - -`~rwheel_desired_rate` (std_msgs/Int32):: -Desired right wheel rotation rate, in encoder ticks per second. +`~wheels_desired_rate` (std_msgs/Int16MultiArray):: +Desired [front left, front right, rear left, rear right] wheel rotation rates, in encoder ticks per second. ==== Subscribed Topics @@ -68,7 +45,10 @@ Desired linear and angular velocity. Number of encoder ticks per meter of travel. `~wheel_separation` (double):: -Distance between the two wheels (meters). +Distance between the two wheels on the same axis (meters). + +`~wheel_separation_length` (double):: +Distance between the front and rear axis (meters). `~rate` (int, default: 50):: The rate that the output velocity target messages will be published (Hz). @@ -76,7 +56,7 @@ The rate that the output velocity target messages will be published (Hz). `~timeout_ticks` (int, default: 2):: The number of velocity target messages that will be published after the last twist message is received. -=== 2. diff_drive_odometry +=== 2. mecanum_drive_odometry Listens for wheel movement and rates and publishes the transform between the odom frame and the robot frame. @@ -90,17 +70,8 @@ The transform between the odometry frame and the robot frame. ==== Subscribed Topics -`~lwheel_ticks` (std_msgs/Int32):: -Cumulative encoder ticks of the left wheel. - -`~rwheel_ticks` (std_msgs/Int32):: -Cumulative encoder ticks of the right wheel. - -`~lwheel_rate` (std_msgs/Float32):: -Left wheel rotation rate, in encoder ticks per second. - -`~rwheel_rate` (std_msgs/Float32):: -Right wheel rotation rate, in encoder ticks per second. +`~wheel_ticks` (std_msgs/Int16MultiArray):: +Cumulative encoder ticks of the [front left, front right, rear left, rear right] wheels. ==== Parameters @@ -110,6 +81,9 @@ Number of encoder ticks per meter of travel. `~wheel_separation` (double):: Distance between the two wheels (m). +`~wheel_separation_length` (double):: +Distance between the front and rear axis (meters). + `~rate` (double, default 10.0):: The rate at which the `tf` and `odom` topics are published (Hz). @@ -133,102 +107,3 @@ The min and max value the encoder should output. Used to calculate odometry when `~wheel_high_wrap` (int, default: 0.7 * (encoder_max - encoder_min + 1) + encoder_min):: If a reading is greater than wheel_high_wrap and the next reading is less than wheel_low_wrap, then the reading has wrapped around in the positive direction, and the odometry will be calculated appropriately. The same concept applies for the negative direction. -=== 3. diff_drive_go_to_goal - -Listens for new goal poses and computes velocities needed to achieve the goal. - -==== Published Topics - -`~distance_to_goal` (std_msgs/Float32):: -Distance to the goal position (meters). - -`~cmd_vel` (geometry_msgs/Twist):: -Desired linear and angular velocity to move toward the goal pose. - -==== Subscribed Topics - -`~goal` (geometry_msgs/Pose):: -Desired goal pose. - -==== Parameters - -`~rate` (float, default: 10):: -Rate at which to publish desired velocities (Hz). - -`~goal_linear_tolerance` (float, default: 0.1):: -The distance from the goal at which the robot is assumed to have accomplished the goal position (meters). - -`~goal_angular_tolerance` (float, default: 0.087):: -The difference between robot angle and goal pose angle at which the robot is assumed to have -accomplished the goal attitude (radians). Default value is approximately 5 degrees. - -`~max_linear_velocity` (float, default: 0.2):: -The maximum linear velocity toward the goal (meters/second). - -`~max_angular_velocity` (float, default: 1.5):: -The maximum angular velocity (radians/second). - -`~max_linear_acceleration` (float, default: 4.0):: -The maximum linear acceleration (meters/second^2). - -`~forwardMovementOnly` (boolean, default: true):: -If true, only forward movement is allowed to achieve the goal position. -If false, the robot will move backward to the goal if that is the most -direct path. - -`~Kp` (float, default: 3.0):: -Linear distance proportionality constant. Higher values make the robot accelerate more quickly toward the goal and decelerate less quickly. - -`~Ka` (float: default: 8.0):: -Proportionality constant for angle to goal position. Higher values make the robot turn more quickly toward the goal. - -`~Kb` (float: default: -1.5):: -Proportionality constant for angle to goal pose direction. Higher values make the robot turn more quickly toward the goal pose direction. This value should be negative, per _Autonomous Mobile Robots_. - -The control law for determining the linear and angular velocity to move toward the goal works as follows. Let _d_ be the distance to the goal. Let _a_ be the angle between the robot heading and the goal position, where left is positive. Let _b_ be the angle between the goal direction and the final pose angle, where left is positive. Then the robot linear and angular velocities are calculated like this: - - v = Kp * d - w = Ka*a + Kb*b - -See _Autonomous Mobile Robots, Second Edition_ by Siegwart et. al., section 3.6.2.4. In this code, when the robot -is near enough to the goal, _v_ is set to zero, and _w_ is simply _Kb*b_. - -To ensure convergence toward the goal, _K~p~_ and _K~a~_ must be positive, _K~b~_ must be negative, and _K~a~_ -must be greater than _K~p~_. To ensure robust convergence, so that the robot never changes direction, -_K~a~_ - 5/3*_K~b~_ - 2/pi*_K~p~_ must be greater than zero. - -=== 4. diff_drive_mock_robot - -Implements a simulation of perfect differential drive robot hardware. It immediately follows any speed -commands received with infinite acceleration, and publishes the wheel encoder values and encoder -rates. - -==== Published Topics - -`~lwheel_ticks` (std_msgs/Int32):: -Cumulative encoder ticks of the left wheel. - -`~rwheel_ticks` (std_msgs/Int32):: -Cumulative encoder ticks of the right wheel. - -`~lwheel_rate` (std_msgs/Float32):: -Left wheel rotation rate, in encoder ticks per second. - -`~rwheel_rate` (std_msgs/Float32):: -Right wheel rotation rate, in encoder ticks per second. - -==== Subscribed Topics - -`~lwheel_desired_rate` (std_msgs/Int32):: -Desired left wheel rotation rate, in encoder ticks per second. - -`~rwheel_desired_rate` (std_msgs/Int32):: -Desired right wheel rotation rate, in encoder ticks per second. - -==== Parameters - -`~cmd_timeout` (float, default: 0.2):: -The amount of time after the last wheel rate message when the robot should stop automatically (seconds). - -`~rate` (float, default 10.0):: -The rate at which the simulated wheel encoder values and rates should be published (Hz).