Gets readings from the five reflectance sensors on the bottom of the 3pi+ 32U4. More...

#include <Pololu3piPlus32U4LineSensors.h>

Classes
struct	CalibrationData
	Stores sensor calibration data. More...

Public Member Functions
void	setTimeout (uint16_t timeout)
	Sets the timeout for RC sensors. More...

uint16_t	getTimeout ()
	Returns the timeout. More...

void	calibrate (LineSensorsReadMode mode=LineSensorsReadMode::On)
	Reads the sensors for calibration. More...

void	resetCalibration ()
	Resets all calibration that has been done. More...

void	read (uint16_t *sensorValues, LineSensorsReadMode mode=LineSensorsReadMode::On)
	Reads the raw sensor values into an array. More...

void	readCalibrated (uint16_t *sensorValues, LineSensorsReadMode mode=LineSensorsReadMode::On)
	Reads the sensors and provides calibrated values between 0 and 1000. More...

uint16_t	readLineBlack (uint16_t *sensorValues, LineSensorsReadMode mode=LineSensorsReadMode::On)
	Reads the sensors, provides calibrated values, and returns an estimated black line position. More...

uint16_t	readLineWhite (uint16_t *sensorValues, LineSensorsReadMode mode=LineSensorsReadMode::On)
	Reads the sensors, provides calibrated values, and returns an estimated white line position. More...

void	emittersOn ()
	Turns the IR LEDs on. More...

void	emittersOff ()
	Turns the IR LEDs off. 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. More...

CalibrationData	calibrationOff
	Data from calibrating with emitters off. More...

Static Public Attributes
static const uint8_t	_sensorCount = 5
	The 3pi+ 32U4 has 5 line sensors. More...

static const uint16_t	defaultTimeout = 4000
	Default timeout for RC sensors (in microseconds). More...

static const uint8_t	emitterPin = 11

static const uint8_t	line0Pin = 12

static const uint8_t	line1Pin = A0

static const uint8_t	line2Pin = A2

static const uint8_t	line3Pin = A3

static const uint8_t	line4Pin = A4

Detailed Description

Gets readings from the five reflectance sensors on the bottom of the 3pi+ 32U4.

The readLineBlack() and readLineWhite() methods will always return values that increase from left to right, with 0 corresponding to the leftmost sensor and 4000 corresponding to the rightmost sensor.

Definition at line 36 of file Pololu3piPlus32U4LineSensors.h.

Member Function Documentation

◆ calibrate()

void Pololu3piPlus32U4::LineSensors::calibrate ( LineSensorsReadMode mode = LineSensorsReadMode::On )

Reads the sensors for calibration.

Parameters

mode	The emitter behavior during calibration, as a member of the LineSensorsReadMode enum. The default is LineSensorsReadMode::On. Manual emitter control with LineSensorsReadMode::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 five, 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 26 of file Pololu3piPlus32U4LineSensors.cpp.

◆ emittersOff()

void Pololu3piPlus32U4::LineSensors::emittersOff ( )

inline

Turns the IR LEDs off.

Definition at line 272 of file Pololu3piPlus32U4LineSensors.h.

◆ emittersOn()

void Pololu3piPlus32U4::LineSensors::emittersOn ( )

inline

Turns the IR LEDs on.

Definition at line 266 of file Pololu3piPlus32U4LineSensors.h.

◆ getTimeout()

uint16_t Pololu3piPlus32U4::LineSensors::getTimeout ( )

inline

Returns the timeout.

Returns: The RC sensor timeout in microseconds.

◆ read()

void Pololu3piPlus32U4::LineSensors::read	(	uint16_t *	sensorValues,
		LineSensorsReadMode	mode = `LineSensorsReadMode::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 five readings.
	mode	The emitter behavior during the read, as a member of the LineSensorsReadMode enum. The default is LineSensorsReadMode::On.

Example usage:

uint16_t sensorValues[5];

lineSensors.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 121 of file Pololu3piPlus32U4LineSensors.cpp.

◆ readCalibrated()

void Pololu3piPlus32U4::LineSensors::readCalibrated	(	uint16_t *	sensorValues,
		LineSensorsReadMode	mode = `LineSensorsReadMode::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 all five values.
	mode	The emitter behavior during the read, as a member of the LineSensorsReadMode enum. The default is LineSensorsReadMode::On. Manual emitter control with LineSensorsReadMode::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 145 of file Pololu3piPlus32U4LineSensors.cpp.

◆ readLineBlack()

uint16_t Pololu3piPlus32U4::LineSensors::readLineBlack	(	uint16_t *	sensorValues,
		LineSensorsReadMode	mode = `LineSensorsReadMode::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 five values.
	mode	The emitter behavior during the read, as a member of the LineSensorsReadMode enum. The default is LineSensorsReadMode::On. Manual emitter control with LineSensorsReadMode::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 204 of file Pololu3piPlus32U4LineSensors.h.

◆ readLineWhite()

uint16_t Pololu3piPlus32U4::LineSensors::readLineWhite	(	uint16_t *	sensorValues,
		LineSensorsReadMode	mode = `LineSensorsReadMode::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 five values.
	mode	The emitter behavior during the read, as a member of the LineSensorsReadMode enum. The default is LineSensorsReadMode::On. Manual emitter control with LineSensorsReadMode::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 229 of file Pololu3piPlus32U4LineSensors.h.

◆ resetCalibration()

void Pololu3piPlus32U4::LineSensors::resetCalibration ( )

Resets all calibration that has been done.

Definition at line 15 of file Pololu3piPlus32U4LineSensors.cpp.

◆ setTimeout()

void Pololu3piPlus32U4::LineSensors::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 4000 µs.

The maximum allowed timeout is 32767.

Definition at line 8 of file Pololu3piPlus32U4LineSensors.cpp.

Member Data Documentation

◆ _sensorCount

const uint8_t Pololu3piPlus32U4::LineSensors::_sensorCount = 5

static

The 3pi+ 32U4 has 5 line sensors.

Definition at line 40 of file Pololu3piPlus32U4LineSensors.h.

◆ calibrationOff

CalibrationData Pololu3piPlus32U4::LineSensors::calibrationOff

Data from calibrating with emitters off.

Definition at line 261 of file Pololu3piPlus32U4LineSensors.h.

◆ calibrationOn

CalibrationData Pololu3piPlus32U4::LineSensors::calibrationOn

Data from calibrating with emitters on.

Definition at line 258 of file Pololu3piPlus32U4LineSensors.h.

◆ defaultTimeout

const uint16_t Pololu3piPlus32U4::LineSensors::defaultTimeout = 4000

static

Default timeout for RC sensors (in microseconds).

Definition at line 43 of file Pololu3piPlus32U4LineSensors.h.

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

Classes

Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Function Documentation

◆ calibrate()

◆ emittersOff()

◆ emittersOn()

◆ getTimeout()

◆ read()

◆ readCalibrated()

◆ readLineBlack()

◆ readLineWhite()

◆ resetCalibration()

◆ setTimeout()

Member Data Documentation

◆ _sensorCount

◆ calibrationOff

◆ calibrationOn

◆ defaultTimeout