Getting Started with the RedBot a learn.sparkfun.com tutorial

Introduction

The RedBot is robotic development platform capable of teaching basic robotics and sensor integration! Based on the SparkFun RedBoard and programmable in the Arduino environment, the RedBot has all the I/O you need to make a small robot in no time at all. The RedBot family consists of the RedBot Mainboard (motor driver and main controller), sensor modules and add-ons, and The RedBot Kit.

We’ve also written a comprehensive library supporting the existing peripherals, which will be expanded to support additional peripherals as we add them.

Background Reading

Before you go any further, you should probably make certain that you’re familiar with these other topics:

• What is an Arduino? - Since the RedBot is based off the Arduino platform, it’s a good idea to understand what that means.
• Installing the Arduino IDE - If you don’t have the Arduino software installed, this guide will help you out.
• Installing an Arduino Library - To get the most out of the RedBot, you’ll want to install our RedBot library. This tutorial will show you how.
• Accelerometer basics - One of the core sensors for the RedBot is an accelerometer. To find out more about accelerometers, check out this guide.
• Analog to digital conversion - Many useful sensors for the RedBot will be analog. This guide will help you interface with them and make the most of the data you get back.
• Pulse width modulation (PWM) - The RedBot includes two headers with PWM signals, and uses PWM to control the speed of the motors. It’s probably a good idea to be familiar with the concept.
• I²C - The RedBot Accelerometer, which ships with the RedBot kit, uses I²C to communicate with the RedBot. While the accelerometer is accessible through the library with no knowledge of I²C required, if you want to get more out of it, you can check out this tutorial.

Hardware

RedBot Mainboard

The RedBot Mainboard was designed to be as versatile as possible. Here’s a quick tour of the hardware that’s on the board:

1. Analog/digital headers - These three headers provide one I/O pin, which can be used for analog input as well as digital input or output, as well as 5V power and ground. In addition, the header with A4 and A5 can be used for connecting I²C devices; the RedBot Accelerometer is designed to solder directly to this header, making connecting an accelerometer a snap.
2. Analog input header - This header provides an additional two analog input pins. These pins can’t be used for digital signals, however.
3. Analog output/digital headers - These two headers provide four pins which can be used for either PWM output or regular digital I/O. Note that the power supply for these headers is connected directly to the battery, providing extra umph for servo motors, but devices expecting 5V should not be connected directly to them!
4. The RedBot has a socket for an XBee module, providing easy wireless interfacing.
5. A switch allows you to select whether the XBee communicates via the standard serial I/O pins (0 and 1, accessible through the built in Serial command set) or via pins 14 and 15 (A0 and A1), using the SoftwareSerial library. Using the software mode will consume two of your analog inputs, however.
6. Headers are available to allow the user to tap off the 5V and ground signals.
7. A power switch puts the board into a very low power consumption mode (microamps or less) allowing you to turn the board off without pulling the power connection.
8. A motor disable switch allows you to turn off the motor driver so you can program the board without having it drive all over.
9. Headers are available to break out the motor outputs.
10. A header has also been provided to allow you to access the input supply, either for purposes of driving additional circuitry or to allow more flexibility than the standard barrel jack does for power sources.
11. An LED is connected to pin 13 to allow basic sanity checks that code is loading and running on the board.
12. A power LED will remain lit whenever the power switch is active.

RedBot Line Follower Sensor

The Line Follower sensor is an add-on for your RedBot that gives your robot the ability to detect lines or nearby objects. The sensor works by detecting reflected light coming from its own infrared LED. By measuring the amount of reflected infrared light, it can detect transitions from light to dark (lines) or even objects directly in front of it.

The sensor has a 3-pin header which connects directly to the RedBot Mainboard via female to female jumper wires. Use the included RedBot library to detect lines or objects. A mounting hole lets you easily connect one or more of these to the front or back of your robot chassis.

RedBot Accelerometer

The Accelerometer sensor is an add-on for your RedBot that provides bump and motion detection. The sensor works by measuring acceleration forces on the x, y, and z axis. By measuring the amount of acceleration (or lack there of) your robot can get a better understanding of its movements.

The sensor has a 2x3 unpopulated footprint which connects directly to the RedBot Mainboard via a female header. You can also solder the sensor directly to the headers on the Mainboard if you wish.

Magician Chassis

The Magician Chassis is an economical robot platform with a lot of versatility. It features two gearmotors with 65mm wheels and a caster. The chassis plates are cut from acrylic with a wide variety of mounting holes for sensors, controllers, power, etc. The chassis does require some basic assembly but detailed instructions are included.

Arduino Library

To help you make getting your robot moving as easy as possible, we’ve written an Arduino library. Here’s a walk-through of the commands that the library provides. We’ll see them in action later, with an example sketch. If you need a refresher on how to install an Arduino library, please see our library tutorial.

RedBotMotor function

The RedBotMotor function within the library provides control over all basic motor functionality. You should find it very easy to control your robot’s motion using this command set.

language:cpp
RedBotMotor();

The constructor for the class, which is used to create a class object that can be referred to later, accepts no parameters. It will automatically configure all the peripherals and I/O lines you need to drive the motors. For example, creating an instance of the the RedBotMotor named motor

RedBotMotor motor;

will allow you to call all of the other functions from that class. Such as

motor.drive(255);

Now, let’s go over some of the functions that live within that class.

void drive(int speed);
void rightDrive(int speed);
void leftDrive(int speed);

The three drive commands cause the motors to start turning. drive() starts both motors at (approximately) equal speeds; rightDrive() and leftDrive() activate their appropriate motors. Sign is important; positive speeds go forward, negative speeds go backwards. The range of speeds is from 0-255, although speeds below about 75 may not provide enough torque to start the motor turning. If you want very slow motion, try starting at a higher speed, then turning the speed down a bit.

void pivot(int speed);

Pivot turns the robot on its axis by spinning one motor one way and the other the opposite direction. Positive values correspond to anti-clockwise rotation; negative values to clockwise rotation.

void stop();
void rightStop();
void leftStop();

These commands discontinue the PWM output to one or both motors. The motors will continue to coast for a short time after this command is issued; if you need to stop quickly, use…

void brake();
void rightBrake();
void leftBrake();

Brake actually effectively shorts the terminals of the motors together, causing them to stop turning much faster than the stop() commands do. After a brake() has been issued, the wheels will also be much harder to turn, allowing the robot to hold position against a slope.

RedBotSensor

The RedBotSensor class supports the line following sensors included in the kit.

RedBotSensor(int pin);

Pass the constructor the name of the pin to which the sensor is attached, and the library will take care of the rest.

void setBGLevel();
void setDetectLevel();

The level setting commands take stock of the surface the sensors are over at the moment and try to characterize it, so the detection of a transition can be automated. For example, if your robot is going to try to follow a black line on a white surface, run setDetectLevel() while the sensor is looking at the line, and setBGLevel() while the sensor is not looking at the line. The library will attempt to figure out a good rule for calling an edge having been seen.

boolean check();

Returns true if the current reading is consistent with the levels determined during the setDetectLevel() call, and false otherwise.

int read();

Returns the analog level of the sensor, if you prefer to do your own processing on the data.

RedBotAccel

Another sensor provided for the RedBot is a specially designed accelerometer board. This board couples a Freescale MMA8452Q accelerometer with a TI PCA9306 level shifter and is designed to attached directly to the A4/A5 header on the RedBot. In addition to normal accelerometer data collection, it can be used to detect bumps (as in collisions) or taps (for user input).

RedBotAccel();

The class constructor accepts no parameters; simply instantiate an object of the class and the library will handle all necessary configuration. Including the I²C library provided by Arduino is not necessary either; all that is handled by the library.

void read();

Unlike most read-type functions, read() does not actually return a value. What it does is copy the most recent accelerometer values into three variables (naturally enough, named x, y and z. Those values can then be easily referred to using the class object name.

void enableBump();
boolean checkBump();
void setBumpThresh(int xThresh);

These three functions allow the user to enable and check bump detection. Under normal circumstances, the setBumpThresh() function shouldn’t be needed; the bump threshold is already set to a good value. Users may find it useful to increase or decrease the sensitivity level; the range for that number is 0-127.

checkBump() returns a true if a bump has been detected since the last time checkBump() was called. It may be useful to call checkBump() to clear any existing bumps before attempting to detect a bump for decision making purposes, as the bump flag will remain set until it is read.

Example

This example uses the RedBot kit hardware and the RedBot library to realize a simple line following robot. We’ll break the code down, bit by bit, and analyze it.

The sketch is included with the library on the SparkFun Github site. Download the .zip archive and copy the directories in the “Arduino” directory into your Arduino Sketchbook.

Main file

The sketch is divided into two files: the main (Demo1.ino) file and a support (lineFollowing.ino) file. We’ll take them one at a time, and explore the code a bit beyond what the comments provide. Please note that you’ll need to combine the two sketches in order to compile them.

language:cpp
#include <RedBot.h>
#include <SoftwareSerial.h>

The first step is to include the libraries we’ll need to get the code working. Obviously we want to include the RedBot library, but we’ll also include the SoftwareSerial library just so we can demonstrate the creation of a software serial port to access the XBee.

RedBotMotor motor;

RedBotSensor lSen = RedBotSensor(A2);
RedBotSensor cSen = RedBotSensor(A3);
RedBotSensor rSen = RedBotSensor(A6);

RedBotAccel xl;

SoftwareSerial xbee(15, 14);

Next, we’ll instantiate objects of the various classes. This creates an object that can be manipulated and accessed using other functions later on.

The RedBotMotor class object can be accessed to control the motors. No initialization parameters are accepted.

The ‘RedBotSensor` class object links a line sensor to one of the analog inputs. We’ll see in a bit why this is useful.

Creating a RedBotAccel object allows you to easily access the accelerometer without having to worry about all the ins and outs of the I²C interface. It also allows you to access the bump detection functionality of the accelerometer.

void setup()
{
  Serial.begin(57600);
  xbee.begin(57600);

The first step in the setup() function is to initialize both the standard Serial interface as well as the software serial port we instantiated above. This allows us to interface with our XBee module regardless of the position of the hardware/software interface switch.

  xl.enableBump();
}

Next, we’ll enable bump detection. This feature allows the accelerometer to raise a flag when it detects a bump or tap, which can be checked by the main program using the checkBump() function.

boolean following = false;

void loop()
{
  if  (xl.checkBump() && following == false) following = true;

  if (following)
  {
    followNoCal();
  }
}

The loop() function is pretty simple. We wait for the accelerometer to detect a bump, then take off looking for the line to follow. The nitty-gritty details of what’s involved in following is covered in the ancillary file.

lineFollowing.ino

Now, we’re going to explore the lineFollowing.ino file to see how the line following is done.

#define darkLevel  200
#define seekSpd    150
#define fwdSpd     200

We start with a few definitions. darkLevel is the analog reading above which we consider a line to be found. We also define a couple of speeds that we’ll use throughout the following logic for different motions.

void followNoCal()
{
  static boolean centerOnLine = false;
  static boolean onLine = false;

Using the static keyword causes the variable to maintain its value across calls to the function and to only be initialized on the first call to the function. These variables track whether the robot has found the line and whether or not the center sensor of the three is detecting the line at the moment.

  int rLevel, lLevel, cLevel; // Sensor levels.
  rLevel = rSen.read();
  lLevel = lSen.read();
  cLevel = cSen.read();

The next step is to read the current sensor levels. We’ll use these values to figure out where we are relative to the line.

  if (cLevel < darkLevel &&
      centerOnLine == false) motor.drive(seekSpd);

If we aren’t on the line, and haven’t yet found the line, drive forward slow-ish, looking for the line.

  if (cLevel >= darkLevel) centerOnLine = true;

Once we’ve found the line with our center sensor, we want to note that we’ve found the line by setting the centerOnLine flag.

  if (centerOnLine &&
      onLine == false)
  {
    motor.rightBrake();
    while (rLevel < darkLevel) rLevel = rSen.read();
    motor.drive(fwdSpd);
    onLine = true;
  }

If we’ve found the line with the center sensor, BUT we haven’t “locked in” on the line yet, start turning to the right while looking for the line. When we find it, drive forward and set our “found-the-line” flag.

  if (cLevel < darkLevel &&
      onLine == true)
  {
    if (rLevel >= darkLevel)
    {
      motor.rightBrake();
      while (cLevel < darkLevel)
      {
        cLevel = cSen.read();
      }
      motor.drive(fwdSpd);
    }
    else if (lLevel >= darkLevel)
    {
      motor.leftBrake();
      while (cLevel < darkLevel)
      {
        cLevel = cSen.read();
      }
      motor.drive(fwdSpd);
    }
  }
}

Finally, this is our “oops, lost the line!” logic. If the center sensor isn’t on the line anymore, we should still be seeing the line with the right or left sensor. Depending on which of those we still see the line with, we want to turn back towards the line until the center sensor sees the line.

Going Further

Get moving!

Hopefully, this guide has given you enough information to get started with the RedBot. Look for more sensors, kits and content around the RedBot platform!

Once you’ve mastered the art of line following robots, try you hand at other types of robots. You could use a robotic claw and a pan/tilt bracket to design a robot with an arm to fetch items for you. You could create your own remote control using variousSparkFunparts. And, last but not least, you can always give your robot a new look with differenttypes of robot chassis.

learn.sparkfun.com |CC BY-SA 3.0 | SparkFun Electronics | Boulder, Colorado