QTRSensors library
Classes | Public Member Functions | List of all members
QTRSensors Class Reference

Represents a QTR sensor array. More...

#include <QTRSensors.h>

Classes

struct  CalibrationData
 Stores sensor calibration data. More...
 

Public Member Functions

void setTypeRC ()
 Specifies that the sensors are RC. More...
 
void setTypeAnalog ()
 Specifies that the sensor type is analog. More...
 
QTRType getType ()
 Returns the type of the sensors. More...
 
void setSensorPins (const uint8_t *pins, uint8_t sensorCount)
 Sets the sensor pins. More...
 
void setTimeout (uint16_t timeout)
 Sets the timeout for RC sensors. More...
 
uint16_t getTimeout ()
 Returns the timeout for RC sensors. More...
 
void setSamplesPerSensor (uint8_t samples)
 Sets the number of analog readings to average per analog sensor. More...
 
uint16_t getSamplesPerSensor ()
 Returns the number of analog readings to average per analog sensor. More...
 
void setEmitterPin (uint8_t emitterPin)
 Sets the emitter control pin for the sensors. More...
 
void setEmitterPins (uint8_t oddEmitterPin, uint8_t evenEmitterPin)
 Sets separate odd and even emitter control pins for the sensors. More...
 
void releaseEmitterPins ()
 Releases emitter pin/pins that have been set. More...
 
uint8_t getEmitterPinCount ()
 Returns the number of emitter control pins in use. More...
 
uint8_t getEmitterPin ()
 Returns the emitter control pin. More...
 
uint8_t getOddEmitterPin ()
 Returns the odd emitter control pin. More...
 
uint8_t getEvenEmitterPin ()
 Returns the even emitter control pin. More...
 
void setDimmable ()
 Specifies that the sensors are dimmable. More...
 
void setNonDimmable ()
 Specifies that the sensors are non-dimmable. More...
 
bool getDimmable ()
 Returns whether the sensors are dimmable. More...
 
void setDimmingLevel (uint8_t dimmingLevel)
 Sets the dimming level. More...
 
uint8_t getDimmingLevel ()
 Returns the dimming level. More...
 
void emittersOff (QTREmitters emitters=QTREmitters::All, bool wait=true)
 Turns the IR LEDs off. More...
 
void emittersOn (QTREmitters emitters=QTREmitters::All, bool wait=true)
 Turns the IR LEDs on. More...
 
void emittersSelect (QTREmitters emitters)
 Turns on the selected emitters and turns off the other emitters with optimized timing. More...
 
void calibrate (QTRReadMode mode=QTRReadMode::On)
 Reads the sensors for calibration. More...
 
void resetCalibration ()
 Resets all calibration that has been done.
 
void read (uint16_t *sensorValues, QTRReadMode mode=QTRReadMode::On)
 Reads the raw sensor values into an array. More...
 
void readCalibrated (uint16_t *sensorValues, QTRReadMode mode=QTRReadMode::On)
 Reads the sensors and provides calibrated values between 0 and 1000. More...
 
uint16_t readLineBlack (uint16_t *sensorValues, QTRReadMode mode=QTRReadMode::On)
 Reads the sensors, provides calibrated values, and returns an estimated black line position. More...
 
uint16_t readLineWhite (uint16_t *sensorValues, QTRReadMode mode=QTRReadMode::On)
 Reads the sensors, provides calibrated values, and returns an estimated white line position. More...
 

Public Attributes

Calibration data

See calibrate() and readCalibrated() for details.

These variables are made public so that you can use them for your own calculations and do things like saving the values to EEPROM, performing sanity checking, etc.

CalibrationData calibrationOn
 Data from calibrating with emitters on.
 
CalibrationData calibrationOff
 Data from calibrating with emitters off.
 

Detailed Description

Represents a QTR sensor array.

An instance of this class represents a QTR sensor array, consisting of one or more sensors of the same type. This could be either a single QTR sensor board or multiple boards controlled as a group.

See Usage Notes for an overview of how this library can be used and some example code.

Definition at line 83 of file QTRSensors.h.

Member Function Documentation

◆ calibrate()

void QTRSensors::calibrate ( QTRReadMode  mode = QTRReadMode::On)

Reads the sensors for calibration.

Parameters
modeThe emitter behavior during calibration, as a member of the QTRReadMode enum. The default is QTRReadMode::On. Manual emitter control with QTRReadMode::Manual is not supported.

This method reads the sensors 10 times and uses the results for calibration. The sensor values are not returned; instead, the maximum and minimum values found over time are stored in calibrationOn and/or calibrationOff for use by the readCalibrated() method.

If the storage for the calibration values has not been initialized, this function will (re)allocate the arrays and initialize the maximum and minimum values to 0 and the maximum possible sensor reading, respectively, so that the very first calibration sensor reading will update both of them.

Note that the minimum and maximum pointers in the CalibrationData structs will point to arrays of length sensorCount, as specified in setSensorPins(), and they will only be allocated when calibrate() is called. If you only calibrate with the emitters on, the calibration arrays that hold the off values will not be allocated (and vice versa).

See Usage Notes for more information and example code.

Definition at line 304 of file QTRSensors.cpp.

◆ emittersOff()

void QTRSensors::emittersOff ( QTREmitters  emitters = QTREmitters::All,
bool  wait = true 
)

Turns the IR LEDs off.

Parameters
emittersWhich emitters to turn off, as a member of the QTREmitters enum. The default is QTREmitters::All.
waitIf true (the default), this function delays to give the sensors time to turn off before returning. Otherwise, it returns immediately.

This function is mainly for use by the read() method. Since read() normally turns the emitters on and off automatically for each reading, calling this function yourself will not affect the readings unless the read mode is QTRReadMode::Manual, which tells read() to leave the emitters alone.

Definition at line 102 of file QTRSensors.cpp.

◆ emittersOn()

void QTRSensors::emittersOn ( QTREmitters  emitters = QTREmitters::All,
bool  wait = true 
)

Turns the IR LEDs on.

Parameters
emittersWhich emitters to turn on, as a member of the QTREmitters enum. The default is QTREmitters::All.
waitIf true (the default), this function delays to give the sensors time to turn on before returning. Otherwise, it returns immediately.

If the sensors are dimmable and a dimming level is set, this function will apply the dimming level after turning the emitters on.

This function is mainly for use by the read() method. Since read() normally turns the emitters on and off automatically for each reading, calling this function yourself will not affect the readings unless the read mode is QTRReadMode::Manual, which tells read() to leave the emitters alone.

Definition at line 151 of file QTRSensors.cpp.

◆ emittersSelect()

void QTRSensors::emittersSelect ( QTREmitters  emitters)

Turns on the selected emitters and turns off the other emitters with optimized timing.

Parameters
emittersWhich emitters to turn on, as a member of the QTREmitters enum. The other emitters will be turned off.

This function turns on the selected emitters while it waits for the other emitters to turn off. For example, emittersSelect(QTREmitters::Odd) turns on the odd-numbered emitters while turning off the even-numbered emitters. Using this method avoids unnecessary delays compared to calling emittersOff() and emittersOn() separately, but it still waits for all emitters to be in the right states before returning.

Definition at line 247 of file QTRSensors.cpp.

◆ getDimmable()

bool QTRSensors::getDimmable ( )
inline

Returns whether the sensors are dimmable.

Returns
True if this object is configured to treat the sensors as dimmable, false otherwise.

See also setDimmable() and setNonDimmable().

Definition at line 297 of file QTRSensors.h.

◆ getDimmingLevel()

uint8_t QTRSensors::getDimmingLevel ( )
inline

Returns the dimming level.

Returns
The dimming level.

See also setDimmingLevel().

Definition at line 322 of file QTRSensors.h.

◆ getEmitterPin()

uint8_t QTRSensors::getEmitterPin ( )
inline

Returns the emitter control pin.

Returns
The Arduino digital pin number of the emitter control pin (QTRNoEmitterPin if undefined).

This function is intended for use when there is a single emitter pin specified; you can use getOddEmitterPin() and getEvenEmitterPin() instead when two are specified.

See also setEmitterPin().

Definition at line 247 of file QTRSensors.h.

◆ getEmitterPinCount()

uint8_t QTRSensors::getEmitterPinCount ( )
inline

Returns the number of emitter control pins in use.

Returns
The number of emitter control pins previously specified (1 with setEmitterPin() or 2 with setEmitterPins()). If no emitter pins have been specified (the default), or if previously specified pins were released with releaseEmitterPins(), this function returns 0.

Definition at line 235 of file QTRSensors.h.

◆ getEvenEmitterPin()

uint8_t QTRSensors::getEvenEmitterPin ( )
inline

Returns the even emitter control pin.

Returns
The Arduino digital pin number of the even emitter control pin (QTRNoEmitterPin if undefined).

This function is intended for use when there are separate odd and even emitter pins specified; you can use getEmitterPin() instead when only one is specified.

See also getOddEmitterPin() and setEmitterPins().

Definition at line 271 of file QTRSensors.h.

◆ getOddEmitterPin()

uint8_t QTRSensors::getOddEmitterPin ( )
inline

Returns the odd emitter control pin.

Returns
The Arduino digital pin number of the odd emitter control pin (QTRNoEmitterPin if undefined).

This function is intended for use when there are separate odd and even emitter pins specified; you can use getEmitterPin() instead when only one is specified.

See also getEvenEmitterPin() and setEmitterPins().

Definition at line 259 of file QTRSensors.h.

◆ getSamplesPerSensor()

uint16_t QTRSensors::getSamplesPerSensor ( )
inline

Returns the number of analog readings to average per analog sensor.

Returns
The samples per channel for analog sensors.

See also setSamplesPerSensor().

Definition at line 180 of file QTRSensors.h.

◆ getTimeout()

uint16_t QTRSensors::getTimeout ( )
inline

Returns the timeout for RC sensors.

Returns
The RC sensor timeout in microseconds.

See also setTimeout().

Definition at line 161 of file QTRSensors.h.

◆ getType()

QTRType QTRSensors::getType ( )
inline

Returns the type of the sensors.

Returns
The sensor type as a member of the QTRType enum.

See also setTypeRC() and setTypeAnalog().

Definition at line 106 of file QTRSensors.h.

◆ read()

void QTRSensors::read ( uint16_t *  sensorValues,
QTRReadMode  mode = QTRReadMode::On 
)

Reads the raw sensor values into an array.

Parameters
[out]sensorValuesA pointer to an array in which to store the raw sensor readings. There MUST be space in the array for as many values as there were sensors specified in setSensorPins().
modeThe emitter behavior during the read, as a member of the QTRReadMode enum. The default is QTRReadMode::On.

Example usage:

uint16_t sensorValues[8];
qtr.read(sensorValues);

The values returned are a measure of the reflectance in abstract units, with higher values corresponding to lower reflectance (e.g. a black surface or a void).

Analog sensors will return a raw value between 0 and 1023 (like Arduino's analogRead() function).

RC sensors will return a raw value in microseconds between 0 and the timeout setting configured with setTimeout() (the default timeout is 2500 µs).

See Usage Notes for more information and example code.

Definition at line 407 of file QTRSensors.cpp.

◆ readCalibrated()

void QTRSensors::readCalibrated ( uint16_t *  sensorValues,
QTRReadMode  mode = QTRReadMode::On 
)

Reads the sensors and provides calibrated values between 0 and 1000.

Parameters
[out]sensorValuesA pointer to an array in which to store the calibrated sensor readings. There MUST be space in the array for as many values as there were sensors specified in setSensorPins().
modeThe emitter behavior during the read, as a member of the QTRReadMode enum. The default is QTRReadMode::On. Manual emitter control with QTRReadMode::Manual is not supported.

0 corresponds to the minimum value stored in calibrationOn or calibrationOff, depending on mode, and 1000 corresponds to the maximum value. Calibration values are typically obtained by calling calibrate(), and they are stored separately for each sensor, so that differences in the sensors are accounted for automatically.

See Usage Notes for more information and example code.

Definition at line 467 of file QTRSensors.cpp.

◆ readLineBlack()

uint16_t QTRSensors::readLineBlack ( uint16_t *  sensorValues,
QTRReadMode  mode = QTRReadMode::On 
)
inline

Reads the sensors, provides calibrated values, and returns an estimated black line position.

Parameters
[out]sensorValuesA pointer to an array in which to store the calibrated sensor readings. There MUST be space in the array for as many values as there were sensors specified in setSensorPins().
modeThe emitter behavior during the read, as a member of the QTRReadMode enum. The default is QTRReadMode::On. Manual emitter control with QTRReadMode::Manual is not supported.
Returns
An estimate of the position of a black line under the sensors.

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, a return value of 1000 indicates that the line is directly below sensor 1, 2000 indicates that it's below sensor 2000, etc. Intermediate values indicate that the line is between two sensors. The formula is (where \(v_0\) represents the value from the first sensor):

\[ {(0 \times v_0) + (1000 \times v_1) + (2000 \times v_2) + \cdots \over v_0 + v_1 + v_2 + \cdots} \]

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 4 is your rightmost sensor and you end up completely off the line to the left, this function will continue to return 4000.

This function is intended to detect a black (or dark-colored) line on a white (or light-colored) background. For a white line, see readLineWhite().

See Usage Notes for more information and example code.

Definition at line 501 of file QTRSensors.h.

◆ readLineWhite()

uint16_t QTRSensors::readLineWhite ( uint16_t *  sensorValues,
QTRReadMode  mode = QTRReadMode::On 
)
inline

Reads the sensors, provides calibrated values, and returns an estimated white line position.

Parameters
[out]sensorValuesA pointer to an array in which to store the calibrated sensor readings. There MUST be space in the array for as many values as there were sensors specified in setSensorPins().
modeThe emitter behavior during the read, as a member of the QTRReadMode enum. The default is QTRReadMode::On. Manual emitter control with QTRReadMode::Manual is not supported.
Returns
An estimate of the position of a white line under the sensors.

This function is intended to detect a white (or light-colored) line on a black (or dark-colored) background. For a black line, see readLineBlack().

See Usage Notes for more information and example code.

Definition at line 526 of file QTRSensors.h.

◆ releaseEmitterPins()

void QTRSensors::releaseEmitterPins ( )

Releases emitter pin/pins that have been set.

This function releases any emitter pins that were previously specified, making them inputs and stopping further control of the emitters through them.

See also setEmitterPin() and setEmitterPins().

Definition at line 78 of file QTRSensors.cpp.

◆ setDimmable()

void QTRSensors::setDimmable ( )
inline

Specifies that the sensors are dimmable.

Calling this function is optional when setting up second-generation QTR or QTRX sensors. By default, the library assumes the sensors are dimmable.

For first-generation QTR sensors, see setNonDimmable().

Definition at line 280 of file QTRSensors.h.

◆ setDimmingLevel()

void QTRSensors::setDimmingLevel ( uint8_t  dimmingLevel)

Sets the dimming level.

Parameters
dimmingLevelThe dimming level (0 to 31). A dimming level of 0 corresponds to full current and brightness, with higher dimming levels meaning lower currents.

See your sensor board's product page or documentation for details on the relationship of the dimming level to the LED current.

The dimming level will take effect the next time emittersOn() is called (either from your own program or by one of the library's read methods), and it will be applied again whenever the emitters are turned on after that.

This setting is only used by dimmable sensors, and an emitter control pin/pins must be connected and defined for dimming to be applied.

Definition at line 95 of file QTRSensors.cpp.

◆ setEmitterPin()

void QTRSensors::setEmitterPin ( uint8_t  emitterPin)

Sets the emitter control pin for the sensors.

Parameters
emitterPinThe Arduino digital pin that controls whether the IR LEDs are on or off.

Specifying an emitter pin is optional, and the pin is not present on some QTR sensor boards. If a valid pin is connected and specified, the emitters will only be turned on during a reading; otherwise, the IR emitters will always be on. No emitter pin is specified by default.

With second-generation QTR or QTRX sensor arrays that have two emitter control pins, you can control all of the emitters together by specifying a single emitter pin connected to either the CTRL ODD or CTRL EVEN pin on the sensor board. For independent control of the odd- and even-numbered emitters, see setEmitterPins().

If you call this function after an emitter pin/pins have already been specified, any existing emitter pins will be released; see also releaseEmitterPins().

Definition at line 56 of file QTRSensors.cpp.

◆ setEmitterPins()

void QTRSensors::setEmitterPins ( uint8_t  oddEmitterPin,
uint8_t  evenEmitterPin 
)

Sets separate odd and even emitter control pins for the sensors.

Parameters
oddEmitterPinThe Arduino digital pin that controls the odd-numbered IR LEDs.
evenEmitterPinThe Arduino digital pin that controls the even-numbered IR LEDs.

This function only works with second-generation QTR or QTRX sensor arrays that have two emitter control pins. To specify a single emitter pin for all sensors, see setEmitterPin().

If you call this function after an emitter pin/pins have already been specified, any existing emitter pins will be released; see also releaseEmitterPins().

Definition at line 66 of file QTRSensors.cpp.

◆ setNonDimmable()

void QTRSensors::setNonDimmable ( )
inline

Specifies that the sensors are non-dimmable.

Call this function to set up first-generation QTR sensors and allow them to be read slightly faster (since their emitters can be turned on and off slightly more quickly than those on dimmable sensors).

See also setDimmable().

Definition at line 289 of file QTRSensors.h.

◆ setSamplesPerSensor()

void QTRSensors::setSamplesPerSensor ( uint8_t  samples)

Sets the number of analog readings to average per analog sensor.

Parameters
samplesThe number of 10-bit analog samples (analog-to-digital conversions) to average per sensor each time it is read.

Increasing samples increases noise suppression at the cost of sample rate. The maximum number of samples per sensor is 64; the default is 4.

The samples per sensor setting only applies to analog sensors.

Definition at line 50 of file QTRSensors.cpp.

◆ setSensorPins()

void QTRSensors::setSensorPins ( const uint8_t *  pins,
uint8_t  sensorCount 
)

Sets the sensor pins.

Parameters
[in]pinsA pointer to an array containing the Arduino pins that the sensors are connected to.
sensorCountThe number of sensors, which should match the length of the pins array.

Example usage:

// Set pins for four RC sensors connected to pins 6, 7, A0, and A1.
// (Most analog pins can also be used as digital pins.)
qtr.setTypeRC();
qtr.setSensorPins((const uint8_t[]){6, 7, A0, A1}, 4);
// Set pins for four analog sensors connected to pins A2, A3, A4, and A5.
qtr.setSensorPins((const uint8_t[]){A2, A3, A4, A5}, 4);

If calibration data has already been stored, calling this method will force the storage for the calibration values to be reallocated and reinitialized the next time calibrate() is called (it sets calibrationOn.initialized and calibrationOff.initialized to false).

Definition at line 16 of file QTRSensors.cpp.

◆ setTimeout()

void QTRSensors::setTimeout ( uint16_t  timeout)

Sets the timeout for RC sensors.

Parameters
timeoutThe length of time, in microseconds, beyond which you consider the sensor reading completely black.

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 µs, 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. The default timeout is 2500 µs.

The maximum allowed timeout is 32767. (This prevents any possibility of an overflow when using QTRReadMode::OnAndOff or QTRReadMode::OddEvenAndOff).

The timeout setting only applies to RC sensors.

Definition at line 43 of file QTRSensors.cpp.

◆ setTypeAnalog()

void QTRSensors::setTypeAnalog ( )

Specifies that the sensor type is analog.

Call this function to set up A-type sensors.

Definition at line 10 of file QTRSensors.cpp.

◆ setTypeRC()

void QTRSensors::setTypeRC ( )

Specifies that the sensors are RC.

Call this function to set up RC-type sensors.

Definition at line 4 of file QTRSensors.cpp.


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