5. Arduino Libraries for the Orangutan and 3pi Robot

5.a. OrangutanAnalog - Analog Input Library
5.b. OrangutanBuzzer - High-Level Buzzer Control Library
5.c. OrangutanLCD - LCD Control Library
5.d. OrangutanLEDs - LED Control Library
5.e. OrangutanMotors - Motor Control Library
5.f. OrangutanPushbuttons - Pushbutton Interface Library
5.g. Pololu3pi - Sensor Library for the 3pi Robot

Note: Because the Orangutans were not designed as official Arduino boards, not all existing Arduino library code will be directly compatible with them. For example, certain Arduino functions like delayMicroseconds() and pulseIn() are designed to run at 16 MHz and hence their behavior is altered by the Orangutan’s 20 MHz clock. In other cases, Orangutan-specific libraries might conflict with existing Arduino libraries if the two are competing for the same mega168 hardware peripherals (e.g. two libraries that try to use Timer1 in different ways will not be compatible).

Overview

This section provides a series of Orangutan-specific libraries that will allow you to easily interface with the Orangutan/3pi hardware from the Arduino environment. It is important to note that the Baby Orangutan B is a hardware subset of the larger Orangutan SV-xx8 and LV-168, and these Orangutans are (almost) a hardware subset of the 3pi robot. What this means is that any library code that works on the Baby Orangutan B will also work on the Orangutan and 3pi robot, and (almost) any library code that works on the Orangutan will also work on the 3pi. The following subsections contain detailed documentation of each Orangutan Arduino library. All of the libraries that apply to the Orangutan will work for the corresponding hardware on the 3pi robot.

The only library class for which it is meaningful to have multiple instances is PololuQTRSensors. All the other classes consist entirely of static methods, so it does not make sense to instantiate them multiple times. As of version 101215, the C versions of the library functions are also available for use in your Arduino programs. This means that there are three possible ways for you to call library methods:

unsigned int x;

// C++ function through instantiated object
OrangutanAnalog analog; // this line is usually placed above setup()
x = analog.readTrimpot();

// C++ function through class scope
x = OrangutanAnalog::readTrimpot();

// C function
x = read_trimpot();

The only library classes that need to be explicitly initialized before they are used are PololuQTRSensors and Pololu3pi, since these objects are initialized with user-specified parameters. None of the remaining Orangutan library objects needs to be explicitly initialized in your setup() function as initialization is automatically performed when needed.

Download Instructions

The Pololu Arduino Libraries are provided in a zip file, which you can download from the following link:

If you are using an older version of the Arduino environment, we strongly recommend that you update to Arduino 1.0.1 and use the latest version of the Pololu Arduino Libraries. However, previous versions of the libraries are provided here for compatibility with older Arduino environments:

Installation

Note: If you currently have an older version of our Pololu Arduino Libraries, your first step should be to delete all of the Orangutan___ and Pololu___ directories from your libraries directory. If you don’t perform this step, the newer version of the libraries might not be compiled.

Decompress the archive and move each of the Orangutan___ and Pololu___ directories within the libpololu-avr folder into the libraries subdirectory inside your Arduino sketchbook. You can view your sketchbook location by selecting File > Preferences in the Arduino environment; if there is not already a “libraries” folder in that location, you should create it yourself. The screen shot below shows where the library directories should appear once they are extracted:

After installing the library, restart the Arduino environment so it can find the libraries and their examples. You should now be able to use these libraries in your sketches. For example, if you want to use the OrangutanBuzzer library, you can select Sketch > Import Library > OrangutanBuzzer from your Arduino IDE, or you can simply type #include <OrangutanBuzzer.h> at the top of your sketch. Note that you might need to restart your Arduino IDE before it sees the new libraries. If you do not need the functionality of a specific library, you should leave it out of your sketch (simply delete the #include line associated with it from the top of your sketch if you’ve already added it). Included libraries will take up program space, even if you don’t use them in your program.

Usage Examples

Most libraries come with at least one example sketch that demonstrates how the library can be used. To load an example sketch, open the Arduino IDE and go to File > Examples > Orangutan____.

The Pololu3pi library comes with several detailed line-following and maze-solving example sketches that can be loaded using File > Examples > Pololu3pi.