Gets readings from the three proximity sensors on the front sensor array. More...

#include <Zumo32U4ProximitySensors.h>

Public Member Functions
	Zumo32U4ProximitySensors ()
	Minimal constructor. More...

	Zumo32U4ProximitySensors (uint8_t *pins, uint8_t numSensors, uint8_t lineSensorEmitterPin=defaultLineSensorEmitterPin)
	Constructor that takes pin arguments. More...

void	initThreeSensors (uint8_t lineSensorEmitterPin=defaultLineSensorEmitterPin)
	Configures this object to use all three proximity sensors. More...

void	initFrontSensor (uint8_t lineSensorEmitterPin=defaultLineSensorEmitterPin)
	Configures this object to use just the front proximity sensor. More...

void	init (uint8_t *pins, uint8_t numSensors, uint8_t lineSensorEmitterPin=defaultLineSensorEmitterPin)
	Configures this object to use a custom set of pins. More...

uint8_t	getNumSensors () const
	Returns the number of sensors. More...

void	setPeriod (uint16_t period)
	Sets the period used for the IR pulses. More...

void	setBrightnessLevels (uint16_t *levels, uint8_t levelCount)
	Sets the sequence of brightness levels used by read(). More...

void	setPulseOnTimeUs (uint16_t pulseOnTimeUs)
	Sets the duration, in microseconds, for each burst of IR pulses emitted by the read() function. More...

void	setPulseOffTimeUs (uint16_t pulseOffTimeUs)
	Sets the amount of time, in microseconds, that the read() function will leave the pulses off before going on to the next step. More...

uint8_t	getNumBrightnessLevels () const
	Returns the number of brightness levels. More...

void	lineSensorEmittersOff ()
	Turns the IR emitters for the line sensors off. More...

void	pullupsOn ()
	Sets each sensor pin to an input with pull-up resistors enabled.

bool	readBasic (uint8_t sensorNumber)
	Does a quick digital reading of the specified sensor without emitting any IR pulses. More...

void	read ()
	Emits IR pulses and gets readings from the sensors. More...

uint8_t	countsWithLeftLeds (uint8_t sensorNumber) const
	Returns the number of brightness levels for the left LEDs that activated the specified sensor. More...

uint8_t	countsWithRightLeds (uint8_t sensorNumber) const
	Returns the number of brightness levels for the right LEDs that activated the specified sensor. More...

uint8_t	countsLeftWithLeftLeds () const
	Returns the number of brightness levels for the left LEDs that activated the left proximity sensor. More...

uint8_t	countsLeftWithRightLeds () const
	Returns the number of brightness levels for the right LEDs that activated the left proximity sensor. More...

uint8_t	countsFrontWithLeftLeds () const
	Returns the number of brightness levels for the left LEDs that activated the front proximity sensor. More...

uint8_t	countsFrontWithRightLeds () const
	Returns the number of brightness levels for the right LEDs that activated the front proximity sensor. More...

uint8_t	countsRightWithLeftLeds () const
	Returns the number of brightness levels for the left LEDs that activated the right proximity sensor. More...

uint8_t	countsRightWithRightLeds () const
	Returns the number of brightness levels for the right LEDs that activated the right proximity sensor. More...

bool	readBasicLeft ()
	Does a quick digital reading of the left sensor. More...

bool	readBasicFront ()
	Does a quick digital reading of the front sensor. More...

bool	readBasicRight ()
	Does a quick digital reading of the right sensor. More...

Static Public Attributes
static const uint8_t	defaultLineSensorEmitterPin = 11
	The default line sensor emitter pin. More...

static const uint16_t	defaultPeriod = 420
	The default period for the infrared pulses. More...

static const uint16_t	defaultPulseOnTimeUs = 421
	The default duration of the bursts of infrared pulses emitted, in microseconds. More...

static const uint16_t	defaultPulseOffTimeUs = 578
	The default time to leave the infrared LEDs off between readings, in microseconds. More...

Detailed Description

Gets readings from the three proximity sensors on the front sensor array.

This class allows you to get measurements from the IR proximity sensors on the Zumo 32U4 Front Sensor Array.

By default, this class uses pins 20 (A2), 22 (A4), 4, and 11.

Since this class uses Zumo32U4IRPulses, which uses Timer 3, it might conflict with other libraries using Timer 3. Timer 3 is only used while the read() function is running and can be used for other purposes after the function returns.

Configuring the pins

This class allows you to choose what pins will be used for sensors. Each sensor pin will be configured as a pulled-up input and digital readings will be performed on the pin to see if the sensor is active.

By default, this class will drive pin 11 low before taking readings in order to disable the IR emitters of the line sensors so they do not interfere with the proximity sensors. You can change what pin is used, or you can disable this feature.

For more information, see initThreeSensors(), initFrontSensor(), and init().

Reading the sensors

The read() function takes care of disabling the emitters for the line sensors, sending sequences of pulses to the left and right IR LEDs, and performing digital readings on the proximity sensor pins to see if they are active.

There are several configuration options that allow you to control the details of how the read() function behaves:

Interpreting the sensor readings

The readings generated by the read() function consist of two numbers for each sensor: the number of brightness levels for the left LEDs that activated the sensor, and the number of brightness levels for the right LEDs that activated the sensor.

A higher reading corresponds to more IR light getting reflected to the sensor, which is influenced by the size, reflectivity, proximity, and location of nearby objects. However, the presence of other sources of 38 kHz IR pulses (e.g. from another robot) can also affect the readings.

Basic readings

The readBasic() function does a quick digital reading of a sensor without emitting any IR pulses. This can be useful for detecting other robots that are emitting pulses of IR at 38 kHz.

Brightness levels

The sequence of IR pulse brightness levels used by the read() function has a big effect on the readings returned by this class. The levels can be changed by calling setBrightnessLevels().

The default IR pulse brightness levels used are 4, 15, 32, 55, 85, and 120.

These numbers each represent the pulse width to be used in a burst of IR pulses. Specifically, the pulse width is (1 + brightness) / (16 MHz).

We determined by experimenting that the useful range of levels is from about 4 to 120, so we chose those as the minimum and maximum. We used ((2.236 + 1.756*i)^2 - 1) with i from 0 to 5 to generate the intermediate points.

Definition at line 105 of file Zumo32U4ProximitySensors.h.

Constructor & Destructor Documentation

◆ Zumo32U4ProximitySensors() [1/2]

Zumo32U4ProximitySensors::Zumo32U4ProximitySensors ( )

inline

Minimal constructor.

If you use this (i.e. by not providing any arguments when you create the Zumo32U4ProximitySensors object), then you will have to call initThreeSensors(), initFrontSensor(), or init() before using the functions in this class.

Definition at line 121 of file Zumo32U4ProximitySensors.h.

◆ Zumo32U4ProximitySensors() [2/2]

Zumo32U4ProximitySensors::Zumo32U4ProximitySensors	(	uint8_t *	pins,
		uint8_t	numSensors,
		uint8_t	lineSensorEmitterPin = `defaultLineSensorEmitterPin`
	)

inline

Constructor that takes pin arguments.

This constructor calls init() with the specified arguments.

Definition at line 129 of file Zumo32U4ProximitySensors.h.

Member Function Documentation

◆ countsFrontWithLeftLeds()

uint8_t Zumo32U4ProximitySensors::countsFrontWithLeftLeds ( ) const

inline

Returns the number of brightness levels for the left LEDs that activated the front proximity sensor.

This function assumes pin 22 (A4) is connected to the front sensor. It returns 0 if the object is not configured to use that pin as a sensor.

Definition at line 416 of file Zumo32U4ProximitySensors.h.

◆ countsFrontWithRightLeds()

uint8_t Zumo32U4ProximitySensors::countsFrontWithRightLeds ( ) const

inline

Returns the number of brightness levels for the right LEDs that activated the front proximity sensor.

This function assumes pin 22 (A4) is connected to the front sensor. It returns 0 if the object is not configured to use that pin as a sensor.

Definition at line 427 of file Zumo32U4ProximitySensors.h.

◆ countsLeftWithLeftLeds()

uint8_t Zumo32U4ProximitySensors::countsLeftWithLeftLeds ( ) const

inline

Returns the number of brightness levels for the left LEDs that activated the left proximity sensor.

This function assumes pin 20 (A2) is connected to the left sensor. It returns 0 if the object is not configured to use that pin as a sensor.

Definition at line 394 of file Zumo32U4ProximitySensors.h.

◆ countsLeftWithRightLeds()

uint8_t Zumo32U4ProximitySensors::countsLeftWithRightLeds ( ) const

inline

Returns the number of brightness levels for the right LEDs that activated the left proximity sensor.

This function assumes pin 20 (A2) is connected to the left sensor. It returns 0 if the object is not configured to use that pin as a sensor.

Definition at line 405 of file Zumo32U4ProximitySensors.h.

◆ countsRightWithLeftLeds()

uint8_t Zumo32U4ProximitySensors::countsRightWithLeftLeds ( ) const

inline

Returns the number of brightness levels for the left LEDs that activated the right proximity sensor.

This function assumes pin 4 is connected to the right sensor. It returns 0 if the object is not configured to use that pin as a sensor.

Definition at line 438 of file Zumo32U4ProximitySensors.h.

◆ countsRightWithRightLeds()

uint8_t Zumo32U4ProximitySensors::countsRightWithRightLeds ( ) const

inline

Returns the number of brightness levels for the right LEDs that activated the right proximity sensor.

This function assumes pin 4 is connected to the right sensor. It returns 0 if the object is not configured to use that pin as a sensor.

Definition at line 449 of file Zumo32U4ProximitySensors.h.

◆ countsWithLeftLeds()

uint8_t Zumo32U4ProximitySensors::countsWithLeftLeds ( uint8_t sensorNumber ) const

Returns the number of brightness levels for the left LEDs that activated the specified sensor.

Parameters

sensorNumber The zero-based index of the sensor. This number should be less than the number of sensors, or else this function returns 0.

Definition at line 175 of file Zumo32U4ProximitySensors.cpp.

◆ countsWithRightLeds()

uint8_t Zumo32U4ProximitySensors::countsWithRightLeds ( uint8_t sensorNumber ) const

Returns the number of brightness levels for the right LEDs that activated the specified sensor.

Parameters

sensorNumber The zero-based index of the sensor. This number should be less than the number of sensors, or else this function returns 0.

Definition at line 181 of file Zumo32U4ProximitySensors.cpp.

◆ getNumBrightnessLevels()

uint8_t Zumo32U4ProximitySensors::getNumBrightnessLevels ( ) const

inline

Returns the number of brightness levels.

This could be useful for formatting the sensor readings for display.

Definition at line 297 of file Zumo32U4ProximitySensors.h.

◆ getNumSensors()

uint8_t Zumo32U4ProximitySensors::getNumSensors ( ) const

inline

Returns the number of sensors.

This could be useful for iterating through all the sensors.

Definition at line 188 of file Zumo32U4ProximitySensors.h.

◆ init()

void Zumo32U4ProximitySensors::init	(	uint8_t *	pins,
		uint8_t	numSensors,
		uint8_t	lineSensorEmitterPin = `defaultLineSensorEmitterPin`
	)

Configures this object to use a custom set of pins.

Parameters

pins	A pointer to an array with the pin numbers for the sensors.
numSensors	The number of sensors.
lineSensorEmitterPin	The number of the pin that controls the emitters for the line sensors. This pin is used to turn off the emitters for line sensors so they do not cause false readings on the proximity sensors. You can specify a value of SENSOR_NO_PIN for this parameter if you want this class to not do anything to the emitters.

Definition at line 47 of file Zumo32U4ProximitySensors.cpp.

◆ initFrontSensor()

void Zumo32U4ProximitySensors::initFrontSensor ( uint8_t lineSensorEmitterPin = defaultLineSensorEmitterPin )

inline

Configures this object to use just the front proximity sensor.

This function sets up this object to use just the front proximity sensor on the Zumo32U4 Front Sensor Array. The pin used will be 22 (A4), and the pins for other two sensors will not be modified.

Parameters

lineSensorEmitterPin The number of the pin that controls the emitters for the line sensors. This pin is used to turn off the emitters for line sensors so they do not cause false readings on the proximity sensors. You can specify a value of SENSOR_NO_PIN for this parameter if you want this class to not do anything to the emitters.

Definition at line 167 of file Zumo32U4ProximitySensors.h.

◆ initThreeSensors()

void Zumo32U4ProximitySensors::initThreeSensors ( uint8_t lineSensorEmitterPin = defaultLineSensorEmitterPin )

inline

Configures this object to use all three proximity sensors.

This function sets up this object to use the left, front, and right proximity sensors on the Zumo32U4 Front Sensor Array. The pins used for these sensors will be 20 (A2), 22 (A4), and 4 respectively.

For this configuration to work, jumpers on the front sensor array must be installed in order to connect pin 20 to LFT and connect pin 4 to RGT.

Parameters

lineSensorEmitterPin The number of the pin that controls the emitters for the line sensors. This pin is used to turn off the emitters for line sensors so they do not cause false readings on the proximity sensors. You can specify a value of SENSOR_NO_PIN for this parameter if you want this class to not do anything to the emitters.

Definition at line 150 of file Zumo32U4ProximitySensors.h.

◆ lineSensorEmittersOff()

void Zumo32U4ProximitySensors::lineSensorEmittersOff ( )

Turns the IR emitters for the line sensors off.

Turns the line sensors for the IR emitters off, and then delays. The pin used to control the emitters is specified in the constructor, or a call to init(), initThreeSensors(), or initFrontSensor(). The pin will be driven low. The delay can be specified by calling setPulseOffTimeUs().

Definition at line 115 of file Zumo32U4ProximitySensors.cpp.

◆ read()

void Zumo32U4ProximitySensors::read ( )

Emits IR pulses and gets readings from the sensors.

This is the main function of this class. Almost all other functions in this class serve to configure how this function will work or to access the results from this function.

This function performs the following steps:

It calls pullupsOn().
It calls lineSensorEmittersOff().
For each configured brightness level, it:
1. Starts IR pulses on the left LEDs.
2. Takes a reading of each sensor.
3. Turns off the pulses.
4. Starts IR pulses on right LEDs.
5. Takes a reading of each sensor.
6. Turns off the pulses.

The brightness levels can be configured with setBrightnessLevels(). The frequency of the IR pulses (which is normally 38 kHz) can be adjusted with setPeriod(). The delays used during this process can be configured with setPulseOnTimeUs() and setPulseOffTimeUs().

The output of this function is two numbers for each sensor: the number of brightness levels for left LEDs that activated the sensor, and the number of brightness levels for the right LEDs that activated the sensor.

You can retrieve the numbers by calling countsWithLeftLeds(), countsWithRightLeds(), or a number of other helper functions defined in this class.

With the default timing parameters, the amount of time this function takes to run is approximately 2.15 milliseconds per brightness level plus 0.62 milliseconds. The number of sensors has only a small affect on the run time.

Definition at line 129 of file Zumo32U4ProximitySensors.cpp.

◆ readBasic()

bool Zumo32U4ProximitySensors::readBasic ( uint8_t sensorNumber )

Does a quick digital reading of the specified sensor without emitting any IR pulses.

Before calling this function, you should make sure that pullupsOn() and lineSensorEmittersOff() have both been called or else you could get false readings. You can either call these functions directly or just call read().

Returns: 1 if the sensor is active, 0 if not.

Parameters

sensorNumber The zero-based index of the sensor. This number should be less than the number of sensors, or else this function's behavior is undefined.

Definition at line 169 of file Zumo32U4ProximitySensors.cpp.

◆ readBasicFront()

bool Zumo32U4ProximitySensors::readBasicFront ( )

inline

Does a quick digital reading of the front sensor.

This function assumes pin 22 (A4) is connected to the left sensor. It returns 0 if the object is not configured to use that pin as a sensor.

This function calls readBasic(), so see that function's documentation for more information.

Definition at line 475 of file Zumo32U4ProximitySensors.h.

◆ readBasicLeft()

bool Zumo32U4ProximitySensors::readBasicLeft ( )

inline

Does a quick digital reading of the left sensor.

This function assumes pin 20 (A2) is connected to the left sensor. It returns 0 if the object is not configured to use that pin as a sensor.

This function calls readBasic(), so see that function's documentation for more information.

Definition at line 462 of file Zumo32U4ProximitySensors.h.

◆ readBasicRight()

bool Zumo32U4ProximitySensors::readBasicRight ( )

inline

Does a quick digital reading of the right sensor.

This function assumes pin 4 is connected to the right sensor. It returns 0 if the object is not configured to use that pin as a sensor.

This function calls readBasic(), so see that function's documentation for more information.

Definition at line 488 of file Zumo32U4ProximitySensors.h.

◆ setBrightnessLevels()

void Zumo32U4ProximitySensors::setBrightnessLevels	(	uint16_t *	levels,
		uint8_t	levelCount
	)

Sets the sequence of brightness levels used by read().

Each brightness level in the sequence will be used as the brightness parameter to Zumo32U4IRPulses::start().

Note that the order of the brightness levels does matter because the current-limiting components for the IR LEDs on the Zumo 32U4 Main Board include a filter that causes the IR LED power voltage to decrease gradually while the LEDs are on, and recover gradually while they are off. With the default timing parameters, the voltage does not recover completely between bursts of IR pulses.

Parameters

levels	A pointer to an array of brightness levels.
levelCount	The number of brightness levels.

See also: defaultBrightnessLevels

Definition at line 73 of file Zumo32U4ProximitySensors.cpp.

◆ setPeriod()

void Zumo32U4ProximitySensors::setPeriod ( uint16_t period )

inline

Sets the period used for the IR pulses.

The period determines the frequency of the IR pulses, which affects how sensitive the IR proximity sensors are. The default period results in a frequency of about 38 kHz, which maximizes the sensitivity.

This parameter is used as the period parameter for Zumo32U4IRPulses::start, so see the documentation of that function for details.

See also: defaultPeriod

Definition at line 251 of file Zumo32U4ProximitySensors.h.

◆ setPulseOffTimeUs()

void Zumo32U4ProximitySensors::setPulseOffTimeUs ( uint16_t pulseOffTimeUs )

inline

Sets the amount of time, in microseconds, that the read() function will leave the pulses off before going on to the next step.

This delay is also used by lineSensorEmittersOff().

See also: defaultPulseOffTimeUs

Definition at line 289 of file Zumo32U4ProximitySensors.h.

◆ setPulseOnTimeUs()

void Zumo32U4ProximitySensors::setPulseOnTimeUs ( uint16_t pulseOnTimeUs )

inline

Sets the duration, in microseconds, for each burst of IR pulses emitted by the read() function.

See also: defaultPulseOnTimeUs

Definition at line 278 of file Zumo32U4ProximitySensors.h.

Member Data Documentation

◆ defaultLineSensorEmitterPin

const uint8_t Zumo32U4ProximitySensors::defaultLineSensorEmitterPin = 11

static

The default line sensor emitter pin.

This is equal to the SENSOR_LEDON constant defined in Zumo32U4LineSensors.h.

Definition at line 113 of file Zumo32U4ProximitySensors.h.

◆ defaultPeriod

const uint16_t Zumo32U4ProximitySensors::defaultPeriod = 420

static

The default period for the infrared pulses.

The default period is 420, which results in a frequency of 38.005 kHz.

The period can be changed by calling setPeriod().

Definition at line 200 of file Zumo32U4ProximitySensors.h.

◆ defaultPulseOffTimeUs

const uint16_t Zumo32U4ProximitySensors::defaultPulseOffTimeUs = 578

static

The default time to leave the infrared LEDs off between readings, in microseconds.

Ideally we would like the different measurements taken by the read() function to each be independent and not affect eachother, so we would like the sensor to go back to its original state before we start the next set of pulses. Therefore, it is necessary to wait long enough to guarantee that the previous IR pulses are no longer affecting the sensor output.

According to the TSSP77038 datasheet, the sensor output pulse duration could be up to 6/(38 kHz) longer than the duration of the IR pulses, and the sensor output pulse could start as late as 15/(38 kHz) after the IR pulses start. Therefore, it is possible for the sensor output pulse to end up to 21/(38 kHz) after the ending of the IR pulses.

So the default off time is 22/(38 kHz) = 578 us.

In our experiments, we saw that the sensor output pulse actually ends within 300 microseconds after the IR pulses end, so an off time of 300 us might be okay.

The off time can be changed by calling setPulseOffTimeUs().

Definition at line 238 of file Zumo32U4ProximitySensors.h.

◆ defaultPulseOnTimeUs

const uint16_t Zumo32U4ProximitySensors::defaultPulseOnTimeUs = 421

static

The default duration of the bursts of infrared pulses emitted, in microseconds.

According to the TSSP77038 datasheet, the delay between the start of the IR pulses and the start of the sensor output pulse could be anywhere between 7/(38 kHz) and 15/(38 kHz).

The default pulse on time of 16/(38 kHz) = 421 us guarantees we are not missing output pulses by reading the sensor too soon.

The on time can be changed by calling setPulseOnTimeUs().

Definition at line 213 of file Zumo32U4ProximitySensors.h.

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

src/Zumo32U4ProximitySensors.h
src/Zumo32U4ProximitySensors.cpp

Public Member Functions

Static Public Attributes

Detailed Description

Configuring the pins

Reading the sensors

Interpreting the sensor readings

Basic readings

Brightness levels

Constructor & Destructor Documentation

◆ Zumo32U4ProximitySensors() [1/2]

◆ Zumo32U4ProximitySensors() [2/2]

Member Function Documentation

◆ countsFrontWithLeftLeds()

◆ countsFrontWithRightLeds()

◆ countsLeftWithLeftLeds()

◆ countsLeftWithRightLeds()

◆ countsRightWithLeftLeds()

◆ countsRightWithRightLeds()

◆ countsWithLeftLeds()

◆ countsWithRightLeds()

◆ getNumBrightnessLevels()

◆ getNumSensors()

◆ init()

◆ initFrontSensor()

◆ initThreeSensors()

◆ lineSensorEmittersOff()

◆ read()

◆ readBasic()

◆ readBasicFront()

◆ readBasicLeft()

◆ readBasicRight()

◆ setBrightnessLevels()

◆ setPeriod()

◆ setPulseOffTimeUs()

◆ setPulseOnTimeUs()

Member Data Documentation

◆ defaultLineSensorEmitterPin

◆ defaultPeriod

◆ defaultPulseOffTimeUs

◆ defaultPulseOnTimeUs