Read from reflectance sensor array. More...

#include <ZumoReflectanceSensorArray.h>

Inheritance diagram for ZumoReflectanceSensorArray:

Public Member Functions
	ZumoReflectanceSensorArray ()
	Minimal constructor. More...

	ZumoReflectanceSensorArray (unsigned char emitterPin)
	Constructor; initializes with given emitter pin and defaults for other settings. More...

	ZumoReflectanceSensorArray (unsigned char *pins, unsigned char numSensors, unsigned int timeout=2000, unsigned char emitterPin=ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN)
	Constructor; initializes with all settings as given. More...

void	init (unsigned char emitterPin=ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN)
	Initializes with given emitter pin and and defaults for other settings. More...

void	init (unsigned char *pins, unsigned char numSensors, unsigned int timeout=2000, unsigned char emitterPin=ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN)
	Initializes with all settings as given. More...

void	read (unsigned int *sensor_values, unsigned char readMode=QTR_EMITTERS_ON)
	Reads the raw sensor values into an array. More...

void	emittersOff ()
	Turns the IR LEDs off. More...

void	emittersOn ()
	Turns the IR LEDs on. More...

void	calibrate (unsigned char readMode=QTR_EMITTERS_ON)
	Reads the sensors for calibration. More...

void	resetCalibration ()
	Resets all calibration that has been done. More...

void	readCalibrated (unsigned int *sensor_values, unsigned char readMode=QTR_EMITTERS_ON)
	Returns sensor readings normalized to values between 0 and 1000. More...

int	readLine (unsigned int *sensor_values, unsigned char readMode=QTR_EMITTERS_ON, unsigned char white_line=0)
	Returns an estimated position of a line under the sensor array. More...

Public Attributes
unsigned int *	calibratedMinimumOn
	The calibrated minimum values measured for each sensor, with emitters on. More...

unsigned int *	calibratedMaximumOn
	The calibrated maximum values measured for each sensor, with emitters on. More...

unsigned int *	calibratedMinimumOff
	The calibrated minimum values measured for each sensor, with emitters off. More...

unsigned int *	calibratedMaximumOff
	The calibrated maximum values measured for each sensor, with emitters off. More...

Protected Member Functions
void	init (unsigned char *pins, unsigned char numSensors, unsigned char emitterPin)

Protected Attributes
unsigned char *	_pins

unsigned char	_numSensors

unsigned char	_emitterPin

unsigned int	_maxValue

int	_lastValue

Detailed Description

Read from reflectance sensor array.

ZumoReflectanceSensorArray provides an interface for using a Zumo Reflectance Sensor Array connected to a Zumo robot. It 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, it 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

ZumoReflectanceSensorArray 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 LineSensorCalibration example demonstrates a calibration routine.

Reading the sensors

ZumoReflectanceSensorArray 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 Arduino Library as a dependency for this library.

We recommend using ZumoReflectanceSensorArray 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 on Pololu's website.

Definition at line 92 of file ZumoReflectanceSensorArray.h.

Constructor & Destructor Documentation

◆ ZumoReflectanceSensorArray() [1/3]

ZumoReflectanceSensorArray::ZumoReflectanceSensorArray ( )

inline

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 101 of file ZumoReflectanceSensorArray.h.

◆ ZumoReflectanceSensorArray() [2/3]

ZumoReflectanceSensorArray::ZumoReflectanceSensorArray ( unsigned char emitterPin )

inline

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

Parameters

emitterPin Pin that turns IR emitters on or off.

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

Definition at line 111 of file ZumoReflectanceSensorArray.h.

◆ ZumoReflectanceSensorArray() [3/3]

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

inline

Constructor; initializes with all settings as given.

Parameters

pins	Array of pin numbers for sensors.
numSensors	Number of sensors.
timeout	Maximum duration of reflectance reading in microseconds.
emitterPin	Pin that turns IR emitters on or off.

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

Definition at line 127 of file ZumoReflectanceSensorArray.h.

Member Function Documentation

◆ calibrate()

void QTRSensors::calibrate ( unsigned char readMode = QTR_EMITTERS_ON )

inherited

Reads the sensors for calibration.

Parameters

readMode Read mode (QTR_EMITTERS_OFF, QTR_EMITTERS_ON, or QTR_EMITTERS_ON_AND_OFF).

The sensor values read by this function are not returned; instead, the maximum and minimum values found over time are stored internally and used for the readCalibrated() method. You can access the calibration (i.e raw max and min sensor readings) through the public member pointers calibratedMinimumOn, calibratedMaximumOn, calibratedMinimumOff, and calibratedMaximumOff. Note that these pointers will point to arrays of length numSensors, as specified in the constructor, and they will only be allocated after calibrate() has been called. If you only calibrate with the emitters on, the calibration arrays that hold the off values will not be allocated.

The ZumoReflectanceSensorArray class inherits this function from the QTRSensors class.

Definition at line 149 of file QTRSensors.cpp.

◆ emittersOff()

void QTRSensors::emittersOff ( )

inherited

Turns the IR LEDs off.

This is mainly for use by the read() method, and calling this function before or after reading the sensors will have no effect on the readings, but you might wish to use it for testing purposes. This method will only do something if the emitter pin specified in the constructor is valid (i.e. not QTR_NO_EMITTER_PIN) and the corresponding connection is made.

The ZumoReflectanceSensorArray class inherits this function from the QTRSensors class.

Definition at line 110 of file QTRSensors.cpp.

◆ emittersOn()

void QTRSensors::emittersOn ( )

inherited

Turns the IR LEDs on.

This is mainly for use by the read() method, and calling this function before or after reading the sensors will have no effect on the readings, but you might wish to use it for testing purposes. This method will only do something if the emitter pin specified in the constructor is valid (i.e. not QTR_NO_EMITTER_PIN) and the corresponding connection is made.

The ZumoReflectanceSensorArray class inherits this function from the QTRSensors class.

Definition at line 119 of file QTRSensors.cpp.

◆ init() [1/2]

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

inline

Initializes with all settings as given.

Parameters

pins	Array of pin numbers for sensors.
numSensors	Number of sensors.
timeout	Maximum duration of reflectance reading in microseconds.
emitterPin	Pin 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 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:

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:

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

Definition at line 220 of file ZumoReflectanceSensorArray.h.

◆ init() [2/2]

void ZumoReflectanceSensorArray::init ( unsigned char emitterPin = ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN )

inline

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

Parameters

emitterPin Pin 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 153 of file ZumoReflectanceSensorArray.h.

◆ read()

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

Reads the raw sensor values into an array.

Parameters

sensor_values	Array to populate with sensor readings.
readMode	Read mode (`QTR_EMITTERS_OFF`, `QTR_EMITTERS_ON`, or `QTR_EMITTERS_ON_AND_OFF`).

There must be space in the sensor_values 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.

◆ readCalibrated()

void QTRSensors::readCalibrated	(	unsigned int *	sensor_values,
		unsigned char	readMode = `QTR_EMITTERS_ON`
	)

inherited

Returns sensor readings normalized to values between 0 and 1000.

Parameters

sensor_values	Array to populate with sensor readings.
readMode	Read mode (`QTR_EMITTERS_OFF`, `QTR_EMITTERS_ON`, or `QTR_EMITTERS_ON_AND_OFF`).

0 corresponds to a reading that is less than or equal to the minimum value read by calibrate() and 1000 corresponds to a reading that is greater than or equal to the maximum value. Calibration values are stored separately for each sensor, so that differences in the sensors are accounted for automatically.

The ZumoReflectanceSensorArray class inherits this function from the QTRSensors class.

Definition at line 235 of file QTRSensors.cpp.

◆ readLine()

int QTRSensors::readLine	(	unsigned int *	sensor_values,
		unsigned char	readMode = `QTR_EMITTERS_ON`,
		unsigned char	whiteLine = `0`
	)

inherited

Returns an estimated position of a line under the sensor array.

Parameters

sensor_values	Array to populate with sensor readings.
readMode	Read mode (`QTR_EMITTERS_OFF`, `QTR_EMITTERS_ON`, or `QTR_EMITTERS_ON_AND_OFF`).
whiteLine	0 to detect a dark line on a light surface; 1 to detect a light line on a dark surface.

Returns: An estimated line position.

This function operates the same as readCalibrated(), but with a feature designed for line following: it returns an estimated position of the line. The estimate is made using a weighted average of the sensor indices multiplied by 1000, so that a return value of 0 indicates that the line is directly below sensor 0 (or was last seen by sensor 0 before being lost), a return value of 1000 indicates that the line is directly below sensor 1, 2000 indicates that it's below sensor 2, etc. Intermediate values indicate that the line is between two sensors. The formula is:

\[ \newcommand{sv}[1]{\mathtt{sensor_values[#1]}} \text{return value} = \frac{(0 \times \sv{0}) + (1000 \times \sv{1}) + (2000 \times \sv{2}) + \ldots} {\sv{0} + \sv{1} + \sv{2} + \ldots} \]

As long as your sensors aren't spaced too far apart relative to the line, this returned value is designed to be monotonic, which makes it great for use in closed-loop PID control. Additionally, this method remembers where it last saw the line, so if you ever lose the line to the left or the right, its line position will continue to indicate the direction you need to go to reacquire the line. For example, if sensor 5 is your rightmost sensor and you end up completely off the line to the left, this function will continue to return 5000.

By default, this function assumes a dark line (high values) on a light background (low values). If your line is light on dark, set the optional second argument whiteLine to true. In this case, each sensor value will be replaced by the maximum possible value minus its actual value before the averaging.

The ZumoReflectanceSensorArray class inherits this function from the QTRSensors class.

Definition at line 315 of file QTRSensors.cpp.

◆ resetCalibration()

void QTRSensors::resetCalibration ( )

inherited

Resets all calibration that has been done.

This function discards the calibration values that have been previously recorded, resetting the min and max values.

The ZumoReflectanceSensorArray class inherits this function from the QTRSensors class.

Definition at line 129 of file QTRSensors.cpp.

Member Data Documentation

◆ calibratedMaximumOff

unsigned int * QTRSensors::calibratedMaximumOff

inherited

The calibrated maximum values measured for each sensor, with emitters off.

This pointer is unallocated and set to 0 until calibrate() is called, and then allocated to exactly the size required. Depending on the readMode argument to calibrate(), only the On or Off values might be allocated, as required. This variable is made public so that you can use the calibration values for your own calculations and do things like saving them to EEPROM, performing sanity checking, etc.

The ZumoReflectanceSensorArray class inherits this variable from the QTRSensors class.

Definition at line 127 of file QTRSensors.h.

◆ calibratedMaximumOn

unsigned int * QTRSensors::calibratedMaximumOn

inherited

The calibrated maximum values measured for each sensor, with emitters on.

This pointer is unallocated and set to 0 until calibrate() is called, and then allocated to exactly the size required. Depending on the readMode argument to calibrate(), only the On or Off values might be allocated, as required. This variable is made public so that you can use the calibration values for your own calculations and do things like saving them to EEPROM, performing sanity checking, etc.

The ZumoReflectanceSensorArray class inherits this variable from the QTRSensors class.

Definition at line 125 of file QTRSensors.h.

◆ calibratedMinimumOff

unsigned int * QTRSensors::calibratedMinimumOff

inherited

The calibrated minimum values measured for each sensor, with emitters off.

This pointer is unallocated and set to 0 until calibrate() is called, and then allocated to exactly the size required. Depending on the readMode argument to calibrate(), only the On or Off values might be allocated, as required. This variable is made public so that you can use the calibration values for your own calculations and do things like saving them to EEPROM, performing sanity checking, etc.

The ZumoReflectanceSensorArray class inherits this variable from the QTRSensors class.

Definition at line 126 of file QTRSensors.h.

◆ calibratedMinimumOn

unsigned int * QTRSensors::calibratedMinimumOn

inherited

The calibrated minimum values measured for each sensor, with emitters on.

This pointer is unallocated and set to 0 until calibrate() is called, and then allocated to exactly the size required. Depending on the readMode argument to calibrate(), only the On or Off values might be allocated, as required. This variable is made public so that you can use the calibration values for your own calculations and do things like saving them to EEPROM, performing sanity checking, etc.

The ZumoReflectanceSensorArray class inherits this variable from the QTRSensors class.

Definition at line 124 of file QTRSensors.h.

The documentation for this class was generated from the following file:

ZumoReflectanceSensorArray.h

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Calibration

Reading the sensors

Class inheritance

Constructor & Destructor Documentation

◆ ZumoReflectanceSensorArray() [1/3]

◆ ZumoReflectanceSensorArray() [2/3]

◆ ZumoReflectanceSensorArray() [3/3]

Member Function Documentation

◆ calibrate()

◆ emittersOff()

◆ emittersOn()

◆ init() [1/2]

◆ init() [2/2]

◆ read()

◆ readCalibrated()

◆ readLine()

◆ resetCalibration()

Member Data Documentation

◆ calibratedMaximumOff

◆ calibratedMaximumOn

◆ calibratedMinimumOff

◆ calibratedMinimumOn