AVR Library Command Reference

12. 3pi Robot Functions

This section of the library provides convenient access for 3pi-specific hardware. Currently, it only provides access

for the 5 QTR-based line sensors that are included in the 3pi. That is, the QTR functions described in Section 11 do

not need to be used for the 3pi. The functions described below are enabled by including one of the 3pi files:

#include <pololu/3pi.h> // use this line for C

#include <pololu/Pololu3pi.h> // use this line for C++

The necessary Orangutan include files will be included automatically.

Using this library will automatically configure Timer2, which will cause it to conflict with other libraries that use

Timer2. See Section 7 (Motors) and Section 11 (Sensors) for more information.

For a higher level overview of this library and programs that show how this library can be used, please see the

Pololu 3pi Robot User’s Guide [http://www.pololu.com/docs/0J21].

static unsigned char Pololu3pi::init(unsigned int line_sensor_timeout = 1000)

unsigned char pololu_3pi_init(unsigned int line_sensor_timeout)

Initializes the 3pi robot. This sets up the line sensors, turns the IR emitters off to save power, and resets the

system timer (except within the Arduino environment). The parameter line_sensor_timeout specifies the timeout

in Timer2 counts. This number should be the length of time in Timer2 counts beyond which you consider the

sensor reading completely black. It is recommended that you set timeout to be between 500 and 3000 us,

depending on factors like the ambient lighting. This allows you to shorten the duration of a sensor-reading cycle

while maintaining useful measurements of reflectance. For the 3pi, you can convert Timer2 counts to

microseconds by dividing by 2.5 or multiplying by 0.4 (2000 us = 5000 Timer2 counts = line_sensor_timeout of

5000).

void Pololu3pi::read(unsigned int *sensorValues, unsigned char readMode = IR_EMITTERS_ON)

void read_line_sensors(unsigned int *sensorValues, unsigned char readMode)

Reads the raw sensor values into an array. There MUST be space for five unsigned int values in the array. The

values returned are a measure of the reflectance, between 0 and the line_sensor_timeout argument provided in to

the init() function.

The functions that read values from the sensors all take an argument readMode, which specifies the kind of read

that will be performed. Several options are defined: IR_EMITTERS_OFF specifies that the reading should be

made without turning on the infrared (IR) emitters, in which case the reading represents ambient light levels near

the sensor; IR_EMITTERS_ON specifies that the emitters should be turned on for the reading, which results in a

measure of reflectance; and IR_EMITTERS_ON_AND_OFF specifies that a reading should be made in both the

on and off states. The values returned when the IR_EMITTERS_ON_AND_OFF option is used are given by on +

max – off, where on is the reading with the emitters on, off is the reading with the emitters off, and max is the

maximum sensor reading. This option can reduce the amount of interference from uneven ambient lighting. Note

that emitter control will only work if you specify a valid emitter pin in the constructor.

Example usage:

unsigned int sensor_values[5];

read_line_sensors(sensor_values);

void Pololu3pi::emittersOn()

void emitters_on()

Turn the IR LEDs on. This is mainly for use by read_line_sensors(), and calling this function before or after the

reading the sensors will have no effect on the readings, but you may wish to use it for testing purposes.

12. 3pi Robot Functions Page 31 of 35