ZumoReflectanceSensorArray.h

00001 /*! \file ZumoReflectanceSensorArray.h
00002  *
00003  * See the ZumoReflectanceSensorArray class reference for more information about
00004  * this library.
00005  *
00006  * \class ZumoReflectanceSensorArray ZumoReflectanceSensorArray.h
00007  * \brief Read from reflectance sensor array
00008  *
00009  * The ZumoReflectanceSensorArray library provides an interface for using a
00010  * [Zumo Reflectance Sensor Array](http://www.pololu.com/product/1419) connected
00011  * to a Zumo robot. The library provides access to the raw sensor values as well
00012  * as to high level functions including calibration and line-tracking.
00013  *
00014  * For calibration, memory is allocated using the `malloc()` function. This
00015  * conserves RAM: if all six sensors are calibrated with the emitters both on
00016  * and off, a total of 48 bytes is dedicated to storing calibration values.
00017  * However, for an application where only two sensors are used, and the
00018  * emitters are always on during reads, only 4 bytes are required.
00019  *
00020  * Internally, this library uses all standard Arduino functions such as
00021  * `micros()` for timing and `digitalRead()` for getting the sensor values, so
00022  * it should work on all Arduinos without conflicting with other libraries.
00023  *
00024  * ### Calibration ###
00025  *
00026  * This library allows you to use the `calibrate()` method to easily calibrate
00027  * your sensors for the particular conditions it will encounter. Calibrating
00028  * your sensors can lead to substantially more reliable sensor readings, which
00029  * in turn can help simplify your code. As such, we recommend you build a
00030  * calibration phase into your Zumo's initialization routine. This can be as
00031  * simple as a fixed duration over which you repeatedly call the `calibrate()`
00032  * method.
00033  *
00034  * During this calibration phase, you will need to expose each of your
00035  * reflectance sensors to the lightest and darkest readings they will encounter.
00036  * For example, if your Zumo is programmed to be a line follower, you will want
00037  * to slide it across the line during the calibration phase so the each sensor
00038  * can get a reading of how dark the line is and how light the ground is (or you
00039  * can program it to automatically turn back and forth to pass all of the
00040  * sensors over the line). The **SensorCalibration** example included with this
00041  * library demonstrates a calibration routine.
00042  *
00043  * ### Reading the sensors
00044  *
00045  *
00046  * This library gives you a number of different ways to read the sensors.
00047  *
00048  * - You can request raw sensor values using the `read()` method.
00049  *
00050  * - You can request calibrated sensor values using the `readCalibrated()`
00051  *   method. Calibrated sensor values will always range from 0 to 1000, with the
00052  *   extreme values corresponding to the most and least reflective surfaces
00053  *   encountered during calibration.
00054  *
00055  * - For line-detection applications, you can request the line location using
00056  *   the `readLine()` method. This function provides calibrated values
00057  *   for each sensor and returns an integer that tells you where it thinks the
00058  *   line is.
00059  *
00060  * ### Class Inheritance ###
00061  *
00062  * The ZumoReflectanceSensorArray class is derived from the QTRSensorsRC class,
00063  * which is in turn derived from the QTRSensors base class. The QTRSensorsRC and
00064  * QTRSensors classes are part of the \ref QTRSensors.h "QTRSensors" library,
00065  * which provides more general functionality for working with reflectance
00066  * sensors and is included in the Zumo Shield libraries as a dependency for this
00067  * library.
00068  *
00069  * We recommend using the ZumoReflectanceSensorArray library instead of
00070  * the \ref QTRSensors.h "QTRSensors" library when programming an Arduino on a
00071  * Zumo. For documentation specific to the %QTRSensors library, please see its
00072  * [user's guide](http://www.pololu.com/docs/0J19) on Pololu's website.
00073  */
00074 
00075 #ifndef ZumoReflectanceSensorArray_h
00076 #define ZumoReflectanceSensorArray_h
00077 
00078 #include "QTRSensors.h"
00079 #include <mbed.h>
00080 
00081 /*
00082 #if defined(__NUCLEO__) //need to check actual board/processor name
00083   // Nucleo Board
00084   #define ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN  PA4  //need to check actual pin number/name
00085 */
00086 #if defined(__AVR_ATmega32U4__)
00087   // Arduino Leonardo
00088   #define ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN  A4
00089 #elif defined(TARGET_NUCLEO_F103RB)
00090   // Nucleo F103RB
00091   #define ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN  PC_1 //or PA_10???
00092 #else
00093   // Arduino UNO and other ATmega328P/168 Arduinos
00094   #define ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN  2 
00095 #endif
00096 
00097 class ZumoReflectanceSensorArray : public QTRSensorsRC
00098 {
00099   public:
00100 
00101   /*! \brief Minimal constructor.
00102    *
00103    * This version of the constructor performs no initialization. If it is used,
00104    * the user must call init() before using the methods in this class.
00105    */
00106   ZumoReflectanceSensorArray() {}
00107 
00108   /*! \brief Constructor; initializes with given emitter pin and defaults for
00109    *         other settings.
00110    *
00111    * \param emitterPin Pin that turns IR emitters on or off.
00112    *
00113    * This constructor calls `init(PinName emitterPin)` with the specified
00114    * emitter pin and default values for other settings.
00115    */
00116   ZumoReflectanceSensorArray(PinName emitterPin){
00117     init(emitterPin);
00118   }
00119 
00120   /*! \brief Constructor; initializes with all settings as given.
00121    *
00122    * \param pins       Array of pin numbers for sensors.
00123    * \param numSensors Number of sensors.
00124    * \param timeout    Maximum duration of reflectance reading in microseconds.
00125    * \param emitterPin Pin that turns IR emitters on or off.
00126    *
00127    * This constructor calls `init(PinName * pins, unsigned char
00128    * numSensors, unsigned int timeout, PinName emitterPin)` with all
00129    * settings as given.
00130    */
00131   ZumoReflectanceSensorArray(PinName *pins, unsigned char numSensors, unsigned int timeout = 2000, PinName emitterPin = ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN){
00132     QTRSensorsRC::init(pins, numSensors, timeout, emitterPin);
00133   }
00134 
00135   /*! \brief Initializes with given emitter pin and and defaults for other
00136    *         settings.
00137    *
00138    * \param emitterPin Pin that turns IR emitters on or off.
00139    *
00140    * This function initializes the ZumoReflectanceSensorArray object with the
00141    * specified emitter pin. The other settings are set to default values: all
00142    * six sensors on the array are active, and a timeout of 2000 microseconds is
00143    * used.
00144    *
00145    * \a emitterPin is the Arduino digital pin that controls whether the IR LEDs
00146    * are on or off. This pin is optional; if a valid pin is specified, the
00147    * emitters will only be turned on during a reading. If \a emitterPin is not
00148    * specified, the emitters will be controlled with pin 2 on the Uno (and other
00149    * ATmega328/168 boards) or pin A4 on the Leonardo (and other ATmega32U4
00150    * boards). (The "LED ON" jumper on the Zumo Reflectance Sensor Array must be
00151    * configured correctly for this to work.) If the value `QTR_NO_EMITTER_PIN`
00152    * (255) is used, you can leave the emitter pin disconnected and the IR
00153    * emitters will always be on.
00154    */
00155   void init(PinName emitterPin = ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN){
00156     PinName sensorPins[]={ D4, A3, D11, A0, A2, D5 };  // sensorPins[] = { D4, A3, D11, A0, A2, D5 };
00157     QTRSensorsRC::init(sensorPins, sizeof(sensorPins), 2000, emitterPin);
00158   }
00159 
00160   /*! \brief Initializes with all settings as given.
00161    *
00162    * \param pins       Array of pin numbers for sensors.
00163    * \param numSensors Number of sensors.
00164    * \param timeout    Maximum duration of reflectance reading in microseconds.
00165    * \param emitterPin Pin that turns IR emitters on or off.
00166    *
00167    * This function initializes the ZumoReflectanceSensorArray object with all
00168    * settings as given.
00169    *
00170    * The array \a pins should contain the Arduino digital pin numbers for each
00171    * sensor.
00172    *
00173    * \a numSensors specifies the length of the \a pins array (the number of
00174    * reflectance sensors you are using).
00175    *
00176    * \a timeout specifies the length of time in microseconds beyond which you
00177    * consider the sensor reading completely black. That is to say, if the pulse
00178    * length for a pin exceeds \a timeout, pulse timing will stop and the reading
00179    * for that pin will be considered full black. It is recommended that you set
00180    * \a timeout to be between 1000 and 3000 us, depending on factors like the
00181    * height of your sensors and ambient lighting. This allows you to shorten the
00182    * duration of a sensor-reading cycle while maintaining useful measurements of
00183    * reflectance. If \a timeout is not specified, it defaults to 2000 us. (See
00184    * the [product page](http://www.pololu.com/product/1419) for the Zumo
00185    * Reflectance Sensor Array on Pololu's website for an overview of the
00186    * sensors' principle of operation.)
00187    *
00188    * \a emitterPin is the Arduino digital pin that controls whether the IR LEDs
00189    * are on or off. This pin is optional; if a valid pin is specified, the
00190    * emitters will only be turned on during a reading. If \a emitterPin is not
00191    * specified, the emitters will be controlled with pin 2 on the Uno (and other
00192    * ATmega328/168 boards) or pin A4 on the Leonardo (and other ATmega32U4
00193    * boards). (The corresponding connection should be made with the "LED ON"
00194    * jumper on the Zumo Reflectance Sensor Array.) If the value
00195    * `QTR_NO_EMITTER_PIN` (255) is used, you can leave the emitter pin
00196    * disconnected and the IR emitters will always be on.
00197    *
00198    * This version of `%init()` can be useful if you only want to use a subset
00199    * of the six reflectance sensors on the array. For example, using the
00200    * outermost two sensors (on pins 4 and 5 by default) is usually enough for
00201    * detecting the ring border in sumo competitions:
00202    *
00203    * ~~~{.ino}
00204    * ZumoReflectanceSensorArray reflectanceSensors;
00205    *
00206    * ...
00207    *
00208    * reflectanceSensors.init((unsigned char[]) {4, 5}, 2);
00209    * ~~~
00210    *
00211    * Alternatively, you can use \ref ZumoReflectanceSensorArray(unsigned char * pins, unsigned char numSensors, unsigned int timeout, unsigned char emitterPin)
00212    * "a different constructor" to declare and initialize the object at the same
00213    * time:
00214    *
00215    * ~~~{.ino}
00216    *
00217    * ZumoReflectanceSensorArray reflectanceSensors((unsigned char[]) {4, 5}, 2);
00218    * ~~~
00219    *
00220    */
00221   void init(PinName *pins, unsigned char numSensors, unsigned int timeout = 2000, PinName emitterPin = ZUMO_SENSOR_ARRAY_DEFAULT_EMITTER_PIN){
00222     QTRSensorsRC::init(pins, numSensors, timeout, emitterPin);
00223   }
00224 };
00225 
00226 // documentation for inherited functions
00227 
00228 /*! \fn void QTRSensors::read(unsigned int *sensor_values, unsigned char readMode = QTR_EMITTERS_ON)
00229 \memberof ZumoReflectanceSensorArray
00230  * \brief Reads the raw sensor values into an array.
00231  *
00232  * \param sensorValues Array to populate with sensor readings.
00233  * \param readMode     Read mode (`QTR_EMITTERS_OFF`, `QTR_EMITTERS_ON`, or
00234  *                     `QTR_EMITTERS_ON_AND_OFF`).
00235  *
00236  * There **must** be space in the \a sensorValues array for as many values as
00237  * there were sensors specified in the constructor. The values returned are
00238  * measures of the reflectance in units of microseconds. They will be raw
00239  * readings between 0 and the \a timeout argument (in units of microseconds)
00240  * provided in the constructor (which defaults to 2000).
00241  *
00242  * The \a readMode argument specifies the kind of read that will be performed.
00243  * Several options are defined:
00244  *
00245  * - `QTR_EMITTERS_OFF` specifies that the reading should be made without
00246  *   turning on the infrared (IR) emitters, in which case the reading represents
00247  *   ambient light levels near the sensor.
00248  * - `QTR_EMITTERS_ON` specifies that the emitters should be turned on for the
00249  *   reading, which results in a measure of reflectance.
00250  * - `QTR_EMITTERS_ON_AND_OFF` specifies that a reading should be made in both
00251  *   the on and off states. The values returned when this option is used are
00252  *   given by the formula **on + max &minus; off**, where **on** is the reading
00253  *   with the emitters on, **off** is the reading with the emitters off, and
00254  *   **max** is the maximum sensor reading. This option can reduce the amount of
00255  *   interference from uneven ambient lighting.
00256  *
00257  * Note that emitter control will only work if you specify a valid emitter pin
00258  * in the constructor and make the corresponding connection (with the "LED ON"
00259  * jumper or otherwise).
00260  *
00261  * The ZumoReflectanceSensorArray class inherits this function from the
00262  * QTRSensors class.
00263  */
00264 
00265 /*! \fn void QTRSensors::emittersOff()
00266  * \brief Turns the IR LEDs off.
00267  *
00268  * This is mainly for use by the `read()` method, and calling this function
00269  * before or after reading the sensors will have no effect on the readings, but
00270  * you might wish to use it for testing purposes. This method will only do
00271  * something if the emitter pin specified in the constructor is valid (i.e. not
00272  * `QTR_NO_EMITTER_PIN`) and the corresponding connection is made.
00273  *
00274  * The ZumoReflectanceSensorArray class inherits this function from the
00275  * QTRSensors class.
00276  */
00277 
00278 /*! \fn void QTRSensors::emittersOn()
00279  * \brief Turns the IR LEDs on.
00280  * \copydetails emittersOff
00281  */
00282 
00283 /*! \fn void QTRSensors::calibrate(unsigned char readMode = QTR_EMITTERS_ON)
00284  * \brief Reads the sensors for calibration.
00285  *
00286  * \param readMode     Read mode (`QTR_EMITTERS_OFF`, `QTR_EMITTERS_ON`, or
00287  *                     `QTR_EMITTERS_ON_AND_OFF`).
00288  *
00289  * The sensor values read by this function are not returned; instead, the
00290  * maximum and minimum values found over time are stored internally and used for
00291  * the `readCalibrated()` method. You can access the calibration (i.e raw max
00292  * and min sensor readings) through the public member pointers
00293  * `calibratedMinimumOn`, `calibratedMaximumOn`, `calibratedMinimumOff`, and
00294  * `calibratedMaximumOff`. Note that these pointers will point to arrays of
00295  * length \a numSensors, as specified in the constructor, and they will only be
00296  * allocated **after** `calibrate()` has been called. If you only calibrate with
00297  * the emitters on, the calibration arrays that hold the off values will not be
00298  * allocated.
00299  *
00300  * The ZumoReflectanceSensorArray class inherits this function from the
00301  * QTRSensors class.
00302  */
00303 
00304 /*! \fn void QTRSensors::resetCalibration()
00305  * \brief Resets all calibration that has been done.
00306  *
00307  * This function discards the calibration values that have been previously
00308  * recorded, resetting the min and max values.
00309  *
00310  * The ZumoReflectanceSensorArray class inherits this function from the
00311  * QTRSensors class.
00312  */
00313 
00314 /*! \fn void QTRSensors::readCalibrated(unsigned int *sensor_values, unsigned char readMode = QTR_EMITTERS_ON)
00315  * \brief Returns sensor readings normalized to values between 0 and 1000.
00316  *
00317  * \param sensorValues Array to populate with sensor readings.
00318  * \param readMode     Read mode (`QTR_EMITTERS_OFF`, `QTR_EMITTERS_ON`, or
00319  *                     `QTR_EMITTERS_ON_AND_OFF`).
00320  *
00321  * 0 corresponds to a reading that is less than or equal to the minimum value
00322  * read by `calibrate()` and 1000 corresponds to a reading that is greater than
00323  * or equal to the maximum value. Calibration values are stored separately for
00324  * each sensor, so that differences in the sensors are accounted for
00325  * automatically.
00326  *
00327  * The ZumoReflectanceSensorArray class inherits this function from the
00328  * QTRSensors class.
00329  */
00330 
00331 /*! \fn int QTRSensors::readLine(unsigned int *sensor_values, unsigned char readMode = QTR_EMITTERS_ON, unsigned char whiteLine = 0)
00332  * \brief Returns an estimated position of a line under the sensor array.
00333  *
00334  * \param sensorValues Array to populate with sensor readings.
00335  * \param readMode     Read mode (`QTR_EMITTERS_OFF`, `QTR_EMITTERS_ON`, or
00336  *                     `QTR_EMITTERS_ON_AND_OFF`).
00337  * \param whiteLine   0 to detect a dark line on a light surface; 1 to detect
00338  *                     a light line on a dark surface.
00339  * \return An estimated line position.
00340  *
00341  * This function operates the same as `readCalibrated()`, but with a feature
00342  * designed for line following: it returns an estimated position of the line.
00343  * The estimate is made using a weighted average of the sensor indices
00344  * multiplied by 1000, so that a return value of 0 indicates that the line is
00345  * directly below sensor 0 (or was last seen by sensor 0 before being lost), a
00346  * return value of 1000 indicates that the line is directly below sensor 1, 2000
00347  * indicates that it's below sensor 2, etc. Intermediate values indicate that
00348  * the line is between two sensors. The formula is:
00349  *
00350  * \f[
00351  *   \newcommand{sv}[1]{\mathtt{sensorValues[#1]}}
00352  *   \text{return value} =
00353  *     \frac{(0 \times \sv{0}) + (1000 \times \sv{1}) + (2000 \times \sv{2}) + \ldots}
00354  *          {\sv{0} + \sv{1} + \sv{2} + \ldots}
00355  * \f]
00356  *
00357  * As long as your sensors aren't spaced too far apart relative to the line,
00358  * this returned value is designed to be monotonic, which makes it great for use
00359  * in closed-loop PID control. Additionally, this method remembers where it last
00360  * saw the line, so if you ever lose the line to the left or the right, its line
00361  * position will continue to indicate the direction you need to go to reacquire
00362  * the line. For example, if sensor 5 is your rightmost sensor and you end up
00363  * completely off the line to the left, this function will continue to return
00364  * 5000.
00365  *
00366  * By default, this function assumes a dark line (high values) on a light
00367  * background (low values). If your line is light on dark, set the optional
00368  * second argument \a whiteLine to true. In this case, each sensor value will be
00369  * replaced by the maximum possible value minus its actual value before the
00370  * averaging.
00371  *
00372  * The ZumoReflectanceSensorArray class inherits this function from the
00373  * QTRSensors class.
00374  */
00375 
00376  
00377 // documentation for inherited member variables
00378 
00379 /*!
00380  * \property unsigned int * QTRSensors::calibratedMinimumOn
00381  * \brief The calibrated minimum values measured for each sensor, with emitters
00382  *        on.
00383  *
00384  * This pointer is unallocated and set to 0 until `calibrate()` is called, and
00385  * then allocated to exactly the size required. Depending on the \a readMode
00386  * argument to `calibrate()`, only the On or Off values might be allocated, as
00387  * required. This variable is made public so that you can use the calibration
00388  * values for your own calculations and do things like saving them to EEPROM,
00389  * performing sanity checking, etc.
00390  *
00391  * The ZumoReflectanceSensorArray class inherits this variable from the
00392  * QTRSensors class.
00393  *
00394  * \property unsigned int * QTRSensors::calibratedMaximumOn
00395  * \brief The calibrated maximum values measured for each sensor, with emitters
00396  *        on.
00397  * \copydetails QTRSensors::calibratedMinimumOn
00398  *
00399  * \property unsigned int * QTRSensors::calibratedMinimumOff
00400  * \brief The calibrated minimum values measured for each sensor, with emitters
00401  *        off.
00402  * \copydetails QTRSensors::calibratedMinimumOn
00403  *
00404  * \property unsigned int * QTRSensors::calibratedMaximumOff
00405  * \brief The calibrated maximum values measured for each sensor, with emitters
00406  *        off.
00407  * \copydetails QTRSensors::calibratedMinimumOn
00408  */
00409 
00410 #endif