Description

This tutorial is for those who want to use this library with your custom differential drive robot. However, the easiest way to use this library is from a SnappyXO robot kit designed and optimized for use with this library. In this tutorial, the robot requirements and the steps to use the path following library are covered.

Robot Requirements

A sample robot using the SnappyXO robotics kit have been put together in this page. The robot should have the following:

• Arduino board
  • The board needs two interrupt pins for the encoders.
  • The board needs to be either compatible with SoftwareSerial or have multiple Serial ports.
  • Confused about the Arduino requirements? If you have an Arduino Uno or higher, you should be fine. Just make sure there are enough ports for controlling the two motors and other peripheral devices you may optionally want to attach.
• Bluetooth module
  • The ArduinoBlue-library can be used to draw a path that your robot can follow. It can also be used to control the robot in other ways using the joystick, buttons, and sliders.
  • ArduinoBlue-library is compatible with the HM-10 or HM-11 bluetooth module. If you're curious about the difference between the HM-10 and HM-11, take a look at this Reddit post. The HM-19 is yet to be tested, but it should work as well.
• Motor controller
  • The motor controller that can control the motor speeds.
  • Reverse is only necessary if you want to use the reverse command.
  • The tutorial uses the Pololu DRV8835 motor shield for the Arduino Uno, but the library is flexible enough for use with any motor controller.
• Rotary encoders on both motors.
  • Quadrature encoders have two outputs, but only one output per encoder is necessary. This is because the library does not determine the direction of the motors through the encoder. It assumes the direction based on what motor move function is called from the MotorManager. For example, if the robot is set to move forward, it will assume forward motor movement.
  • The number of pulses per revolution (PPR) of the robot wheel must be sufficiently high (> 60 PPR). Note that the PPR of robot wheel and the PPR of motor shaft (AKA encoder resolution may be different, depending on where the encoder wheel is mounted.
    • If you mount the encoder wheel at the input shaft of a motor with a gear ratio of 100, the PPR of robot wheel will be 3 * 100 = 300 PPR.
    • If you mount the enncoder wheel at the robot wheel shaft, the PPR of the robot wheel will be same as the PPR of the
  • Encoder requirement:
    • The PPR of robot wheel must be sufficiently high (> 60 PPR). Note the difference below between PPR of robot wheel versus PPR encoder wheel:
      • PPR robot wheel: The number of encoder sesnor pulses per revolution of the robot wheel.
      • PPR encoder wheel (AKA Encoder Resolution): The number of encoder sensor pulses per revolution of the encoder shaft.
    • How to compute PPR robot wheel:
      • If you mount the encoder wheel at the robot wheel shaft: (PPR robot wheel) = (PPR encoder wheel).
      • If you mount the encoder wheel at the input shaft of a gear motor: (PPR robot wheel) = (PPR encoder wheel) x (gear ratio).
• Wheels with treads
  • It is recommended that wheels with less slip, such as those with rubber tracks, are used to minimize the chance of slip.
• Ball caster
  • We recommend the robot to use a ball caster to minimize friction and to make it easier to turn. Ball caster's are typically in the front of the robot as shown in the following image.
• Everything else necessary not mentioned for a functional differential drive robot. (batteries, chassis, etc)

Code Walkthrough and Tutorial

This sample code uses the ArduinoBlue-library. The user draws a path on the ArduinoBlue app and the robot follows the drawn path. The ArduinoBlue library is not necessary to use this library.

Constants

The first step is to set the necessary constants and make the measurements. Set these constants on the code:

• ENCODER_LEFT_PIN - Left encoder output pin.
• ENCODER_RIGHT_PIN - Right encoder output pin.
• BLUETOOTH_TX - Bluetooth module TX pin.
• BLUETOOTH_RX - Bluetooth module RX pin.
• RADIUS - Wheel radius in mm.
• LENGTH - Base length in mm (distance from the left to right wheel).
• BAUD_RATE - The serial monitor and the bluetooth module baud rate. Do not use separate baud rates for the serial and bluetooth module as this may cause interference.
• MOTOR_SPEED_MAX - Maximum write value that corresponds to the maximum speed of the motor. This will usually be 255, which is the maximum analog write value. See "Required Customizations" section for clarification.
• PULSES_PER_REV - The number of pulses per revolution of the wheel. Note: this is not the number of pulses per revolution of the encoder shaft, which may be different.
• MIN_PULSE_INTERVAL - This is the minimum time in microseconds before recording each pulse from the encoder. This is only necessary for encoders that have a tendency to "bounce." Keep in mind the Nyquist theorem. For a motor that has a maximum revolution of 140 RPM with PULSES_PER_REV of 20 PPR, you can work out the minimum pulse interval as follows.

(140 rev/s) x (180 pulses/rev) = (25200 pulses/min)

(1/2800 min/pulse) x (6E7 microsecond/min) = (2380 microsecond/pulse)

By Nyquist dividing by two,

1190 microsecond/pulse.

Or simply use this formula to compute this parameter,

MIN_PULSE_INTERVAL in microsecond = 1/(maximum wheel velocity in RPM x PULSES_PER_REV x 2) x 6E7

But don't worry about calculating it! Try using a low enough value (like 200 microsecond) and it should work fine in most cases.

Required Customizations

Once the constants have been set. Code the following functions to meet the following specifications. The speed parameter goes from 0 to MOTOR_SPEED_MAX. These methods are callbacks and will be called from the library to move the robot.

• setLeftForward(int speed) - Set the left motor to go forward at speed.
• setLeftReverse(int speed) - Set the left motor to go reverse at speed.
• setRightForward(int speed) - Set the right motor to go forward at speed.
• setRightReverse(int speed) - Set the right motor to go reverse at speed.

Baud Rate

Using a higher baud rate than the typical 9600 bps is recommended. The baud rate must be the same for both the serial and SoftwareSerial to prevent interference. The default baud rate on the bluetooth module is 9600 bps. To change this, follow these steps:

• Under ArduinoBlue example codes, run HM10_console.ino with the correct pins set.
• Ensure that the bluetooth module is disconnected and LED is flashing.
• Input the command as shown in the figure.
  • Example: "AT+BAUD4" for 115200 bps
• You should get the following response "OK+GET:#"
• Once the bluetooth module is restarted, it will communicate with the newly set baud rate.

Verification

Once the customization methods are written, the customizations need to be verified. Test the robot using the testEncoders() and testMotors() functions.

To test the ArduinoBlue functionality, simply run the the ArduinoBlue basic example code with the correct pins and baud rate.

PID Tuning

The example code has kp set to 100 and kd set to 25. These values have been tested with two robots and was found to work well. Thanks to the robustness and stability of the pure pursuit algorithm, a large range of kp and kd values was stable. Of course, your robot may require different PID parameters. If you find that your robot is unstable when following the path, try adjusting them. Virtual path following is similar to line following. You can find many articles devoted to tuning line follower robots.

Have Fun

After the verification is complete, follow these steps to have your robot follow a drawn path!

• On ArduinoBlue settings, enable the "Path Feature."
• Connect to bluetooth module.
• Go on the "Path" tab draw your path. Then press "Move."
• The robot should follow the path.

The triangle represents the robot location and heading and the blue dot is the goal point that the robot is trying to follow.