[232] | 1 | /*
|
---|
| 2 | QTRSensors.h - Library for using Pololu QTR reflectance
|
---|
| 3 | sensors and reflectance sensor arrays: QTR-1A, QTR-8A, QTR-1RC, and
|
---|
| 4 | QTR-8RC. The object used will determine the type of the sensor (either
|
---|
| 5 | QTR-xA or QTR-xRC). Then simply specify in the constructor which
|
---|
| 6 | Arduino I/O pins are connected to a QTR sensor, and the read() method
|
---|
| 7 | will obtain reflectance measurements for those sensors. Smaller sensor
|
---|
| 8 | values correspond to higher reflectance (e.g. white) while larger
|
---|
| 9 | sensor values correspond to lower reflectance (e.g. black or a void).
|
---|
| 10 |
|
---|
| 11 | * QTRSensorsRC should be used for QTR-1RC and QTR-8RC sensors.
|
---|
| 12 | * QTRSensorsAnalog should be used for QTR-1A and QTR-8A sensors.
|
---|
| 13 | */
|
---|
| 14 |
|
---|
| 15 | /*
|
---|
| 16 | * Written by Ben Schmidel et al., October 4, 2010
|
---|
| 17 | * Copyright (c) 2008-2012 Pololu Corporation. For more information, see
|
---|
| 18 | *
|
---|
| 19 | * http://www.pololu.com
|
---|
| 20 | * http://forum.pololu.com
|
---|
| 21 | * http://www.pololu.com/docs/0J19
|
---|
| 22 | *
|
---|
| 23 | * You may freely modify and share this code, as long as you keep this
|
---|
| 24 | * notice intact (including the two links above). Licensed under the
|
---|
| 25 | * Creative Commons BY-SA 3.0 license:
|
---|
| 26 | *
|
---|
| 27 | * http://creativecommons.org/licenses/by-sa/3.0/
|
---|
| 28 | *
|
---|
| 29 | * Disclaimer: To the extent permitted by law, Pololu provides this work
|
---|
| 30 | * without any warranty. It might be defective, in which case you agree
|
---|
| 31 | * to be responsible for all resulting costs and damages.
|
---|
| 32 | */
|
---|
| 33 |
|
---|
| 34 | #ifndef QTRSensors_h
|
---|
| 35 | #define QTRSensors_h
|
---|
| 36 |
|
---|
| 37 | #define QTR_EMITTERS_OFF 0
|
---|
| 38 | #define QTR_EMITTERS_ON 1
|
---|
| 39 | #define QTR_EMITTERS_ON_AND_OFF 2
|
---|
| 40 |
|
---|
| 41 | #define QTR_NO_EMITTER_PIN 255
|
---|
| 42 |
|
---|
| 43 | #define QTR_MAX_SENSORS 16
|
---|
| 44 |
|
---|
| 45 | // This class cannot be instantiated directly (it has no constructor).
|
---|
| 46 | // Instead, you should instantiate one of its two derived classes (either the
|
---|
| 47 | // QTR-A or QTR-RC version, depending on the type of your sensor).
|
---|
| 48 | class QTRSensors
|
---|
| 49 | {
|
---|
| 50 | public:
|
---|
| 51 |
|
---|
| 52 | // Reads the sensor values into an array. There *MUST* be space
|
---|
| 53 | // for as many values as there were sensors specified in the constructor.
|
---|
| 54 | // Example usage:
|
---|
| 55 | // unsigned int sensor_values[8];
|
---|
| 56 | // sensors.read(sensor_values);
|
---|
| 57 | // The values returned are a measure of the reflectance in abstract units,
|
---|
| 58 | // with higher values corresponding to lower reflectance (e.g. a black
|
---|
| 59 | // surface or a void).
|
---|
| 60 | // If measureOffAndOn is true, measures the values with the
|
---|
| 61 | // emitters on AND off and returns on - (timeout - off). If this
|
---|
| 62 | // value is less than zero, it returns zero.
|
---|
| 63 | // This method will call the appropriate derived class's readPrivate(),
|
---|
| 64 | // which is defined as a virtual function in the base class and
|
---|
| 65 | // overridden by each derived class's own implementation.
|
---|
| 66 | void read(unsigned int *sensor_values, unsigned char readMode = QTR_EMITTERS_ON);
|
---|
| 67 |
|
---|
| 68 | // Turn the IR LEDs off and on. This is mainly for use by the
|
---|
| 69 | // read method, and calling these functions before or
|
---|
| 70 | // after the reading the sensors will have no effect on the
|
---|
| 71 | // readings, but you may wish to use these for testing purposes.
|
---|
| 72 | void emittersOff();
|
---|
| 73 | void emittersOn();
|
---|
| 74 |
|
---|
| 75 | // Reads the sensors for calibration. The sensor values are
|
---|
| 76 | // not returned; instead, the maximum and minimum values found
|
---|
| 77 | // over time are stored internally and used for the
|
---|
| 78 | // readCalibrated() method.
|
---|
| 79 | void calibrate(unsigned char readMode = QTR_EMITTERS_ON);
|
---|
| 80 |
|
---|
| 81 | // Resets all calibration that has been done.
|
---|
| 82 | void resetCalibration();
|
---|
| 83 |
|
---|
| 84 | // Returns values calibrated to a value between 0 and 1000, where
|
---|
| 85 | // 0 corresponds to the minimum value read by calibrate() and 1000
|
---|
| 86 | // corresponds to the maximum value. Calibration values are
|
---|
| 87 | // stored separately for each sensor, so that differences in the
|
---|
| 88 | // sensors are accounted for automatically.
|
---|
| 89 | void readCalibrated(unsigned int *sensor_values, unsigned char readMode = QTR_EMITTERS_ON);
|
---|
| 90 |
|
---|
| 91 | // Operates the same as read calibrated, but also returns an
|
---|
| 92 | // estimated position of the robot with respect to a line. The
|
---|
| 93 | // estimate is made using a weighted average of the sensor indices
|
---|
| 94 | // multiplied by 1000, so that a return value of 0 indicates that
|
---|
| 95 | // the line is directly below sensor 0, a return value of 1000
|
---|
| 96 | // indicates that the line is directly below sensor 1, 2000
|
---|
| 97 | // indicates that it's below sensor 2000, etc. Intermediate
|
---|
| 98 | // values indicate that the line is between two sensors. The
|
---|
| 99 | // formula is:
|
---|
| 100 | //
|
---|
| 101 | // 0*value0 + 1000*value1 + 2000*value2 + ...
|
---|
| 102 | // --------------------------------------------
|
---|
| 103 | // value0 + value1 + value2 + ...
|
---|
| 104 | //
|
---|
| 105 | // By default, this function assumes a dark line (high values)
|
---|
| 106 | // surrounded by white (low values). If your line is light on
|
---|
| 107 | // black, set the optional second argument white_line to true. In
|
---|
| 108 | // this case, each sensor value will be replaced by (1000-value)
|
---|
| 109 | // before the averaging.
|
---|
| 110 | int readLine(unsigned int *sensor_values, unsigned char readMode = QTR_EMITTERS_ON, unsigned char white_line = 0);
|
---|
| 111 |
|
---|
| 112 | // Calibrated minumum and maximum values. These start at 1000 and
|
---|
| 113 | // 0, respectively, so that the very first sensor reading will
|
---|
| 114 | // update both of them.
|
---|
| 115 | //
|
---|
| 116 | // The pointers are unallocated until calibrate() is called, and
|
---|
| 117 | // then allocated to exactly the size required. Depending on the
|
---|
| 118 | // readMode argument to calibrate, only the On or Off values may
|
---|
| 119 | // be allocated, as required.
|
---|
| 120 | //
|
---|
| 121 | // These variables are made public so that you can use them for
|
---|
| 122 | // your own calculations and do things like saving the values to
|
---|
| 123 | // EEPROM, performing sanity checking, etc.
|
---|
| 124 | unsigned int *calibratedMinimumOn;
|
---|
| 125 | unsigned int *calibratedMaximumOn;
|
---|
| 126 | unsigned int *calibratedMinimumOff;
|
---|
| 127 | unsigned int *calibratedMaximumOff;
|
---|
| 128 |
|
---|
| 129 | ~QTRSensors();
|
---|
| 130 |
|
---|
| 131 | protected:
|
---|
| 132 |
|
---|
| 133 | QTRSensors()
|
---|
| 134 | {
|
---|
| 135 |
|
---|
| 136 | };
|
---|
| 137 |
|
---|
| 138 | void init(unsigned char *pins, unsigned char numSensors, unsigned char emitterPin);
|
---|
| 139 |
|
---|
| 140 | unsigned char *_pins;
|
---|
| 141 | unsigned char _numSensors;
|
---|
| 142 | unsigned char _emitterPin;
|
---|
| 143 | unsigned int _maxValue; // the maximum value returned by this function
|
---|
| 144 |
|
---|
| 145 | private:
|
---|
| 146 |
|
---|
| 147 | virtual void readPrivate(unsigned int *sensor_values) = 0;
|
---|
| 148 |
|
---|
| 149 | // Handles the actual calibration. calibratedMinimum and
|
---|
| 150 | // calibratedMaximum are pointers to the requested calibration
|
---|
| 151 | // arrays, which will be allocated if necessary.
|
---|
| 152 | void calibrateOnOrOff(unsigned int **calibratedMinimum,
|
---|
| 153 | unsigned int **calibratedMaximum,
|
---|
| 154 | unsigned char readMode);
|
---|
| 155 | };
|
---|
| 156 |
|
---|
| 157 |
|
---|
| 158 |
|
---|
| 159 | // Object to be used for QTR-1RC and QTR-8RC sensors
|
---|
| 160 | class QTRSensorsRC : public QTRSensors
|
---|
| 161 | {
|
---|
| 162 | public:
|
---|
| 163 |
|
---|
| 164 | // if this constructor is used, the user must call init() before using
|
---|
| 165 | // the methods in this class
|
---|
| 166 | QTRSensorsRC();
|
---|
| 167 |
|
---|
| 168 | // this constructor just calls init()
|
---|
| 169 | QTRSensorsRC(unsigned char* pins, unsigned char numSensors,
|
---|
| 170 | unsigned int timeout = 4000, unsigned char emitterPin = 255);
|
---|
| 171 |
|
---|
| 172 | // The array 'pins' contains the Arduino pin number for each sensor.
|
---|
| 173 |
|
---|
| 174 | // 'numSensors' specifies the length of the 'pins' array (i.e. the
|
---|
| 175 | // number of QTR-RC sensors you are using). numSensors must be
|
---|
| 176 | // no greater than 16.
|
---|
| 177 |
|
---|
| 178 | // 'timeout' specifies the length of time in microseconds beyond
|
---|
| 179 | // which you consider the sensor reading completely black. That is to say,
|
---|
| 180 | // if the pulse length for a pin exceeds 'timeout', pulse timing will stop
|
---|
| 181 | // and the reading for that pin will be considered full black.
|
---|
| 182 | // It is recommended that you set timeout to be between 1000 and
|
---|
| 183 | // 3000 us, depending on things like the height of your sensors and
|
---|
| 184 | // ambient lighting. Using timeout allows you to shorten the
|
---|
| 185 | // duration of a sensor-reading cycle while still maintaining
|
---|
| 186 | // useful analog measurements of reflectance
|
---|
| 187 |
|
---|
| 188 | // 'emitterPin' is the Arduino pin that controls the IR LEDs on the 8RC
|
---|
| 189 | // modules. If you are using a 1RC (i.e. if there is no emitter pin),
|
---|
| 190 | // or if you just want the emitters on all the time and don't want to
|
---|
| 191 | // use an I/O pin to control it, use a value of 255 (QTR_NO_EMITTER_PIN).
|
---|
| 192 | void init(unsigned char* pins, unsigned char numSensors,
|
---|
| 193 | unsigned int timeout = 2000, unsigned char emitterPin = QTR_NO_EMITTER_PIN);
|
---|
| 194 |
|
---|
| 195 |
|
---|
| 196 |
|
---|
| 197 | private:
|
---|
| 198 |
|
---|
| 199 | // Reads the sensor values into an array. There *MUST* be space
|
---|
| 200 | // for as many values as there were sensors specified in the constructor.
|
---|
| 201 | // Example usage:
|
---|
| 202 | // unsigned int sensor_values[8];
|
---|
| 203 | // sensors.read(sensor_values);
|
---|
| 204 | // The values returned are a measure of the reflectance in microseconds.
|
---|
| 205 | void readPrivate(unsigned int *sensor_values);
|
---|
| 206 | };
|
---|
| 207 |
|
---|
| 208 |
|
---|
| 209 |
|
---|
| 210 | // Object to be used for QTR-1A and QTR-8A sensors
|
---|
| 211 | class QTRSensorsAnalog : public QTRSensors
|
---|
| 212 | {
|
---|
| 213 | public:
|
---|
| 214 |
|
---|
| 215 | // if this constructor is used, the user must call init() before using
|
---|
| 216 | // the methods in this class
|
---|
| 217 | QTRSensorsAnalog();
|
---|
| 218 |
|
---|
| 219 | // this constructor just calls init()
|
---|
| 220 | QTRSensorsAnalog(unsigned char* pins,
|
---|
| 221 | unsigned char numSensors, unsigned char numSamplesPerSensor = 4,
|
---|
| 222 | unsigned char emitterPin = 255);
|
---|
| 223 |
|
---|
| 224 | // the array 'pins' contains the Arduino analog pin assignment for each
|
---|
| 225 | // sensor. For example, if pins is {0, 1, 7}, sensor 1 is on
|
---|
| 226 | // Arduino analog input 0, sensor 2 is on Arduino analog input 1,
|
---|
| 227 | // and sensor 3 is on Arduino analog input 7.
|
---|
| 228 |
|
---|
| 229 | // 'numSensors' specifies the length of the 'analogPins' array (i.e. the
|
---|
| 230 | // number of QTR-A sensors you are using). numSensors must be
|
---|
| 231 | // no greater than 16.
|
---|
| 232 |
|
---|
| 233 | // 'numSamplesPerSensor' indicates the number of 10-bit analog samples
|
---|
| 234 | // to average per channel (i.e. per sensor) for each reading. The total
|
---|
| 235 | // number of analog-to-digital conversions performed will be equal to
|
---|
| 236 | // numSensors*numSamplesPerSensor. Note that it takes about 100 us to
|
---|
| 237 | // perform a single analog-to-digital conversion, so:
|
---|
| 238 | // if numSamplesPerSensor is 4 and numSensors is 6, it will take
|
---|
| 239 | // 4 * 6 * 100 us = ~2.5 ms to perform a full readLine().
|
---|
| 240 | // Increasing this parameter increases noise suppression at the cost of
|
---|
| 241 | // sample rate. The recommended value is 4.
|
---|
| 242 |
|
---|
| 243 | // 'emitterPin' is the Arduino pin that controls the IR LEDs on the 8RC
|
---|
| 244 | // modules. If you are using a 1RC (i.e. if there is no emitter pin),
|
---|
| 245 | // or if you just want the emitters on all the time and don't want to
|
---|
| 246 | // use an I/O pin to control it, use a value of 255 (QTR_NO_EMITTER_PIN).
|
---|
| 247 | void init(unsigned char* analogPins, unsigned char numSensors,
|
---|
| 248 | unsigned char numSamplesPerSensor = 4, unsigned char emitterPin = QTR_NO_EMITTER_PIN);
|
---|
| 249 |
|
---|
| 250 |
|
---|
| 251 |
|
---|
| 252 | private:
|
---|
| 253 |
|
---|
| 254 | // Reads the sensor values into an array. There *MUST* be space
|
---|
| 255 | // for as many values as there were sensors specified in the constructor.
|
---|
| 256 | // Example usage:
|
---|
| 257 | // unsigned int sensor_values[8];
|
---|
| 258 | // sensors.read(sensor_values);
|
---|
| 259 | // The values returned are a measure of the reflectance in terms of a
|
---|
| 260 | // 10-bit ADC average with higher values corresponding to lower
|
---|
| 261 | // reflectance (e.g. a black surface or a void).
|
---|
| 262 | void readPrivate(unsigned int *sensor_values);
|
---|
| 263 |
|
---|
| 264 | unsigned char _numSamplesPerSensor;
|
---|
| 265 | };
|
---|
| 266 |
|
---|
| 267 |
|
---|
| 268 | #endif
|
---|