Your RedBot robot has other useful components, which can be categorized as either physical inputs or physical outputs.

Physical inputs (such as sensors, etc.) are components that gather data from the physical environment. The D12 push button on the circuit board and the wheel encoders are both examples of physical inputs. Most of the other components on your RedBot are physical inputs that help the robot sense its environment.

Physical outputs (such as motors, etc.) are components that can perform some action in the physical environment. The D13 LED light on the circuit board and the motors are both examples of physical outputs. The only other component on your RedBot that is a physical output is its speaker.

Speaker

The RedBot has a small speaker (labeled as a "buzzer") that should be attached to I/O pin 9 on the circuit board.

This speaker can produce simple sounds. The speaker can only play one tone (sound) at a time, but you can create different sounds or sound patterns. You could even program it to play simple music by playing one note at a time.

Sounds can be useful as audio alerts or feedback to people interacting with your robot.

Mechanical Bumpers

The RedBot has two mechanical bumpers (left and right) at its front to detect collisions 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

IR Line Sensors

The RedBot has three IR line sensors (left, center, and right) mounted at its front close to the surface. The bottom of each line 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 reflects more IR light, while a dark-colored surface reflects less IR light.

• If the surface is farther away from the sensor, the IR light becomes more scattered, and less IR light will be reflected back to the detector. Even a small increase in the distance between the sensor and the surface will significantly reduce the amount of reflected IR light.

There are several robot behaviors that can be performed using the IR sensors:

• The IR sensors can be used to make the robot follow a line by adjusting the left and right motor powers to keep the robot centered on the line as it drives.

• The IR sensors can be used to make the robot avoid a line by turning away from a detected line. In this case, lines act as "borders" to keep the robot inside (or outside) a certain area or path.

• The IR sensors can be used to count line markers that the robot crosses while driving and then make the robot stop or turn once it reaches a desired line number.

• The IR sensors can be used to avoid driving over a drop-off by stopping the motors if the IR sensor measurements are too high (which may indicate the front edge of the robot is hanging over a drop-off, such as the edge of a table, a stair step leading down, a hole in the surface, etc.).

Detecting lines with the IR sensors works best with a dark line on a uniform light surface (or vice versa). The line also needs to be the right width: not too wide – but not too narrow. A line width between 0.5—0.75 inch is ideal.

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

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. For example, smartphones use accelerometers to detect the phone's orientation, and then the phone changes the screen orientation to match how the phone is being held.

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 represents pitch. Pitch is the front-to-back rotation on the device's Y axis. The pitch angle can range from -180° to 180°.

• If the RedBot is perfectly level from front-to-back, the pitch is zero (angle XZ = 0).

• If the front of the RedBot is rotated 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 RedBot is rotated down, the pitch is a negative value (angle XZ < 0). For example, if the front of the RedBot were pointing straight down, the pitch would be -90°.

ROLL

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

• If the RedBot is perfectly level from side-to-side, the roll is zero (angle YZ = 0).

• If the left side of the RedBot is rotated up, the roll is a positive value (angle YZ > 0). For example, if the left side of the RedBot were pointing straight up, the roll would be 90°.

• If the left side of the RedBot is rotated down, the roll is a negative value (angle XZ < 0). For example, if the left side of the RedBot were pointing straight down, the roll would be -90°.

YAW

Angle XY represents yaw. Yaw is the right-to-left rotation on the device's Z axis. The yaw angle can range from -180° to 180°. However, when the RedBot 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.)

Ultrasonic Sensor

An ultrasonic sensor uses sonar to measure the distance ahead to the closest object in the robot's path. This can be used to avoid collisions with obstacles. This is similar to how bats and dolphins use echolocation for navigation and hunting.

The ultrasonic sensor has a transmitter (i.e., a speaker) that can produce high-frequency sound, which cannot be heard by the human ear. The sensor also has a receiver (i.e., a microphone) that detects the echo of the high-frequency sound when it is reflected back from a nearby object. By measuring how much time it takes for the echo to arrive, you can calculate the distance between the sensor and the closest object.

This 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 distance measurements from the sensor are very accurate, within about 3 mm (about 0.1 inch) of the actual distance.

The primary use of the ultrasonic sensor is to prevent collisions. If the sensor detects a nearby obstacle in the path ahead, the robot can be programmed to avoid the obstacle by stopping or turning. You could even use this sensor to program your robot to navigate a maze on its own.

However, the ultrasonic sensor might not detect obstacles off to the left side or right side — if those obstacles are outside the 15° detection cone directly in front of the sensor. For these situations, you may want to use the mechanical bumpers as a fallback system to supplement the ultrasonic sensor. Since the mechanical bumper whiskers extend outwards on both sides, they can detect a collision with an obstacle that the ultrasonic sensor might not detect (as shown below).

The ultrasonic sensor should be connected to the RedBot circuit board by a 4-wire jumper cable (will be different colors – two wires are for data, one is for power, and one is for ground):

• The transmitter data wire (Trig) should be connected to I/O pin A0.

• The receiver data wire (Echo) should be connected to I/O pin A1.

You will use an Arduino code editor (also called an IDE – Integrated Development Environment) to create and save your Arduino apps for your robot. You'll also use the code editor to upload apps to your robot, in order to actually run them.

Follow these instructions to set up an Arduino code editor on your computer. There are two options: you could use the Arduino Create web editor or the Arduino IDE desktop editor. Check with your teacher to see which editor you should set up.

Once your Arduino code editor is ready to use, go on to the next step in this tutorial.

This Robotics Code Guidebook is a supplement to the Robotics Project Guidebook.

What's in this Guidebook?

This guidebook contains a series of robotics code tutorials to help you get familiar with programming your robot to perform different behaviors and tasks.

In addition, this guidebook contains coding references to explain how to add code in your robot app to control its physical inputs and outputs. There are also coding references for different robot behaviors and navigation modes.

Finally, this guidebook also contains links to external resources, such as an online Arduino code editor (web IDE) for creating your robot apps, programming language references, and additional experiments for learning how to use the robot.

// example code block

void setup() {
​
}
​
void loop() {
​
}

Your Robotics Kit

This guidebook is tailored for a two-wheeled robotics kit called the SparkFun Inventor's Kit for RedBot, which will simply be referred to as the RedBot.

SparkFun sells other sensors and actuators that may be compatible the RedBot. If possible, it is highly recommended to add an ultrasonic sensor to the RedBot for more design possibilities. This sensor is inexpensive and can be easily connected to one of the unused set of pins on the RedBot circuit board.

Copyright and License

Copyright © 2017-2021 Michael Frontz and Jim Lyst, Indiana University School of Informatics and Computing at IUPUI

This material is part of the Computing by Design high school computer science curriculum developed for the Informatics Diversity-Enhanced Workforce (iDEW) program, an award-winning community partnership in central Indiana that is broadening student participation in computing and helping students develop the skills essential for success in the 21st century workplace. The iDEW program is managed by the Indiana University School of Informatics and Computing at IUPUI.

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. You are free to use, share, or adapt this material for noncommercial purposes as long as you provide proper attribution and distribute any copies or adaptations under this same license.

Motors and Wheels

The RedBot is a two-wheeled robot. It also has a semi-circular plastic "nub caster" on the underside of its chassis at the back. This caster acts as a third point of contact to balance the robot (similar to a third wheel, except the caster doesn't rotate).

Each wheel is driven by its own motor, which is connected to the RedBot circuit board by a pair of red and black wires. These left and right motors can be controlled as a set or independently, in order to make the robot drive forward, backwards, or make turns.

You can also determine how much power each motor receives, in order to rotate the wheels faster or slower, to control the speed of your robot as it drives and turns.

Wheel Encoders

Located directly behind each wheel motor is a wheel encoder. The wheel encoder is used to count exactly how many times that motor has rotated. These wheel encoder counts can be used to:

• make the robot drive in a straight line (by adjusting the motor powers if one motor happens to be rotating slightly faster than the other)

• calculate how far the robot has driven (by determining how many times the wheel has turned and multiplying that by the wheel circumference)

The 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.

So 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.

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 encoders are one of the most useful sensors on your robot because they can allow your robot to drive straight for specific distances and to make turns of specific angles (such as: 90° right, 90° left, 180° around, etc.).

In this first tutorial, you'll become familiar with your team's robotics kit. Your team might receive a new robotics kit that needs to be assembled – or you might receive an existing robot that is ready to use.

Tutorial Goals

The goals of this tutorial are to help you:

• Understand the parts of your robot and their purposes

• Identify the physical inputs and outputs that your robot can use to sense and act

RedBot Kit

This guidebook is tailored for a two-wheeled robotics kit called the SparkFun Inventor's Kit for RedBot, which will simply be referred to as the RedBot kit.

​SparkFun is a company that sells products to help people build and program electronics devices. SparkFun created its RedBot kit by incorporating an Arduino-based microcontroller into an easy-to-use circuit board and packaged it with a set of motors, wheels, sensors, and other parts to help you learn how to program a wheeled robot. It is also possible to purchase additional parts (sensors, servo motors, etc.) that can be used with this RedBot kit.

Once assembled, your RedBot should look like this:

A simple (but important) step is to understand the orientation of the RedBot — specifically, which end is the front of the robot? An easy way to remember: most of the sensors are attached at the front end, while the circuit board is located at the back end.

If you have an ultrasonic sensor, it should be mounted at the front of the robot on top of the chassis (above the mechanical bumpers and IR line sensors). The ultrasonic sensor should face forward, like a pair of "eyes" (though an ultrasonic sensor actually uses high-frequency sound waves to "see").

Next you'll add commands in your app code to turn the LED on and off in a repeating pattern.

Turn On LED

Your app can receive signals from inputs using the digitalRead() or analogRead() methods, depending on whether the values being received will be digital or analog.

Your app can send signals to outputs using the digitalWrite() or analogWrite() methods, depending on whether the values being sent will be digital or analog.

The LED can be controlled as a digital output that is either "on" or "off".

You'll need to send an "on" signal to the LED pin, in order to turn on the LED light. Add this code statement within the loop() function (between the curly braces):

The digitalWrite() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: 13, etc.) or a variable that stores a pin number. In this case, the variable LED is listed (which has a value equal to 13).

2. The signal value, which can be HIGH or LOW. Your RedBot uses this value to send an electrical signal through the pin: HIGH is a signal of 5 volts which represents "on," while LOW is a signal of 0 volts which represents "off." In this case, the signal was set to HIGH because you want to turn on the LED light.

Add Time Delay

You'll want to leave the LED turned on for a certain amount of time before you send the "off" signal.

Because the RedBot's app code runs very fast, there will be certain situations where you'll want to insert delays into the code, in order to allow time for certain events to occur.

Your app can use the delay() method to insert a time delay. It acts like a timer that makes the app wait before performing the next line of code.

You'll need to add a delay after the LED has been turned on. Add this code statement (as a separate line of code) within the loop() function (after the digitalWrite() statement):

The delay() method requires one parameter inside its parentheses:

• The time value, which can be an integer number (whole number) or a variable that stores an integer. The value represents the number of milliseconds for the time delay (1000 ms = 1 second). In this case, the delay was set to 500 ms (0.5 second).

Turn Off LED

Next, you'll send an "off" signal to the LED pin. Add this code statement (as a separate line of code) within the loop() function (after the delay() statement):

You can see that the second parameter in this digitalWrite() statement was set to LOW, which represents "off" for a digital output.

Add Another Delay

When all the code within the loop() function has been performed, the loop() will automatically repeat itself. Since the first line of code in your loop() turns on the LED, you'll want to add another delay to leave the LED turned off for a brief amount of time before the loop() repeats itself (which will start by turning the LED back on again).

Add this code statement (as a separate line of code) within the loop() function (after the second digitalWrite() statement):

At this point, the code within your loop() function should perform these actions (in order):

1. Turn On LED light

2. Wait 0.5 second

3. Turn Off LED light

4. Wait 0.5 second

5. Repeat

This represents all the code needed for your first version of the "Hello World" app. In the next step, you'll upload the app to your robot to test it out.

Circuit Board

The SparkFun RedBot kit contains a printed circuit board (PCB) that incorporates an ATmega328P microcontroller, which will act like the “brain” of your robot. SparkFun refers to this circuit board as the RedBot mainboard.

A microcontroller is a small computer on a single integrated circuit that contains a processor (CPU), memory, storage, and programmable input/output pins.

Compared to the tech specs of a "regular" computer, a microcontroller is much less powerful – it has a slower processor, less memory, and less storage. This is because microcontrollers are used in devices that have dedicated functions (such as: automobile engine control systems, medical devices, office machines, appliances, etc.). These dedicated devices typically don’t require as much computing power to perform their specialized tasks.

The RedBot circuit board also has various pins, ports, buttons, switches, and LED lights. Wires from different inputs (such as: sensors, etc.) and outputs (such as: motors, etc.) are connected to the pins on the circuit board to create a functional robot. You control the robot by programming an app that will run on the microcontroller.

• ATmega328P Microcontroller: controls entire robot and runs robot's app

  • Processor: 8-bit 20Mhz AVR

  • Memory: 2KB RAM

  • Storage: 32KB Flash

  • Input/Output: supports up to 23 general-purpose I/O pins

• TB6612FNG Dual DC Motor Driver Chip: used to control the two wheel motors

• FTDI FT232R USB Chip: used to send and receive data through the USB port

• Input/Output Pins: used to connect wires for inputs (sensors, etc.) and outputs (speaker, etc.)

  • These I/O pins are in groups labeled as "Sensor" or "Servo" – each group has 6 pins, representing a set of 3 pins on the left and another set of 3 pins on the right.

  • Each set of 3 pins has one pin for input/output of data, a second pin for power (5V = positive), and a third pin for ground (GND = negative). Typically, a white wire connects to the I/O pin, a red wire connects to the 5V pin, and a black wire connects to the GND pin.

  • The "Sensor" I/O pins are numbered as: A0, A1, A2, A3, A4, A5, A6, A7.

  • The "Servo" I/O pins are numbered as: 3, 9, 10, 11.

  • There are also I/O pins connected directly to a LED light (pin D13) and push button (pin D12).

• Motor Pins: used to connect wires for left and right motors (which are a type of output)

• Power Supply Jack: used to provide power to robot (by plugging in barrel jack from battery pack)

• Mini USB Port: used to connect robot to computer (either to download new app from computer or to send serial data to computer)

• LED Lights:

  • Power LED: Green LED that indicates the robot is powered on

  • D13 LED: Green LED that can be controlled by your robot's app

  • TX and RX LEDs: Green LEDs indicating data transfer between robot and computer

• Buttons:

  • Reset Button: Restarts your robot's app (similar to turning robot off and back on)

  • D12 Button: Robot's app can be coded to detect if this button is pressed

• Switches:

  • Power Switch (OFF/ON): used to turn robot off or on (be sure to turn off robot before storing to conserve battery power)

  • Motor Switch (STOP/RUN): normally should be set to RUN, but can temporarily set to STOP to stop motors (but robot's app will continue to run if power is on)

  • XBee Serial Mode Switch (HW/SW): used to set XBee serial communication mode (leave this set to HW – unless you're using an XBee wireless antenna module)

Robot Firmware and App

Unlike other computers, a microcontroller is designed to store and run only one app at a time. The app determines what actions the robot will perform. Whenever the robot is powered on, the robot's app will automatically start and will run in a continuous loop.

If you need to change your robot's app, the new app has to be downloaded over USB (and will replace the old app). Later, you will complete several practice tutorials to learn how to program and download apps that control your robot's actions.

Let's add a variable in your app code to represent the built-in LED light.

Add Global Variable for LED

Your "Hello World" app will make the RedBot circuit board's built-in green LED light turn on and off in a blinking pattern. This will be accomplished by sending separate "on" and "off" signals to the LED's pin.

Each I/O pin on the RedBot circuit board is identified by a pin number (such as: A0, A1, A2, 3, 9, 10, etc.). In this case, the RedBot's built-in green LED light is connected to pin D13 (via internal circuitry).

When coding an Arduino app, you will typically create global variables to store the pin numbers for the inputs and outputs connected to your circuit board that you want to control. This will help make your code easier to understand because the variable names help identify each input or output.

You'll need to "declare" (create) a global variable to store the pin number of the built-in LED. Add this code statement to your app by inserting it (as a separate line of code) before the setup() function:

This code statement does 3 things (in order):

1. It declares a data type for the variable's value. In this case, int stands for integer (whole number). Arduino pin numbers are always treated as int values (even if they contain letters).

2. It declares the variable's name. In this case, the variable will be called LED. You get to decide what to name your variables. Choose names that will make sense to anyone reviewing your code.

3. It assigns a value to the variable. In this case, the variable's value will be equal to 13, which is the pin number for the RedBot's built-in LED light.

Notice that this code statement ends with a . Typically, each code statement in your app will end with a semi-colon. The semi-colon separates code statements, similar to how periods separate sentences in written English.

• The exceptions to ending with a semi-colon are certain statements (such as functions, conditionals, loops, etc.) that use to enclose other code statements. However, within the curly braces, each code statement will end with a semi-colon.

Although you can actually list multiple code statements on the same line (because their semi-colons will separate them), each code statement is traditionally listed on its own separate line to make it easier to read the code.

Save Your App Code

The Arduino code editor does NOT autosave as you type, so be sure to periodically save your code.

Arduino Create (Web Editor)

At the top of the code editor panel, hover your mouse cursor over the button with 3 dots, and then select "Save" from the pop-up menu.

Arduino IDE (Desktop Editor)

Under the File menu, select "Save" – alternatively, you can click the Save icon (looks like a downward arrow) at the top of the code editor window.

Tips for Naming Variables

You get to decide what to name each variable in your app's code. However, here are a few rules and recommendations to help you name your variables:

RULES

• Each global variable must have a unique name.

• Variable names must be one word (no spaces allowed).

• Variable names can contain lowercase letters, uppercase letters, numbers, and certain special characters (such as underscores, etc.) – but the name cannot start with a number.

RECOMMENDATIONS

• Make each variable's name concise yet descriptive, so it will be easy to read and understand.

  • Example of variable name that's concise yet descriptive: LED

  • Example of variable name that's too concise: L

  • Example of variable name that's too descriptive: greenD13LEDlight

• • Examples of variable name using underscore: push_button

  • Examples of variable name using camelCase: pushButton

• If you have multiple inputs or outputs of the same type (mechanical bumpers, IR line sensors, etc.), add an adjective (or number) to their variable names to help identify them in your app code.

  • Examples of variable names using adjectives: leftBumper, rightBumper

Next you'll add a command in your app code to designate the LED pin as an output.

Set Pin Mode for LED

A variety of inputs and outputs can be connected to the I/O pins on your RedBot circuit board. Your app code needs to identify which I/O pins you are using and whether each of these pins will be used for an input or output. This is referred to as setting the pin modes.

Setting the pin modes for your inputs and outputs only needs to occur one time when your app first starts to run, so the code statements to do this should be added within the setup() function.

So you'll need to set the pin mode for the built-in LED that you'll be using. Add this code statement within the setup() function (between the curly braces):

The pinMode() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: 13, etc.) or a variable that stores a pin number. In this case, the variable LED is listed (which has a value equal to 13).

2. The mode value, which can be INPUT, INPUT_PULLUP, or OUTPUT. Your RedBot uses this value to change the electrical behavior of the pin, so the pin can either receive signals from an input or send signals to an output. In this case, the mode was set to OUTPUT because your app will be sending "on" and "off" signals to the LED light.

At this point, your app code should look similar to this:

Notice that the pinMode() statement shown in the app code above is indented (using the tab key). This is a useful practice when adding code statements within curly braces because it helps make the code easier to read and understand – especially if your app contains many code statements nested within each other.

Verify Your App Code

The Arduino code editor does NOT check your code syntax as you type, so be sure to periodically verify your code to check for errors. You can verify your code even if you're not done creating your entire app.

Verify your app code by clicking the Verify icon (looks like a checkmark) at the top of the code editor panel. (The Arduino code editor will first save your code before verifying it.)

After the verification is done, a message will appear in a status bar at the bottom of the code editor panel:

• If your code compiled without any errors, the status bar will display a success message. (In the web editor, the message will say "Success." In the desktop editor, the message will say "Done compiling.")

• If your code contains an error, the status bar will display an error message with a description of the error, and the code editor will highlight the specific line number in your code where the error was detected (although the actual cause of the error usually occurs on a previous line). You'll want to fix the error and then try verifying your code again.

In this second tutorial, you'll program a "Hello World" app for your robot by using its LED light, speaker, and push button.

Tutorial Goals

The goals of this tutorial are to help you:

• Understand how to use the Arduino programming language to code apps for your robot

• Program a Hello World app that controls your robot's LED light, speaker, and push button

Arduino Programming Language

The RedBot robot runs apps written in a programming language called . The Arduino language is designed to make it easier to write programs for microcontrollers. Many electronic kits and robotics kits use Arduino for programming.

Arduino is actually a code library written in another computer language called (similar to how jQuery is a code library written in JavaScript). If and when necessary, your Arduino program can also incorporate code written directly in C++.

An Arduino program (or app) is also referred to as a sketch because the Arduino language is designed to allow you to quickly create a program — just like a sketch is a quick drawing.

These tutorials will introduce you to some of the basics of programming with Arduino. For additional help, the is useful for learning more about the structure and syntax of Arduino code.

What is a Hello World app?

When learning a new programming language, the first step that many people take is to create what is called a program. Traditionally, this program simply displays the text "Hello World" on the screen and only requires a few lines of code. The purpose is to demonstrate that you can create a simple yet functional program in the new coding language. It's a first step before creating more complex programs.

However, your robot does not have a built-in screen. The good news is your RedBot circuit board does have a built-in green LED light (D13) that can be controlled by your robot's app. So you'll first program a simple app that makes the built-in LED blink on and off repeatedly, as a way of saying "Hello World."

After that you'll modify the app to use the robot's speaker to produce a "beep" sound when the LED light blinks. Then you'll modify the app to detect when the built-in button (D12) on the circuit board is pressed, in order to make the LED blink and the speaker beep. Once all that is done, you'll start programming apps to make your robot drive around.

In this third tutorial, you'll learn how to make your robot drive and turn by using its motors and wheel encoders.

Tutorial Goals

The goals of this tutorial are to help you:

• Program robot apps that use the motors and wheel encoders to drive and turn precisely

Next, you'll code an app to make your robot turn 90° right. Then you'll modify the app so the robot turns 90° left and turns 180° around.

Save Copy of App With New Name

In your Arduino code editor, use the "Save As" command to save a copy of your existing driving_test app as a different app named: pivot_test

If necessary, here are instructions for how to save a copy of an app with a new name.

Once you saved the new app name, modify the block comment near the beginning of the app code to change Driving Test to Pivot Test.

Turn Right

The most common types of turns needed for robot navigation are: turn 90° right, turn 90° left, and turn 180° around.

The RedBotMotors class defines a method named pivot() that can be used to turn the robot either clockwise or counter-counterclockwise. The pivot() method turns the robot by driving both motors in opposite directions.

There are other ways to turn your robot, but the pivot() method results in a perfectly tight turn because the robot's axis of rotation is centered between its wheels. Pivoting is the best way to turn the robot when space is limited (as it will be in your robot demonstration environment).

When the motors.pivot() method is used in your code, the motors will start and will keep pivoting continuously. You'll use a delay() statement to allow the motors to pivot for a certain amount of time before turning the motors off with the motors.brake() method.

First, modify the "Press to Start" code within the if statement in the loop() function to remove the existing code statements that make the robot drive forward and then backward.

Next, you'll add new code so that when the robot's button is pressed, the robot will drive forward for 1.5 seconds (about 2 feet), turn 90° right, and then drive forward for another 1.5 seconds. Add this new code within the if statement in the loop() function (after the noTone() statement):

    motors.drive(200);
    delay(1500);
    motors.brake();

    motors.pivot(100);
    delay(650);
    motors.brake();

    motors.drive(200);
    delay(1500);
    motors.brake();

The motors.pivot() method requires one parameter inside its parentheses:

• The motor power, which can be any integer (whole number) between -255 and 255. A positive power pivots the robot clockwise (to the right), and a negative power pivots the robot counter-clockwise (to the left). A larger absolute power produces a faster pivot speed (-255 and 255 are the fastest speeds, while -1 and 1 are the slowest speeds). In this case, the power will be 100.

The second delay() of 650 milliseconds (0.65 seconds) is an estimate of how much time it will take your robot to pivot 90 degrees. You may have to change this value after testing your robot.

Upload App to Robot

Follow the steps to upload the app to your robot:

1. Connect Robot to Computer

2. Turn on Robot Power

3. Select Correct Board and Port

4. Upload App to Robot

Unplug the USB cable from the robot, and place the robot on the floor. Be sure an area of about 3 feet square in front and to the right of the robot is clear of any obstacles.

• Press the D12 button on your robot's circuit board. Your robot should beep and then drive forward for 1.5 seconds (about 22 inches). Then the robot should pivot 90° right, and then drive forward for another 1.5 seconds (about 22 inches).

Test out your robot's app several times to see how close the pivot is to a 90° right turn.

In the app code, the second delay() of 650 milliseconds (0.65 seconds) is an estimate of how much time it will take your robot to pivot 90 degrees. You may have to change this value based on your testing:

• If your robot is pivoting less than 90°, increase the pivot delay() time slightly (such as: 700 ms).

• If your robot is pivoting more than 90°, decrease the pivot delay() time slightly (such as: 600 ms).

If you do change the pivot delay() time, upload the modified app to your robot, and test it again with the new value. You may need to change the value several times to fine-tune your results.

Later in this tutorial, you'll learn how to use the wheel encoders to measure how far the wheels have turned, in order to make the robot pivot by a specific angle.

Turn Left

Next, you'll modify the app code so your robot will pivot 90° left. To do this, you simply need to make the robot pivot counter-clockwise by using a negative motor power.

Modify the motors.pivot() statement so the motor power is -100 (instead of positive).

You don't need to change the pivot delay() time because the amount of time to pivot 90 degrees should be the same whether the robot is pivoting clockwise (to the right) or counter-clockwise (to the left).

Upload the modified app to your robot.

Unplug the USB cable from the robot, and place the robot on the floor. Be sure an area of about 3 feet square in front and to the left of the robot is clear of any obstacles.

• Press the D12 button on your robot's circuit board. Your robot should beep and then drive forward for 1.5 seconds (about 22 inches). Then the robot should pivot 90° left, and then drive forward for another 1.5 seconds (about 22 inches).

Test out your robot's app several times to see how close the pivot is to a 90° left turn.

Turn Around

Next, you'll modify the app code so your robot will pivot 180° to turn around. To do this, you simply need to allow the robot to pivot for twice the amount of time as a 90° pivot.

For a 180° turn, it doesn't matter if the robot pivots clockwise or counter-clockwise. So you can either leave the motor power in the motors.pivot() statement as -100 (counter-clockwise) — or you can change the power back to 100 (clockwise).

Modify the pivot delay() time so its value is twice the amount that was needed for a 90° turn. For example, if the time required for a 90° turn was 650 milliseconds, try 1300 ms for a 180° turn.

Upload the modified app to your robot.

Unplug the USB cable from the robot, and place the robot on the floor. Be sure a path of about 3 feet in front of the robot is clear of any obstacles.

• Press the D12 button on your robot's circuit board. Your robot should beep and then drive forward for 1.5 seconds (about 22 inches). Then the robot should pivot 180° around, and then drive forward for another 1.5 seconds (about 22 inches), returning approximately to its starting point.

Test out your robot's app several times to see how close the pivot is to a 180° turn. You may have to adjust the pivot delay() time in the app code, and re-upload the app to test again.

Let's upload your "Hello World" app to your robot to see if it works.

Connect Robot to Computer

Your RedBot kit should have a USB to Mini-USB cable that allows you to connect the robot to a computer, in order to update the robot's app (or to send serial data to the computer).

Carefully plug the small end of this cable into the Mini-USB port on your RedBot circuit board. Plug the other end of the cable into a USB port on your computer.

Turn On Robot Power

Your RedBot is powered by a battery pack containing 4 AA batteries. Be sure the battery pack cable is plugged into the barrel jack on your RedBot circuit board.

Slide the RedBot's Power switch to ON. The RedBot's green Power LED light should turn on.

Select Correct Board and Port

In order to upload your app to your robot, the code editor must know which type of Arduino board your robot has and which USB port on your computer that the robot is connected to.

If you previously selected your Arduino board type (which should be "Arduino/Genuino Uno"), the code editor should remember this selection.

Arduino Create (Web Editor)

1. Click "Select Other Board & Port" in the drop down menu at the top of the code editor panel.

2. In the pop-up, verify that "Arduino/Genuino Uno" is selected, and then select the correct USB port that your robot is connected to. Finally, click the OK button.

   • On Mac, the correct port should include "usbserial" as part of its name.

   • On Windows, there should be one or more numbered COM ports listed. You may have to select one, try uploading your app — and then if the app won't upload, switch to another COM port instead until you identify the correct port.

Arduino IDE (Desktop Editor)

Under the Tools menu, verify that "Arduino/Genuino" is selected in the Board sub-menu, and then select the correct USB port in the Port sub-menu:

• On Mac, the correct port should include "usbserial" as part of its name.

• On Windows, there should be one or more numbered COM ports listed. You may have to select one, try uploading your app — and then if the app won't upload, switch to another COM port instead until you identify the correct port.

Once you've selected the correct port, the code editor should remember this selection while you keep the code editor open. However, if you close the code editor, you'll have to select the correct port again the next time you open and use the code editor.

Upload App to Robot

Click the Upload icon (looks like a right arrow) at the top of the code editor panel. The code editor will automatically save and verify the app before uploading it to your robot.

During the upload process, you may notice two other green LED lights (labeled TX and RX, located next to the Mini USB port) blinking rapidly as the app code is transferred to the robot.

Once the upload is complete, the new app will immediately start running on your robot.

Confirm App Works

Confirm that the built-in green D13 LED light blinks on and off in a repeating pattern (changing every 0.5 second).

Arduino devices, such as the RedBot, can only store and run one app at a time. If you want to change the app running on your robot, you have to upload a different app from your code editor to the robot.

Modify App and Upload to Robot

Next, try modifying the code within the loop() function to make the LED blink faster (Hint: use shorter delays).

Upload your modified app to your robot to see if your changes worked as you expected.

Then modify the code to make the LED blink slower. Then upload your modified app to your robot to see if it works.

As your last step of this tutorial, you'll modify the "Hello World" app so your robot's LED and speaker will "blink" and "beep" whenever the D12 button on the robot's circuit board is pressed.

Add Global Variable for Button

You'll need to create a global variable to store the pin number of the RedBot's built-in button, which is connected to pin D12 (via internal circuitry)

Add this code statement before the setup() function:

int button = 12;

Your code should now have three separate code statements before the setup() function to declare a global variable for the LED, a global variable for the speaker, and a global variable for the button.

Set Pin Mode for Button

The button is an example of an input because your app will use it to receive data (i.e., to detect when someone presses the button). So you'll need to set the pin mode for the button to be an input.

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).

Your code should now have three separate code statements within the setup() function to set the pin mode for the LED, set the pin mode for the speaker, and set the pin mode for the button.

Check If Button Pressed

Your app can receive signals from inputs using the digitalRead() or analogRead() methods, depending on whether the values being received will be digital or analog.

The button can be read as a digital input that is either "pressed" or "not pressed."

Your app will need to use an if statement and the digitalRead() method to check if the button is being pressed. Add this code within the loop() function (before the first digitalWrite() statement that turns on the LED):

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

The digitalRead() method requires one parameter insides its parentheses:

1. The I/O pin number, which can be the actual pin number (such as: 12, etc.) or a variable that stores a pin number. In this case, the variable named button is listed (which has a value equal to 12).

The digitalRead() method will check the button and return a value of either HIGH or LOW:

• HIGH indicates the button is NOT currently pressed.

• LOW indicates the button is currently pressed.

An if statement checks whether a specific condition (listed insides its parentheses) is true or false.

In this case, the condition being checked is whether the value returned from digitalRead(button) is equal to LOW:

• If this condition is true, the app will perform whatever code statements are listed within the curly braces of the if statement.

• If this condition is false, the app will not perform the code statements within the curly braces of the if statement.

Here's what we want to happen: if the button is pressed, the LED will blink and the speaker will beep at the same time.

To do that, you're going to move the existing code statements in the loop() that make the LED blink and speaker beep, so those code statements are now listed within the curly braces of the if statement.

1. Select the code statements to be moved, cut them (choose "Cut" from Edit menu – or press Control-X on keyboard), and then paste them in their new location (choose "Paste" from Edit menu – or press Control-V on keyboard).

2. You may want to use the tab key to indent the code statements that you moved (so it is more visually clear that they are contained within the curly braces of the ifstatement).

3. Modify the second delay() method, so the delay is 200 milliseconds. This will act as a 0.2 second pause between each check of the button (to allow sufficient time for a person to release the button, so the code doesn't read a single button press as if it were multiple presses).

Just for reference, here's what your loop() function should now look like:

void loop() {
  // put your main code here, to run repeatedly:
  if (digitalRead(button) == LOW) {
    // add code to perform when button is pressed
    digitalWrite(LED, HIGH);
    tone(speaker, 2000);
    delay(200);
    digitalWrite(LED, LOW);
    noTone(speaker);
    delay(200);
  }
}

Upload Modified App to Robot

Upload the modified app to your robot, confirm that it works correctly.

The robot's LED and speaker should briefly blink and beep (in sync) only when you press the D12 button on the RedBot circuit board.

If your teacher requires you to submit a file containing your completed "Hello World" app code, follow these instruction to download a copy of your app.

In the next tutorial, you'll program apps to make your robot drive around and make turns.

Next, you'll modify the "Hello World" app so your robot makes a "beep" sound with its speaker whenever the D13 LED blinks.

Add Global Variable for Speaker

You'll need to create a global variable to store the pin number of the speaker (buzzer) that should be connected to I/O pin 9 on the RedBot's circuit board.

Add this code statement before the setup() function:

int speaker = 9;

Your code should now have two separate code statements before the setup() function to declare a global variable for the LED and a global variable for the speaker.

Set Pin Mode for Speaker

Like the LED light, the speaker is also an output because your app will send signals to the speaker to produce sound. So you'll need to set the pin mode for the speaker to be an output.

Add this code statement within the setup() function:

pinMode(speaker, OUTPUT);

Your code should now have two separate code statements within the setup() function to set the pin mode for the LED and set the pin mode for the speaker.

Produce Tone (Sound)

The speaker can only play one tone (sound) at a time. The tone() method is used to produce a sound of a specific frequency (pitch).

Add this code statement (as a separate line of code) within the loop() function (after the first digitalWrite() statement, which turns on the LED):

tone(speaker, 2000);

The tone() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number of the speaker, which can be the actual pin number (such as: 9, etc.) or a variable that stores a pin number. In this case, the variable speaker is listed (which has a value equal to 9).

2. The frequency for the tone, which can be an integer value (whole number) or a variable that stores an integer. The frequency value can be between 20-20000 hertz. Lower numbers will have a lower pitch, while higher numbers will have a higher pitch. In this case, the frequency will be 2000 hertz.

Stop Tone

When you use the tone() method in your app code to produce a sound, the speaker will keep playing the sound until you use a separate method in the code to stop the sound.

Let's stop the speaker sound when the LED is turned off.

Add this code statement (as a separate line of code) within the loop() function (after the second digitalWrite() statement, which turns off the LED):

noTone(speaker);

The tone() method requires just one parameter inside its parentheses:

1. The I/O pin number, which can be the actual pin number (such as: 9, etc.) or a variable that stores a pin number. In this case, the variable speaker is listed (which has a value equal to 9).

Modify Delay Times

Modify the first delay() method within the loop() function, so the delay will be 200 milliseconds. This will allow the LED and speaker to blink and beep for only 0.2 seconds.

Modify the second delay() method within the loop() function, so the delay will be 1500 milliseconds. This will create a 1.5 second pause between each blink/beep.

Upload Modified App to Robot

If your robot is still connected to your computer and powered on, you should be able to upload the modified app by clicking the Upload icon (looks like a right arrow) at the top of the code editor panel. The code editor will automatically save and verify the app before uploading it to your robot.

Otherwise, if you disconnected your robot from your computer, be sure to:

1. Connect Robot to Computer

2. Turn on Robot Power

3. Select Correct Board and Port

4. Upload App to Robot

Once the modified app is uploaded to your robot, confirm that it works correctly. The robot's LED and speaker should briefly blink and beep (in sync) in a repeating pattern (with 1.5 second pause between each blink/beep).

First, you'll code an app to make your robot drive forward. Then you'll modify the app so the robot drives forward and then backward.

Create New App Template

If necessary, log in to the Arduino Create web editor, or open the Arduino IDE desktop editor.

Create a new app template. If you need a reminder, here are instructions for creating a new app template.

Rename App

Rename the the new app as: driving_test

If you need a reminder, here are instructions for how to rename an app.

Add Block Comment

Add this block comment at the beginning of your app code. Modify the comment to list your information.

/*
Driving Test
Team Info
Teacher - Class Period
*/

Include RedBot Library

Arduino apps can include one or more libraries. A library is a pre-built code file that makes it easier to program certain things in your app.

There is a SparkFun RedBot Library that makes it much easier to control the motors and sensors connected to your RedBot.

You will need to add a copy of the SparkFun RedBot Library to your code editor, which is a one-time process. Then you will also need to include a copy of this library in each new robot app.

Follow these instructions to (1) add the SparkFun RedBot Library to your code editor, and (2) include the library in your current app.

You should now have an #include statement for the RedBot library (filename: RedBot.h) listed at the beginning of your app code.

Create Object for Motors

The RedBot.h library contains Arduino code that defines different classes of objects. Each class defines a set of properties (variables) and methods (functions) for a specific type of object.

Your robot apps will use these classes to create objects in your app code. An object is a special type of variable that represents a specific instance (member) of a class. An object has all the properties and methods defined for that class.

The objects in your robot app code will correspond to real-life parts on your robot (such as: motors, wheel encoders, mechanical bumpers, etc.).

One of the classes in the RedBot library that you'll use in your apps is the RedBotMotors class, which defines methods to control your robot's left and right motors.

You'll need to create a new RedBotMotors object as a global variable in your app, so you can use this object to control your robot's motors. Add this code statement before the setup() function:

RedBotMotors motors;

This code statement does two things (in order):

1. It declares the class for the object. This is similar to declaring a data type for a variable. In this case, RedBotMotors is the name of the class in the RedBot library being used to create the new object.

2. It declares the object's name. In this case, the object will be named motors. Just like with other variables, you get to decide what to name your objects.

Add Code for "Press to Start"

As a reminder, whenever you upload a new app to your robot, the new app starts running immediately (even before you've had a chance to unplug the USB cable from your robot). In a worst-case scenario, your robot might accidentally drive off your desk and crash onto the floor.

Therefore as a safety feature, most of the robot apps in these tutorials will use an if statement within the loop() function to check whether the D12 button on the circuit board has been pressed before making the robot drive around. When the button is pressed, the speaker and built-in LED will beep and blink as a confirmation before performing other robot actions (such as driving, etc.).

Create global variables for the LED pin, speaker pin, and button pin by adding this code before the setup() function:

int LED = 13;
int speaker = 9;
int button = 12;

Set the pin modes for the LED, speaker, and button by adding this code within the setup() function:

    pinMode(LED, OUTPUT);
    pinMode(speaker, OUTPUT);
    pinMode(button, INPUT_PULLUP);

Check whether the button has been pressed by adding this code within the loop() function:

  if (digitalRead(button) == LOW) {
    // code to perform when button is pressed
    digitalWrite(LED, HIGH);
    tone(speaker, 2000);
    delay(200);
    digitalWrite(LED, LOW);
    noTone(speaker);
    // add code for other robot actions (driving, etc.)
    
  }

Basically, this code for "Press to Start" is the same as the final version of the "Hello World" app you completed in the previous tutorial — except the second delay() statement was removed (because the code that will be added for "other robot actions" will act as a delay between each check of the button).

Drive Forward

The RedBotMotors class defines a method named drive() that can be used to drive the motors either forward or backwards. The RedBotMotors class also defines a method named brake() that can be used to stop the motors.

Therefore, your motors object has a motors.drive() method and a motors.brake() method (as well as any other methods defined in the RedBotMotors class).

When the motors.drive() method is used in your code, the motors will start and will keep driving continuously (sort of like cruise control on a car). You'll use a delay() statement to allow the motors to drive for a certain amount of time before turning the motors off with the motors.brake() method.

When the robot's button is pressed, let's make your robot drive forward for 2 seconds and then brake. Add this code within the if statement in the loop() function (after the noTone() statement):

    motors.drive(200); // drive forward
    delay(2000); // allow to drive for 2 seconds
    motors.brake();

The motors.drive() method requires one parameter inside its parentheses:

• The motor power, which can be any integer (whole number) between -255 and 255. A positive power drives the robot forward, and a negative power drives the robot backward. A larger absolute power produces a faster driving speed (-255 and 255 are the fastest speeds, while -1 and 1 are the slowest speeds). In this case, the power will be 200.

Upload App to Robot

Follow the steps to upload the app to your robot:

1. Connect Robot to Computer

2. Turn on Robot Power

3. Select Correct Board and Port

4. Upload App to Robot

Unplug the USB cable from the robot, and place the robot on the floor. Be sure a path of at least 3 feet in front of the robot is clear of any obstacles. (Just to be safe, also be sure a path of 3 feet behind the robot is clear — in case your robot's motor wires were accidentally reversed during assembly.)

Press the D12 button on your robot's circuit board. Your robot should beep and then drive forward for 2 seconds (about 30 inches).

TROUBLESHOOTING

• If your robot doesn't drive at all, first check that its Motor switch is set to RUN. If the switch was correct, next check the left and right motor wires on the circuit board to verify the red and black wires are correctly plugged in. If the wires were correct, replace the batteries in the robot's battery pack.

• If your robot spins clockwise (to the right), unplug and reverse the red and black wires of the right motor on the circuit board.

• If your robot spins counter-clockwise (to the left), unplug and reverse the red and black wires of the left motor on the circuit board.

• If your robot drives backward, first check your app code to make sure you used a positive value for the motor power (not a negative value). If the app code is correct, unplug and reverse the red and black wires for each motor on the circuit board.

NOTE: If your robot drives forward but not in a perfectly straight line, this is actually normal. Even though the two motors are supposed to be identical and are receiving identical power, they might not necessarily rotate at the exact same rate. Even a minor difference in their rotation rates will cause the robot to drift either to the left or to the right as it drives (depending on which motor is rotating more slowly).

Later in this tutorial, you'll learn how to use the wheel encoders to measure the rotation rates of the motors, in order to make small power adjustments to each motor so the robot drives in a straight line.

Drive Backward (Reverse)

Next you'll modify the app so the robot will drive forward for 2 seconds, stop briefly, drive backward for 2 seconds, and finally stop approximately at its starting point.

Add this code within the if statement in the loop() function (after the motors.brake() statement):

    delay(1000); // pause for 1 second
    motors.drive(-200); // drive backward
    delay(2000); // allow to drive for 2 seconds
    motors.brake();

Upload the modified app to your robot. Unplug the USB cable from the robot, and place the robot on the floor. Be sure a path of at least 3 feet in front of the robot is clear of any obstacles.

Press the D12 button on your robot's circuit board. Your robot should beep and then drive forward for 2 seconds (about 30 inches). It should stop and pause for 1 second before driving backward for 2 seconds (about 30 inches), returning approximately to its starting point.

If you want, you can modify the app further to try different motor powers or different delay times — just be sure you have a clear driving path to avoid crashing your robot into any obstacles.

In this fourth tutorial, you'll learn how to make your robot detect objects in its path by using its mechanical bumpers and (if equipped) ultrasonic sensor.

Tutorial Goals

The goals of this tutorial are to help you:

• Program a robot app that uses the mechanical bumpers to detect collisions with objects

• Program a robot app that uses the ultrasonic sensor to avoid collisions with objects

How Mechanical Bumpers Work

The RedBot has left and right mechanical bumpers with "whiskers" to detect collisions with obstacles. Each "whisker" is a flexible metal wire that will bend during a collision. If the wire bends far enough, it will make electrical contact with a metal screw on the bumper board. It is similar to how a switch or button works.

Check Positions of Whiskers and Bumpers

In order for the bumpers to detect collisions accurately, you need to check the positions of the wire whiskers and the bumper boards. Otherwise, it simply may not be physically possible for the wire 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 robot's front end). You also might need to unplug the 3-wire cable that connects to the bumper. After adjusting the wire whisker, correctly reconnect the 3-wire cable, and then reattach the bumper to the robot's front end.

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, it may not be physically possible for the wire whisker to make contact with the metal screw.

The picture 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's front end. Rotate the bumper board slightly, so the metal screw is further forward than the side strut. Then tighten the top screw of the plastic standoff to secure the bumper.

Next, you'll code an app that uses the wheel encoders to make your robot drive straight for a specific distance (measured in inches).

Using Wheel Encoder Counts for Driving and Pivoting

The ring magnet attached to each motor shaft has 4 pairs of N-S poles, similar to the diagram below.

As the motor shaft and its attached ring magnet complete one full rotation, the wheel encoder detects 4 changes (or "ticks") in the magnetic field as the magnetic poles pass by the sensor. Each wheel encoder keeps track of the total number of "ticks" it has counted.

However, each rotation of the motor shaft only turns the wheel a certain number of degrees. The RedBot motors have a gearbox ratio of 48:1, which means it actually takes 48 rotations of the motor shaft to make the wheel complete one full revolution.

We can use this information to calculate how many "ticks" counted by the wheel encoder would 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 RedBot's wheels, we can also calculate the distance that the RedBot travels during one wheel revolution. The 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 counted by wheel encoder = 1 wheel revolution = 8.04 inches traveled

By keeping track of the total number of magnetic "ticks" counted for each motor, you can use the wheel encoders to perform several useful robot behaviors:

1. Drive in a straight line by making small adjustments in the individual motor powers applied to the left and right motors, to make sure they rotate at the same rate (which is necessary for straight driving).

2. Drive for a specific distance by calculating how far the wheels have traveled while driving. (This is typically combined with adjusting the left and right motor powers to drive straight.)

3. Pivot (or turn) by a specific angle by calculating how far the wheels have traveled while pivoting (or turning) in a circle. This can be used for pivoting on both wheels or turning on one wheel.

Create New App

Open your Arduino code editor, and create a new app template.

Add a block comment at the beginning of the app code to identify your new app:

Rename App

Rename the the new app as: drive_distance_test

Include RedBot Library

Create Objects for Motors, Button, and Encoders

Your app will need to create new objects (as global variables) to represent the robot's motors, button, and wheel encoders. Add this code before the setup() function:

Add Code for "Press to Start"

Create global variables for the LED pin and speaker pin by adding this code before the setup() function:

Set the pin modes for the LED and speaker by adding this code within the setup() function:

Check whether the button has been pressed by adding this code within the loop() function:

Add Custom Function to Drive Specific Distance

You'll add a custom function named driveDistance() which contains code to make your robot drive in a straight line for a specified distance by using the wheel encoders.

Add this custom function after the loop() function (i.e., after its closing curly brace):

Call Custom Function in Loop

Remember that the code within a custom function is only performed if the custom function is "called" by its name within another function, such as the setup() function or loop() function.

When calling the driveDistance() custom function, you must pass in a value for the distance (inches) by listing a number inside the parentheses after the function's name.

You'll use the driveDistance() function to make your robot drive straight for 36 inches. Add this code statement within the if statement in the loop() function (after the noTone() statement):

By listing the name of the custom function, the custom function is "called" — so the code within that custom function will be performed one time. By listing 36 inside the parentheses, the robot will drive straight for 36 inches.

The driveDistance() function could also be used to make your robot drive backward — just pass in a negative number when calling the function.

Upload App to Robot

Follow the steps to connect your robot to your computer, and upload the app.

Unplug the USB cable from the robot, and place the robot on the floor. Create a "start line" on the floor (using masking tape, etc.). Line up the front edge of the robot with the front edge of the start line. Be sure a path of at least 3 feet in front of the robot is clear of any obstacles.

Press the D12 button on your robot's circuit board. Your robot should beep and then drive forward in a straight line for 36 inches.

Then measure the distance from the front of the start line to the front of the robot, in order to measure the actual distance traveled and see how close it is to 36 inches.

Line up the robot with the start line, and test again. Repeat the test several times to determine the average distance.

The driveDistance() function contains a local variable named correction which has been set to -1.0 because during our testing, our robot was driving about 1 inch too far when using a motor power of 150. The reason for this is because it takes a small amount of time for the robot to apply the brakes and come to a complete stop.

If your robot is driving too far (or not far enough), you'll want to change the value assigned to correction in the driveDistance() function:

• If your robot is driving too far, subtract from the correction value. For example, if your robot is driving 0.5 inch too far (36.5 inches), subtract 0.5 from correction, changing it from -1.0 to -1.5.

• If your robot is not driving far enough, add to the correction value. For example, if your robot is driving 0.5 inch too little (35.5 inches), add 0.5 to correction, changing it from -1.0 to -0.5.

If you do adjust the correction value, upload the modified app to your robot, and test again to ensure the driving distance is accurate (within 0.5 inch of the intended distance).

Next, you'll code an app to test your robot's wheel encoders by sending serial data to your computer.

How Wheel Encoders Work

Located directly behind each motor is a wheel encoder, which is a sensor that can count exactly how many times the motor has rotated. These left and right wheel encoder counts can be used to:

• make the robot drive in a straight line (by adjusting the motor powers if one motor happens to be rotating slightly faster than the other)

• calculate how far the robot has driven (by determining how many times the wheel has rotated and multiplying that by the wheel circumference)

The 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 (these are referred to as "ticks") as the ring rotates. This is how the wheel encoder can count how many times the motor has rotated.

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 alignment of the left and right wheel encoders. If necessary, you might need to push (or pull) the sensor to position it correctly.

Create New App

Open your Arduino code editor, and create a new app template.

Add a block comment at the beginning of the app code to identify your new app:

Rename App

Rename the the new app as: wheel_encoder_test

Include RedBot Library

Create Objects for Motors, Button, and Encoders

There are three classes defined in the RedBot library that you'll use in this app:

• RedBotMotors class — used to control the left and right motors

• RedBotButton class — used to control the built-in D12 button

• RedBotEncoder class — used to control the left and right wheel encoders

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

As you can see, the first code statement creates a RedBotMotors object named motors, which your app will use to control your left and right motors.

The second code statement creates a RedBotButton object named button, which your app will use to check whether the D12 button is pressed. We're doing this to show you another possible way to check the button. The difference is your code won't need to identify the button's pin number and won't need to set the button's pin mode — because the RedBotButton object does this automatically when it is created. In addition, the code statement that you'll use to read the button is slightly different (as you'll see later).

The third code statement creates a RedBotEncoder object named encoder, which your app will use to control both wheel encoders. This code statement does three things (in order):

1. It declares the class for the object. This is similar to declaring a data type for a variable. In this case, RedBotEncoder is the name of the class in the RedBot library being used to create the new object.

2. It declares the object's name. In this case, the object will be named encoder. Just like with other variables, you get to decide what to name your objects.

3. It indicates the I/O pin numbers for the encoders. In this case, A2 is the I/O pin used by the left wheel encoder, and 10 is the I/O pin used by the right wheel encoder.

Begin Serial Communication

When your robot and computer are connected with a USB cable, they can communicate with each other by transferring serial data.

In this app, your robot will send data from the wheel encoders to your computer. Your Arduino code editor has a serial monitor window that can be used to view this serial data communication.

Add this code statement within the setup() function:

This starts the serial data communication and sets the data transfer rate to 9600 bits per second.

Add Custom Function to Test Wheel Encoders

As you've learned, every Arduino app must have one setup() function and one loop() function. In addition, you can add your own custom functions to your app.

A custom function is typically used to contain code that performs a specific task or subtask. Custom functions are useful for breaking up your app into smaller code modules that are easier to understand and easier to re-use.

Custom functions are typically listed after the loop() function. Each custom function added to your app must be given a unique name to identify it. You get to decide what to name your custom functions, but choose names that will make sense to anyone reading your code. (The same rules and recommendations for naming variables apply to naming functions).

In this case, you'll add a custom function that contains all the code to perform a test of the wheel encoders. The function will be named testWheelEncoders().

Add this custom function after the loop() function (i.e., after its closing curly brace):

In line 4 above, you can see that the code statement used to check whether the built-in D12 button is pressed is slightly different when you use a RedBotButton object:

• The RedBotButton object named button has a read() method that can be used to detect whether or not the button is being pressed.

• If the button.read() method returns a value equal to true, it means the button is pressed. (Otherwise, a value of false means the button is not pressed.)

When the button is pressed, two things will occur:

• Both wheel encoder counters will be reset back to zero by using the code statement: encoder.clearEnc(BOTH);

• Both motors will start driving at a power of 150.

Then the wheel encoder data is sent to the computer using Serial.print() statements. This is the data that will be displayed in the computer's serial monitor window.

Finally, if either the left or right encoder count reaches 1000 or higher (which will happen after the motors have been driving for a few seconds), the motors will be braked.

Call Custom Function in Loop

The code within a custom function is only performed if the custom function is "called" by its name within another function, such as the setup() function or loop() function.

Add this code statement within the loop() function:

By listing the name of the custom function, the custom function is "called" — so the code within that custom function will be performed one time.

For this app, this will be only code statement listed within the loop() function. Since the loop() function repeats itself continuously, the testWheelEncoders() function will be called repeatedly.

Upload App to Robot

Connect your robot to your computer using the USB cable. 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.

Turn on your robot, and upload the app to your robot. After the upload is complete, do not unplug the USB cable. You have to keep the robot connected to your computer to allow the serial data communication.

View Data in Serial Monitor

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

• 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 should start driving. In the serial monitor, view the data showing 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.

Each line of serial data (one set of left and right encoder counts) represents the testWheelEncoders() function being performed one time. Each time the loop() function repeats, it calls the custom function, which sends another line of serial data to the serial monitor.

You'll probably notice that the wheel encoder counts do not stop exactly at 1000. This is normal — it takes a brief amount of time for the braking to occur. The final counts should be less than 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), then turn off the robot's power, and check the wheel encoder alignment again. After correcting the alignment, turn the robot's power back on to restart the app.

Next, you'll code an app that uses the wheel encoders to make your robot pivot by a specific angle (measured in degrees).

Using Wheel Encoder Counts to Calculate Pivot Angle

The wheel encoders can also be used to pivot (turn) your RedBot by a specific angle by measuring the distance traveled by the wheels while pivoting.

When pivoting, the robot turns in a circle centered between the robot's wheels. The distance between the centers of the RedBot wheel treads is 6.125 inches, which represents the diameter of the robot's pivot circle. If the robot pivoted 360°, the distance traveled by each wheel would be equal to the circumference of this pivot circle:

C = 𝛑 × d = 3.14 × 6.125 = 19.23 inches

Usually you will want your RedBot to pivot by a specific angle that is less than 360° — such as 45°, 90°, 180°, etc. For any specific angle, you can calculate its arc length (i.e., a "partial circumference"):

L = 𝛂 / 360° × 𝛑 × d

The arc length (L) represents the distance each wheel will travel while pivoting by a specific angle (𝛂).

For example, when pivoting by 90°, the arc length is:

L = 90° / 360° × 𝛑 × d = 0.25 × 3.14 × 6.125 = 4.81 inches

Once this arc length is calculated for a specific angle, the wheel encoders can be used to control how long the wheels are pivoted.

Save Copy of App With New Name

In your Arduino code editor, use the "Save As" command to save a copy of your existing drive_distance_test app as a different app named: pivot_angle_test

If necessary, here are .

Once you saved the new app name, modify the block comment near the beginning of the app code to change Drive Distance Test to Pivot Angle Test.

Add Custom Function to Pivot Specific Angle

You'll add another custom function named pivotAngle() which contains code to make your robot pivot by a specified angle by using the wheel encoders.

Add this custom function after the loop() function (i.e., after its closing curly brace):

Call Custom Function in Loop

Remember that the code within a custom function is only performed if the custom function is "called" by its name within another function, such as the setup() function or loop() function.

When calling the pivotAngle() custom function, you must pass in a value for the angle (degrees) by listing a number inside the parentheses after the function's name:

• A positive angle will pivot the robot clockwise to the right.

• A negative angle will pivot the robot counter-clockwise to the left.

You'll use the pivotAngle() function to make your robot pivot 90° right.

First, delete the driveDistance(36); code statement within the if statement in the loop() function (after the noTone() statement), and then replace it with this code statement instead:

By listing the name of the custom function, the custom function is "called" — so the code within that custom function will be performed one time. By listing 90 inside the parentheses, the robot will pivot clockwise by 90 degrees.

Upload App to Robot

Follow the steps to connect your robot to your computer, and upload the app.

Unplug the USB cable from the robot, and place the robot on the floor. Create a "plus sign" on the floor (using masking tape, etc.). The "plus sign" should consist of two lines about 12 inches long (i.e., slightly longer than the robot) that cross at a right angle (90°).

Place the robot on the "plus sign" so its wheels are centered on one line, while the front of the robot is aligned with the other line, which will act as the starting point (0°) for the pivot angle. The diagram below shows the proper starting alignment.

Press the D12 button on your robot's circuit board. Your robot should beep and then pivot 90° right.

Use the "plus sign" to visually check how the alignment of the pivoted robot compares to 90° right.

Align the robot with the lines, and test again. Repeat the test several times to determine if the pivoting needs to be adjusted with a correction value.

The pivotAngle() function contains a local variable named correction which has been set to -5.0 because during our testing, our robot was pivoting about 5 degrees too far when using a motor power of 100. The reason for this is because it takes a small amount of time for the robot to apply the brakes and come to a complete stop.

If your robot is pivoting too much (or too little), you'll want to change the value assigned to correction in the pivotAngle() function:

• If your robot is pivoting too much, subtract from the correction value. For example, if your robot is pivoting 5 degrees too much (95°), subtract 5 from correction, changing it from -5.0 to -10.0.

• If your robot is pivoting too little, add to the correction value. For example, if your robot is pivoting 5 degrees too little (85°), add 5 to correction, changing it from -5.0 to 0.0.

If you do adjust the correction value, upload the modified app to your robot, and test again to ensure the pivot angle is accurate (within 5 degrees of the intended angle).

Modify App to Turn Left

Next, you'll modify the app code so your robot will pivot 90° left. To pivot counter-clockwise to the the left, you specify a negative angle when calling the pivotAngle() function.

Modify the call to pivotAngle() within the loop() by changing the angle from 90 to -90.

Upload the modified app to your robot. Align the robot on the "plus sign," and press the D12 button to verify that your robot pivots 90° left.

Modify App to Turn Around

Next, you'll modify the app code so your robot will pivot 180° around.

Modify the call to pivotAngle() within the loop() by changing the angle to 180.

Upload the modified app to your robot. Align the robot on the "plus sign," and press the D12 button to verify that your robot pivots 180° around.

Modify App to Drive and Pivot in Pattern

Finally, you'll modify the app to make your robot drive in a pattern using multiple calls to the driveDistance()function and the pivotAngle() function.

You'll make the robot follow the pattern shown in the diagram below. When the robot reaches the end, it will turn around and retrace its path back to the start.

First, delete the pivotAngle(180); code statement within the loop() function, and then replace it with this code instead:

Upload the modified app to your robot. Align the robot on the "plus sign," and press the D12 button to verify that your robot drives and pivots following the pattern. The robot should return back to its staring point (though it probably won't be perfectly aligned back on the "plus sign").

In the next tutorial, you'll program apps to make your robot detect objects in its path.

First, you'll code an app to test your mechanical bumpers.

Be sure that you've first checked the positions of your wire whiskers and bumper boards to make any necessary physical adjustments. (If necessary, refer back to the introduction for this tutorial.)

Save Copy of App With New Name

In your Arduino code editor, open your existing app named pivot_angle_test. Use the "Save As" command to save a copy as a different app named: mechanical_bumper_test

Once you saved the new app name, modify the block comment near the beginning of the app code to change Pivot Angle Test to Mechanical Bumper Test.

Create Objects for Bumpers

The SparkFun RedBot Library also defines a class named RedBotBumper that is used to control the left and right mechanical bumpers.

You'll need to create two new RedBotMotors objects for your left and right mechanical bumpers as part of the global variables in your app. Add this code before the setup() function:

Hopefully, the code syntax for creating new objects is starting to look familiar:

• RedBotBumper declares the class for the new object.

• leftBumper and rightBumper represent unique names for each object. Again, you decide what to name your objects. They should make sense to anyone reading the code.

• 3 and 11 represent the I/O pin numbers that the left and right bumpers should be connected to. If your bumpers were connected to different pins, you'd change these pin numbers.

Add Custom Function to Check Bumpers

You'll add another custom function named checkBumpers() which will contain code to check whether the left or right mechanical bumpers have collided with an obstacle.

The RedBotBumper class defines a method named read() which is used to detect whether or not a bumper has collided with an obstacle. Each bumper acts like a switch or button.

The read() method will return a value of either HIGH or LOW:

• If the value is LOW, it means the bumper has collided with an obstacle (i.e., the wire whisker has bent backwards far enough to make electrical contact with the metal screw on the bumper board).

Add this custom function after the loop() function (i.e., after its closing curly brace):

You can see that the custom function contains an if-else statement to check the left and right bumpers. If a collision is detected, the first response is to brake the motors (which hopefully makes sense). It will also use the speaker to produce an "alert" sound.

You'll also notice that this function uses an alternate form of the tone() method, which saves a bit of coding. Notice that three parameters (instead of just two) are listed inside the parentheses:

• speaker represents the speaker's pin number (which was declared as a global variable)

• 250 represents the frequency of the tone (which can be any value between 20-20000)

• 200 represents the duration (in milliseconds) to play the tone. After the duration is over, the tone will automatically stop playing.

By including a third parameter for the duration of the tone, you don't have to include the delay() and noTone() code statements, which is convenient.

Later, you'll add other code within the function to make the robot perform additional actions (such as backing up, etc.) when a collision is detected.

Call Custom Function in Loop

You'll need to call the checkBumpers() function within the loop() function.

However, you first need to delete all the existing code within the loop() function (including the "Press to Start" code that checks if the button is pressed).

Then add a code statement to call the checkBumpers() function within the loop() function.

For reference, your loop() function should now look like this:

Upload App to Robot

Follow the steps to connect your robot to your computer, and upload the app.

For this app, you don't have to unplug the USB cable. You can also just keep the robot standing upright on its back end (with its wheels in the air).

Use your finger to press down on the wire whisker of the left bumper. When the wire has bent far enough to touch the metal screw on the bumper board, you should hear a tone. If you release the whisker, the tone should stop. Repeat this test for the right bumper.

As your last step of this tutorial, you'll code an app that uses the wheel encoders to make your robot drive straight continuously (rather than for a specific distance).

Driving straight continuously is usually combined with other robot behaviors that you'll learn about in the upcoming tutorials: detecting collisions, avoiding collisions, avoiding a line, counting lines crossed, etc.

Create New App

Open your Arduino code editor, and create a new app template.

Add a block comment at the beginning of the app code to identify your new app:

Rename App

Rename the the new app as: drive_straight_test

If you need a reminder, here are .

Include RedBot Library

. (You don't need to add the library to your code editor again — just include the library in this new app.)

Create Objects for Motors, Button, and Encoders

Your app will need to create new objects (as global variables) to represent the robot's button, motors, and wheel encoders. Add this code before the setup() function:

Add Code for "Press to Start"

This app will use a different version of the "Press to Start" code.

Create global variables for the LED pin and speaker pin by adding this code before the setup() function:

Set the pin modes for the LED and speaker by adding this code within the setup() function:

In this version of the "Press to Start" code, you'll still press the D12 button to "start" the robot. However, once the robot is "started," you can press the D12 button again to "pause" the robot. (Pressing the button yet again will "start" the robot again.)

To do this, you'll use a global variable to keep track of whether or not the robot has been "started." Add this code statement before the setup() function:

This code statement does three things (in order):

1. It declares a data type for the variable's value. In this case, bool stands for boolean. A boolean value can either be true or false. In this case, true will mean the robot is "started," and false will mean the robot is "paused."

2. It declares the variable's name. In this case, the variable will be called started. You get to decide what to name your variables. Choose names that will make sense to anyone reviewing your code.

3. It assigns a value to the variable. In this case, the variable's initial value will be equal to false because we don't want to "start" the robot until the D12 button is pressed.

Next, you'll add a custom function named checkButton() that will check whether the D12 button is pressed. If the button is pressed, the function will reverse the current value of started from true to false (or from false to true).

Add this custom function after the loop() function (i.e., after its closing curly brace):

The code statement that reverses the value of started is: started = !started;

This code statement works by assigning a new value to started that is equal to its opposite value. For a boolean variable, listing an exclamation point in front of the variable name represents its opposite value. So if started currently has a value of true, it will be assigned a new value of false (or vice versa).

Now add this new code within the loop() function:

As you can see, this code will call the checkButton() function. Then it uses an if-else statement to perform different code (not added yet) depending on whether started is true or false.

Add Custom Function to Drive Straight

You'll add another custom function named driveStraight() which will contain code to use the wheel encoders to make your robot drive in a continuous straight line (as long as this function is called continuously by the loop() function).

The driveStraight() function works similar to the driveDistance() function, except it doesn't stop the robot after a specific distance.

Add this custom function after the loop() function:

Add Global Variables for Motor Powers and Encoder Counts

The driveStraight() function checks to see whether the wheel encoder counts are increasing at the same rate (by comparing how much their current counts increased from their previous counts). If one of the wheel encoder counts is increasing at a faster rate, the function adjusts the individual motor powers to try to keep them rotating at the same rate (which makes the robot drive straight).

In order to do this, the driveStraight() function relies on global variables to track the left and right motor powers, as well as the left and right encoder counts. Add this code before the setup() function:

Reset Encoder Counters

You'll also want to reset both wheel encoder counters to zero when the app first starts. Add this code statement within the setup() function:

Add Code to Perform When Robot is Started

When the D12 button is pressed to "start" the robot, we want to make the robot drive straight continuously.

Add this code within the if statement in the loop() function, so it will be performed when started is true:

Add Code to Perform When Robot is Paused

Once the robot has been "started," the D12 button can be pressed again to "pause" the robot.

When the robot is "paused," we want to make sure the robot stops driving.

Add this code within the else statement in the loop() function, so it will be performed when started is false:

Upload App to Robot

Follow the steps to connect your robot to your computer, and upload the app.

Unplug the USB cable from the robot, and place the robot on the floor. Be sure the robot has a clear path to drive forward for at least 6 feet.

Press the D12 button to "start" the robot driving in a straight line. It should keep driving in a straight line continuously, so you'll have to pick up the robot at some point and "pause" it by pressing the D12 button (or you can press the Reset button).

If you want to test further, place the robot on the floor, and press the button to "start" the robot again.

First, you'll code an app to test your robot's IR line sensors by sending serial data to your computer.

Create New App

Open your Arduino code editor, and create a new app template.

Add a block comment at the beginning of the app code to identify your new app:

/*
Line Sensors Test
Team Info
Teacher - Class Period
*/

Rename App

Rename the the new app as: line_sensors_test

If you need a reminder, here are instructions for how to rename an app.

Include RedBot Library

Follow the steps to include the SparkFun RedBot Library in your app. (You don't need to add the library to your code editor again — just include the library in this new app.)

Create Objects for Line Sensors

The SparkFun RedBot Library also defines a class named RedBotSensor that can be used to control the IR line sensors.

You'll need to create three new RedBotSensor objects for your line sensors as part of the global variables in your app. Add this code before the setup() function:

RedBotSensor leftLine(A3);
RedBotSensor centerLine(A6);
RedBotSensor rightLine(A7);

Hopefully, the code syntax for creating new objects looks familiar by now:

• RedBotSensor declares the class for the new object.

• leftLine, centerLine, and rightLine represent unique names for each object. Again, you decide what to name your objects. The names should make sense to anyone reading the code.

• A3, A6, and A7 represent the I/O pin numbers that the left, center, and right line sensors should be connected to. If your sensors were connected to different pins, you'd change these pin numbers.

Begin Serial Communication

When your robot and computer are connected with a USB cable, they can communicate with each other by transferring serial data.

In this app, your robot will send data (IR sensor measurements) to your computer. Your Arduino code editor has a serial monitor window that can be used to view this serial data communication.

Add this code statement within the setup() function:

Serial.begin(9600);

This starts the serial data communication and sets the data transfer rate to 9600 bits per second.

Add Custom Function to Test Line Sensors

You'll add a custom function named testLineSensors() which will contain code to read the values from each IR line sensor and send these to your computer as serial data.

The RedBotSensor class defines a method named read() which is used to read the value from a specific IR line sensor. The read() method will return an integer value (whole number) between 0-1023 representing 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 (greater than 1000), 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.).

Add this custom function after the loop() function:

void testLineSensors() {
  // get IR sensor readings
  int leftSensor = leftLine.read();
  int centerSensor = centerLine.read();
  int rightSensor = rightLine.read();

  // send data to serial monitor
  Serial.print("L: ");
  Serial.print(leftSensor);
  Serial.print("\tC: ");
  Serial.print(centerSensor);
  Serial.print("\tR:");
  Serial.println(rightSensor);

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

Call Custom Function in Loop

As you hopefully remember, the code within a custom function is only performed if the custom function is "called" by its name within another function, such as the setup() function or loop() function.

Add this code statement within the loop() function:

testLineSensors();

By listing the name of the custom function, the custom function is "called" — so the code within that custom function will be performed one time.

For this app, this will be only code statement listed within the loop() function. Since the loop() function repeats itself continuously, the testLineSensors() function will be called repeatedly.

Upload App to Robot

Connect your robot to your computer using the USB cable. Turn on your robot, and upload the app to your robot.

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

View Data in Serial Monitor

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

• 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.

Place the robot on a sheet of white paper on your desk or table. View the IR sensor readings in the serial monitor. Even for a white sheet of paper, the sensor readings will probably be between 400-700. Your sensor readings will probably have different values. All of this normal — the IR sensor readings can be affected by the ambient light in the room.

Next, use a black permanent marker to draw a line (about 0.5 inch wide and about 3 inches long) in the middle of the paper. Alternatively, you could print this test page.

Position the robot so only the center line sensor is above the dark line. View the IR sensor readings in the serial monitor. You should see that the center sensor reading is higher than the left and right sensors (which are positioned above a white surface). For a uniform black line, the center sensor reading should be at least 800 (or higher).

Then rotate the robot so all three line sensors are "on" the dark line. View the sensor readings in the serial monitor. All three sensor readings should be at least 800 (or higher).

Finally, position the robot near the edge of your desk or table. Then slowly roll the robot towards the edge until the IR line sensors are just hanging over the edge (be sure the robot won't roll off). View the sensor readings in the serial monitor. All three sensor readings should be about 1000 (or higher).

Next, you'll code an app to make your robot drive around and detect collisions using its mechanical bumpers.

Save Copy of App With New Name

In your Arduino code editor, use the "Save As" command to save a copy of the mechanical_bumper_test app as a different app named: detect_collisions_test

Once you saved the new app name, modify the block comment near the beginning of the app code to change Mechanical Bumper Test to Detect Collisions Test.

Add Code for "Press to Start"

This app will use a different version of the "Press to Start" code (same version used in C-6 Drive Straight Continuously).

You'll press the D12 button to "start" the robot. Once the robot is "started," you can press the button again to "pause" the robot. (Pressing the button yet again will "start" the robot again.)

You'll use a global variable to keep track of whether or not the robot has been "started." Add this code statement before the setup() function:

bool started = false;

This code statement does three things (in order):

1. It declares a data type for the variable's value. In this case, bool stands for boolean. A boolean value can either be true or false. In this case, true will mean the robot is "started," and false will mean the robot is "paused."

2. It declares the variable's name. In this case, the variable will be called started. You get to decide what to name your variables. Choose names that will make sense to anyone reviewing your code.

3. It assigns a value to the variable. In this case, the variable's initial value will be equal to false because we don't want to "start" the robot until the D12 button is pressed.

Next, you'll add a custom function named checkButton() that will check whether the D12 button is pressed. If the button is pressed, the function will reverse the current value of started from true to false (or from false to true).

Add this custom function after the loop() function (i.e., after its closing curly brace):

void checkButton() {
  if (button.read() == true) {
    // reverse value of started
    started = !started;
    
    // beep and blink as feedback
    digitalWrite(LED, HIGH);
    tone(speaker, 2000);
    delay(200);
    digitalWrite(LED, LOW);
    noTone(speaker);
    delay(200);
  }
}

The code statement that reverses the value of started is: started = !started;

This code statement works by assigning a new value to started that is equal to its opposite value. For a boolean variable, listing an exclamation point in front of the variable name represents its opposite value. So if started currently has a value of true, it will be assigned a new value of false (or vice versa).

Next, delete the code statement that calls the checkBumpers() function within the loop() function. This will give you an "empty" loop() function.

Now add this new code within the loop() function:

  checkButton();
  if (started == true) {
    // add code to perform when "started"
    
  }
  else {
    // add code to perform when "paused"
    
  }

As you can see, this code will call the checkButton() function. Then it uses an if-else statement to perform different code (not added yet) depending on whether started is true or false.

Add Code to Perform When Robot is Started

When the D12 button is pressed to "start" the robot, we want to make the robot drive forward continuously and also check for any bumper collisions.

Add this code within the if statement in the loop() function, so it will be performed when started is true:

    motors.drive(150);
    checkBumpers();

Add Code to Perform When Robot is Paused

Once the robot has been "started," the D12 button can be pressed again to "pause" the robot.

When the robot is "paused," we want to make sure the robot stops driving.

Add this code within the else statement in the loop() function, so it will be performed when started is false:

    motors.brake();

Modify Custom Function to Check Bumpers

You'll modify the checkBumpers() custom function by adding code statements to perform further actions when a bumper collision occurs.

Right now, when a bumper collision is detected, the checkBumpers() function will brake the motors and make a sound.

You'll add code to also make the robot back up (drive in reverse for 12 inches) and then turn right or left (pivot 90°) depending on whether the left or right bumper detected a collision.

Add this code within the if statement in the checkBumpers() function, so it will be performed when the left bumper detects a collision (add this code after the tone() statement):

    delay(1000);
    driveDistance(-12); // back up
    pivotAngle(90); // turn right

Add this code within the else if statement in the checkBumpers() function, so it will be performed when the right bumper detects a collision (add this code after the tone() statement):

    delay(1000);
    driveDistance(-12); // back up
    pivotAngle(-90); // turn left

Upload App to Robot

Follow the steps to connect your robot to your computer, and upload the app.

Unplug the USB cable from the robot, and place the robot on the floor.

Press the D12 button to "start" the robot driving forward. You can use your hand as an obstacle to create collisions with the wire whiskers. When a collision is detected, the robot should stop, make an alert sound, back up, and then turn 90° right or left (depending on which bumper detected the collision).

When you're done testing the robot, you can pick it up, and press the D12 button to "pause" the robot (or you can press the Reset button).

If you want to test further, place the robot on the floor, and press the button to "start" the robot again.

As your last step of this tutorial, you'll code an app to make your robot drive around and use its ultrasonic sensor to avoid collisions with obstacles.

Save Copy of App With New Name

In your Arduino code editor, use the "Save As" command to save a copy of the ultrasonic_sensor_test app as a different app named: avoid_collisions_test

Once you saved the new app name, modify the block comment near the beginning of the app code to change Ultrasonic Sensor Test to Avoid Collisions Test.

Add Custom Function to Avoid Collision

You'll add another custom function named avoidCollision() which will contain code to use measurements from the ultrasonic sensor to avoid colliding with an obstacle.

Add this custom function after the loop() function:

void avoidCollision() {

  // set minimum allowed distance between robot and obstacle
  float minDist = 8.0; // change value as necessary (need decimal)

  // measure distance to nearest obstacle
  float distance = measureDistance();

  // if obstacle is too close, avoid collision
  if (distance <= minDist) {
    // add code to perform (brake, change direction, etc.)
    motors.brake();

  }
}

Add Other Code When Obstacle Too Close

Right now, when the avoidCollision() function detects that an obstacle in the robot's path is too close, it brakes the motors.

Depending on the purpose of your robot and the environment in which it operates, there are different options for what else you might want the robot to do when an obstacle is too close.

In this case, you'll add code so the robot will randomly turn right or left (pivot 90°) by generating a random number (either 0 or 1 – similar to flipping a coin) to decide which direction to turn.

Arduino has a random() method which can be used to generate a random number (integer) within a specific range.

Add this code within the if statement in the avoidCollision() function, so it will be performed when the left bumper detects a collision (add this code after the motors.brake() statement):

    delay(1000);
    // turn right or left based on random number
    long randomNum = random(2); // generate random integer of either 0 or 1
    if (randomNum == 0) pivotAngle(90); // turn right
    else pivotAngle(-90); // turn left

Modify Code to Perform When Robot is Started

When the D12 button is pressed to "start" the robot, we want make the robot drive forward continuously and also avoid any collisions.

First, delete the existing code statements within the if statement in the loop() function that are performed when started is true.

You can also delete the Serial.begin() statement within the setup() function.

Next, add this code within the if statement in the loop() function, so it will be performed when started is true:

    motors.drive(150);
    avoidCollision();

Upload App to Robot

Follow the steps to connect your robot to your computer, and upload the app.

Unplug the USB cable from the robot, and place the robot on the floor.

Press the D12 button to "start" the robot driving forward. You can use your leg as an obstacle in the robot's path. When the robot detects that it is too close to an obstacle, the robot should stop, back up, and then turn 90° right or left.

When you're done testing the robot, you can pick it up, and press the D12 button to "pause" the robot (or you can press the Reset button).

If you want to test further, place the robot on the floor, and press the button to "start" the robot again.

First, you'll code an app that allows your robot to detect a surface drop-off (such as: a table edge, a stair step leading down, a hole in the surface, etc.). This will allow your robot to take actions to protect itself from a fall (by braking, reversing, changing direction, etc.).

A surface drop-off can be easily detected using the IR line sensors. When the front edge of the robot is hanging over a surface drop-off, the IR sensor readings will be very high (typically 1000 or higher).

Save Copy of App With New Name

In your Arduino code editor, use the "Save As" command to save a copy of the line_sensors_test app as a different app named: detect_dropoff_test

Once you saved the new app name, modify the block comment near the beginning of the app code to change Line Sensors Test to Detect Surface Drop-off Test.

Create Objects for Motors and Button

Your app will need to create new objects (as global variables) to represent the robot's motors and button. Add this code before the setup() function:

RedBotMotors motors;
RedBotButton button;

Add Code for "Press to Start"

This app will use the "Press to Start" code. You'll press the D12 button to "start" the robot. Once the robot is "started," you can press the button again to "pause" the robot. (Pressing the button yet again will "start" the robot again.)

You need to declare global variables for the LED pin and speaker pin. You also need a global variable to keep track of whether or not the robot has been "started." Add this code before the setup() function:

int LED = 13;
int speaker = 9;
bool started = false;

Set the pin modes for the LED and speaker by adding this code within the setup() function:

    pinMode(LED, OUTPUT);
    pinMode(speaker, OUTPUT);

This app does not need the Serial.begin() statement within the setup() function. You can turn this code statement into a comment by typing two forward slashes // at the beginning of the statement.

Next, you need to add the custom function named checkButton() that will check whether the D12 button is pressed, in order to "start" or "pause" the robot.

Add this custom function after the loop() function:

void checkButton() {
  if (button.read() == true) {
    // reverse value of started
    started = !started;
    
    // beep and blink as feedback
    digitalWrite(LED, HIGH);
    tone(speaker, 2000);
    delay(200);
    digitalWrite(LED, LOW);
    noTone(speaker);
    delay(200);
  }
}

Next, delete the code statement that calls the testLineSensors() function within the loop() function. This will give you an "empty" loop() function.

Now add this new code within the loop() function:

  checkButton();
  if (started == true) {
    // add code to perform when "started"
    
  }
  else {
    // add code to perform when "paused"
    
  }

Later, you'll add the code to be performed when the robot is started or paused.

Add Custom Function to Check for Surface Drop-Off

You'll add a custom function named checkDropOff() which will contain code to use readings from the IR line sensors to detect a surface drop-off and avoid driving over the drop-off.

Add this custom function after the loop() function:

void checkDropOff() {

  // IR threshold indicating surface drop-off (table edge, hole, etc.)
  int dropOff = 950; // adjust value if necessary

  // get IR sensor readings
  int leftSensor = leftLine.read();
  int centerSensor = centerLine.read();
  int rightSensor = rightLine.read();

  // see if any IR sensors detect drop-off
  if (leftSensor > dropOff || centerSensor > dropOff || rightSensor > dropOff) {
    // add code to perform (brake, reverse, change direction, etc.)
    motors.brake();
    tone(speaker, 1000, 200);
    
  }
}

As you can see, when a drop-off is detected, the robot will brake the motors and make an alert sound. Later, you'll add more code statements to perform additional actions.

Add Code to Perform When Robot is Started

When the D12 button is pressed to "start" the robot, we want the robot to start driving forward and checking for a surface drop-off.

Add this code statement within the if statement in the loop() function, so it will be performed when started is true:

    motors.drive(150);
    checkDropOff();

Add Code to Perform When Robot is Paused

Once the robot has been "started," the D12 button can be pressed again to "pause" the robot.

When the robot is "paused," we want make the robot stop driving.

Add this code statement within the else statement in the loop() function, so it will be performed when started is false:

    motors.brake();

Modify Custom Function to Check for Drop-Off

You'll modify the checkDropOff() custom function by adding code statements to perform further actions when a surface drop-off is detected.

Right now, when a drop-off is detected, the checkDropOff() function will brake the motors and make an alert sound.

You'll add code to also make the robot back up (drive in reverse). The code will also "pause" the robot (by changing the value of started back to false), so you can repeat this surface drop-off test multiple times.

Add this code within the if statement in the checkDropOff() function, so it will be performed when the IR sensors detect a drop-off (add this code after the tone() statement):

    delay(1000);
    motors.drive(-150); // back up
    delay(1000);
    motors.brake();
    started = false; // allow test to be repeated

Upload App to Robot

Follow the steps to connect your robot to your computer, and upload the app.

Unplug the USB cable from the robot, and place the robot on a desk or table, so the robot is about 12 inches away from the edge of the desk (or table) and pointed towards the edge.

Press the D12 button to "start" the robot driving forward. When the robot detects the edge of the desk or table, the robot should stop, make an alert sound, and back up.

If you want to repeat the test, press the button to "start" the robot again.

In this sixth tutorial, you'll learn how to make your robot detect other conditions (e.g., surface drop-offs, the robot's pitch and roll, when the robot is upside-down, when the robot is bumped, etc.) using its IR line sensors and accelerometer.

Tutorial Goals

The goals of this tutorial are to help you:

• Program a robot app that uses the IR line sensors to detect a surface drop-off

• Program a robot app that uses the accelerometer to measure the robot's pitch and roll

• Program a robot app that uses the accelerometer to detect if the robot is upside down

• Program a robot app that uses the accelerometer to detect if the robot has been bumped

Next, you'll code an app to test your robot's accelerometer by measuring the robot's pitch (front-to-back tilt) and roll (side-to-side tilt) and sending these measurements to your computer as serial data.

Create New App

Open your Arduino code editor, and create a new app template.

Add a block comment at the beginning of the app code to identify your new app:

/*
Accelerometer Test
Team Info
Teacher - Class Period
*/

Rename App

Rename the the new app as: accelerometer_test

If you need a reminder, here are instructions for how to rename an app.

Include RedBot Library

Follow the steps to include the SparkFun RedBot Library in your app. (You don't need to add the library to your code editor again — just include the library in this new app.)

Create Object for Accelerometer

The SparkFun RedBot Library also defines a class named RedBotAccel that can be used to control the accelerometer.

You'll need to create a new RedBotAccel object for your accelerometer as part of the global variables in your app. Add this code before the setup() function:

RedBotAccel accel;

Hopefully, the code syntax for creating new objects looks familiar:

• RedBotAccel declares the class for the new object.

• accel represents a name for the object. Again, you decide what to name your objects and variables, as long as the names are unique and will make sense to anyone reading the code.

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.

Begin Serial Communication

When your robot and computer are connected with a USB cable, they can communicate with each other by transferring serial data.

In this app, your robot will send data (accelerometer readings) to your computer. Your Arduino code editor has a serial monitor window that can be used to view this serial data communication.

Add this code statement within the setup() function:

Serial.begin(9600);

This starts the serial data communication and sets the data transfer rate to 9600 bits per second.

Add Custom Function to Test Accelerometer

You'll add a custom function named testAccelerometer() which will contain code to take measurements using the accelerometer and send these to your computer as serial data.

The RedBotAccel class defines a method named read() which is used to take new measurements using the accelerometer. This method will store the measurements as different properties (variables) of your RedBotAccel object.

Here are the different properties for a RedBotAccel object named accel:

• accel.x – raw X-axis accelerometer measurement

• accel.y – raw Y-axis accelerometer measurement

• accel.z – raw Z-axis accelerometer measurement

• accel.angleXZ – calculated angle between the X and Z axes of the accelerometer (represents the front-to-back rotation on the device's Y axis, which is also called pitch)

• accel.angleYZ – calculated angle between the Y and Z axes of the accelerometer (represents the side-to-side rotation on the device's X axis, which is also called roll)

• accel.angleXY – calculated angle between the X and Y axes of the accelerometer (represents the left-to-right rotation on the device's Z axis, which is also called yaw)

For your apps, you probably won't use the raw accelerometer measurements. Instead, you'll most likely want to know the calculated angles for the XZ, YZ, and XY planes.

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.

Add this custom 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);
}

Call Custom Function in Loop

As you remember, the code within a custom function is only performed if the custom function is "called" by its name within another function, such as the setup() function or loop() function.

Add this code statement within the loop() function:

testAccelerometer();

By listing the name of the custom function, the custom function is "called" — so the code within that custom function will be performed one time.

For this app, this will be only code statement listed within the loop() function. Since the loop() function repeats itself continuously, the testAccelerometer() function will be called repeatedly.

Upload App to Robot

Connect your robot to your computer using the USB cable. Turn on your robot, and upload the app to your robot.

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

View Data in Serial Monitor

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

• 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.

Place the robot on a level surface, such as your desk or table. View the accelerometer readings in the serial monitor. 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 pitch, roll, and yaw by rotating your robot's body in different directions.

PITCH

Pitch (angle XZ) is the front-to-back rotation on the device's Y axis. Pitch can range from -180° to 180°.

1. 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°.

2. Rotate the robot so it is level from front-to-back. When it is level, the pitch will be 0°.

3. 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 (angle YZ) is the side-to-side rotation on the device's X axis. Roll can range from -180° to 180°.

1. 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°.

2. Rotate the robot so it is level from side-to-side. When it is level, the roll will be 0°.

3. 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 (angle XY) is the right-to-left rotation on the device's Z axis. Yaw can range from -180° to 180°.

However, when the RedBot 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.

1. Place the robot back down on a level surface, such as your desk or table. Check the yaw value in the serial monitor.

2. 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).

3. 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.

This is why your robot apps will probably not use yaw values from the accelerometer. (However, there are other types of sensors – not included in this kit – which can be used to accurately measure yaw.)

Next, you'll code an app to test your ultrasonic sensor (if your robot is equipped with one).

If necessary, follow these instructions to attach an ultrasonic sensor to the robot.

How Ultrasonic Sensor Works

The ultrasonic sensor has a transmitter (i.e., a speaker) that can produce high-frequency sound, which cannot be heard by the human ear. The sensor also has a receiver (i.e., a microphone) that detects the echo of the high-frequency sound when it is reflected back from a nearby object. By measuring how much time it takes for the echo to arrive, you can calculate the distance between the sensor and the object.

This 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 distance measurements from the sensor are very accurate, within about 3 mm (about 0.1 inch) of the actual distance.

Save Copy of App With New Name

In your Arduino code editor, open your existing app named detect_collisions_test. Use the "Save As" command to save a copy as a different app named: ultrasonic_sensor_test

Once you saved the new app name, modify the block comment near the beginning of the app code to change Detect Collisions Test to Ultrasonic Sensor Test.

Add 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:

int TRIG_PIN = A0;
int ECHO_PIN = A1;

Set Pin Modes for Sensor

You'll need to set the pin modes for the ultrasonic sensor's transmitter (Trig) and receiver (Echo). The transmitter is an output because it will produce high-frequency sound. The receiver is an input because it will detect the echo of the high-frequency sound when it reflects back from nearby obstacles.

Add this code within the setup() function:

  pinMode(TRIG_PIN, OUTPUT);
  pinMode(ECHO_PIN, INPUT);
  digitalWrite(TRIG_PIN, LOW);

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

Begin Serial Communication

When your robot and computer are connected with a USB cable, they can communicate with each other by transferring serial data.

In this app, your robot will send data (distance measurements) to your computer. Your Arduino code editor has a serial monitor window that can be used to view this serial data communication.

Add this code statement within the setup() function:

Serial.begin(9600);

This starts the serial data communication and sets the data transfer rate to 9600 bits per second.

Add Custom Function to Measure Distance

You'll add another custom function named measureDistance() which will contain code that uses the ultrasonic sensor to measure the distance between the sensor and the closest object ahead in the robot's path.

When this custom function is called, it will return the distance measurement as a decimal value (float), which your app will need to store in a local variable.

The comments embedded in the custom function help explain how it works.

Add this custom function after the loop() function:

float measureDistance() {
  // uses HC-SR04 ultrasonic sensor
  unsigned long start_time, end_time, pulse_time;

  // trigger ultrasonic signal for 10 microseconds
  digitalWrite(TRIG_PIN, HIGH);
  delayMicroseconds(10);
  digitalWrite(TRIG_PIN, LOW);

  // wait until echo received
  while (digitalRead(ECHO_PIN) == 0);

  // measure how long echo lasts (pulse time)
  start_time = micros(); // get start time in microseconds
  while (digitalRead(ECHO_PIN) == 1); // wait until echo pulse ends
  end_time = micros(); // get end time
  pulse_time = end_time - start_time; // subtract to get duration

  // pulse time of 23200 represents maximum distance for this sensor
  if (pulse_time > 23200) pulse_time = 23200;

  // calculate distance to object using pulse time
  float dist_cm = pulse_time / 58.0;
  float dist_in = pulse_time / 148.0;

  // need 60 ms delay between ultrasonic sensor readings
  delay(60);

  // return distance value
  return dist_in; // or can return dist_cm
}