User Manual

19. 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 16 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 16 (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 [https://www.pololu.com/docs/0J21].

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

disable_emitter_pin = 0)

unsigned char pololu_3pi_init(unsigned int line_sensor_timeout)

unsigned char pololu_3pi_init_disable_emitter_pin(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). Setting disable_emitter_pin to 1 (C++) or calling the function

pololu_3pi_init_disable_emitter_pin() causes pin PC5 to not be used at all by the library, so that you can use

it for something else.

void Pololu3pi::readLineSensors(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.

19. 3pi Robot Functions Page 63 of 65