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 Orangutan LV-168, and the Orangutan LV-168 is 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 LV-168 and 3pi robot, and any library code that works on the Orangutan LV-168 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 LV-168 will work for the corresponding hardware on the 3pi robot.

The only library class that can be instantiated multiple times is PololuQTRSensors. You should never be using more than one instance of any other library object, so to that end all of the remaining Orangutan/3pi Arduino libraries have made their objects static. This means that there are two possible ways for you to call these library’s methods:

OrangutanLibrary library;
library.method();
OrangutanLibrary::method();

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.

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 arduino-0012/hardware/libraries directory. If you don’t perform this step, the newer version of the libraries might not get compiled. Additionally, the 080929 (86k zip) version of the Pololu Arduino libraries will only work correctly with Arduino version 0012 or later. If you have an older version of the Arduino environment, you either need to update to version 0012 or you can download version 080826 (80k zip) of the Pololu Arduino libraries, which works with Arduino version 0011 but not 0012

Download the following archive: PololuArduinoLibraries-080929.zip (86k zip)

and extract it to your arduino-0012/hardware/libraries directory. Once this is complete you should see a series of new directories have appeared in the extraction directory. The screen shot below shows where the library directories should appear once they are extracted:

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 0012 IDE, or you can simply type #include <OrangutanBuzzer.h> at the top of your sketch. Note that you might need to restart your Arduino 0012 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 > Sketchbook > Examples > Library-Orangutan____.

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