pitsco PRIZM Operating instructions

43212
TETRIX® PRIZM™ Robotics Controller
Programming Guide

Content advising by Paul Uttley, Pamela Scifers, Tim Lankford, Nevin Jones, and Bill Holden.
Build creation and SolidWorks® Composer™ and KeyShot® renderings by Tim Lankford, Brian Eckelberry, and Jason Redd.
Desktop publishing by Todd McGeorge.
©2016 Pitsco, Inc., 915 E. Jefferson, Pittsburg, KS 66762
All rights reserved. This product and related documentation are protected by copyright and are distributed under licenses
restricting their use, copying, and distribution. No part of this product or related documentation may be reproduced in any
form by any means without prior written authorization of Pitsco, Inc.
All other product names mentioned herein might be the trademarks of their respective owners.
Check TETRIXrobotics.com for PDF updates of this guide.
V1.0
10/16

Table of Contents
TETRIX® PRIZM™ Robotics Controller Introduction.................................................................................2
PRIZM Controller Technology Overview..................................................................................................................3
PRIZM Setup.....................................................................................................................................................................................................5
Software Overview.................................................................................................................................................................................8
Software Setup.............................................................................................................................................................................................9
Getting Started Activities
Activity 1: Hello World!...........................................................................................................................................................................15
Activity 2: Moving Your DC Motors...................................................................................................................................................19
Activity 3: Moving Your Servo Motors.............................................................................................................................................22
Activity 4: Introduction to the Line Finder Sensor.....................................................................................................................25
Activity 5: Introduction to the Ultrasonic Sensor .......................................................................................................................29
Building and Coding the PRIZM TaskBot
Hardware Overview ................................................................................................................................................................................36
Activity 6: Build the TaskBot ................................................................................................................................................................51
Activity 7: Drive Forward.......................................................................................................................................................................84
Activity 8: Drive in a Circle....................................................................................................................................................................87
Activity 9: Drive in a Square.................................................................................................................................................................90
Activity 10: Simplify the Square.........................................................................................................................................................93
Building Interlude: Make the TaskBot Smart!...............................................................................................................................96
Activity 11: Drive to a Line and Stop............................................................................................................................................. 102
Activity 12: Follow a Line ................................................................................................................................................................... 105
Activity 13: Drive Toward a Wall and Stop.................................................................................................................................. 108
Activity 14: Avoiding Obstacles ...................................................................................................................................................... 111
Building Interlude: Give the TaskBot Attitude! ......................................................................................................................... 114
Activity 15: Combining the Sensors.............................................................................................................................................. 120
Build, Code, Test, Learn . . . Go! ........................................................................................................................................................ 123
Appendix
TETRIX PRIZM Robotics Controller Technical Specifications............................................................................................... 124
PRIZM Controller Component Overview and Pinout Diagrams ....................................................................................... 126
TETRIX PRIZM Arduino Library Functions................................................................................................................................... 133
TETRIX PRIZM Arduino Library Functions Chart ...................................................................................................................... 146
TETRIX PRIZM Arduino Library Functions Cheat Sheet......................................................................................................... 153
TETRIX PRIZM Sample Code Library.............................................................................................................................................. 154

Welcome, Coders, Roboticists,
Engineers, Students, Teachers,
Mentors, and Coaches,
Happy coding,
building, problem
solving, engineering,
and collaborating!
Pitsco Education is pleased to bring you the TETRIX® PRIZM™ Robotics Controller Programming Guide –
an exciting and progressive series of activities that teaches the essentials of learning to program your
TETRIX MAX creations using the PRIZM controller and the Arduino Software (IDE).
This programming guide offers a valuable tool for teaching students and teachers how to use the
PRIZM controller (the brain) and the TETRIX MAX system to build and code smart, precise robots that
are as real-world as it gets. The guide comes with five getting started activities, step-by-step building
instructions for creating a TaskBot, 10 complete TaskBot-oriented lessons, and Hacking the Code
extension activities, making it a great tool for exploring the functionality of the PRIZM controller,
TETRIX hardware components, and Arduino Software (IDE) and offering students a great foundation to
build on.
By combining the plug-and-play PRIZM controller with the intuitive MAX building system and an easy-
to-use, text-based software environment, this solution offers a great entry into teaching and learning
through robotics. The progressive nature of the activities enables robotic creations to come to life
quickly and easily, meaning students can experience instant success and focus more classroom time
on problem solving and applying their STEM knowledge.
Plus, PRIZM is not just a great tool for teaching programming. It can bring to life lessons on sensors,
power, gear ratios, and more. Even the controller’s clear polycarbonate shield was designed to
maximize educational value – letting users see the inner architecture of the controller.
We have also included some STEM Extensions (concepts beyond the scope of this guide) that can
be covered in each lesson if you choose to do so. These extensions can be incorporated if you have
content knowledge of these concepts or if you can work with other teachers to integrate these
concepts.
We hope this guide offers a great jumping-off point to learning with PRIZM. We cannot wait to see the
innovative projects and robotic creations that result.
2Getting Started

PRIZM Controller Technology Overview
PRIZM Robotics Controller:
A programmable device that is the brain of a TETRIX MAX robot.
6 standard control servo ports
2 quadrature
encoder input ports
Battery connection port
2 DC motor
control
ports
Start
button
Stop/Reset
button
1 motor controller
expansion port
USB
programming
port
1 I2C port
4 digital sensor ports
3 analog
sensor ports
2 continuous
rotation
servo ports
For complete, detailed specifications, please refer to the TETRIX PRIZM Robotics
Controller Technical Specifications located in the appendix on page 124.
Getting Started 3

Ultrasonic Sensor:
Enables a robot to measure
distance to an object and
respond to movement
DC Motor:
12-volt DC motor that
features 152 rpm and
320 oz-in. of torque
Standard Servo Motor:
Allows for exact
positioning within a
180-degree range of
motion
Motor Shaft Encoder:
Allows you to program the DC motors using both rotation
and degrees. Please note: The TETRIX Motor Shaft Encoder
Pack does not come as part of the robotics set and requires an
additional purchase.
Line Finder Sensor:
Enables a robot to follow
a black line on a white
background or vice versa
Powerpole Motor Cable:
Connects the DC Motor to
the power source
Continuous Rotation
Servo Motor:
Allows for continuous
direction of movement,
both forward and backward
Sensor:
A device that detects and responds to surrounding environmental factors
Motor:
A machine that produces motion or power for completing work
Encoder:
A sensing device that converts motion to an electrical signal that is read by the PRIZM controller to determine position,
count, speed, or direction of the TETRIX DC Motors
4Getting Started

Attaching the Sensors:
To connect a sensor to the PRIZM, plug one
end of the sensor adapter wire into the
sensor. Plug the other end into ports labeled
D2-D5 or A1-A3.
Attaching the DC Motors:
To connect a DC motor to the PRIZM, attach
the white end of the Powerpole connector
to the motor and plug the mating colored
connectors into one of the two motor
ports. Connectors should be plugged in
RED to RED and BLACK to BLACK for proper
operation.
Attaching the Servo Motors:
To connect a standard servo motor to the
PRIZM, plug one end of the servo wire into
servo ports 1-6. To connect a continuous
rotation servo motor to the PRIZM, plug one
end of the servo wire into servo ports labeled
CR1 or CR2.
PRIZM™ Setup
Getting Started 5

Warning: Do not attempt to use third-party battery packs with the PRIZM
controller. The TETRIX battery packs are equipped with a safety fuse and are
the only packs approved for use with the system. Damage to the product as a
result of doing so will void your warranty.
Downloading and Uploading:
The PRIZM USB port is used for
communication between PRIZM and a
Windows, Mac, or Linux device.
The port enables users to download and
upload data from the computer to the PRIZM
controller.
To upload a program to the PRIZM, plug
the B Connector of the USB cable into the
controller’s USB labeled port and plug the A
Connector into your device.
Powering the PRIZM:
The PRIZM controller is powered by a
TETRIX 12-Volt Rechargeable NiMH Battery
Pack.
Included with the PRIZM controller is an
on/off power switch assembly designed to
connect the battery pack connector to the
PRIZM-style Powerpole battery connection
port.
Instructions for assembling the battery and
on/off kit are included in the Building the
TaskBot activity in this guide.
6Getting Started

Attaching the Battery to the PRIZM:
To connect the battery pack to the PRIZM,
plug the colored battery connectors into
one of the two battery ports located on the
controller. Connectors should be plugged
RED to RED and BLACK to BLACK for proper
operation. Do not connect in reverse polarity.
The battery pack can be plugged into either
the top or bottom row of the port.
Warning: Do not attempt to connect two battery packs to one PRIZM
controller. Damage and failure will occur if this is attempted. Use only one
battery pack to power the PRIZM system and any extra daisy-chained
expansion controllers.
Getting Started 7

Software Overview
The Arduino Integrated Development Environment (IDE) is open-source software
that compiles code and sends it to the hardware. As a text-based and developer-
friendly software with a huge existing user base, the Arduino Software (IDE) is
supported for a variety of Windows, Macintosh, and Linux devices. This makes the
Arduino Software (IDE) flexible, classroom friendly, and competition ready and offers
all users, even the hobbyist, a low entry and high ceiling. All these factors make it
perfect for beginner and veteran coders alike.
The Arduino Software (IDE) uses a C-based programming language to communicate
with the PRIZM. Within the Arduino Software (IDE) an individual program is referred
to as a sketch. Each of the activities in this guide will involve creating a sketch that
gives instructions to the robot.
For the purposes of this guide, we will focus on the basics of using the Arduino
Software (IDE) as it applies to the PRIZM controller. Working through examples and
hands-on application of code using a small TaskBot constructed with the TETRIX
MAX robotics building system will show you how easy it is to use Arduino with
PRIZM.
Note: This is not meant
to be a complete tutorial
on programming with the
Arduino C-based language.
There are many excellent
resources available on the
web to learn more about
advanced programming
skills. If you are interested
in such resources, a good
place to start would be the
Arduino website at
www.arduino.cc.
8Getting Started

Software Setup
The first thing we need to do is install the Arduino Software (IDE). The software can
be found at the Arduino website (www.arduino.cc) for Windows, Macintosh, and
Linux operating systems. From the Arduino homepage, click the Download tab. On
the Download page, select the download for your operating system and follow any
additional instructions.
Installing the PRIZM Controller Arduino Library
Adding custom libraries can expand the usability of the Arduino Software (IDE).
Libraries are collections of code that make it easier to create a program, or, as
Arduino calls it, a sketch. After you have successfully installed the Arduino Software
(IDE), you can add the Arduino PRIZM controller library. The PRIZM controller library
contains special functions written for the TETRIX PRIZM controller. Many, but not all,
of the functions will be explored in our activities.
For a deeper look at all available functions in the PRIZM library, please refer to the
appendix section titled TETRIX PRIZM Arduino Library Functions.
The PRIZM library is distributed as a .zip file: TETRIX_PRIZM.zip. The first step is to
download the PRIZM library from the TETRIX website. We can find the library at
www.TETRIXrobotics.com/PRIZMdownloads.
After the library has been downloaded, there are two ways to install the PRIZM
library into the Arduino Software (IDE).
Importing a .zip Library
One way is to import it using the Arduino Software (IDE) Add .ZIP Library menu
option.
In the Arduino Software (IDE), navigate to Sketch > Include Library. From the drop-
down menu, select Add .ZIP Library (Figure 1).
Figure 1
Note: All instructions
and screen shots used
throughout this guide are
based on the 1.6.11 version
of the Arduino Software (IDE).
Instructions and views might
slightly vary based on the
platform and version you are
using.
Teacher note:
• Depending on your
classroom and IT situation,
you might want to
download and install the
Arduino Software (IDE) and
the TETRIX PRIZM Arduino
Library on the computers
you and your students will
be using.
• It is recommended that
you organize the class into
teams of two to four It is
recommended that you
go through each process
before students do. This
will enable you to have a
good understanding of
what student questions
might arise and how to
answer those questions.
Tip: Figures within this
section show typical
installation within Windows.
The look and file locations
within the Mac and Linux
operating systems might
vary.
Getting Started 9

You will be prompted to select the library you would like to add. Navigate to the
location where you saved the TETRIX_PRIZM.zip library file, select it, and open it
(Figure 2).
Return to the Sketch > Include Library menu. You should now see the library at
the bottom of the drop-down menu. It is ready to be used in our sketches; however,
example sketches for the library will not appear in the File > Examples menu until
after the Arduino Software (IDE) has been restarted.
Manual Installation
To install the PRIZM library manually, first close the Arduino Software (IDE)
application. Then, extract the .zip file TETRIX_PRIZM.zip containing the library. After
the folder is extracted, drag or copy the TETRIX_PRIZM folder into the Arduino
libraries folder.
For Windows users, it will likely be called Documents\Arduino\libraries.
For Mac users, it will likely be called Documents/Arduino/libraries.
For Linux users, it will be the libraries folder in the Arduino sketchbook.
Restart the Arduino Software (IDE). Make sure the TETRIX_PRIZM library appears in
the Sketch > Include Library menu of the software.
In addition, several PRIZM sketch examples will now appear in the File > Examples
> TETRIX_PRIZM drop-down menu.
That’s it! We have successfully installed the PRIZM Arduino library.
Figure 2
10 Getting Started

Configuring USB Communication
PRIZM and the Arduino Software (IDE) will communicate with each other through
the computer’s USB port.
Therefore, before we can begin programming, we first need to be sure that the
PRIZM controller is properly set up in the Arduino Software (IDE) for communication
over the USB port.
The easiest way to do this is to first start the Arduino Software (IDE) and navigate to
Tools > Board and select Arduino/Genuino Uno (Figure 3). The PRIZM controller
uses the same processor chip as a genuine Arduino UNO, so this is the board you
will select.
Figure 3
Getting Started 11

Next, without the PRIZM connected, navigate to Tools > Port (Figure 4) and check
the current connections. If there are no current connections detected, the word Port
will be grayed out. If there are connections detected, take note of the COM ports
that are listed.
Next, plug the PRIZM controller into a USB port and power it up by connecting the
TETRIX battery pack and turning the power switch on.
Figure 4: Port drop-down menu with PRIZM not connected.
Please note that lists might vary.
12 Getting Started

Navigate to Tools > Port and select the newly installed COM port. The new COM
port will be the PRIZM. By selecting the new COM port, you are telling the Arduino
Software (IDE) to use this port for communications. The COM port you use will likely
be different from the one in Figure 5.
The new port that appears in this example is COM32.
Select the new port item to tell the Arduino Software (IDE) to use this port for
communications. Our port will likely be different and that is OK. When the
communications port has been set up, communications with the PRIZM controller
have been enabled and coding can begin.
When this step is complete, our computer system will automatically default to
this selected port each time we plug in our PRIZM controller and start the Arduino
Software (IDE).
With power applied, the blue power indicator LED will be lit. Be sure to give the
PRIZM controller time to complete the first-time connect installation. This could
take 5-10 seconds. After the PRIZM has been connected and installed, it will be
assigned a COM port by the computer system.
Figure 5: Port drop-down menu after PRIZM is
connected to USB port and powered on.
Tip: Each PRIZM unit will
use a different COM port
on the same computer. For
each new PRIZM that is
connected, follow the steps
for numbering controllers
and matching to the
computer as detailed above.
One potential way around
this issue is to number
each PRIZM controller and
assign it to a corresponding
computer. This will facilitate
the computer selecting the
correct port for PRIZM each
time it is connected and
powered up.
Getting Started 13

Getting Started Activities
Now, it is time to get started with the activities. Each of the five getting started
activities is designed to introduce you to the Arduino Software (IDE) and how it
works with the PRIZM and select basic hardware. Success with these first five
activities will demonstrate how easy it is to use Arduino Software (IDE) with the
PRIZM and prepare you for coding the PRIZM TaskBot.
The Arduino Sketch
As we begin creating our first sketch, it is necessary to understand some basic rules
about sketches. It is best to think of a sketch as a list of instructions to be carried out
in the order that they are written down. Each sketch will have several instructions,
and typically each instruction will be one line of text within the sketch. Lines of text
within a sketch are also known as code, which is why programming is sometimes
called coding.
Most of the rules that affect text-based programming are known as syntax, which is
similar to grammar and punctuation in English.
For instance, each line of code must end with a semicolon just like a period marks
the end of a sentence. As we come across more coding rules in the activities, we will
make sure to explain them.
Many times the best way to learn how to code is by following an example. In the
following sections we will work through several coding examples to better explain
how to create sketches and upload them to the PRIZM controller.
An example sketch of each function can be found in the File > Examples >
TETRIX_PRIZM drop-down menu.
Note: If you are already
comfortable with coding in
Arduino sketches and want
to jump ahead, an overview
of each library function can
still be a helpful starting
point. We have created
and included definitions of
the functions along with
descriptions that show how
each would appear in an
Arduino sketch. You can find
these in the appendix of this
guide on pages 133-145.
More library functions might
be added in the future as the
library is updated to newer
versions.
Note: In addition to the
PRIZM library, there is an
entire collection of Arduino
language commands that
are necessary to understand
before we can create
functional programs. The
Arduino language reference
as well as numerous
language learning tutorials
can be found by visiting the
Arduino homepage at
www.arduino.cc.
14 Getting Started Activities

Activity 1: Hello World!
Let’s begin with a very simple sketch that will blink the onboard PRIZM red LED. This
activity will be the PRIZM equivalent of a Hello World! program, which is usually
the intro activity for any beginning programmer. The sketch we will create is one of
the simplest and most basic PRIZM functions and requires only the PRIZM, a power
source, and a USB connection to the computer.
Parts Needed
• PRIZM controller
• USB cable
• A charged TETRIX 12-Volt
Rechargeable NiMH Battery Pack
• PRIZM Controller On/Off Battery
Switch Adapter
• Computer
Figure 6
Opening the Sketch
Let’s start by looking at our first example sketch. Open the sketch by selecting File >
Examples > TETRIX_PRIZM > GettingStarted_Act1_Blink_RedLED. A new sketch
window will open titled GettingStarted_Act1_Blink_RedLED (Figure 6).
Getting Started Activities 15

Building the Knowledge Base
Before we can upload the sketch to the PRIZM, we need to make sure the PRIZM
has power, is connected to the computer, and is detected by the computer (Figure
7). When the PRIZM is connected as shown, power on the PRIZM with the on/off
switch. You will know the PRIZM has power by the glowing blue light. To see if the
PRIZM is detected by the computer, check the port as we did in the Configuring
USB Communication section.
As the data uploads, the yellow LEDs to the side of the USB connection will flash.
When the upload is finished, there will be a solid green LED beside the red Reset
button. The green LED means the code is ready to execute. Press Start to execute
the code. The red LED next to the Reset button will blink off and on in one-second
intervals. To stop the program, press the Reset button.
Congratulations! You have successfully uploaded your first sketch to the PRIZM and
demonstrated the results to the world.
Executing the Code
To upload the sketch to the PRIZM, click Upload (Figure 8).
Figure 7
Figure 8
16 Getting Started Activities

Real-World Connection
Many things within the electronic world around us blink, such as caution lights for
road construction warnings, waffle irons (the blinking light turns solid when the
waffles are ready), or notifications on our phones indicating that we have incoming
calls. The rate at which these items blink – or when they blink – is controlled by
electronics. This control can be from simple timing circuits – or it can be from
computers or other devices with microprocessor chips.
STEM Extensions
Science
• Electricity terms (voltage, current, and resistance)
• How an LED works
• What determines the color of an LED
Technology
• How computers work
• How computers are programmed
Engineering
• Problem-solving process
Math
• Frequency
• Duration
• Sequence
Tip: Remember that you
can print and use the TETRIX
PRIZM Arduino Library
Functions Cheat Sheet within
the appendix on page 153 as
a quick reference for all the
functions available to you.
Tip: Want to see this in
action? You can by watching
our RoboBench video series
for the PRIZM Programming
Guide. You can find the
entire series at video.
tetrixrobotics.com or on
the TETRIXrobotics YouTube
channel.
Moving Forward
For more detailed information about the sketch process and the PRIZM library
functions involved in blinking the LED, refer to the following sections within the
appendix: TETRIX PRIZM Arduino Library Functions:
• Page 133 about include statements
• Page 134 about initialization functions
• Page 136 about the Start button
• Page 137 about onboard LEDs
For now, let’s change some parameters in our code and see how it affects the
behavior of the red LED. According to the comments in the example, the delay
function defines the duration the LED is on or off. This is a parameter we can
change in our code. Experiment with changing those values to create new blinking
behaviors for the LED. Try making the LED blink faster or slower.
Getting Started Activities 17

Hacking the Code Activity
With the example as a reference, try creating the blinking LED in a new sketch.
Instead of just blinking the red LED, try to blink the green LED too. Flashing or
blinking lights have a rich tradition as a method of signaling or long-distance
communication. You could challenge yourself to communicate“Hello World!”in
blinking Morse code.
To start a new sketch, select File > New. Be sure to use the appendix: TETRIX PRIZM
Arduino Library Functions in the back of the guide for help with sketch structure
and syntax. An example library of code can also be found in the appendix for those
that need extra help. Do not forget to use basic software skills such as copy and
paste.
When creating your own sketch, there is a built-in software tool to help ensure your
code is free of syntax errors. You can check your syntax by clicking Verify (Figure 9).
This will cause the code to compile but not upload. You will be prompted to save
your sketch before verification.
If there are errors in the code, they will be displayed in the compiler error window at
the bottom of the sketch window (Figure 10).
Errors will need to be corrected before code can be uploaded to the PRIZM
controller. If there are no errors, the compiler will complete and indicate that it is
done compiling, and you can upload your code.
Figure 10
Tip: In the sketch window
the PRIZM library functions
change color when they
are typed or spelled
correctly. Consequently,
if spelled incorrectly they
will not change. In Arduino,
the PRIZM functions are
recognized by the software
as keywords and will turn
orange when the syntax is
correct.
Tip: An example library of
code to help you get started
with this challenge can be
found in the appendix. If you
have a digital copy of this
guide, you can simply copy
and paste the sample code
for each activity into your
sketch window. A digital
download can be found at
www.TETRIXrobotics.com/
PRIZMdownloads.
Figure 9
18 Getting Started Activities