TRSensors.h

00001 /*
00002   QTRSensors.h - Library for using Pololu QTR reflectance
00003     sensors and reflectance sensor arrays: QTR-1A, QTR-8A, QTR-1RC, and 
00004     QTR-8RC.  The object used will determine the type of the sensor (either
00005     QTR-xA or QTR-xRC).  Then simply specify in the constructor which 
00006     Arduino I/O pins are connected to a QTR sensor, and the read() method
00007     will obtain reflectance measurements for those sensors.  Smaller sensor
00008     values correspond to higher reflectance (e.g. white) while larger
00009     sensor values correspond to lower reflectance (e.g. black or a void).
00010     
00011     * QTRSensorsRC should be used for QTR-1RC and QTR-8RC sensors.
00012     * QTRSensorsAnalog should be used for QTR-1A and QTR-8A sensors.
00013 */
00014     
00015 /*
00016  * Written by Ben Schmidel et al., October 4, 2010
00017  * Copyright (c) 2008-2012 Pololu Corporation. For more information, see
00018  *
00019  *   http://www.pololu.com
00020  *   http://forum.pololu.com
00021  *   http://www.pololu.com/docs/0J19
00022  *
00023  * You may freely modify and share this code, as long as you keep this
00024  * notice intact (including the two links above).  Licensed under the
00025  * Creative Commons BY-SA 3.0 license:
00026  *
00027  *   http://creativecommons.org/licenses/by-sa/3.0/
00028  *
00029  * Disclaimer: To the extent permitted by law, Pololu provides this work
00030  * without any warranty.  It might be defective, in which case you agree
00031  * to be responsible for all resulting costs and damages.
00032  */
00033 
00034 #ifndef TRSensors_h
00035 #define TRSensors_h
00036 
00037 #include "mbed.h"
00038 
00039 #define QTR_EMITTERS_OFF 0
00040 #define QTR_EMITTERS_ON 1
00041 #define QTR_EMITTERS_ON_AND_OFF 2
00042 
00043 #define QTR_NO_EMITTER_PIN  255
00044 
00045 #define QTR_MAX_SENSORS 16
00046 
00047 // This class cannot be instantiated directly (it has no constructor).
00048 // Instead, you should instantiate one of its two derived classes (either the
00049 // QTR-A or QTR-RC version, depending on the type of your sensor).
00050 class TRSensors
00051 {
00052   public:
00053     
00054   TRSensors();
00055     // Reads the sensor values into an array. There *MUST* be space
00056     // for as many values as there were sensors specified in the constructor.
00057     // Example usage:
00058     // unsigned int sensor_values[8];
00059     // sensors.read(sensor_values);
00060     // The values returned are a measure of the reflectance in abstract units,
00061     // with higher values corresponding to lower reflectance (e.g. a black
00062     // surface or a void).
00063     // If measureOffAndOn is true, measures the values with the
00064     // emitters on AND off and returns on - (timeout - off).  If this
00065     // value is less than zero, it returns zero.
00066     // This method will call the appropriate derived class' readPrivate(), as
00067     // determined by the _type data member.  Making this method virtual
00068     // leads to compiler warnings, which is why this alternate approach was
00069     // taken.
00070     void AnalogRead(unsigned int *sensor_values);
00071   
00072     // Reads the sensors for calibration.  The sensor values are
00073     // not returned; instead, the maximum and minimum values found
00074     // over time are stored internally and used for the
00075     // readCalibrated() method.
00076     void calibrate();
00077 
00078     // Returns values calibrated to a value between 0 and 1000, where
00079     // 0 corresponds to the minimum value read by calibrate() and 1000
00080     // corresponds to the maximum value.  Calibration values are
00081     // stored separately for each sensor, so that differences in the
00082     // sensors are accounted for automatically.
00083     void readCalibrated(unsigned int *sensor_values);
00084 
00085     // Operates the same as read calibrated, but also returns an
00086     // estimated position of the robot with respect to a line. The
00087     // estimate is made using a weighted average of the sensor indices
00088     // multiplied by 1000, so that a return value of 0 indicates that
00089     // the line is directly below sensor 0, a return value of 1000
00090     // indicates that the line is directly below sensor 1, 2000
00091     // indicates that it's below sensor 2000, etc.  Intermediate
00092     // values indicate that the line is between two sensors.  The
00093     // formula is:
00094     // 
00095     //    0*value0 + 1000*value1 + 2000*value2 + ...
00096     //   --------------------------------------------
00097     //         value0  +  value1  +  value2 + ...
00098     //
00099     // By default, this function assumes a dark line (high values)
00100     // surrounded by white (low values).  If your line is light on
00101     // black, set the optional second argument white_line to true.  In
00102     // this case, each sensor value will be replaced by (1000-value)
00103     // before the averaging.
00104     int readLine(unsigned int *sensor_values, unsigned char white_line = 0);
00105 
00106     // Calibrated minumum and maximum values. These start at 1000 and
00107     // 0, respectively, so that the very first sensor reading will
00108     // update both of them.
00109     //
00110     // The pointers are unallocated until calibrate() is called, and
00111     // then allocated to exactly the size required.  Depending on the
00112     // readMode argument to calibrate, only the On or Off values may
00113     // be allocated, as required.
00114     //
00115     // These variables are made public so that you can use them for
00116     // your own calculations and do things like saving the values to
00117     // EEPROM, performing sanity checking, etc.
00118   unsigned char _numSensors;
00119     unsigned int *calibratedMin;
00120     unsigned int *calibratedMax;
00121 
00122 };
00123 
00124 #endif