Bill Grimes / ZumoReflectanceSensorArray

A port of the pololu header from arduino to mbed

Dependencies:   PololuQTRSensors

Embed: (wiki syntax)

« Back to documentation index

ZumoReflectanceSensorArray Class Reference
Public Member Functions

ZumoReflectanceSensorArray Class Reference

Read from reflectance sensor array. More...

#include <ZumoReflectanceSensorArray.h>

Public Member Functions

 ZumoReflectanceSensorArray ()
 Minimal constructor.
 ZumoReflectanceSensorArray (PinName emitterPin)
 Constructor; initializes with given emitter pin and defaults for other settings.
 ZumoReflectanceSensorArray (PinName *pins, unsigned char numSensors, unsigned int timeout=2000, PinName emitterPin=ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN)
 Constructor; initializes with all settings as given.
void init (PinName emitterPin=ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN)
 Initializes with given emitter pin and and defaults for other settings.
void init (PinName *pins, unsigned char numSensors, unsigned int timeout=2000, PinName emitterPin=ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN)
 Initializes with all settings as given.
void read (unsigned int *sensor_values, unsigned char readMode=QTR_EMITTERS_ON)
 Reads the raw sensor values into an array.

Detailed Description

Read from reflectance sensor array.

The ZumoReflectanceSensorArray library provides an interface for using a [Zumo Reflectance Sensor Array](http://www.pololu.com/product/1419) connected to a Zumo robot. The library provides access to the raw sensor values as well as to high level functions including calibration and line-tracking.

For calibration, memory is allocated using the `malloc()` function. This conserves RAM: if all six sensors are calibrated with the emitters both on and off, a total of 48 bytes is dedicated to storing calibration values. However, for an application where only two sensors are used, and the emitters are always on during reads, only 4 bytes are required.

Internally, this library uses all standard Arduino functions such as `micros()` for timing and `digitalRead()` for getting the sensor values, so it should work on all Arduinos without conflicting with other libraries.

### Calibration ###

This library allows you to use the `calibrate()` method to easily calibrate your sensors for the particular conditions it will encounter. Calibrating your sensors can lead to substantially more reliable sensor readings, which in turn can help simplify your code. As such, we recommend you build a calibration phase into your Zumo's initialization routine. This can be as simple as a fixed duration over which you repeatedly call the `calibrate()` method.

During this calibration phase, you will need to expose each of your reflectance sensors to the lightest and darkest readings they will encounter. For example, if your Zumo is programmed to be a line follower, you will want to slide it across the line during the calibration phase so the each sensor can get a reading of how dark the line is and how light the ground is (or you can program it to automatically turn back and forth to pass all of the sensors over the line). The **SensorCalibration** example included with this library demonstrates a calibration routine.

### Reading the sensors

This library gives you a number of different ways to read the sensors.

  • You can request raw sensor values using the `read()` method.
  • You can request calibrated sensor values using the `readCalibrated()` method. Calibrated sensor values will always range from 0 to 1000, with the extreme values corresponding to the most and least reflective surfaces encountered during calibration.
  • For line-detection applications, you can request the line location using the `readLine()` method. This function provides calibrated values for each sensor and returns an integer that tells you where it thinks the line is.

### Class Inheritance ###

The ZumoReflectanceSensorArray class is derived from the QTRSensorsRC class, which is in turn derived from the QTRSensors base class. The QTRSensorsRC and QTRSensors classes are part of the QTRSensors library, which provides more general functionality for working with reflectance sensors and is included in the Zumo Shield libraries as a dependency for this library.

We recommend using the ZumoReflectanceSensorArray library instead of the QTRSensors library when programming an Arduino on a Zumo. For documentation specific to the QTRSensors library, please see its [user's guide](http://www.pololu.com/docs/0J19) on Pololu's website.

Definition at line 97 of file ZumoReflectanceSensorArray.h.

Constructor & Destructor Documentation

ZumoReflectanceSensorArray (  )

Minimal constructor.

This version of the constructor performs no initialization. If it is used, the user must call init() before using the methods in this class.

Definition at line 106 of file ZumoReflectanceSensorArray.h.

ZumoReflectanceSensorArray ( PinName  emitterPin )

Constructor; initializes with given emitter pin and defaults for other settings.

Parameters:
emitterPinPin that turns IR emitters on or off.

This constructor calls `init(PinName emitterPin)` with the specified emitter pin and default values for other settings.

Definition at line 116 of file ZumoReflectanceSensorArray.h.

ZumoReflectanceSensorArray ( PinName *  pins,
unsigned char  numSensors,
unsigned int  timeout = 2000,
PinName  emitterPin = ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN 
)

Constructor; initializes with all settings as given.

Parameters:
pinsArray of pin numbers for sensors.
numSensorsNumber of sensors.
timeoutMaximum duration of reflectance reading in microseconds.
emitterPinPin that turns IR emitters on or off.

This constructor calls `init(PinName * pins, unsigned char numSensors, unsigned int timeout, PinName emitterPin)` with all settings as given.

Definition at line 131 of file ZumoReflectanceSensorArray.h.

Member Function Documentation

void init ( PinName  emitterPin = ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN )

Initializes with given emitter pin and and defaults for other settings.

Parameters:
emitterPinPin that turns IR emitters on or off.

This function initializes the ZumoReflectanceSensorArray object with the specified emitter pin. The other settings are set to default values: all six sensors on the array are active, and a timeout of 2000 microseconds is used.

emitterPin is the Arduino digital pin that controls whether the IR LEDs are on or off. This pin is optional; if a valid pin is specified, the emitters will only be turned on during a reading. If emitterPin is not specified, the emitters will be controlled with pin 2 on the Uno (and other ATmega328/168 boards) or pin A4 on the Leonardo (and other ATmega32U4 boards). (The "LED ON" jumper on the Zumo Reflectance Sensor Array must be configured correctly for this to work.) If the value `QTR_NO_EMITTER_PIN` (255) is used, you can leave the emitter pin disconnected and the IR emitters will always be on.

Definition at line 155 of file ZumoReflectanceSensorArray.h.

void init ( PinName *  pins,
unsigned char  numSensors,
unsigned int  timeout = 2000,
PinName  emitterPin = ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN 
)

Initializes with all settings as given.

Parameters:
pinsArray of pin numbers for sensors.
numSensorsNumber of sensors.
timeoutMaximum duration of reflectance reading in microseconds.
emitterPinPin that turns IR emitters on or off.

This function initializes the ZumoReflectanceSensorArray object with all settings as given.

The array pins should contain the Arduino digital pin numbers for each sensor.

numSensors specifies the length of the pins array (the number of reflectance sensors you are using).

timeout specifies the length of time in microseconds beyond which you consider the sensor reading completely black. That is to say, if the pulse length for a pin exceeds timeout, pulse timing will stop and the reading for that pin will be considered full black. It is recommended that you set timeout to be between 1000 and 3000 us, depending on factors like the height of your sensors and ambient lighting. This allows you to shorten the duration of a sensor-reading cycle while maintaining useful measurements of reflectance. If timeout is not specified, it defaults to 2000 us. (See the [product page](http://www.pololu.com/product/1419) for the Zumo Reflectance Sensor Array on Pololu's website for an overview of the sensors' principle of operation.)

emitterPin is the Arduino digital pin that controls whether the IR LEDs are on or off. This pin is optional; if a valid pin is specified, the emitters will only be turned on during a reading. If emitterPin is not specified, the emitters will be controlled with pin 2 on the Uno (and other ATmega328/168 boards) or pin A4 on the Leonardo (and other ATmega32U4 boards). (The corresponding connection should be made with the "LED ON" jumper on the Zumo Reflectance Sensor Array.) If the value `QTR_NO_EMITTER_PIN` (255) is used, you can leave the emitter pin disconnected and the IR emitters will always be on.

This version of `init()` can be useful if you only want to use a subset of the six reflectance sensors on the array. For example, using the outermost two sensors (on pins 4 and 5 by default) is usually enough for detecting the ring border in sumo competitions:

~~~{.ino} ZumoReflectanceSensorArray reflectanceSensors;

...

reflectanceSensors.init((unsigned char[]) {4, 5}, 2); ~~~

Alternatively, you can use a different constructor to declare and initialize the object at the same time:

~~~{.ino}

ZumoReflectanceSensorArray reflectanceSensors((unsigned char[]) {4, 5}, 2); ~~~

Definition at line 221 of file ZumoReflectanceSensorArray.h.

void read ( unsigned int *  sensor_values,
unsigned char  readMode = QTR_EMITTERS_ON 
)

Reads the raw sensor values into an array.

Parameters:
sensorValuesArray to populate with sensor readings.
readModeRead mode (`QTR_EMITTERS_OFF`, `QTR_EMITTERS_ON`, or `QTR_EMITTERS_ON_AND_OFF`).

There **must** be space in the sensorValues array for as many values as there were sensors specified in the constructor. The values returned are measures of the reflectance in units of microseconds. They will be raw readings between 0 and the timeout argument (in units of microseconds) provided in the constructor (which defaults to 2000).

The readMode argument specifies the kind of read that will be performed. Several options are defined:

  • `QTR_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.
  • `QTR_EMITTERS_ON` specifies that the emitters should be turned on for the reading, which results in a measure of reflectance.
  • `QTR_EMITTERS_ON_AND_OFF` specifies that a reading should be made in both the on and off states. The values returned when this option is used are given by the formula **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 and make the corresponding connection (with the "LED ON" jumper or otherwise).

The ZumoReflectanceSensorArray class inherits this function from the QTRSensors class.

Generated on Sun Jul 24 2022 21:14:56 by  doxygen 1.7.2