FastArduino  v1.7
C++ library to build fast but small Arduino/AVR projects
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  SonarType : uint8_t {
  SonarType::BLOCKING,
  SonarType::ASYNC_INT,
  SonarType::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 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_usthe 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_mmthe 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.