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...

#include <fastarduino/devices/sonar.h>

Public Types
using	RTT = timer::RTT< NTIMER_ >
	The type of `timer::RTT` used by this `MultiHCSR04` instance. More...

using	EVENT = SonarEvent< NTIMER_ >
	The exact `SonarEvent` type produced by this `MultiHCSR04` instance. More...

Public Member Functions
	MultiHCSR04 (RTT &rtt)
	Construct a new a multi-sonar sensors handler. More...

void	trigger (uint16_t timeout_ms)
	Start ranging on all sonars connected to this `MultiHCSR04`. More...

bool	active () const
	Tell if a ranging is under way on any sonar managed by this `MultiHCSR04` instance. More...

uint8_t	ready () const
	Tell, for which of the connected sonars, the latest ranging, started by `trigger()`, is finished, ie the echo pulse has been received. More...

bool	all_ready () const
	Tell if the latest ranging, started by `trigger()`, is finished for all connected sonars, ie the echo pulse has been received. More...

void	set_ready ()
	Force readiness of all connected sensors, ie the end of current ranging. More...

Static Public Attributes
static constexpr const board::DigitalPin	TRIGGER = TRIGGER_
	The `board::DigitalPin` connected to the sensors trigger pins. More...

static constexpr const board::Port	ECHO_PORT = ECHO_PORT_
	The MCU port to which all echo pins of sonars handled by this class are connected. More...

static constexpr const uint8_t	ECHO_MASK = ECHO_MASK_
	The mask determining which pins of `ECHO_PORT` are actually connected to a real sonar echo pin. More...

static constexpr const uint16_t	MAX_RANGE_M = 4
	The approximate maximum range, in meters, that this sonar sensor supports. More...

static constexpr const uint16_t	DEFAULT_TIMEOUT_MS = MAX_RANGE_M * 2 * ONE_MILLI_32 / SPEED_OF_SOUND + 1
	The default timeout duration, in milliseconds, to use if you want to cover the maximum range of the sensor. More...

Friends
struct	isr_handler

Detailed Description

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>
class devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >

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.

With this class, all connected sonars start ranging at the same time. This method works exclusively in asynchronous mode.

Note that, contrarily to the HCSR04 class, this class does not handle calculation or storeage of echo pulse duration for all connected sonars; instead, it produces SonarEvents upon each sonar event occurring:

echo pulse leading edge received
echo pulse trailing edge received
timeout occurred while waiting for echo pulse reception You need to register proper callbacks in order to receive these events and process them. It is the responsibility your callbacks to calculate (and optionally store) echo pulse duration, based on all received SonarEvents.

Template Parameters

NTIMER_	the AVR timer of the `timer::RTT` to use for this `MultiHCSR04`
TRIGGER_	the `board::DigitalPin` connected to the sensors trigger pins; that can be any available pin.
ECHO_PORT_	the MCU port to which all echo pins of sonars handled by this class are connected; this port must support PCINT interrupts.
ECHO_MASK_	the mask determining which pins of `ECHO_PORT_` are actually connected to a real sonar echo pin; for each bit set, the matching pin must be able to generate a PCINT interrupt when its level changes.

See also: SonarEvent; REGISTER_MULTI_HCSR04_PCI_ISR_METHOD(); REGISTER_MULTI_HCSR04_RTT_TIMEOUT_METHOD(); REGISTER_MULTI_HCSR04_PCI_ISR_FUNCTION(); REGISTER_MULTI_HCSR04_RTT_TIMEOUT_FUNCTION()

Definition at line 1107 of file sonar.h.

Member Typedef Documentation

◆ RTT

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

using devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::RTT = timer::RTT<NTIMER_>

The type of timer::RTT used by this MultiHCSR04 instance.

Definition at line 1129 of file sonar.h.

◆ EVENT

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

using devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::EVENT = SonarEvent<NTIMER_>

The exact SonarEvent type produced by this MultiHCSR04 instance.

Definition at line 1131 of file sonar.h.

Constructor & Destructor Documentation

◆ MultiHCSR04()

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::MultiHCSR04 ( RTT & rtt )

inlineexplicit

Construct a new a multi-sonar sensors handler.

Parameters

rtt	a reference to an existing `timer::RTT` for echo pulse duration counting; this RTT shall be started before using any other methods of this sonar.

Definition at line 1155 of file sonar.h.

Member Function Documentation

◆ trigger()

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

void devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::trigger ( uint16_t timeout_ms )

inline

Start ranging on all sonars connected to this MultiHCSR04.

When calling this method, a trigger pulse is sent to all connected sonars. After this call, SonarEvents will be generated and propagated to callbacks whenever any of the following occurs:

an echo pulse leading edge is detected on a sonar
an echo pulse trailing edge is detected on a sonar
timeout occurred while waiting for echo pulses

Parameters

timeout_ms the timeout, in milliseconds, after which the ranging will stop if no echo pulse has been received

See also: REGISTER_MULTI_HCSR04_PCI_ISR_METHOD(); REGISTER_MULTI_HCSR04_RTT_TIMEOUT_METHOD(); REGISTER_MULTI_HCSR04_PCI_ISR_FUNCTION(); REGISTER_MULTI_HCSR04_RTT_TIMEOUT_FUNCTION()

Definition at line 1177 of file sonar.h.

◆ active()

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

bool devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::active ( ) const

inline

Tell if a ranging is under way on any sonar managed by this MultiHCSR04 instance.

Ranging is started when calling trigger() and finishes when one of the following conditions is true:

all connected sonars have received an echo pulse
timeout has occurred while waiting for one (or more) echo pulses

Definition at line 1197 of file sonar.h.

◆ ready()

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

uint8_t devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::ready ( ) const

inline

Tell, for which of the connected sonars, the latest ranging, started by trigger(), is finished, ie the echo pulse has been received.

If you want to know if ranging for all connected sonars is finished, then use all_ready() instead.

Returns: a bit mask where each set bit indicates that ranging is finished for the corresponding sonar.

See also: trigger(); all_ready(); set_ready()

Definition at line 1215 of file sonar.h.

◆ all_ready()

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

bool devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::all_ready ( ) const

inline

Tell if the latest ranging, started by trigger(), is finished for all connected sonars, ie the echo pulse has been received.

If you want to know for which connected sonars ranging is finished, then use ready() instead.

Definition at line 1226 of file sonar.h.

◆ set_ready()

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

void devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::set_ready ( )

inline

Force readiness of all connected sensors, ie the end of current ranging.

This can be used by callbacks e.g. to stop current ranging when a timeout has occurred.

Definition at line 1236 of file sonar.h.

Friends And Related Function Documentation

◆ isr_handler

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

friend struct isr_handler

friend

Definition at line 1282 of file sonar.h.

Member Data Documentation

◆ TRIGGER

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

constexpr const board::DigitalPin devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::TRIGGER = TRIGGER_

staticconstexpr

The board::DigitalPin connected to the sensors trigger pins.

Definition at line 1111 of file sonar.h.

◆ ECHO_PORT

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

constexpr const board::Port devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::ECHO_PORT = ECHO_PORT_

staticconstexpr

The MCU port to which all echo pins of sonars handled by this class are connected.

Definition at line 1113 of file sonar.h.

◆ ECHO_MASK

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

constexpr const uint8_t devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::ECHO_MASK = ECHO_MASK_

staticconstexpr

The mask determining which pins of ECHO_PORT are actually connected to a real sonar echo pin.

Definition at line 1115 of file sonar.h.

◆ MAX_RANGE_M

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

constexpr const uint16_t devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::MAX_RANGE_M = 4

staticconstexpr

The approximate maximum range, in meters, that this sonar sensor supports.

Any obstacle beyond this distance will generate no echo pulse from the sensor.

Definition at line 1138 of file sonar.h.

◆ DEFAULT_TIMEOUT_MS

template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::Port ECHO_PORT_, uint8_t ECHO_MASK_>

constexpr const uint16_t devices::sonar::MultiHCSR04< NTIMER_, TRIGGER_, ECHO_PORT_, ECHO_MASK_ >::DEFAULT_TIMEOUT_MS = MAX_RANGE_M * 2 * ONE_MILLI_32 / SPEED_OF_SOUND + 1

staticconstexpr

The default timeout duration, in milliseconds, to use if you want to cover the maximum range of the sensor.

Using any greater timeout value would be pointless.

See also: MAX_RANGE_M; trigger()

Definition at line 1147 of file sonar.h.

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

fastarduino/devices/sonar.h

Public Types

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ RTT

◆ EVENT

Constructor & Destructor Documentation

◆ MultiHCSR04()

Member Function Documentation

◆ trigger()

◆ active()

◆ ready()

◆ all_ready()

◆ set_ready()

Friends And Related Function Documentation

◆ isr_handler

Member Data Documentation

◆ TRIGGER

◆ ECHO_PORT

◆ ECHO_MASK

◆ MAX_RANGE_M

◆ DEFAULT_TIMEOUT_MS