Ultrasonic Sensor

Example Usage

// Basic
App.make_ultrasonic("Ultrasonic", 12, 13); // trigger pin: 12, echo pin: 13
// Filter out timeouts
auto ultrasonic = App.make_ultrasonic("Ultrasonic", 12, 13);
ultrasonic.mqtt->set_filters({
    new sensor::FilterOutNANFilter(), // filter out timeouts
});
// Set timeout, 4 meters
ultrasonic.sensor->set_timeout_m(4.0f);

See Application::make_ultrasonic_sensor().

API Reference

class UltrasonicSensorComponent : public sensor::PollingSensorComponent

This sensor component allows you to use your ultrasonic distance sensors.

Instances of this component periodically send out a short pulse to an ultrasonic sensor, thus creating an ultrasonic sound, and check how long it takes until an “echo” comes back. With this we can measure the distance to an object.

Sometimes it can happen that we send a short ultrasonic pulse, but never hear the echo. In order to not wait for that signal indefinitely, this component has an additional parameter that allows setting a timeout is microseconds (or meters). If this timeout is reached, the sensor reports a “nan” (not a number) float value. The timeout defaults to 11662µs or 2m.

Usually these would be like HC-SR04 ultrasonic sensors: one trigger pin for sending the signal and another one echo pin for receiving the signal. Be very careful with that sensor though: it’s made for 5v VCC and doesn’t work very well with the ESP’s 3.3V, so you need to create a voltage divider in order to not damage your ESP.

Note: The MQTTSenorComponent will create a moving average over these values by default, to disable this behavior, call ultrasonic->mqtt->clear_filters() or similar like above.

Public Functions

UltrasonicSensorComponent(const std::string &name, GPIOPin *trigger_pin, GPIOPin *echo_pin, uint32_t update_interval = 5000)

Construct the ultrasonic sensor with the specified trigger pin and echo pin.

Parameters
  • trigger_pin: The trigger pin where pulses are sent to.
  • echo_pin: The echo pin where the echo is listened for.
  • update_interval: The interval in ms the sensor should check for new values.

void set_timeout_us(uint32_t timeout_us)

Set the timeout for waiting for the echo in µs.

void set_timeout_m(float timeout_m)

Set the timeout for waiting for the echo in meter.

float get_timeout_m() const

Get the timeout in meters for waiting for the echo.

uint32_t get_timeout_us() const

Get the timeout in µs for waiting for the echo.

void setup()

Set up pins and register interval.

void dump_config()
void update()
std::string unit_of_measurement()

Override this to set the Home Assistant unit of measurement for this sensor.

Return “” to disable this feature.

Return
The icon of this sensor, for example “°C”.

std::string icon()

Override this to set the Home Assistant icon for this sensor.

Return “” to disable this feature.

Return
The icon of this sensor, for example “mdi:battery”.

int8_t accuracy_decimals()

Return the accuracy in decimals for this sensor.

float get_setup_priority() const

Hardware setup priority, before MQTT and WiFi.

void set_pulse_time_us(uint32_t pulse_time_us)

Set the time in µs the trigger pin should be enabled for in µs, defaults to 10µs (for HC-SR04)

uint32_t get_pulse_time_us() const

Return the time in µs the trigger pin should be enabled for.

Protected Attributes

GPIOPin *trigger_pin_
GPIOPin *echo_pin_
uint32_t timeout_us_ = {11662}
uint32_t pulse_time_us_ = {10}

2 meters.

Protected Static Functions

float us_to_m(uint32_t us)

Helper function to convert the specified echo duration in µs to meters.

uint32_t m_to_us(float m)

Helper function to convert the specified distance in meters to the echo duration in µs.