Represents a QTR sensor array. More...

#include <QTRSensors.h>

Inheritance diagram for QTRSensors:

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.

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

mode	The 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).

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

emitters	Which emitters to turn off, as a member of the QTREmitters enum. The default is QTREmitters::All.
wait	If 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

emitters	Which emitters to turn on, as a member of the QTREmitters enum. The default is QTREmitters::All.
wait	If 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

emitters Which 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.

◆ 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.

◆ 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.

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.

◆ getTimeout()

uint16_t QTRSensors::getTimeout ( )

inline

Returns the timeout for RC sensors.

Returns: The RC sensor timeout in microseconds.

◆ 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]	sensorValues	A 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().
	mode	The 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).

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]	sensorValues	A 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().
	mode	The 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.

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]	sensorValues	A 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().
	mode	The 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().

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]	sensorValues	A 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().
	mode	The 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().

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

dimmingLevel The 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

emitterPin The 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

oddEmitterPin	The Arduino digital pin that controls the odd-numbered IR LEDs.
evenEmitterPin	The 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).

◆ setSamplesPerSensor()

void QTRSensors::setSamplesPerSensor ( uint8_t samples )

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

Parameters

samples The 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]	pins	A pointer to an array containing the Arduino pins that the sensors are connected to.
	sensorCount	The 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.setTypeAnalog();
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

timeout The 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:

Classes

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ calibrate()

◆ emittersOff()

◆ emittersOn()

◆ emittersSelect()

◆ getDimmable()

◆ getDimmingLevel()

◆ getEmitterPin()

◆ getEmitterPinCount()

◆ getEvenEmitterPin()

◆ getOddEmitterPin()

◆ getSamplesPerSensor()

◆ getTimeout()

◆ getType()

◆ read()

◆ readCalibrated()

◆ readLineBlack()

◆ readLineWhite()

◆ releaseEmitterPins()

◆ setDimmable()

◆ setDimmingLevel()

◆ setEmitterPin()

◆ setEmitterPins()

◆ setNonDimmable()

◆ setSamplesPerSensor()

◆ setSensorPins()

◆ setTimeout()

◆ setTypeAnalog()

◆ setTypeRC()