Add: Seeed Studio MR60BHA2 mmWave Sensor (#7589)

Co-authored-by: Spencer Yan <spencer@spenyan.com>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

CODEOWNERS

@@ -355,6 +355,7 @@ esphome/components/sdl/* @clydebarrow
 esphome/components/sdm_meter/* @jesserockz @polyfaces
 esphome/components/sdp3x/* @Azimath
 esphome/components/seeed_mr24hpc1/* @limengdu
+esphome/components/seeed_mr60bha2/* @limengdu
 esphome/components/seeed_mr60fda2/* @limengdu
 esphome/components/selec_meter/* @sourabhjaiswal
 esphome/components/select/* @esphome/core

esphome/components/seeed_mr60bha2/__init__.py

@@ -0,0 +1,41 @@
+import esphome.codegen as cg
+from esphome.components import uart
+import esphome.config_validation as cv
+from esphome.const import CONF_ID
+
+CODEOWNERS = ["@limengdu"]
+DEPENDENCIES = ["uart"]
+MULTI_CONF = True
+
+mr60bha2_ns = cg.esphome_ns.namespace("seeed_mr60bha2")
+
+MR60BHA2Component = mr60bha2_ns.class_(
+    "MR60BHA2Component", cg.Component, uart.UARTDevice
+)
+
+CONF_MR60BHA2_ID = "mr60bha2_id"
+
+CONFIG_SCHEMA = (
+    cv.Schema(
+        {
+            cv.GenerateID(): cv.declare_id(MR60BHA2Component),
+        }
+    )
+    .extend(uart.UART_DEVICE_SCHEMA)
+    .extend(cv.COMPONENT_SCHEMA)
+)
+
+FINAL_VALIDATE_SCHEMA = uart.final_validate_device_schema(
+    "seeed_mr60bha2",
+    require_tx=True,
+    require_rx=True,
+    baud_rate=115200,
+    parity="NONE",
+    stop_bits=1,
+)
+
+
+async def to_code(config):
+    var = cg.new_Pvariable(config[CONF_ID])
+    await cg.register_component(var, config)
+    await uart.register_uart_device(var, config)

esphome/components/seeed_mr60bha2/seeed_mr60bha2.cpp

@@ -0,0 +1,173 @@
+#include "seeed_mr60bha2.h"
+#include "esphome/core/log.h"
+
+#include <utility>
+
+namespace esphome {
+namespace seeed_mr60bha2 {
+
+static const char *const TAG = "seeed_mr60bha2";
+
+// Prints the component's configuration data. dump_config() prints all of the component's configuration
+// items in an easy-to-read format, including the configuration key-value pairs.
+void MR60BHA2Component::dump_config() {
+  ESP_LOGCONFIG(TAG, "MR60BHA2:");
+#ifdef USE_SENSOR
+  LOG_SENSOR(" ", "Breath Rate Sensor", this->breath_rate_sensor_);
+  LOG_SENSOR(" ", "Heart Rate Sensor", this->heart_rate_sensor_);
+  LOG_SENSOR(" ", "Distance Sensor", this->distance_sensor_);
+#endif
+}
+
+// main loop
+void MR60BHA2Component::loop() {
+  uint8_t byte;
+
+  // Is there data on the serial port
+  while (this->available()) {
+    this->read_byte(&byte);
+    this->rx_message_.push_back(byte);
+    if (!this->validate_message_()) {
+      this->rx_message_.clear();
+    }
+  }
+}
+
+/**
+ * @brief Calculate the checksum for a byte array.
+ *
+ * This function calculates the checksum for the provided byte array using an
+ * XOR-based checksum algorithm.
+ *
+ * @param data The byte array to calculate the checksum for.
+ * @param len The length of the byte array.
+ * @return The calculated checksum.
+ */
+static uint8_t calculate_checksum(const uint8_t *data, size_t len) {
+  uint8_t checksum = 0;
+  for (size_t i = 0; i < len; i++) {
+    checksum ^= data[i];
+  }
+  checksum = ~checksum;
+  return checksum;
+}
+
+/**
+ * @brief Validate the checksum of a byte array.
+ *
+ * This function validates the checksum of the provided byte array by comparing
+ * it to the expected checksum.
+ *
+ * @param data The byte array to validate.
+ * @param len The length of the byte array.
+ * @param expected_checksum The expected checksum.
+ * @return True if the checksum is valid, false otherwise.
+ */
+static bool validate_checksum(const uint8_t *data, size_t len, uint8_t expected_checksum) {
+  return calculate_checksum(data, len) == expected_checksum;
+}
+
+bool MR60BHA2Component::validate_message_() {
+  size_t at = this->rx_message_.size() - 1;
+  auto *data = &this->rx_message_[0];
+  uint8_t new_byte = data[at];
+
+  if (at == 0) {
+    return new_byte == FRAME_HEADER_BUFFER;
+  }
+
+  if (at <= 2) {
+    return true;
+  }
+  uint16_t frame_id = encode_uint16(data[1], data[2]);
+
+  if (at <= 4) {
+    return true;
+  }
+
+  uint16_t length = encode_uint16(data[3], data[4]);
+
+  if (at <= 6) {
+    return true;
+  }
+
+  uint16_t frame_type = encode_uint16(data[5], data[6]);
+
+  if (frame_type != BREATH_RATE_TYPE_BUFFER && frame_type != HEART_RATE_TYPE_BUFFER &&
+      frame_type != DISTANCE_TYPE_BUFFER) {
+    return false;
+  }
+
+  uint8_t header_checksum = new_byte;
+
+  if (at == 7) {
+    if (!validate_checksum(data, 7, header_checksum)) {
+      ESP_LOGE(TAG, "HEAD_CKSUM_FRAME ERROR: 0x%02x", header_checksum);
+      ESP_LOGV(TAG, "GET FRAME: %s", format_hex_pretty(data, 8).c_str());
+      return false;
+    }
+    return true;
+  }
+
+  // Wait until all data is read
+  if (at - 8 < length) {
+    return true;
+  }
+
+  uint8_t data_checksum = new_byte;
+  if (at == 8 + length) {
+    if (!validate_checksum(data + 8, length, data_checksum)) {
+      ESP_LOGE(TAG, "DATA_CKSUM_FRAME ERROR: 0x%02x", data_checksum);
+      ESP_LOGV(TAG, "GET FRAME: %s", format_hex_pretty(data, 8 + length).c_str());
+      return false;
+    }
+  }
+
+  const uint8_t *frame_data = data + 8;
+  ESP_LOGV(TAG, "Received Frame: ID: 0x%04x, Type: 0x%04x, Data: [%s] Raw Data: [%s]", frame_id, frame_type,
+           format_hex_pretty(frame_data, length).c_str(), format_hex_pretty(this->rx_message_).c_str());
+  this->process_frame_(frame_id, frame_type, data + 8, length);
+
+  // Return false to reset rx buffer
+  return false;
+}
+
+void MR60BHA2Component::process_frame_(uint16_t frame_id, uint16_t frame_type, const uint8_t *data, size_t length) {
+  switch (frame_type) {
+    case BREATH_RATE_TYPE_BUFFER:
+      if (this->breath_rate_sensor_ != nullptr && length >= 4) {
+        uint32_t current_breath_rate_int = encode_uint32(data[3], data[2], data[1], data[0]);
+        if (current_breath_rate_int != 0) {
+          float breath_rate_float;
+          memcpy(&breath_rate_float, &current_breath_rate_int, sizeof(float));
+          this->breath_rate_sensor_->publish_state(breath_rate_float);
+        }
+      }
+      break;
+    case HEART_RATE_TYPE_BUFFER:
+      if (this->heart_rate_sensor_ != nullptr && length >= 4) {
+        uint32_t current_heart_rate_int = encode_uint32(data[3], data[2], data[1], data[0]);
+        if (current_heart_rate_int != 0) {
+          float heart_rate_float;
+          memcpy(&heart_rate_float, &current_heart_rate_int, sizeof(float));
+          this->heart_rate_sensor_->publish_state(heart_rate_float);
+        }
+      }
+      break;
+    case DISTANCE_TYPE_BUFFER:
+      if (!data[0]) {
+        if (this->distance_sensor_ != nullptr && length >= 8) {
+          uint32_t current_distance_int = encode_uint32(data[7], data[6], data[5], data[4]);
+          float distance_float;
+          memcpy(&distance_float, &current_distance_int, sizeof(float));
+          this->distance_sensor_->publish_state(distance_float);
+        }
+      }
+      break;
+    default:
+      break;
+  }
+}
+
+}  // namespace seeed_mr60bha2
+}  // namespace esphome

esphome/components/seeed_mr60bha2/seeed_mr60bha2.h

@@ -0,0 +1,61 @@
+#pragma once
+#include "esphome/core/component.h"
+#include "esphome/core/defines.h"
+#ifdef USE_SENSOR
+#include "esphome/components/sensor/sensor.h"
+#endif
+#include "esphome/components/uart/uart.h"
+#include "esphome/core/automation.h"
+#include "esphome/core/helpers.h"
+
+#include <map>
+
+namespace esphome {
+namespace seeed_mr60bha2 {
+
+static const uint8_t DATA_BUF_MAX_SIZE = 12;
+static const uint8_t FRAME_BUF_MAX_SIZE = 21;
+static const uint8_t LEN_TO_HEAD_CKSUM = 8;
+static const uint8_t LEN_TO_DATA_FRAME = 9;
+
+static const uint8_t FRAME_HEADER_BUFFER = 0x01;
+static const uint16_t BREATH_RATE_TYPE_BUFFER = 0x0A14;
+static const uint16_t HEART_RATE_TYPE_BUFFER = 0x0A15;
+static const uint16_t DISTANCE_TYPE_BUFFER = 0x0A16;
+
+enum FrameLocation {
+  LOCATE_FRAME_HEADER,
+  LOCATE_ID_FRAME1,
+  LOCATE_ID_FRAME2,
+  LOCATE_LENGTH_FRAME_H,
+  LOCATE_LENGTH_FRAME_L,
+  LOCATE_TYPE_FRAME1,
+  LOCATE_TYPE_FRAME2,
+  LOCATE_HEAD_CKSUM_FRAME,  // Header checksum: [from the first byte to the previous byte of the HEAD_CKSUM bit]
+  LOCATE_DATA_FRAME,
+  LOCATE_DATA_CKSUM_FRAME,  // Data checksum: [from the first to the previous byte of the DATA_CKSUM bit]
+  LOCATE_PROCESS_FRAME,
+};
+
+class MR60BHA2Component : public Component,
+                          public uart::UARTDevice {  // The class name must be the name defined by text_sensor.py
+#ifdef USE_SENSOR
+  SUB_SENSOR(breath_rate);
+  SUB_SENSOR(heart_rate);
+  SUB_SENSOR(distance);
+#endif
+
+ public:
+  float get_setup_priority() const override { return esphome::setup_priority::LATE; }
+  void dump_config() override;
+  void loop() override;
+
+ protected:
+  bool validate_message_();
+  void process_frame_(uint16_t frame_id, uint16_t frame_type, const uint8_t *data, size_t length);
+
+  std::vector<uint8_t> rx_message_;
+};
+
+}  // namespace seeed_mr60bha2
+}  // namespace esphome

esphome/components/seeed_mr60bha2/sensor.py

@@ -0,0 +1,57 @@
+import esphome.codegen as cg
+from esphome.components import sensor
+import esphome.config_validation as cv
+from esphome.const import (
+    CONF_DISTANCE,
+    DEVICE_CLASS_DISTANCE,
+    ICON_HEART_PULSE,
+    ICON_PULSE,
+    ICON_SIGNAL,
+    STATE_CLASS_MEASUREMENT,
+    UNIT_BEATS_PER_MINUTE,
+    UNIT_CENTIMETER,
+)
+
+from . import CONF_MR60BHA2_ID, MR60BHA2Component
+
+DEPENDENCIES = ["seeed_mr60bha2"]
+
+CONF_BREATH_RATE = "breath_rate"
+CONF_HEART_RATE = "heart_rate"
+
+CONFIG_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(CONF_MR60BHA2_ID): cv.use_id(MR60BHA2Component),
+        cv.Optional(CONF_BREATH_RATE): sensor.sensor_schema(
+            accuracy_decimals=2,
+            state_class=STATE_CLASS_MEASUREMENT,
+            icon=ICON_PULSE,
+        ),
+        cv.Optional(CONF_HEART_RATE): sensor.sensor_schema(
+            accuracy_decimals=0,
+            icon=ICON_HEART_PULSE,
+            state_class=STATE_CLASS_MEASUREMENT,
+            unit_of_measurement=UNIT_BEATS_PER_MINUTE,
+        ),
+        cv.Optional(CONF_DISTANCE): sensor.sensor_schema(
+            device_class=DEVICE_CLASS_DISTANCE,
+            state_class=STATE_CLASS_MEASUREMENT,
+            unit_of_measurement=UNIT_CENTIMETER,
+            accuracy_decimals=2,
+            icon=ICON_SIGNAL,
+        ),
+    }
+)
+
+
+async def to_code(config):
+    mr60bha2_component = await cg.get_variable(config[CONF_MR60BHA2_ID])
+    if breath_rate_config := config.get(CONF_BREATH_RATE):
+        sens = await sensor.new_sensor(breath_rate_config)
+        cg.add(mr60bha2_component.set_breath_rate_sensor(sens))
+    if heart_rate_config := config.get(CONF_HEART_RATE):
+        sens = await sensor.new_sensor(heart_rate_config)
+        cg.add(mr60bha2_component.set_heart_rate_sensor(sens))
+    if distance_config := config.get(CONF_DISTANCE):
+        sens = await sensor.new_sensor(distance_config)
+        cg.add(mr60bha2_component.set_distance_sensor(sens))

esphome/const.py

@@ -1001,6 +1001,7 @@ ICON_GRAIN = "mdi:grain"
 ICON_GYROSCOPE_X = "mdi:axis-x-rotate-clockwise"
 ICON_GYROSCOPE_Y = "mdi:axis-y-rotate-clockwise"
 ICON_GYROSCOPE_Z = "mdi:axis-z-rotate-clockwise"
+ICON_HEART_PULSE = "mdi:heart-pulse"
 ICON_HEATING_COIL = "mdi:heating-coil"
 ICON_KEY_PLUS = "mdi:key-plus"
 ICON_LIGHTBULB = "mdi:lightbulb"
@@ -1040,6 +1041,7 @@ ICON_WEATHER_WINDY = "mdi:weather-windy"
 ICON_WIFI = "mdi:wifi"
 
 UNIT_AMPERE = "A"
+UNIT_BEATS_PER_MINUTE = "bpm"
 UNIT_BECQUEREL_PER_CUBIC_METER = "Bq/m³"
 UNIT_BYTES = "B"
 UNIT_CELSIUS = "°C"

tests/components/seeed_mr60bha2/common.yaml

@@ -0,0 +1,19 @@
+uart:
+  - id: seeed_mr60fda2_uart
+    tx_pin: ${uart_tx_pin}
+    rx_pin: ${uart_rx_pin}
+    baud_rate: 115200
+    parity: NONE
+    stop_bits: 1
+
+seeed_mr60bha2:
+  id: my_seeed_mr60bha2
+
+sensor:
+  - platform: seeed_mr60bha2
+    breath_rate:
+      name: "Real-time respiratory rate"
+    heart_rate:
+      name: "Real-time heart rate"
+    distance:
+      name: "Distance to detection object"

tests/components/seeed_mr60bha2/test.esp32-c3-ard.yaml

@@ -0,0 +1,5 @@
+substitutions:
+  uart_tx_pin: GPIO5
+  uart_rx_pin: GPIO4
+
+<<: !include common.yaml

tests/components/seeed_mr60bha2/test.esp32-c3-idf.yaml

@@ -0,0 +1,5 @@
+substitutions:
+  uart_tx_pin: GPIO5
+  uart_rx_pin: GPIO4
+
+<<: !include common.yaml