API to handle ultrasonic distance rangers (aka "sonar") such as the HC-SR04. More...

#include <fastarduino/boards/board.h>
#include <fastarduino/gpio.h>
#include <fastarduino/time.h>
#include <fastarduino/realtime_timer.h>
#include <fastarduino/utilities.h>
#include <fastarduino/int.h>
#include <fastarduino/pci.h>

Include dependency graph for sonar.h:

Go to the source code of this file.

Classes
class	devices::sonar::AbstractSonar< NTIMER_ >
	An abstract base class for some sonar classes defined as part of this API. More...

class	devices::sonar::HCSR04< NTIMER_, TRIGGER_, ECHO_, SONAR_TYPE_ >

struct	devices::sonar::SonarEvent< NTIMER_ >
	This type holds information about events occurring within `MultiHCSR04` handler. More...

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

Namespaces
namespace	devices
	Defines all API for all external devices supported by FastArduino.

namespace	devices::sonar
	Defines the API for sonar support.

Macros
#define	REGISTER_HCSR04_INT_ISR(TIMER, INT_NUM, TRIGGER, ECHO)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::HCSR04` to listen to echo pulses when the echo pin is a `board::ExternalInterruptPin`. More...

#define	REGISTER_HCSR04_PCI_ISR(TIMER, PCI_NUM, TRIGGER, ECHO, ...)
	Register the necessary ISR (Interrupt Service Routine) for a set of several `devices::sonar::HCSR04` to listen to echo pulses when the echo pin is a `board::InterruptPin`. More...

#define	SONAR_PINS(TRIGGER, ECHO) devices::sonar::isr_handler::TriggerEcho<TRIGGER, ECHO>
	Macro used to build proper arguments for `REGISTER_DISTINCT_HCSR04_PCI_ISR()`. More...

#define	REGISTER_DISTINCT_HCSR04_PCI_ISR(TIMER, PCI_NUM, SONAR_PINS1, ...)
	Register the necessary ISR (Interrupt Service Routine) for a set of several `devices::sonar::HCSR04` to listen to echo pulses when the echo pin is a `board::InterruptPin`. More...

#define	REGISTER_HCSR04_INT_ISR_METHOD(TIMER, INT_NUM, TRIGGER, ECHO, HANDLER, CALLBACK)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::HCSR04` to listen to echo pulses when the echo pin is a `board::ExternalInterruptPin`, and call back a handler's method if the sonar has finished receiving the echo pulse. More...

#define	REGISTER_HCSR04_INT_ISR_FUNCTION(TIMER, INT_NUM, TRIGGER, ECHO, CALLBACK)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::HCSR04` to listen to echo pulses when the echo pin is a `board::ExternalInterruptPin`, along with a callback function that will be notified when the sonar has finished receiving the echo pulse. More...

#define	REGISTER_HCSR04_PCI_ISR_METHOD(TIMER, PCI_NUM, TRIGGER, ECHO, HANDLER, CALLBACK)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::HCSR04` to listen to echo pulses when the echo pin is a `board::InterruptPin`, and call back a handler's method if the sonar has finished receiving the echo pulse. More...

#define	REGISTER_HCSR04_PCI_ISR_FUNCTION(TIMER, PCI_NUM, TRIGGER, ECHO, CALLBACK)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::HCSR04` to listen to echo pulses when the echo pin is a `board::InterruptPin`, along with a callback function that will be notified when the sonar has finished receiving the echo pulse. More...

#define	REGISTER_HCSR04_RTT_TIMEOUT(TIMER_NUM, SONAR, ...)
	Register the necessary ISR (Interrupt Service Routine) for a set of `devices::sonar::HCSR04` to be notified when a timeout occurs; this ISR is also in charge of the associated `timer::RTT` time update. More...

#define	REGISTER_HCSR04_RTT_TIMEOUT_METHOD(TIMER_NUM, HANDLER, CALLBACK, SONAR, ...)
	Register the necessary ISR (Interrupt Service Routine) for a set of `devices::sonar::HCSR04` to be notified, and call back a handler's method, when a timeout occurs; this ISR is also in charge of the associated `timer::RTT` time update. More...

#define	REGISTER_HCSR04_RTT_TIMEOUT_FUNCTION(TIMER_NUM, CALLBACK, SONAR, ...)
	Register the necessary ISR (Interrupt Service Routine) for a set of `devices::sonar::HCSR04` to be notified, and call back a function, when a timeout occurs; this ISR is also in charge of the associated `timer::RTT` time update. More...

#define	REGISTER_MULTI_HCSR04_PCI_ISR_METHOD(TIMER, PCI_NUM, TRIGGER, ECHO_PORT, ECHO_MASK, HANDLER, CALLBACK)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::MultiHCSR04` to listen to echo pulses on all sonars connected to it, and call back a handler's method. More...

#define	REGISTER_MULTI_HCSR04_PCI_ISR_FUNCTION(TIMER, PCI_NUM, TRIGGER, ECHO_PORT, ECHO_MASK, CALLBACK)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::MultiHCSR04` to listen to echo pulses on all sonars connected to it, and call back a function. More...

#define	REGISTER_MULTI_HCSR04_RTT_TIMEOUT_METHOD(TIMER_NUM, SONAR, HANDLER, CALLBACK)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::MultiHCSR04` to be notified, and call back a handler's method, when a timeout occurs; this ISR is also in charge of the associated `timer::RTT` time update. More...

#define	REGISTER_MULTI_HCSR04_RTT_TIMEOUT_FUNCTION(TIMER_NUM, SONAR, CALLBACK)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::MultiHCSR04` to be notified, and call back a function, when a timeout occurs; this ISR is also in charge of the associated `timer::RTT` time update. More...

#define	REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_METHOD(TIMER_NUM, SONAR, HANDLER, CB_TIMEOUT, CB_RTT)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::MultiHCSR04` to be notified, and call back one of two handler's methods, for each of the following events: More...

#define	REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_FUNCTION(TIMER_NUM, SONAR, CB_TIMEOUT, CB_RTT)
	Register the necessary ISR (Interrupt Service Routine) for a `devices::sonar::MultiHCSR04` to be notified, and call back one of two functions, for each of the following events: More...

#define	DECL_SONAR_ISR_HANDLERS_FRIEND
	This macro shall be used in a class containing a private callback method, registered by one (or more) of: More...

Typedefs
template<board::Timer NTIMER_, board::DigitalPin TRIGGER_, board::DigitalPin ECHO_>
using	devices::sonar::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	devices::sonar::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	devices::sonar::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	devices::sonar::SonarType : uint8_t { devices::sonar::BLOCKING , devices::sonar::ASYNC_INT , devices::sonar::ASYNC_PCINT }
	This enum defines the different modes, supported by `HCSR04`, to calculate the echo pin pulse duration. More...

Functions
static constexpr uint16_t	devices::sonar::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	devices::sonar::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	devices::sonar::SPEED_OF_SOUND = 340UL
	The approximate speed of sound (and ultrasonic) waves, in the air, expressed in meters per second. More...

Detailed Description

API to handle ultrasonic distance rangers (aka "sonar") such as the HC-SR04.

Definition in file sonar.h.

Macro Definition Documentation

◆ REGISTER_HCSR04_INT_ISR

#define REGISTER_HCSR04_INT_ISR	(	TIMER,
		INT_NUM,
		TRIGGER,
		ECHO
	)

Value:

    ISR(CAT3(INT, INT_NUM, _vect))                                               \
    {                                                                            \
        devices::sonar::isr_handler::sonar_int<INT_NUM, TIMER, TRIGGER, ECHO>(); \
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::HCSR04 to listen to echo pulses when the echo pin is a board::ExternalInterruptPin.

Parameters

TIMER	the `board::Timer` type used to instantiate the `devices::sonar::HCSR04` template class.
INT_NUM	the number of the `INT` vector for the `board::ExternalInterruptPin` connected to the echo pin
TRIGGER	the `board::DigitalPin` connected to the sonar trigger pin
ECHO	the `board::ExternalInterruptPin` connected to the sonar echo pin

See also: devices::sonar::HCSR04

Definition at line 46 of file sonar.h.

◆ REGISTER_HCSR04_PCI_ISR

#define REGISTER_HCSR04_PCI_ISR	(	TIMER,
		PCI_NUM,
		TRIGGER,
		ECHO,
		...
	)

Value:

    ISR(CAT3(PCINT, PCI_NUM, _vect))                                                            \
    {                                                                                           \
        devices::sonar::isr_handler::sonar_pci<PCI_NUM, TIMER, TRIGGER, ECHO, ##__VA_ARGS__>(); \
    }

Register the necessary ISR (Interrupt Service Routine) for a set of several devices::sonar::HCSR04 to listen to echo pulses when the echo pin is a board::InterruptPin.

This macro supports registration of an ISR for several HCSR04, sharing one single trigger pin, and having all echo pins on the same port.

Parameters

TIMER	the `board::Timer` type used to instantiate the `devices::sonar::HCSR04` template class.
PCI_NUM	the number of the `PCINT` vector for the `board::InterruptPin` connected to the echo pin
TRIGGER	the `board::DigitalPin` connected to the sonar trigger pin
ECHO	the `board::InterruptPin` connected to the sonar echo pin
...	other echo pins for other `HCSR04`

See also: devices::sonar::HCSR04; REGISTER_DISTINCT_HCSR04_PCI_ISR()

Definition at line 70 of file sonar.h.

◆ SONAR_PINS

#define SONAR_PINS	(	TRIGGER,
		ECHO
	)	devices::sonar::isr_handler::TriggerEcho<TRIGGER, ECHO>

Macro used to build proper arguments for REGISTER_DISTINCT_HCSR04_PCI_ISR().

Each constructed argument is actually a pair of pins, one board::DigitalPin (the trigger pin of the sonar), one board::InterruptPin (the echo pin of the sonar).

Parameters

TRIGGER	the `board::DigitalPin` connected to the trigger pin of the sonar
ECHO	the `board::InterruptPin` connected to the echo pin of the sonar

See also: REGISTER_DISTINCT_HCSR04_PCI_ISR()

Definition at line 86 of file sonar.h.

◆ REGISTER_DISTINCT_HCSR04_PCI_ISR

#define REGISTER_DISTINCT_HCSR04_PCI_ISR	(	TIMER,
		PCI_NUM,
		SONAR_PINS1,
		...
	)

Value:

    ISR(CAT3(PCINT, PCI_NUM, _vect))                                                                   \
    {                                                                                                  \
        devices::sonar::isr_handler::sonar_distinct_pci<PCI_NUM, TIMER, SONAR_PINS1, ##__VA_ARGS__>(); \
    }

Register the necessary ISR (Interrupt Service Routine) for a set of several devices::sonar::HCSR04 to listen to echo pulses when the echo pin is a board::InterruptPin.

This macro supports registration of an ISR for several HCSR04, using distinct trigger pins, but having all echo pins on the same port.

Parameters

TIMER	the `board::Timer` type used to instantiate the `devices::sonar::HCSR04` template class.
PCI_NUM	the number of the `PCINT` vector for the `board::InterruptPin` connected to the echo pin
SONAR_PINS1	the pair of pins connected to the 1st sonar; this is a specific type, created by `SONAR_PINS()` macro.
...	other pairs of (trigger pin, echo pin) for other `HCSR04`

See also: devices::sonar::HCSR04; SONAR_PINS(); REGISTER_HCSR04_PCI_ISR()

Definition at line 107 of file sonar.h.

◆ REGISTER_HCSR04_INT_ISR_METHOD

#define REGISTER_HCSR04_INT_ISR_METHOD	(	TIMER,
		INT_NUM,
		TRIGGER,
		ECHO,
		HANDLER,
		CALLBACK
	)

Value:

    ISR(CAT3(INT, INT_NUM, _vect))                                                                         \
    {                                                                                                      \
        devices::sonar::isr_handler::sonar_int_method<INT_NUM, TIMER, TRIGGER, ECHO, HANDLER, CALLBACK>(); \
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::HCSR04 to listen to echo pulses when the echo pin is a board::ExternalInterruptPin, and call back a handler's method if the sonar has finished receiving the echo pulse.

Parameters

TIMER	the `board::Timer` type used to instantiate the `devices::sonar::HCSR04` template class.
INT_NUM	the number of the `INT` vector for the `board::ExternalInterruptPin` connected to the echo pin
TRIGGER	the `board::DigitalPin` connected to the sonar trigger pin
ECHO	the `board::ExternalInterruptPin` connected to the sonar echo pin
HANDLER	the class holding the callback method
CALLBACK	the method of `HANDLER` that will be called when the sonar has received the echo pulse; this must be a proper PTMF (pointer to member function).

See also: devices::sonar::HCSR04; REGISTER_HCSR04_INT_ISR(); REGISTER_HCSR04_INT_ISR_FUNCTION()

Definition at line 133 of file sonar.h.

◆ REGISTER_HCSR04_INT_ISR_FUNCTION

#define REGISTER_HCSR04_INT_ISR_FUNCTION	(	TIMER,
		INT_NUM,
		TRIGGER,
		ECHO,
		CALLBACK
	)

Value:

    ISR(CAT3(INT, INT_NUM, _vect))                                                                  \
    {                                                                                               \
        devices::sonar::isr_handler::sonar_int_function<INT_NUM, TIMER, TRIGGER, ECHO, CALLBACK>(); \
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::HCSR04 to listen to echo pulses when the echo pin is a board::ExternalInterruptPin, along with a callback function that will be notified when the sonar has finished receiving the echo pulse.

Parameters

TIMER	the `board::Timer` type used to instantiate the `devices::sonar::HCSR04` template class.
INT_NUM	the number of the `INT` vector for the `board::ExternalInterruptPin` connected to the echo pin
TRIGGER	the `board::DigitalPin` connected to the sonar trigger pin
ECHO	the `board::ExternalInterruptPin` connected to the sonar echo pin
CALLBACK	the function that will be called when the sonar has received the echo pulse

See also: devices::sonar::HCSR04; REGISTER_HCSR04_INT_ISR(); REGISTER_HCSR04_INT_ISR_METHOD()

Definition at line 157 of file sonar.h.

◆ REGISTER_HCSR04_PCI_ISR_METHOD

#define REGISTER_HCSR04_PCI_ISR_METHOD	(	TIMER,
		PCI_NUM,
		TRIGGER,
		ECHO,
		HANDLER,
		CALLBACK
	)

Value:

    ISR(CAT3(PCINT, PCI_NUM, _vect))                                                                       \
    {                                                                                                      \
        devices::sonar::isr_handler::sonar_pci_method<PCI_NUM, TIMER, TRIGGER, ECHO, HANDLER, CALLBACK>(); \
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::HCSR04 to listen to echo pulses when the echo pin is a board::InterruptPin, and call back a handler's method if the sonar has finished receiving the echo pulse.

Parameters

TIMER	the `board::Timer` type used to instantiate the `devices::sonar::HCSR04` template class.
PCI_NUM	the number of the `PCINT` vector for the `board::InterruptPin` connected to the echo pin
TRIGGER	the `board::DigitalPin` connected to the sonar trigger pin
ECHO	the `board::InterruptPin` connected to the sonar echo pin
HANDLER	the class holding the callback method
CALLBACK	the method of `HANDLER` that will be called when the sonar has received the echo pulse; this must be a proper PTMF (pointer to member function).

See also: devices::sonar::HCSR04; REGISTER_DISTINCT_HCSR04_PCI_ISR(); REGISTER_HCSR04_PCI_ISR(); REGISTER_HCSR04_PCI_ISR_FUNCTION()

Definition at line 185 of file sonar.h.

◆ REGISTER_HCSR04_PCI_ISR_FUNCTION

#define REGISTER_HCSR04_PCI_ISR_FUNCTION	(	TIMER,
		PCI_NUM,
		TRIGGER,
		ECHO,
		CALLBACK
	)

Value:

    ISR(CAT3(PCINT, PCI_NUM, _vect))                                                                \
    {                                                                                               \
        devices::sonar::isr_handler::sonar_pci_function<PCI_NUM, TIMER, TRIGGER, ECHO, CALLBACK>(); \
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::HCSR04 to listen to echo pulses when the echo pin is a board::InterruptPin, along with a callback function that will be notified when the sonar has finished receiving the echo pulse.

Parameters

TIMER	the `board::Timer` type used to instantiate the `devices::sonar::HCSR04` template class.
PCI_NUM	the number of the `PCINT` vector for the `board::InterruptPin` connected to the echo pin
TRIGGER	the `board::DigitalPin` connected to the sonar trigger pin
ECHO	the `board::InterruptPin` connected to the sonar echo pin
CALLBACK	the function that will be called when the sonar has received the echo pulse

See also: devices::sonar::HCSR04; REGISTER_HCSR04_PCI_ISR(); REGISTER_HCSR04_PCI_ISR_METHOD()

Definition at line 210 of file sonar.h.

◆ REGISTER_HCSR04_RTT_TIMEOUT

#define REGISTER_HCSR04_RTT_TIMEOUT	(	TIMER_NUM,
		SONAR,
		...
	)

Value:

    ISR(CAT3(TIMER, TIMER_NUM, _COMPA_vect))                                              \
    {                                                                                     \
        devices::sonar::isr_handler::sonar_rtt_change<TIMER_NUM, SONAR, ##__VA_ARGS__>(); \
    }

Register the necessary ISR (Interrupt Service Routine) for a set of devices::sonar::HCSR04 to be notified when a timeout occurs; this ISR is also in charge of the associated timer::RTT time update.

Parameters

TIMER_NUM	the number of the TIMER feature for the target MCU
SONAR	the actual type of the first sonar to notify (instantiated template of `devices::sonar::HCSR04`)
...	the actual types of other sonars to notify

See also: devices::sonar::HCSR04; HCSR04::echo_us(); HCSR04::await_echo_us(); HCSR04::async_echo(); REGISTER_RTT_ISR()

Definition at line 232 of file sonar.h.

◆ REGISTER_HCSR04_RTT_TIMEOUT_METHOD

#define REGISTER_HCSR04_RTT_TIMEOUT_METHOD	(	TIMER_NUM,
		HANDLER,
		CALLBACK,
		SONAR,
		...
	)

Value:

    ISR(CAT3(TIMER, TIMER_NUM, _COMPA_vect))                                                  \
    {                                                                                         \
        if (devices::sonar::isr_handler::sonar_rtt_change<TIMER_NUM, SONAR, ##__VA_ARGS__>()) \
            interrupt::CallbackHandler<void (HANDLER::*)(), CALLBACK>::call();                \
    }

Register the necessary ISR (Interrupt Service Routine) for a set of devices::sonar::HCSR04 to be notified, and call back a handler's method, when a timeout occurs; this ISR is also in charge of the associated timer::RTT time update.

Parameters

TIMER_NUM	the number of the TIMER feature for the target MCU
HANDLER	the class holding the callback method
CALLBACK	the function that will be called when the timeout has occurred
SONAR	the actual type of the first sonar to notify (instantiated template of `devices::sonar::HCSR04`)
...	the actual types of other sonars to notify

See also: devices::sonar::HCSR04; HCSR04::echo_us(); HCSR04::await_echo_us(); HCSR04::async_echo(); REGISTER_HCSR04_RTT_TIMEOUT()

Definition at line 257 of file sonar.h.

◆ REGISTER_HCSR04_RTT_TIMEOUT_FUNCTION

#define REGISTER_HCSR04_RTT_TIMEOUT_FUNCTION	(	TIMER_NUM,
		CALLBACK,
		SONAR,
		...
	)

Value:

    ISR(CAT3(TIMER, TIMER_NUM, _COMPA_vect))                                                  \
    {                                                                                         \
        if (devices::sonar::isr_handler::sonar_rtt_change<TIMER_NUM, SONAR, ##__VA_ARGS__>()) \
            interrupt::CallbackHandler<void (*)(), CALLBACK>::call();                         \
    }

Register the necessary ISR (Interrupt Service Routine) for a set of devices::sonar::HCSR04 to be notified, and call back a function, when a timeout occurs; this ISR is also in charge of the associated timer::RTT time update.

Parameters

TIMER_NUM	the number of the TIMER feature for the target MCU
CALLBACK	the function that will be called when the timeout has occurred
SONAR	the actual type of the first sonar to notify (instantiated template of `devices::sonar::HCSR04`)
...	the actual types of other sonars to notify

See also: devices::sonar::HCSR04; HCSR04::echo_us(); HCSR04::await_echo_us(); HCSR04::async_echo(); REGISTER_HCSR04_RTT_TIMEOUT()

Definition at line 282 of file sonar.h.

◆ REGISTER_MULTI_HCSR04_PCI_ISR_METHOD

#define REGISTER_MULTI_HCSR04_PCI_ISR_METHOD	(	TIMER,
		PCI_NUM,
		TRIGGER,
		ECHO_PORT,
		ECHO_MASK,
		HANDLER,
		CALLBACK
	)

Value:

    ISR(CAT3(PCINT, PCI_NUM, _vect))                                                                           \
    {                                                                                                          \
        using ISRHANDLER = devices::sonar::isr_handler;                                                        \
        ISRHANDLER::multi_sonar_pci_method<PCI_NUM, TIMER, TRIGGER, ECHO_PORT, ECHO_MASK, HANDLER, CALLBACK>();\
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::MultiHCSR04 to listen to echo pulses on all sonars connected to it, and call back a handler's method.

Parameters

TIMER	the `board::Timer` type used to instantiate the `devices::sonar::MultiHCSR04` template class.
PCI_NUM	the number of the `PCINT` vector for the `board::InterruptPin` connected to the echo pin
TRIGGER	the `board::DigitalPin` connected to the sonars trigger pins
ECHO_PORT	the `board::Port` connected to all sonar echo pins
ECHO_MASK	the mask to apply to `ECHO_PORT` to define which pins of this port are connected to a sonar
HANDLER	the class holding the callback method
CALLBACK	the method of `HANDLER` that will be called when one sonar echo pin changes level, i.e. when a leading or trailing edge of the echo pulse is received; this must be a proper PTMF (pointer to member function) which takes one argument of type `const SonarEvent<TIMER>&`.

See also: devices::sonar::MultiHCSR04; devices::sonar::SonarEvent; REGISTER_MULTI_HCSR04_PCI_ISR_FUNCTION(); REGISTER_MULTI_HCSR04_RTT_TIMEOUT_METHOD()

Definition at line 313 of file sonar.h.

◆ REGISTER_MULTI_HCSR04_PCI_ISR_FUNCTION

#define REGISTER_MULTI_HCSR04_PCI_ISR_FUNCTION	(	TIMER,
		PCI_NUM,
		TRIGGER,
		ECHO_PORT,
		ECHO_MASK,
		CALLBACK
	)

Value:

    ISR(CAT3(PCINT, PCI_NUM, _vect))                                                                    \
    {                                                                                                   \
        using ISRHANDLER = devices::sonar::isr_handler;                                                 \
        ISRHANDLER::multi_sonar_pci_function<PCI_NUM, TIMER, TRIGGER, ECHO_PORT, ECHO_MASK, CALLBACK>();\
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::MultiHCSR04 to listen to echo pulses on all sonars connected to it, and call back a function.

Parameters

TIMER	the `board::Timer` type used to instantiate the `devices::sonar::MultiHCSR04` template class.
PCI_NUM	the number of the `PCINT` vector for the `board::InterruptPin` connected to the echo pin
TRIGGER	the `board::DigitalPin` connected to the sonars trigger pins
ECHO_PORT	the `board::Port` connected to all sonar echo pins
ECHO_MASK	the mask to apply to `ECHO_PORT` to define which pins of this port are connected to a sonar
CALLBACK	the function that will be called when one sonar echo pin changes level, i.e. when a leading or trailing edge of the echo pulse is received; this must take one argument of type `const SonarEvent<TIMER>&`.

See also: devices::sonar::MultiHCSR04; devices::sonar::SonarEvent; REGISTER_MULTI_HCSR04_PCI_ISR_METHOD(); REGISTER_MULTI_HCSR04_RTT_TIMEOUT_FUNCTION()

Definition at line 342 of file sonar.h.

◆ REGISTER_MULTI_HCSR04_RTT_TIMEOUT_METHOD

#define REGISTER_MULTI_HCSR04_RTT_TIMEOUT_METHOD	(	TIMER_NUM,
		SONAR,
		HANDLER,
		CALLBACK
	)

Value:

    ISR(CAT3(TIMER, TIMER_NUM, _COMPA_vect))                                                                     \
    {                                                                                                            \
        using EVENT = typename SONAR::EVENT;                                                                     \
        EVENT event = devices::sonar::isr_handler::multi_sonar_rtt_change<TIMER_NUM, SONAR, EVENT>();            \
        if (event.timeout()) interrupt::CallbackHandler<void (HANDLER::*)(const EVENT&), CALLBACK>::call(event); \
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::MultiHCSR04 to be notified, and call back a handler's method, when a timeout occurs; this ISR is also in charge of the associated timer::RTT time update.

Parameters

TIMER_NUM	the number of the TIMER feature for the target MCU
SONAR	the actual type of the `devices::sonar::MultiHCSR04` for which this ISR is registered
HANDLER	the class holding the callback method
CALLBACK	the method of `HANDLER` that will be called when a timeout occurs; this must be a proper PTMF (pointer to member function) which takes one argument of type `const SonarEvent<TIMER>&`.

See also: devices::sonar::MultiHCSR04; devices::sonar::SonarEvent; REGISTER_MULTI_HCSR04_RTT_TIMEOUT_FUNCTION()

Definition at line 367 of file sonar.h.

◆ REGISTER_MULTI_HCSR04_RTT_TIMEOUT_FUNCTION

#define REGISTER_MULTI_HCSR04_RTT_TIMEOUT_FUNCTION	(	TIMER_NUM,
		SONAR,
		CALLBACK
	)

Value:

    ISR(CAT3(TIMER, TIMER_NUM, _COMPA_vect))                                                            \
    {                                                                                                   \
        using EVENT = typename SONAR::EVENT;                                                            \
        EVENT event = devices::sonar::isr_handler::multi_sonar_rtt_change<TIMER_NUM, SONAR, EVENT>();   \
        if (event.timeout()) interrupt::CallbackHandler<void (*)(const EVENT&), CALLBACK>::call(event); \
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::MultiHCSR04 to be notified, and call back a function, when a timeout occurs; this ISR is also in charge of the associated timer::RTT time update.

Parameters

TIMER_NUM	the number of the TIMER feature for the target MCU
SONAR	the actual type of the `devices::sonar::MultiHCSR04` for which this ISR is registered
CALLBACK	the function that will be called when a timeout occurs; this must take one argument of type `const SonarEvent<TIMER>&`.

See also: devices::sonar::MultiHCSR04; devices::sonar::SonarEvent; REGISTER_MULTI_HCSR04_RTT_TIMEOUT_METHOD()

Definition at line 391 of file sonar.h.

◆ REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_METHOD

#define REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_METHOD	(	TIMER_NUM,
		SONAR,
		HANDLER,
		CB_TIMEOUT,
		CB_RTT
	)

Value:

    ISR(CAT3(TIMER, TIMER_NUM, _COMPA_vect))                                                            \
    {                                                                                                   \
        using EVENT = typename SONAR::EVENT;                                                            \
        EVENT event = devices::sonar::isr_handler::multi_sonar_rtt_change<TIMER_NUM, SONAR, EVENT>();   \
        if (event.timeout())                                                                            \
            interrupt::CallbackHandler<void (HANDLER::*)(const EVENT&), CB_TIMEOUT>::call(event);       \
        interrupt::CallbackHandler<void (HANDLER::*)(), CB_RTT>::call();                                \
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::MultiHCSR04 to be notified, and call back one of two handler's methods, for each of the following events:

a range timeout occurs
the associated timer::RTT is updated (one ms elapsed) This ISR is also in charge of the associated timer::RTT time update.

Parameters

TIMER_NUM	the number of the TIMER feature for the target MCU
SONAR	the actual type of the `devices::sonar::MultiHCSR04` for which this ISR is registered
HANDLER	the class holding the callback method
CB_TIMEOUT	the method of `HANDLER` that will be called when a timeout occurs; this must be a proper PTMF (pointer to member function) which takes one argument of type `const SonarEvent<TIMER>&`.
CB_RTT	the method of `HANDLER` that will be called when the associated `timer::RTT` is updated; this must be a proper PTMF (pointer to member function) which takes no argument. This is typically used by `HANDLER` to retrigger sonars ranging on a periodic basis.

See also: devices::sonar::MultiHCSR04; devices::sonar::SonarEvent; REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_FUNCTION()

Definition at line 423 of file sonar.h.

◆ REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_FUNCTION

#define REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_FUNCTION	(	TIMER_NUM,
		SONAR,
		CB_TIMEOUT,
		CB_RTT
	)

Value:

    ISR(CAT3(TIMER, TIMER_NUM, _COMPA_vect))                                                            \
    {                                                                                                   \
        using EVENT = typename SONAR::EVENT;                                                            \
        EVENT event = devices::sonar::isr_handler::multi_sonar_rtt_change<TIMER_NUM, SONAR, EVENT>();   \
        if (event.timeout())                                                                            \
            interrupt::CallbackHandler<void (*)(const EVENT&), CB_TIMEOUT>::call(event);                \
        interrupt::CallbackHandler<void (*)(), CB_RTT>::call();                                         \
    }

Register the necessary ISR (Interrupt Service Routine) for a devices::sonar::MultiHCSR04 to be notified, and call back one of two functions, for each of the following events:

a range timeout occurs
the associated timer::RTT is updated (one ms elapsed) This ISR is also in charge of the associated timer::RTT time update.

Parameters

TIMER_NUM	the number of the TIMER feature for the target MCU
SONAR	the actual type of the `devices::sonar::MultiHCSR04` for which this ISR is registered
CB_TIMEOUT	the function that will be called when a timeout occurs; this must take one argument of type `const SonarEvent<TIMER>&`.
CB_RTT	the function that will be called when the associated `timer::RTT` is updated; this must take no argument. This is typically used to retrigger sonars ranging on a periodic basis.

See also: devices::sonar::MultiHCSR04; devices::sonar::SonarEvent; REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_METHOD()

Definition at line 454 of file sonar.h.

◆ DECL_SONAR_ISR_HANDLERS_FRIEND

#define DECL_SONAR_ISR_HANDLERS_FRIEND

Value:

    friend struct devices::sonar::isr_handler; \
    DECL_INT_ISR_FRIENDS                       \
    DECL_PCINT_ISR_FRIENDS                     \
    DECL_TIMER_COMP_FRIENDS

This macro shall be used in a class containing a private callback method, registered by one (or more) of:

REGISTER_HCSR04_INT_ISR_METHOD
REGISTER_HCSR04_PCI_ISR_METHOD
REGISTER_HCSR04_RTT_TIMEOUT_METHOD
REGISTER_MULTI_HCSR04_PCI_ISR_METHOD
REGISTER_MULTI_HCSR04_RTT_TIMEOUT_METHOD

It declares the class where it is used as a friend of all necessary functions so that the private callback method can be called properly.

Definition at line 476 of file sonar.h.

Classes

Namespaces

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ REGISTER_HCSR04_INT_ISR

◆ REGISTER_HCSR04_PCI_ISR

◆ SONAR_PINS

◆ REGISTER_DISTINCT_HCSR04_PCI_ISR

◆ REGISTER_HCSR04_INT_ISR_METHOD

◆ REGISTER_HCSR04_INT_ISR_FUNCTION

◆ REGISTER_HCSR04_PCI_ISR_METHOD

◆ REGISTER_HCSR04_PCI_ISR_FUNCTION

◆ REGISTER_HCSR04_RTT_TIMEOUT

◆ REGISTER_HCSR04_RTT_TIMEOUT_METHOD

◆ REGISTER_HCSR04_RTT_TIMEOUT_FUNCTION

◆ REGISTER_MULTI_HCSR04_PCI_ISR_METHOD

◆ REGISTER_MULTI_HCSR04_PCI_ISR_FUNCTION

◆ REGISTER_MULTI_HCSR04_RTT_TIMEOUT_METHOD

◆ REGISTER_MULTI_HCSR04_RTT_TIMEOUT_FUNCTION

◆ REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_METHOD

◆ REGISTER_MULTI_HCSR04_RTT_TIMEOUT_TRIGGER_FUNCTION

◆ DECL_SONAR_ISR_HANDLERS_FRIEND