Add support for the HRXL MaxSonar WR series sensors (#2020)

CODEOWNERS

@@ -49,6 +49,7 @@ esphome/components/gpio/* @esphome/core
 esphome/components/gps/* @coogle
 esphome/components/havells_solar/* @sourabhjaiswal
 esphome/components/homeassistant/* @OttoWinter
+esphome/components/hrxl_maxsonar_wr/* @netmikey
 esphome/components/i2c/* @esphome/core
 esphome/components/improv/* @jesserockz
 esphome/components/inkbird_ibsth1_mini/* @fkirill

esphome/components/hrxl_maxsonar_wr/hrxl_maxsonar_wr.cpp

@@ -0,0 +1,66 @@
+// Official Datasheet:
+//   https://www.maxbotix.com/documents/HRXL-MaxSonar-WR_Datasheet.pdf
+//
+// This implementation is designed to work with the TTL Versions of the
+// MaxBotix HRXL MaxSonar WR sensor series. The sensor's TTL Pin (5) should be
+// wired to one of the ESP's input pins and configured as uart rx_pin.
+
+#include "hrxl_maxsonar_wr.h"
+#include "esphome/core/log.h"
+
+namespace esphome {
+namespace hrxl_maxsonar_wr {
+
+static const char *const TAG = "hrxl.maxsonar.wr.sensor";
+static const uint8_t ASCII_CR = 0x0D;
+static const uint8_t ASCII_NBSP = 0xFF;
+static const int MAX_DATA_LENGTH_BYTES = 6;
+
+/**
+ * The sensor outputs something like "R1234\r" at a fixed rate of 6 Hz. Where
+ * 1234 means a distance of 1,234 m.
+ */
+void HrxlMaxsonarWrComponent::loop() {
+  uint8_t data;
+  while (this->available() > 0) {
+    if (this->read_byte(&data)) {
+      buffer_ += (char) data;
+      this->check_buffer_();
+    }
+  }
+}
+
+void HrxlMaxsonarWrComponent::check_buffer_() {
+  // The sensor seems to inject a rogue ASCII 255 byte from time to time. Get rid of that.
+  if (this->buffer_.back() == static_cast<char>(ASCII_NBSP)) {
+    this->buffer_.pop_back();
+    return;
+  }
+
+  // Stop reading at ASCII_CR. Also prevent the buffer from growing
+  // indefinitely if no ASCII_CR is received after MAX_DATA_LENGTH_BYTES.
+  if (this->buffer_.back() == static_cast<char>(ASCII_CR) || this->buffer_.length() >= MAX_DATA_LENGTH_BYTES) {
+    ESP_LOGV(TAG, "Read from serial: %s", this->buffer_.c_str());
+
+    if (this->buffer_.length() == MAX_DATA_LENGTH_BYTES && this->buffer_[0] == 'R' &&
+        this->buffer_.back() == static_cast<char>(ASCII_CR)) {
+      int millimeters = strtol(this->buffer_.substr(1, MAX_DATA_LENGTH_BYTES - 2).c_str(), nullptr, 10);
+      float meters = float(millimeters) / 1000.0;
+      ESP_LOGV(TAG, "Distance from sensor: %d mm, %f m", millimeters, meters);
+      this->publish_state(meters);
+    } else {
+      ESP_LOGW(TAG, "Invalid data read from sensor: %s", this->buffer_.c_str());
+    }
+    this->buffer_.clear();
+  }
+}
+
+void HrxlMaxsonarWrComponent::dump_config() {
+  ESP_LOGCONFIG(TAG, "HRXL MaxSonar WR Sensor:");
+  LOG_SENSOR("  ", "Distance", this);
+  // As specified in the sensor's data sheet
+  this->check_uart_settings(9600, 1, esphome::uart::UART_CONFIG_PARITY_NONE, 8);
+}
+
+}  // namespace hrxl_maxsonar_wr
+}  // namespace esphome

esphome/components/hrxl_maxsonar_wr/hrxl_maxsonar_wr.h

@@ -0,0 +1,25 @@
+#pragma once
+
+#include "esphome/core/component.h"
+#include "esphome/components/sensor/sensor.h"
+#include "esphome/components/uart/uart.h"
+
+namespace esphome {
+namespace hrxl_maxsonar_wr {
+
+class HrxlMaxsonarWrComponent : public sensor::Sensor, public Component, public uart::UARTDevice {
+ public:
+  // Nothing really public.
+
+  // ========== INTERNAL METHODS ==========
+  void loop() override;
+  void dump_config() override;
+
+ protected:
+  void check_buffer_();
+
+  std::string buffer_;
+};
+
+}  // namespace hrxl_maxsonar_wr
+}  // namespace esphome

esphome/components/hrxl_maxsonar_wr/sensor.py

@@ -0,0 +1,41 @@
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome.components import sensor, uart
+from esphome.const import (
+    CONF_ID,
+    DEVICE_CLASS_EMPTY,
+    STATE_CLASS_MEASUREMENT,
+    UNIT_METER,
+    ICON_ARROW_EXPAND_VERTICAL,
+)
+
+CODEOWNERS = ["@netmikey"]
+DEPENDENCIES = ["uart"]
+
+hrxlmaxsonarwr_ns = cg.esphome_ns.namespace("hrxl_maxsonar_wr")
+HrxlMaxsonarWrComponent = hrxlmaxsonarwr_ns.class_(
+    "HrxlMaxsonarWrComponent", sensor.Sensor, cg.Component, uart.UARTDevice
+)
+
+CONFIG_SCHEMA = (
+    sensor.sensor_schema(
+        UNIT_METER,
+        ICON_ARROW_EXPAND_VERTICAL,
+        3,
+        DEVICE_CLASS_EMPTY,
+        STATE_CLASS_MEASUREMENT,
+    )
+    .extend(
+        {
+            cv.GenerateID(): cv.declare_id(HrxlMaxsonarWrComponent),
+        }
+    )
+    .extend(uart.UART_DEVICE_SCHEMA)
+)
+
+
+async def to_code(config):
+    var = cg.new_Pvariable(config[CONF_ID])
+    await cg.register_component(var, config)
+    await sensor.register_sensor(var, config)
+    await uart.register_uart_device(var, config)

tests/test4.yaml

@@ -63,6 +63,15 @@ sensor:
   - platform: tuya
     id: tuya_sensor
     sensor_datapoint: 1
+  - platform: "hrxl_maxsonar_wr"
+    name: "Rainwater Tank Level"
+    filters:
+      - sliding_window_moving_average:
+          window_size: 12
+          send_every: 12
+      - or:
+        - throttle: "20min"
+        - delta: 0.02
 #
 # platform sensor.apds9960 requires component apds9960
 #