Zumo32U4 library
Classes | Public Member Functions | Static Public Attributes | List of all members
Zumo32U4ProximitySensors Class Reference

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. More...
 
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
sensorNumberThe 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
sensorNumberThe 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
pinsA pointer to an array with the pin numbers for the sensors.
numSensorsThe number of sensors.
lineSensorEmitterPinThe 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
lineSensorEmitterPinThe 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
lineSensorEmitterPinThe 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.

◆ pullupsOn()

void Zumo32U4ProximitySensors::pullupsOn ( )

Sets each sensor pin to an input with pull-up resistors enabled.

Definition at line 103 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:

  1. It calls pullupsOn().
  2. It calls lineSensorEmittersOff().
  3. 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
sensorNumberThe 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
levelsA pointer to an array of brightness levels.
levelCountThe 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: