devices::sonar Namespace Reference

Defines the API for sonar support. More...

Classes
class	AbstractSonar
	An abstract base class for some sonar classes defined as part of this API. More...
class	HCSR04
class	MultiHCSR04
	This template class supports up to 8 HC-SR04 sonars (or equivalent sensors), with their trigger pins gathered and connected to only one MCU pin, and all echo pins connected to the same MCU board::Port. More...
struct	SonarEvent
	This type holds information about events occurring within MultiHCSR04 handler. More...

Typedefs
template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::DigitalPin ECHO_>
using	BLOCKING_HCSR04 = HCSR04< NTIMER_, TRIGGER_, ECHO_, SonarType::BLOCKING >
	This template class supports one HC-SR04 sonar (or equivalent sensor), connected to the MCU via 2 pins. More...
template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::ExternalInterruptPin ECHO_>
using	ASYNC_INT_HCSR04 = HCSR04< NTIMER_, TRIGGER_, board::EXT_PIN< ECHO_ >(), SonarType::ASYNC_INT >
	This template class supports one HC-SR04 sonar (or equivalent sensor), connected to the MCU via 2 pins. More...
template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::InterruptPin ECHO_>
using	ASYNC_PCINT_HCSR04 = HCSR04< NTIMER_, TRIGGER_, board::PCI_PIN< ECHO_ >(), SonarType::ASYNC_PCINT >
	This template class supports one HC-SR04 sonar (or equivalent sensor), connected to the MCU via 2 pins. More...

Enumerations
enum class	SonarType : uint8_t {   BLOCKING ,   ASYNC_INT ,   ASYNC_PCINT }
	This enum defines the different modes, supported by HCSR04, to calculate the echo pin pulse duration. More...

Functions
static constexpr uint16_t	echo_us_to_distance_mm (uint16_t echo_us)
	This method converts the echo duration, in microseconds, to the distance between the sensor and the reflecting obstacle, in millimeters. More...
static constexpr uint16_t	distance_mm_to_echo_us (uint16_t distance_mm)
	This method converts the disatnce, in millimeters, between the sensor and a reflecting object, into the expected echo duration, in microseconds. More...

Variables
static constexpr const uint32_t	SPEED_OF_SOUND = 340UL
	The approximate speed of sound (and ultrasonic) waves, in the air, expressed in meters per second. More...

Detailed Description

Defines the API for sonar support.

Supported ultrasonic sensors have 2 pins:

• one "trigger" pin that, upon a short pulse, will generate ultrasonic waves to be emitted by the sensor
• one "echo" pin that, upon reception of the echoed ultrasonic wave, will generate a pulse which duration is the time during which the ultrasonic wave has travelled from the sensor back to the sensor, after reflecting on some obstacle. This API has been tested on HC-SR04 sensors (cheap ultrasonic sensors with a range of 4 meters).

Typedef Documentation

BLOCKING_HCSR04

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::DigitalPin ECHO_>

using devices::sonar::BLOCKING_HCSR04 = typedef HCSR04<NTIMER_, TRIGGER_, ECHO_, SonarType::BLOCKING>

This template class supports one HC-SR04 sonar (or equivalent sensor), connected to the MCU via 2 pins.

Sonar ranging is performed in blocking mode, i.e. HCSR04::echo_us() method is blocked until ranging is finished or timeout has occurred.

Template Parameters

NTIMER_	the AVR timer of the timer::RTT to use for this sonar
TRIGGER_	the board::DigitalPin connected to the sensor trigger pin; that can be any available pin.
ECHO_	the board::DigitalPin connected to the sensor echo pin

See also

timer::RTT

HCSR04

Definition at line 922 of file sonar.h.

ASYNC_INT_HCSR04

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::ExternalInterruptPin ECHO_>

using devices::sonar::ASYNC_INT_HCSR04 = typedef HCSR04<NTIMER_, TRIGGER_, board::EXT_PIN<ECHO_>(), SonarType::ASYNC_INT>

This template class supports one HC-SR04 sonar (or equivalent sensor), connected to the MCU via 2 pins.

Sonar ranging is performed in asynchronous mode through an board::ExternalInterruptPin.

Template Parameters

NTIMER_	the AVR timer of the timer::RTT to use for this sonar
TRIGGER_	the board::DigitalPin connected to the sensor trigger pin; that can be any available pin.
ECHO_	the board::ExternalInterruptPin connected to the sensor echo pin

See also

timer::RTT

HCSR04

Definition at line 938 of file sonar.h.

ASYNC_PCINT_HCSR04

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::InterruptPin ECHO_>

using devices::sonar::ASYNC_PCINT_HCSR04 = typedef HCSR04<NTIMER_, TRIGGER_, board::PCI_PIN<ECHO_>(), SonarType::ASYNC_PCINT>

This template class supports one HC-SR04 sonar (or equivalent sensor), connected to the MCU via 2 pins.

Sonar ranging is performed in asynchronous mode through an board::InterruptPin.

Template Parameters

NTIMER_	the AVR timer of the timer::RTT to use for this sonar
TRIGGER_	the board::DigitalPin connected to the sensor trigger pin; that can be any available pin.
ECHO_	the board::InterruptPin connected to the sensor echo pin

See also

timer::RTT

HCSR04

Definition at line 954 of file sonar.h.

Enumeration Type Documentation

SonarType

enum class devices::sonar::SonarType : uint8_t

strong

This enum defines the different modes, supported by HCSR04, to calculate the echo pin pulse duration.

Note that you typically do not need this type, neither HCSR04; you should rather use type aliases instead: BLOCKING_HCSR04, ASYNC_INT_HCSR04 or ASYNC_PCINT_HCSR04.

See also

BLOCKING_HCSR04

ASYNC_INT_HCSR04

ASYNC_PCIINT_HCSR04

HCSR04

HCSR04::echo_us()

Enumerator
BLOCKING	In this mode, the HCSR04 will block until the echo pulse is received.
ASYNC_INT	In this mode, the echo pin is a board::ExternalInterruptPin and the HCSR04 will use interrupts to calculate the echo pulse duration. When this mode is used, one registration macro must be called among REGISTER_HCSR04_INT_ISR*.
ASYNC_PCINT	In this mode, the echo pin is a board::InterruptPin and the HCSR04 will use interrupts to calculate the echo pulse duration. When this mode is used, one registration macro must be called among REGISTER_HCSR04_PCI_ISR*.

Definition at line 570 of file sonar.h.

Function Documentation

echo_us_to_distance_mm()

static constexpr uint16_t devices::sonar::echo_us_to_distance_mm ( uint16_t  echo_us )

staticconstexpr

This method converts the echo duration, in microseconds, to the distance between the sensor and the reflecting obstacle, in millimeters.

This method is constexpr hence it can be evaluated at compile-time (for more code size and speed efficiency) when provided a constant argument.

Note that the calculation accounts for the fact that echo_us is the time for a complete roundtrip of the ultrasonic wave, i.e. the time needed for the wave to cover twice the distance between the sensor and the reflecting obstacle.

Parameters

echo_us

the echo pulse duration, in microseconds

Returns

the distance, in millimeters, between the sensor and the obstacle

Definition at line 526 of file sonar.h.

distance_mm_to_echo_us()

static constexpr uint16_t devices::sonar::distance_mm_to_echo_us ( uint16_t  distance_mm )

staticconstexpr

This method converts the disatnce, in millimeters, between the sensor and a reflecting object, into the expected echo duration, in microseconds.

This method is constexpr hence it can be evaluated at compile-time (for more code size and speed efficiency) when provided a constant argument. It can thus be used to calculate constant echo durations based on "threshold" distances that your program may need to specifically address.

Note that the calculation accounts for the fact that the echo duration is the time for a complete roundtrip of the ultrasonic wave, i.e. the time needed for the wave to cover twice the distance between the sensor and the reflecting obstacle.

Parameters

distance_mm

the distance, in millimeters, between the sensor and the obstacle

Returns

the echo pulse duration, in microseconds, expected for distance_mm

Definition at line 550 of file sonar.h.

Variable Documentation

SPEED_OF_SOUND

constexpr const uint32_t devices::sonar::SPEED_OF_SOUND = 340UL

staticconstexpr

The approximate speed of sound (and ultrasonic) waves, in the air, expressed in meters per second.

This constant is useful everytime we need to convert echo durations from the ultrasonic sensor to a concrete distance.

Definition at line 509 of file sonar.h.