1 of 7

Physical Inputs

Push Button
Mechanical Bumpers
IR Line Sensors
Wheel Encoders
Accelerometer
Ultrasonic Sensor *

Push Button (D12)

The RedBot mainboard has a built-in push button that can be detected by your program. The button is hardwired to pin D12 on the RedBot mainboard and is located next to the USB port.

The button can be used as a way for a user to control the robot:

The robot can in order to "start" or "pause" its task.
The robot can before performing the next step in a task.

How to Code Button

There are three different ways to use the button in your robot app:

Option 1: Read the button pin directly using the digitalRead() method
Option 2: Read the button using a RedBotButton object and its read() method
Option 3: Use a OneButton object and its tick() method to detect different types of button presses (i.e., single-press, double-press, and long-press)

Option 1 and Option 2 are similar. They both detect when the button is pressed. It is primarily a matter of personal preference, in terms of which option to use. Most of the coding tutorials and references in this guidebook use the second option.

Option 3 allows your robot to detect up to 3 different types of button presses, so the robot can perform different tasks based on the user's input. This option requires you to include the OneButton library in your robot app.

Read Button Directly

To read the button pin directly, your robot app will need to:

Declare a variable to store the button pin number
Set the pin mode for the button
Use the digitalRead() method to detect whether the button is being pressed
Add code statement(s) to perform certain action(s) if the button is pressed

You'll need to create a global variable to store the pin number of the button, which is connected to pin D12. Add this code statement before the setup() function:

Next, you'll need to set the button's pin mode. Add this code statement within the setup() function:

INPUT_PULLUP indicates the button pin will be used for input and will use a pull-up resistor (which is something that buttons and switches typically use, but other inputs do not).

The digitalRead() method can be used to detect whether or not the button is currently being pressed. It will return a value of either HIGH or LOW:

HIGH indicates the button is NOT being pressed
LOW indicates the button is being pressed

An if statement is typically used to perform a set of actions when the button is pressed.

This code is typically added within the loop() function or within a custom function:

Inside the if statement, you need to add code statements for the specific actions you want performed when the button is pressed.

Alternatively, you can also include an else statement to perform a different set of actions when the button is not pressed. In this case, use this code instead:

Use RedBotButton Object

To read the button using a RedBotButton object, your robot app will need to:

Create a RedBotButton object for the button
Use the object's read() method to detect whether the button is being pressed
Add code statement(s) to perform certain action(s) if the button is pressed

The SparkFun RedBot library has a class named RedBotButton which contains methods (functions) to control the RedBot's built-in D12 push button. This class will automatically set the pin number (12) and pin mode (INPUT_PULLUP) for the button.

Before the setup() function, create a RedBotButton object for the button by assigning the object to a variable:

The RedBotButton object has a read() method that can be used to detect whether or not the button is currently being pressed. It will return a value of either true or false:

true indicates the button is being pressed
false indicates the button is NOT being pressed

An if statement is typically used to perform a set of actions when the button is pressed.

This code is typically added within the loop() function or within a custom function:

Inside the if statement, you need to add code statements for the specific actions you want performed when the button is pressed.

Alternatively, you can also include an else statement to perform a different set of actions when the button is not pressed. In this case, use this code instead:

Use OneButton Object

The RedBot mainboard only has one button, which normally can only be read as being pressed or not pressed. However, the OneButton library makes it possible to detect three different types of button input events:

Single-Press = user presses the button once
Double-Press = user presses the button twice in rapid succession
Long-Press = user presses and holds the button down

To read the button using a OneButton object, your robot app will need to:

Include the OneButton library
Create a OneButton object for the button
Designate custom functions for each type of button input
Add the code to be performed within each custom function
Use the object's tick() method to detect the type of button input

Next, you must include a copy of the OneButton library in your robot app. The following #include statement should be inserted at the beginning of your app code:

Before the setup() function, create a OneButton object by assigning it to a variable and indicating its pin number and whether it will use a pull-up resistor in parentheses:

Add this code within the setup() function to designate the names of custom functions that will be called when the different button input events are detected (single-press, double-press, or long-press):

If desired, you can use other names for the custom functions instead of singlePress, doublePress, and longPress. For example, you could name the functions as task1, task2, and task3.

If you don't need to detect a particular type of button input, just leave it out (or make it into a comment). For example, if you do not need to detect a long-press, then simply exclude the code statement that attaches a custom function to that input event.

After the loop() function, add the custom functions for each type of button input:

Be sure the names of these custom functions match the names that were designated in your setup() function.

Inside each custom function, you need to add code statements for the specific actions you want performed when that type of button input is detected.

Within the loop() function, use the OneButton object's tick() method to check for button input events. Whenever a specific button input event is detected, the custom function that was designated for that input event will automatically be called:

For example, the button.tick() statement might be the only code statement listed within your loop() function. You could put the code for your different robot tasks within the custom functions for singlePress(), doublePress(), and longPress(). This would allow you to use different button presses to start the different robot tasks.

Mechanical Bumpers

The RedBot has two mechanical bumpers (left and right) at its front to with obstacles.

Each mechanical bumper has a wire "whisker" that extends to one side about 6 inches. If the wire whisker collides with an obstacle, the wire will bend and eventually make contact with a metal screw attached to the bumper board. When this happens, it acts like an electrical switch, which the robot can detect has been closed.

Each mechanical bumper is connected to the RedBot circuit board by a 3-wire jumper cable (white, red, and black wires for data, power, and ground):

The left mechanical bumper data wire should be connected to I/O pin 3
The right mechanical bumper data wire should be connected to I/O pin 11

Check Bumper Positions

In order for the bumpers to detect collisions accurately, you may need to adjust the positions of the wire whiskers and the bumper boards. Otherwise, it may not be physically possible for the whiskers to make contact with the metal screw on the bumper boards.

WIRE WHISKERS

In the normal position (no collision), each wire whisker should be positioned very close to the metal screw on its bumper board. There should only be about ⅛ inch between the wire and the screw. Otherwise, if the wire is too far away, it may not be physically possible for an obstacle to bend the wire far enough to make contact with the screw.

To adjust the position of a wire whisker, you have to loosen the plastic standoff screw on the bottom of the bumper board. In order to physically access this screw on an assembled robot, you may have to remove the entire bumper (by removing the top screw of the plastic standoff, which attaches the bumper to the front of the RedBot chassis). You might need to also unplug the 3-wire cable connected to the bumper. After adjusting the wire whisker, correctly reconnect the 3-wire cable, and then reattach the bumper to the robot chassis.

BUMPER BOARDS

Each bumper board should be rotated slightly so the metal screw on the bumper board is positioned slightly in front of the black plastic struts at the front corners of the RedBot chassis. Otherwise, the struts might physically block the wire whisker from making contact with the metal screw on the bumper board.

The photo below shows the mechanical bumpers in the correct position. When looking down on the front of the robot, the metal screw of each bumper board (where the wire whisker will make contact) is visible. If you cannot see these metal screws, your bumpers might not be able to work.

To adjust the position of a bumper board, you have to loosen the the top screw of the plastic standoff, which attaches the bumper to the robot chassis. Rotate the bumper board slightly, so the metal contact screw is further forward than the side strut. Then tighten the top screw of the plastic standoff to secure the bumper in place.

How to Code Bumpers

To use the mechanical bumpers in your robot app, you need to:

Create a RedBotBumper object for each mechanical bumper (left and right)
Use each object's read() method to detect whether a collision has occurred
Add code statement(s) to perform action(s) when a bumper collision is detected

Create Objects for Bumpers

The SparkFun RedBot library has a class named RedBotBumper which defines methods (functions) to control the RedBot's mechanical bumpers.

Before the setup() function, create a RedBotBumper object for each bumper by assigning each object to a variable and indicating its pin number within parentheses:

Read Bumpers

To check the mechanical bumpers for collisions with obstacles, use the RedBotBumper object's read() method to detect whether or not a bumper has collided with an obstacle:

leftBumper.read()
rightBumper.read()

Each bumper acts like a switch or button. The read() method will return a value of either HIGH or LOW:

LOW indicates the bumper has collided with an obstacle (i.e., the wire whisker has bent far enough to make electrical contact with the metal screw on the bumper board).

The leftBumper.read() and rightBumper.read() methods can inserted within an if-else statement:

You will need to decide what code to perform if the left or right bumper collides with an obstacle. Most likely, the first thing that you should do is brake the motors.

IR Line Sensors

The RedBot has three "line following" sensors (left, center, and right) which can be used to detect lines on a surface.

The bottom of each sensor has an LED that transmits infrared (IR) light, which is invisible to the human eye. The bottom of each sensor also has an IR detector, which measures how much of the IR light is reflected back by the surface that the robot is driving on.

The amount of reflected IR light that is detected depends on several factors, including the color of the surface, as well as the distance between the sensor and the surface:

A light-colored surface will reflect more IR light, while a dark-colored surface will reflect less IR light.
If the surface is farther away, the IR light will become more scattered, and less IR light will be reflected back to the detector.

Each IR line sensor is connected to the RedBot circuit board by a 3-wire jumper cable (white, red, and black wires for data, power, and ground):

The left line sensor data wire should be connected to I/O pin A3
The center line sensor data wire should be connected to I/O pin A6
The right line sensor data wire should be connected to I/O pin A7

The IR sensors measurements can be used to perform several useful robot behaviors:

How to Code IR Sensors

To use the IR sensors in your robot app, you will need to:

Create a RedBotSensor object for each IR sensor (left, center, and right)
Use each IR sensor object's read() method to get a measurement
Add code statement(s) to perform action(s) based on the IR sensor measurements

Create RedBotSensor Objects

The SparkFun RedBot library has a class named RedBotSensor which defines methods (functions) to control analog sensors, such as the IR line following sensors.

Before the setup() function, create a RedBotSensor object for each IR sensor by assigning each object a variable name and indicating its pin number within parentheses:

Read IR Sensors

To check the measurements from the IR line following sensors, use the RedBotSensor object's read() method to get a measurement from each sensor:

leftLine.read()
centerLine.read()
rightLine.read()

The read() method will return an int value (integer) between 0-1023 that represents a measurement of how much reflected IR light was detected:

Lower values indicate more IR light was reflected back. This indicates a lighter-colored surface.
Higher values indicate less IR light was reflected back. This indicates a darker-colored surface.

If the values are very high, this probably indicates a surface drop-off (such as: a stair step leading down, the edge of a table, a hole in the surface, etc.).

Since you will typically want to compare the readings from all 3 sensors at the same time, your code could assign the sensor readings to local variables, and then perform actions based on the values stored in those variables:

You will need to add code to do something based on the sensor readings. For example, you might use if statements to perform certain actions if one or more sensor readings are greater than (or less than) a specific value.

Test IR Sensors

To test out your IR sensors, you can view the sensor measurements using the serial monitor in the Arduino code editor.

Add this code statement within the setup() function:

This starts a serial data connection between your robot and your computer and sets the data transfer rate to 9600 bits per second.

A custom function named testLineSensors() can be used to read each IR sensor and send (print) the measurements to your computer as serial data.

Add the testLineSensors() function after the loop() function:

Add this code statement within the loop() function to call the custom function:

This should be only code statement listed within the loop() function.

After uploading the app to your robot, do not unplug the USB cable. You have to keep the robot connected to your computer to allow the serial data communication.

In your Arduino code editor, open the serial monitor, so you can view the serial data:

Arduino Create (Web Editor): Click the Monitor menu link in the left navigation to display the serial monitor in the middle panel.
Arduino IDE (Desktop Editor): Under the Tools menu, select "Serial Monitor." A new window will appear displaying the serial monitor.

It may take a few seconds for the serial connection to be detected by the editor. Then you should see the sensor measurements being displayed in the serial monitor window.

You can try the following tests to see how the sensor measurements change:

Create a dark line on a sheet of white paper. Position the robot's IR sensors on the dark line to view the measurements. Then position the IR sensors on the white paper to compare the measurements. Try testing other surface colors.
Try slowly lifting the front edge of the robot off the table to see how the sensor measurements change with distance from the surface.
Manually roll the robot towards the edge of a table to see how the measurements change when the sensors are hanging over a surface drop-off.

Wheel Encoders

Located directly behind each motor is a wheel encoder. Each wheel encoder is used to count the number of times the motor (left or right) has rotated. This can be used to calculate the distance that the robot has driven or turned.

Each wheel encoder actually consists of two parts:

a Hall Effect sensor that can measure the strength of a magnetic field
a ring magnet (looks like a metal washer) attached to the motor shaft

When the motor rotates the wheel, it also rotates the ring magnet. The Hall effect sensor positioned near the ring detects changes in the magnetic field as the ring rotates. This is how the sensor can count how many times the motor has rotated.

When you think of a magnet, you probably think of a magnet that has 2 poles: north and south. It is true that magnets have pairs of N-S poles. However, a magnet can be created with multiple pairs of N-S poles. The ring magnets attached to the RedBot motors each have 4 pairs of N-S poles, similar to the diagram below.

Each wheel encoder is connected to the RedBot circuit board by a 3-wire jumper cable (white, red, and black wires for data, power, and ground):

The left wheel encoder data wire should be connected to I/O pin A2
The right wheel encoder data wire should be connected to I/O pin 10

The wheel encoder counts can be used to perform to several useful robot behaviors:

Find Distance with Encoders

As each motor shaft rotates, it also rotates its attached ring magnet at the same rate. As the ring magnet completes one full rotation, the Hall effect sensor detects 4 changes (or "ticks") in the magnetic field as each magnetic pole passes by the sensor.

However, each rotation of the motor only turns the wheel a certain number of degrees. The RedBot motors have a gearbox ratio of 48:1, which means it takes 48 rotations of the motor to turn the wheel one complete revolution (360°).

We can use this information to calculate how many "ticks" counted by the wheel encoder represent one revolution of the wheel:

4 ticks per motor rotation × 48 motor rotations per wheel revolution = 192 ticks per wheel revolution

Based on the size of the robot's wheels, we can also calculate the distance that the robot travels during one wheel revolution. This distance is equal to the circumference of the wheel (i.e., the distance around the outer edge of the wheel). The circumference of a circle is its diameter multiplied by pi (approximately 3.14). Since the RedBot's wheels have a diameter of 65 mm (2.56 inches), the distance traveled per wheel revolution is:

C = 𝛑 × d = 3.14 × 2.56 inches = 8.04 inches per wheel revolution

So for your RedBot's wheel encoders, the following is true:

192 ticks of wheel encoder = 1 wheel revolution = 8.04 inches traveled

This information can be used to convert any encoder count into distance traveled — or to convert a desired distance into a target encoder count.

Check Encoder Positions

In order to function accurately, each wheel encoder sensor must be positioned correctly, relative to its ring magnet. The sensor tip must be centered within the silver band of the ring magnet (not too far inward or outward) and must be close to the ring magnet's surface (about ⅛" inch away).

Visually check the position of the left and right encoder sensors. If necessary, you might need to push (or pull) a sensor to position it correctly.

CHECK ENCODERS AFTER CHANGING BATTERIES: Whenever you change the robot's batteries, be sure to check the encoder sensor positions afterwards. It's common to accidentally move the encoder sensors when changing the batteries.

How to Code Encoders

To use the wheel encoders in your robot app, you will need to:

Create a RedBotEncoder object for the wheel encoders
Use the object's clearEnc() method to clear the encoder counters (reset to zero)
Add code statement(s) to drive one or both motors
Use the object's getTicks() method to get the current encoder counts
Add code statement(s) to perform action(s) based on the encoder counts

Create RedBotEncoder Object

The SparkFun RedBot library has a class named RedBotEncoder which defines methods (functions) to control the wheel encoders.

Before the setup() function, create a RedBotEncoder object by assigning it to a variable name and indicating the pin numbers for the left and right encoders in parentheses:

Clear Encoder Counters

The RedBotEncoder object has counters to keep track of how many total magnetic "ticks" have been detected by each wheel encoder.

Before using the wheel encoders, you will typically want to clear the counters by resetting them to zero.

Use the clearEnc() function to clear the encoder counter:

Using a value of BOTH will clear both encoder counters. If necessary, you can use a value of LEFT or RIGHT to only clear a specific encoder counter.

Get Encoder Counts

The RedBotEncoder object has a getTicks() method that returns a long value (long integer) representing the total number of magnetic "ticks" that have been counted by the wheel encoder as its motor rotates.

Since you will typically want to compare the readings from both encoders at the same time, your code could assign the encoder counts to local variables, and then perform actions based on the values stored in those variables:

NOTE: Each encoder will count "ticks" whether its motor is driving forwards or backwards.

Test Wheel Encoders

To test out your wheel encoders, you can view the encoder counts using the serial monitor in the Arduino code editor.

Your app will need to create new objects (as global variables) for these three classes. Add these code statements before the setup() function:

Add this code statement within the setup() function:

This starts a serial data connection between your robot and your computer and sets the data transfer rate to 9600 bits per second.

A custom function named testWheelEncoders() can be used to get each encoder count and send (print) the counts to your computer as serial data.

Add the testWheelEncoders() function after the loop() function:

Add this code statement within the loop() function to call the custom function:

This should be only code statement listed within the loop() function.

After uploading the app to your robot, do not unplug the USB cable. You have to keep the robot connected to your computer to allow the serial data communication.

IMPORTANT: Be sure the robot is standing upright on its back end (with its wheels in the air), so the robot won't drive way while it's connected to your computer.

In your Arduino code editor, open the serial monitor, so you can view the serial data:

Arduino Create (Web Editor): Click the Monitor menu link in the left navigation to display the serial monitor in the middle panel.
Arduino IDE (Desktop Editor): Under the Tools menu, select "Serial Monitor." A new window will appear displaying the serial monitor.

Press the D12 button on your robot's circuit board. Your robot's wheels will start driving. In the serial monitor, view the wheel encoder counts. When either one of the wheel encoder counts reaches 1000 (which should take about 3-4 seconds), the motors will brake.

You'll notice that the wheel encoder counts do not stop exactly at 1000. This is normal because it takes a brief amount of time for the motors to brake. The final counts should probably be between 1000-1050.
You'll probably notice that your left and right wheel encoder counts are not exactly the same. This is normal — they should be close to each other (within about 25), but they probably won't be identical.
If one or both wheel encoders are not working properly (the count stays at zero), turn off the robot's power, and check the encoder sensor position(s). After correcting the sensor position(s), turn the robot's power back on and test again.

Accelerometer

The RedBot has an accelerometer that can be used to measure changes in motion or orientation along 3 axes (X, Y, Z). Accelerometers are used in a variety of devices, including smartphones, fitness trackers, etc.

The accelerometer is a small circuit board that should be connected to I/O pins A4 and A5 on the main RedBot circuit board.

The accelerometer can measure:

the acceleration of the device (i.e., the device speeding up or slowing down)
the acceleration due to Earth's gravity (i.e., the orientation of the device)

Although you can measure the robot's acceleration, you won't use the accelerometer to measure the robot's speed. This is because when an object is traveling at a constant speed, its acceleration is actually zero. An object is only accelerating if its speed is changing (i.e., speeding up or slowing down). Besides you will be able to directly control your robot's speed by adjusting its motor power.

However, you can use the accelerometer to detect when the robot is physically bumped – this type of change in motion is a "pulse" acceleration that is detectable by the accelerometer.

You can also use the accelerometer to detect the orientation of a device by measuring the acceleration due to Earth's gravity, which is a constant downward force acting on all objects. The accelerometer can determine if the device is parallel to Earth's surface or if the device is tilted at an angle.

The accelerometer measures the acceleration along each axis (X, Y, Z) and then uses these measurements to calculate the robot's angle in the XZ plane, YZ plane, and XY plane.

The accelerometer measurements can be used to perform these useful robot behaviors:

The robot can detect when it is upside-down by measuring its tilt from front-to-back (pitch) and from side-to-side (roll).
The robot can detect when it has been bumped by detecting a "pulse" acceleration.

How to Code Accelerometer

To use the accelerometer in your robot app, you will need to:

Create a RedBotAccel object
Use the object's read() method to get accelerometer measurements
Add code statement(s) to perform action(s) based on the measurements

Create RedBotAccel Object

The SparkFun RedBot library has a class named RedBotAccel which defines methods (functions) to control the accelerometer.

Before the setup() function, create a RedBotAccel object by assigning it to a variable:

RedBotAccel accel;

You may have noticed that you didn't have to indicate which I/O pins the accelerometer is connected to. This is because the RedBot library assumes the accelerometer is connected to pins A4 and A5 on the RedBot circuit board.

REDBOT LIBRARY: Be sure your robot app has an #include statement for the SparkFun RedBot library. Here's how to include the RedBot library.

Read Accelerometer

The RedBotAccel object has a read() method which is used to get new accelerometer measurements for each of the 3 axes (X, Y, Z):

accel.read();

The new measurements are stored as properties of the object:

accel.x — acceleration along X axis
accel.y — acceleration along Y axis
accel.z — acceleration along Z axis
accel.angleXZ — device's angle in XZ plane (pitch)
accel.angleYZ — device's angle in YZ plane (roll)
accel.angleXY — device's angle in XY plane (yaw)

The accelerometer measures the acceleration along each axis (X, Y, Z) and then uses these measurements to calculate the device's angle in the XZ plane, YZ plane, and XY plane.

This diagram shows how the accelerometer's X, Y, and Z axes are oriented on the RedBot and what the XZ, YZ, and XY angles represent. These angles are also referred to as pitch, roll, and yaw.

For a wheeled vehicle, pitch and roll are the most important angles to measure as they indicate the tilt of the vehicle from front-to-back and from side-to-side.

PITCH (Angle XZ)

Angle XZ represents pitch. Pitch is the front-to-back rotation on the robot's Y axis. The pitch angle can range from -180° to 180°.

If the robot is perfectly level from front-to-back, the pitch is zero (angle XZ = 0).
If the front of the robot is tilted up, the pitch is a positive value (angle XZ > 0). For example, if the front of the RedBot were pointing straight up, the pitch would be 90°.
If the front of the robot is tilted down, the pitch is a negative value (angle XZ < 0). For example, if the front of the robot were pointing straight down, the pitch would be -90°.

ROLL (Angle YZ)

Angle YZ represents roll. Roll is the side-to-side rotation on the robot's X axis. The roll angle can range from -180° to 180°.

If the robot is perfectly level from side-to-side, the roll is zero (angle YZ = 0).
If the left side of the robot is tilted up, the roll is a positive value (angle YZ > 0). For example, if the left side of the robot were pointing straight up, the roll would be 90°.
If the left side of the robot is tilted down, the roll is a negative value (angle XZ < 0). For example, if the left side of the robot were pointing straight down, the roll would be -90°.

YAW (Angle XY)

Angle XY represents yaw. Yaw is the right-to-left rotation on the robot's Z axis. The yaw angle can range from -180° to 180°.

However, when the robot is on a level surface, the yaw value cannot be accurately determined because the acceleration due to Earth's gravity is acting in the same direction (i.e., downward) as the Z axis.

Therefore, you cannot use the accelerometer's XY angle to determine which clockwise direction the robot is pointed. (However, there are other sensors – not included in this kit – which can be used to accurately measure the yaw angle.)

Test Accelerometer

To test out your accelerometer, you can view the accelerometer measurements using the serial monitor in the Arduino code editor.

Add this code statement within the setup() function:

Serial.begin(9600);

This starts a serial data connection between your robot and your computer and sets the data transfer rate to 9600 bits per second.

A custom function named testAccelerometer() can be used to read the accelerometer and send (print) the measurements to your computer as serial data.

Add the testAccelerometer() function after the loop() function:

void testAccelerometer() {

  // get new accelerometer data
  accel.read();

  // send data to serial monitor
  Serial.print("Pitch: ");
  Serial.print(accel.angleXZ);
  Serial.print("\tRoll: ");
  Serial.print(accel.angleYZ);
  Serial.print("\tYaw: ");
  Serial.println(accel.angleXY);

  // brief delay before next reading
  delay(100);
}

Add this code statement within the loop() function to call the custom function:

testAccelerometer();

This should be only code statement listed within the loop() function.

After uploading the app to your robot, do not unplug the USB cable. You have to keep the robot connected to your computer to allow the serial data communication.

In your Arduino code editor, open the serial monitor, so you can view the serial data:

Arduino Create (Web Editor): Click the Monitor menu link in the left navigation to display the serial monitor in the middle panel.
Arduino IDE (Desktop Editor): Under the Tools menu, select "Serial Monitor." A new window will appear displaying the serial monitor.

It may take a few seconds for the serial connection to be detected by the editor. Then you should see the accelerometer measurements being displayed in the serial monitor window.

Place the robot on a level surface, such as your desk or table. If the surface is perfectly level, the values for pitch (angle XZ) and roll (angle YZ) will be zero. However, you may discover that your values are close to zero (instead of exactly zero).

Follow the steps below to test your robot's pitch, roll, and yaw.

PITCH

Pitch is the front-to-back rotation on the robot's Y axis. Pitch can range from -180° to 180°.

Hold the robot in the air, and slowly rotate the robot from front-to-back to tilt the front end up. Watch the pitch value change in the serial monitor as you change the tilt. When the robot's front end is tilted straight up, the pitch will be 90°.
Rotate the robot so it is level from front-to-back. When it is level, the pitch will be 0°.
Rotate the robot so its front end is tilts down. When the robot's front end is tilted straight down, the pitch will be -90°.

ROLL

Roll is the side-to-side rotation on the robot's X axis. Roll can range from -180° to 180°.

Hold the robot in the air, and slowly rotate the robot from side-to-side, so the left side is tilted up. Watch the pitch change in the serial monitor as you change the tilt. When the robot's left side is tilted straight up, the roll will be 90°.
Rotate the robot so it is level from side-to-side. When it is level, the roll will be 0°.
Rotate the robot so its left side is tilted down. When the robot's left side is tilted straight down, the roll will be -90°.

YAW

Yaw is the right-to-left rotation on the device's Z axis. Yaw can range from -180° to 180°.

Place the robot back down on a level surface, such as your desk or table. Check the yaw value in the serial monitor.
Rotate the robot clockwise to the right, while checking the yaw value in the serial monitor. You'll notice that the yaw value changes randomly – and does not represent which direction the robot is pointed (i.e., the robot's rotation on the Z axis).
Rotate the robot counter-clockwise to the left, while checking the yaw value in the serial monitor. Again, the yaw value changes randomly – and does not represent the robot's direction.

Ultrasonic Sensor *

ADD-ON COMPONENT: The SparkFun RedBot Kit does NOT include an ultrasonic sensor. However, the can be easily connected to a RedBot. Your teacher may have added this sensor to your robotics kit.

An ultrasonic sensor uses sound waves to measure distance. The sensor has a transmitter (i.e., speaker) that produces high-frequency sound (beyond the range of human hearing). The sensor has a receiver (i.e., microphone) that detects the echo of the high-frequency sound when it reflects back from an object. You can calculate the distance between the sensor and the closest object by measuring how much time it takes for the echo to arrive.

If you want to add an ultrasonic sensor to the front of your RedBot, you will need:

The HC-SR04 ultrasonic sensor measures distances in a narrow cone of about 15° in front of the sensor. This sensor can detect obstacles located up to 400 cm away (about 13 feet). The distances calculated from the sensor measurements are very accurate, within about 3 mm (about 0.1 inch) of the actual distance.

The ultrasonic sensor can be used to perform several useful robot behaviors:

Connect Sensor Wires

If necessary, use jumper wires to connect the ultrasonic sensor pins to the open pins on the front-left corner of the RedBot mainboard:

For the 5V and GND pins on the RedBot mainboard, you can use the pins adjacent to A0 or A1 (either side is fine). This means three wires will be connected on one side (such as the A0 side), while the fourth wire is connected to the I/O pin on the other side (such as A1).

Mount Sensor to Robot

If necessary, use velcro tape or foam tape to mount the ultrasonic sensor at the front of the robot on top of its chassis. The sensor's transmitter and receiver should face forward, like a pair of eyes. The sensor will be mounted "upside-down" with its wires pointing up.

Take a section of velcro tape ("hook-and-loop") or double-sided foam tape about 1 inch × 0.5 inch, and cut it in half to form two pieces about 0.5 inch × 0.5 inch.
Place one piece of tape on the top side of the transmitter cylinder, and place the other piece of tape on the top side of the receiver cylinder.
Press the sensor "upside-down" onto the front edge of the top of the robot chassis, so it is attached securely. Be sure the sensor is facing forward.

How to Code Sensor

To use the ultrasonic sensor in your robot app, you need to:

Declare global variables to store the ultrasonic sensor's pin numbers
Set the pin modes for the ultrasonic sensor, and turn its transmitter off
Call a custom function to measure the distance to the closest object

Declare Variables for Sensor

You'll need to create global variables to store the pin numbers of the ultrasonic sensor's transmitter (Trig) and receiver (Echo), which should be connected to I/O pins A0 and A1 on the RedBot's circuit board. Add this code before the setup() function:

Set Pin Modes for Sensor

You'll need to set the pin modes for the ultrasonic sensor's transmitter (Trig) and receiver (Echo). Add this code within the setup() function:

Notice that a digitalWrite() statement was included to ensure the transmitter is turned off (LOW) when the app first starts.

Measure Distance to Object

A custom function named measureDistance() uses readings from the ultrasonic sensor to measure the distance between the sensor and the closest object.

The measureDistance() function will return the distance as a float value (decimal). The function will return the distance in inches, but you can modify the return statement at the end of the function to return the distance in centimeters.

Your code should assign the returned distance value to a local variable, and then perform actions based on the value of the variable:

You'll need to add code to perform actions based on the distance measurement. For example, if the distance is less than 12 inches, you may want to brake the robot's motors to avoid a collision. Then you may want to change the robot's direction before driving again.

Add the measureDistance() custom function after the loop() function:

Test Ultrasonic Sensor

To test out your ultrasonic sensor, you can view distance measurements from the sensor using the serial monitor in the Arduino code editor.

Add this code statement within the setup() function:

This starts a serial data connection between your robot and your computer and sets the data transfer rate to 9600 bits per second.

Add this code within the loop() function:

Be sure to add the measureDistance() custom function after the loop() function.

After uploading the app to your robot, do not unplug the USB cable. You have to keep the robot connected to your computer to allow the serial data communication.

In your Arduino code editor, open the serial monitor, so you can view the serial data:

Arduino Create (Web Editor): Click the Monitor menu link in the left navigation to display the serial monitor in the middle panel.
Arduino IDE (Desktop Editor): Under the Tools menu, select "Serial Monitor." A new window will appear displaying the serial monitor.

It may take a few seconds for the serial connection to be detected by the editor. Then you should see the sensor measurements being displayed in the serial monitor window.

Place your hand (or an object) in front of the ultrasonic sensor, and move your hand (or the object) further or closer to see how the distance measurements change. If desired, you can use a ruler or measuring tape to verify the accuracy of the distance measurements.

Small objects (such as your hand) can be detected accurately if they are within about 24 inches. For farther distances, the object needs to be have a larger surface area to produce an accurate measurement.

Accelerometer

The accelerometer is a small circuit board that should be connected to I/O pins A4 and A5 on the main RedBot circuit board.

The accelerometer can measure:

the acceleration of the device (i.e., the device speeding up or slowing down)
the acceleration due to Earth's gravity (i.e., the orientation of the device)

However, you can use the accelerometer to detect when the robot is physically bumped – this type of change in motion is a "pulse" acceleration that is detectable by the accelerometer.

The accelerometer measures the acceleration along each axis (X, Y, Z) and then uses these measurements to calculate the robot's angle in the XZ plane, YZ plane, and XY plane.

The accelerometer measurements can be used to perform these useful robot behaviors:

The robot can detect when it is upside-down by measuring its tilt from front-to-back (pitch) and from side-to-side (roll).
The robot can detect when it has been bumped by detecting a "pulse" acceleration.

How to Code Accelerometer

To use the accelerometer in your robot app, you will need to:

Create a RedBotAccel object
Use the object's read() method to get accelerometer measurements
Add code statement(s) to perform action(s) based on the measurements

Create RedBotAccel Object

The SparkFun RedBot library has a class named RedBotAccel which defines methods (functions) to control the accelerometer.

Before the setup() function, create a RedBotAccel object by assigning it to a variable:

RedBotAccel accel;

REDBOT LIBRARY: Be sure your robot app has an #include statement for the SparkFun RedBot library. Here's how to include the RedBot library.

Read Accelerometer

The RedBotAccel object has a read() method which is used to get new accelerometer measurements for each of the 3 axes (X, Y, Z):

accel.read();

The new measurements are stored as properties of the object:

accel.x — acceleration along X axis
accel.y — acceleration along Y axis
accel.z — acceleration along Z axis
accel.angleXZ — device's angle in XZ plane (pitch)
accel.angleYZ — device's angle in YZ plane (roll)
accel.angleXY — device's angle in XY plane (yaw)

The accelerometer measures the acceleration along each axis (X, Y, Z) and then uses these measurements to calculate the device's angle in the XZ plane, YZ plane, and XY plane.

For a wheeled vehicle, pitch and roll are the most important angles to measure as they indicate the tilt of the vehicle from front-to-back and from side-to-side.

PITCH (Angle XZ)

Angle XZ represents pitch. Pitch is the front-to-back rotation on the robot's Y axis. The pitch angle can range from -180° to 180°.

If the robot is perfectly level from front-to-back, the pitch is zero (angle XZ = 0).
If the front of the robot is tilted up, the pitch is a positive value (angle XZ > 0). For example, if the front of the RedBot were pointing straight up, the pitch would be 90°.
If the front of the robot is tilted down, the pitch is a negative value (angle XZ < 0). For example, if the front of the robot were pointing straight down, the pitch would be -90°.

ROLL (Angle YZ)

Angle YZ represents roll. Roll is the side-to-side rotation on the robot's X axis. The roll angle can range from -180° to 180°.

If the robot is perfectly level from side-to-side, the roll is zero (angle YZ = 0).
If the left side of the robot is tilted up, the roll is a positive value (angle YZ > 0). For example, if the left side of the robot were pointing straight up, the roll would be 90°.
If the left side of the robot is tilted down, the roll is a negative value (angle XZ < 0). For example, if the left side of the robot were pointing straight down, the roll would be -90°.

YAW (Angle XY)

Angle XY represents yaw. Yaw is the right-to-left rotation on the robot's Z axis. The yaw angle can range from -180° to 180°.

Test Accelerometer

To test out your accelerometer, you can view the accelerometer measurements using the serial monitor in the Arduino code editor.

Add this code statement within the setup() function:

Serial.begin(9600);

This starts a serial data connection between your robot and your computer and sets the data transfer rate to 9600 bits per second.

A custom function named testAccelerometer() can be used to read the accelerometer and send (print) the measurements to your computer as serial data.

Add the testAccelerometer() function after the loop() function:

void testAccelerometer() {

  // get new accelerometer data
  accel.read();

  // send data to serial monitor
  Serial.print("Pitch: ");
  Serial.print(accel.angleXZ);
  Serial.print("\tRoll: ");
  Serial.print(accel.angleYZ);
  Serial.print("\tYaw: ");
  Serial.println(accel.angleXY);

  // brief delay before next reading
  delay(100);
}

Add this code statement within the loop() function to call the custom function:

testAccelerometer();

This should be only code statement listed within the loop() function.

After uploading the app to your robot, do not unplug the USB cable. You have to keep the robot connected to your computer to allow the serial data communication.

In your Arduino code editor, open the serial monitor, so you can view the serial data:

Arduino Create (Web Editor): Click the Monitor menu link in the left navigation to display the serial monitor in the middle panel.
Arduino IDE (Desktop Editor): Under the Tools menu, select "Serial Monitor." A new window will appear displaying the serial monitor.

It may take a few seconds for the serial connection to be detected by the editor. Then you should see the accelerometer measurements being displayed in the serial monitor window.

Follow the steps below to test your robot's pitch, roll, and yaw.

PITCH

Pitch is the front-to-back rotation on the robot's Y axis. Pitch can range from -180° to 180°.

Hold the robot in the air, and slowly rotate the robot from front-to-back to tilt the front end up. Watch the pitch value change in the serial monitor as you change the tilt. When the robot's front end is tilted straight up, the pitch will be 90°.
Rotate the robot so it is level from front-to-back. When it is level, the pitch will be 0°.
Rotate the robot so its front end is tilts down. When the robot's front end is tilted straight down, the pitch will be -90°.

ROLL

Roll is the side-to-side rotation on the robot's X axis. Roll can range from -180° to 180°.

Hold the robot in the air, and slowly rotate the robot from side-to-side, so the left side is tilted up. Watch the pitch change in the serial monitor as you change the tilt. When the robot's left side is tilted straight up, the roll will be 90°.
Rotate the robot so it is level from side-to-side. When it is level, the roll will be 0°.
Rotate the robot so its left side is tilted down. When the robot's left side is tilted straight down, the roll will be -90°.

YAW

Yaw is the right-to-left rotation on the device's Z axis. Yaw can range from -180° to 180°.

Place the robot back down on a level surface, such as your desk or table. Check the yaw value in the serial monitor.
Rotate the robot clockwise to the right, while checking the yaw value in the serial monitor. You'll notice that the yaw value changes randomly – and does not represent which direction the robot is pointed (i.e., the robot's rotation on the Z axis).
Rotate the robot counter-clockwise to the left, while checking the yaw value in the serial monitor. Again, the yaw value changes randomly – and does not represent the robot's direction.

Push Button (D12)

The RedBot mainboard has a built-in push button that can be detected by your program. The button is hardwired to pin D12 on the RedBot mainboard and is located next to the USB port.

The button can be used as a way for a user to control the robot:

The robot can in order to "start" or "pause" its task.
The robot can before performing the next step in a task.

How to Code Button

There are three different ways to use the button in your robot app:

Option 1: Read the button pin directly using the digitalRead() method
Option 2: Read the button using a RedBotButton object and its read() method
Option 3: Use a OneButton object and its tick() method to detect different types of button presses (i.e., single-press, double-press, and long-press)

Read Button Directly

To read the button pin directly, your robot app will need to:

Declare a variable to store the button pin number
Set the pin mode for the button
Use the digitalRead() method to detect whether the button is being pressed
Add code statement(s) to perform certain action(s) if the button is pressed

You'll need to create a global variable to store the pin number of the button, which is connected to pin D12. Add this code statement before the setup() function:

int button = 12;

Next, you'll need to set the button's pin mode. Add this code statement within the setup() function:

pinMode(button, INPUT_PULLUP);

INPUT_PULLUP indicates the button pin will be used for input and will use a pull-up resistor (which is something that buttons and switches typically use, but other inputs do not).

The digitalRead() method can be used to detect whether or not the button is currently being pressed. It will return a value of either HIGH or LOW:

HIGH indicates the button is NOT being pressed
LOW indicates the button is being pressed

An if statement is typically used to perform a set of actions when the button is pressed.

This code is typically added within the loop() function or within a custom function:

if (digitalRead(button) == LOW) {
    // add code to perform if button is pressed

}

Inside the if statement, you need to add code statements for the specific actions you want performed when the button is pressed.

USER FEEDBACK: It is recommended to (i.e., a beep) as feedback to the user when the button is pressed.

Alternatively, you can also include an else statement to perform a different set of actions when the button is not pressed. In this case, use this code instead:

if (digitalRead(button) == LOW) {
    // add code to perform if button is pressed

}
else {
    // add code to perform if button NOT pressed
    
}

Use RedBotButton Object

To read the button using a RedBotButton object, your robot app will need to:

Create a RedBotButton object for the button
Use the object's read() method to detect whether the button is being pressed
Add code statement(s) to perform certain action(s) if the button is pressed

Before the setup() function, create a RedBotButton object for the button by assigning the object to a variable:

RedBotButton button;

REDBOT LIBRARY: Be sure your robot app has an #include statement for the SparkFun RedBot library. .

The RedBotButton object has a read() method that can be used to detect whether or not the button is currently being pressed. It will return a value of either true or false:

true indicates the button is being pressed
false indicates the button is NOT being pressed

An if statement is typically used to perform a set of actions when the button is pressed.

This code is typically added within the loop() function or within a custom function:

if (button.read() == true) {
    // add code to perform if button is pressed

}

Inside the if statement, you need to add code statements for the specific actions you want performed when the button is pressed.

USER FEEDBACK: It is recommended to (i.e., a beep) as feedback to the user when the button is pressed.

Alternatively, you can also include an else statement to perform a different set of actions when the button is not pressed. In this case, use this code instead:

if (button.read() == true) {
    // add code to perform if button is pressed

}
else {
    // add code to perform if button NOT pressed
    
}

Use OneButton Object

Single-Press = user presses the button once
Double-Press = user presses the button twice in rapid succession
Long-Press = user presses and holds the button down

To read the button using a OneButton object, your robot app will need to:

Include the OneButton library
Create a OneButton object for the button
Designate custom functions for each type of button input
Add the code to be performed within each custom function
Use the object's tick() method to detect the type of button input

First, you must add a copy of the OneButton.h library to your code editor. This is a one-time process. , except type onebutton into the search field to find the library.

Next, you must include a copy of the OneButton library in your robot app. The following #include statement should be inserted at the beginning of your app code:

#include <OneButton.h>

Before the setup() function, create a OneButton object by assigning it to a variable and indicating its pin number and whether it will use a pull-up resistor in parentheses:

OneButton button(12, true);

  // designate custom functions for different button inputs
  button.attachClick(singlePress);
  button.attachDoubleClick(doublePress);
  button.attachPress(longPress);

If desired, you can use other names for the custom functions instead of singlePress, doublePress, and longPress. For example, you could name the functions as task1, task2, and task3.

After the loop() function, add the custom functions for each type of button input:

void singlePress() {
    // add code to perform when single-press detected

}

void doublePress() {
    // add code to perform when double-press detected

}

void longPress() {
    // add code to perform when long-press detected

}

Be sure the names of these custom functions match the names that were designated in your setup() function.

Inside each custom function, you need to add code statements for the specific actions you want performed when that type of button input is detected.

USER FEEDBACK: Within the custom functions, it is recommended to (i.e., single-beep, double-beep, or long-beep) that confirms which type of input was detected.

void loop() {
    button.tick(); // check for button input events
    // OPTIONAL: can add other code to perform

}

Wheel Encoders

Each wheel encoder actually consists of two parts:

a Hall Effect sensor that can measure the strength of a magnetic field
a ring magnet (looks like a metal washer) attached to the motor shaft

Each wheel encoder is connected to the RedBot circuit board by a 3-wire jumper cable (white, red, and black wires for data, power, and ground):

The left wheel encoder data wire should be connected to I/O pin A2
The right wheel encoder data wire should be connected to I/O pin 10

The wheel encoder counts can be used to perform to several useful robot behaviors:

The robot can by making small adjustments in the left and right motor powers to make sure both motors rotate at the same average speed.
The robot can by calculating how far the wheels have traveled. This is combined with adjusting the motor powers to drive straight.
The robot can by calculating how far the wheels have traveled while pivoting in a circle.
The robot can by calculating how far the driving wheel has traveled while turning in a circle.

Find Distance with Encoders

We can use this information to calculate how many "ticks" counted by the wheel encoder represent one revolution of the wheel:

4 ticks per motor rotation × 48 motor rotations per wheel revolution = 192 ticks per wheel revolution

C = 𝛑 × d = 3.14 × 2.56 inches = 8.04 inches per wheel revolution

So for your RedBot's wheel encoders, the following is true:

192 ticks of wheel encoder = 1 wheel revolution = 8.04 inches traveled

This information can be used to convert any encoder count into distance traveled — or to convert a desired distance into a target encoder count.

Check Encoder Positions

Visually check the position of the left and right encoder sensors. If necessary, you might need to push (or pull) a sensor to position it correctly.

How to Code Encoders

To use the wheel encoders in your robot app, you will need to:

Create a RedBotEncoder object for the wheel encoders
Use the object's clearEnc() method to clear the encoder counters (reset to zero)
Add code statement(s) to drive one or both motors
Use the object's getTicks() method to get the current encoder counts
Add code statement(s) to perform action(s) based on the encoder counts

Create RedBotEncoder Object

The SparkFun RedBot library has a class named RedBotEncoder which defines methods (functions) to control the wheel encoders.

Before the setup() function, create a RedBotEncoder object by assigning it to a variable name and indicating the pin numbers for the left and right encoders in parentheses:

RedBotEncoder encoder(A2, 10);

REDBOT LIBRARY: Be sure your robot app has an #include statement for the SparkFun RedBot library. .

Clear Encoder Counters

The RedBotEncoder object has counters to keep track of how many total magnetic "ticks" have been detected by each wheel encoder.

Before using the wheel encoders, you will typically want to clear the counters by resetting them to zero.

Use the clearEnc() function to clear the encoder counter:

encoder.clearEnc(BOTH);

Using a value of BOTH will clear both encoder counters. If necessary, you can use a value of LEFT or RIGHT to only clear a specific encoder counter.

Get Encoder Counts

// get current wheel encoder counts
long leftCount = encoder.getTicks(LEFT);
long rightCount = encoder.getTicks(RIGHT);

// add code to do something based on encoder counts

NOTE: Each encoder will count "ticks" whether its motor is driving forwards or backwards.

Test Wheel Encoders

To test out your wheel encoders, you can view the encoder counts using the serial monitor in the Arduino code editor.

Your app will need to create new objects (as global variables) for these three classes. Add these code statements before the setup() function:

RedBotMotors motors;
RedBotButton button;
RedBotEncoder encoder(A2, 10);

Add this code statement within the setup() function:

Serial.begin(9600);

This starts a serial data connection between your robot and your computer and sets the data transfer rate to 9600 bits per second.

A custom function named testWheelEncoders() can be used to get each encoder count and send (print) the counts to your computer as serial data.

Add the testWheelEncoders() function after the loop() function:

void testWheelEncoders() {

    // if button is pressed, reset encoder counters and start motors
    if (button.read() == true) {
        encoder.clearEnc(BOTH);
        motors.drive(150);
    }
    
    // get current encoder counts
    long leftCount = encoder.getTicks(LEFT);
    long rightCount = encoder.getTicks(RIGHT);

    // send data to serial monitor
    Serial.print("Left: ");
    Serial.print(leftCount);
    Serial.print("\t"); // insert tab
    Serial.print("Right: ");
    Serial.println(rightCount);

    // if either count reaches 1000, brake motors
    if (leftCount >= 1000 || rightCount >= 1000) {
        motors.brake();
    }
}

Add this code statement within the loop() function to call the custom function:

testWheelEncoders();

This should be only code statement listed within the loop() function.

After uploading the app to your robot, do not unplug the USB cable. You have to keep the robot connected to your computer to allow the serial data communication.

IMPORTANT: Be sure the robot is standing upright on its back end (with its wheels in the air), so the robot won't drive way while it's connected to your computer.

In your Arduino code editor, open the serial monitor, so you can view the serial data:

Arduino Create (Web Editor): Click the Monitor menu link in the left navigation to display the serial monitor in the middle panel.
Arduino IDE (Desktop Editor): Under the Tools menu, select "Serial Monitor." A new window will appear displaying the serial monitor.

You'll notice that the wheel encoder counts do not stop exactly at 1000. This is normal because it takes a brief amount of time for the motors to brake. The final counts should probably be between 1000-1050.
You'll probably notice that your left and right wheel encoder counts are not exactly the same. This is normal — they should be close to each other (within about 25), but they probably won't be identical.
If one or both wheel encoders are not working properly (the count stays at zero), turn off the robot's power, and check the encoder sensor position(s). After correcting the sensor position(s), turn the robot's power back on and test again.