HC-SR04 超声测距

通用传感器 type 38 使用 sensorType: 3，引脚顺序为 Trig、Echo。读取动作类别为 ultrasonic，通道为 distance，单位 cm。

接线与配置

按模块额定供电连接 VCC/GND，Trig 接输出 GPIO，Echo 接输入 GPIO。5V Echo 必须经过适当电平转换或分压后连接 MCU；不能把 GPIO 电压保护与传感器供电混为一谈。GPIO4/27 仅为经典 ESP32 接线示例。

json

{
  "id": "ultrasonic1",
  "name": "超声测距",
  "type": 38,
  "enabled": false,
  "pinCount": 2,
  "pins": [4, 27],
  "params": { "sensorType": 3, "sampleInterval": 1000 }
}

params: {} 会保留默认传感器类型，不能代替超声配置。先禁用保存，完成电平、引脚和资源检查后启用；配置本身不创建自动采集任务。

采集规则

json

{
  "id": "exec_distance_read",
  "name": "距离采集",
  "enabled": false,
  "triggers": [{ "triggerType": 1, "timerMode": 0, "intervalSec": 5 }],
  "actions": [{
    "targetPeriphId": "ultrasonic1",
    "actionType": 19,
    "actionValue": "{\"periphId\":\"ultrasonic1\",\"sensorCategory\":\"ultrasonic\",\"channelField\":\"distance\",\"dataField\":\"distance\",\"decimalPlaces\":1}",
    "useReceivedValue": false
  }],
  "reportAfterExec": true
}

当前底层测距具有 100ms 最小读取缓存间隔、30ms 回波超时及 2～400cm 范围检查。距离按固定声速系数换算，没有自动温度补偿。旧缓存可能在故障时保留，但失败/过期质量不能作为本次成功读数进入规则。

订阅 ds:ultrasonic1_distance 可比较距离；模板使用 ${ultrasonic1.distance}。发射障碍物事件时，动作 21 填 targetPeriphId: "obstacle_detected" 并为该 ID 创建事件定义，见设备事件。

现场验证

检查 Trig/Echo 是否接反、电平转换、盲区、目标反射面及回波超时。多个超声模块错开测量，避免串扰；加密采样不能解决无回波。水位场景给满位液面保留盲区和机械余量，泡沫、斜面及容器边缘可能造成错误回波，泵的安全停机不能只依赖本页示例。

HC-SR04 超声测距 ​

接线与配置 ​

采集规则 ​

现场验证 ​

HC-SR04 超声测距

接线与配置

采集规则

现场验证