蜂信物联

简体中文

English

简体中文

English

主题

传感器读取动作 ​

本页按当前源码说明行为：读取失败保留在底层的旧缓存不算新测量；动作仅发布质量有效且未超过时限的样本。缓存与页面保留原采样年龄和已记录单位，卡片重绘不会延长有效期，到期显示失效。DS18B20切换探头、电压/NTC校准变化会清旧缓存。启动内单调毫秒不是UTC时间，重启前后不能直接比较；这些软件保护不代表传感器校准或实物验收通过。

动作类型 ​

动作actionType说明
ACTION_SENSOR_READ19读取传感器数据

概述 ​

传感器读取动作触发指定传感器外设进行一次数据采集。采集结果存入传感器缓存，并在规则 reportAfterExec: true 时通过 MQTT 上报。

目标外设驱动负责采样，动作按物理通道形成缓存键 periphId_channelField，外设执行规则决定是否上报或供后续显示、联动使用。显示模板 ${periphId.channelField} 与 MQTT 物模型字段是不同用途，不能把它们当作同一个标识符。

支持的传感器类型 ​

actionValue.sensorCategory 使用字符串，不使用外设类型或驱动内部的数字枚举。执行时去掉首尾空白并转为小写；每个读取动作选择一个通道。

sensorCategory读取方式通道或数值含义驱动单位
analog已配置模拟输入按外设ADC转换配置返回原始值或工程值动作填写对应单位
digitalGPIO读取电平0/1无默认单位
radar雷达外设存在状态0/1，建议字段 presence无默认单位
rf射频接收外设接收电平0/1，不是信号强度无默认单位
pulse编码器count、delta、direction；其余字段按累计计数读取动作填写计数等单位
frequency编码器rpm 读取转速，其余字段读取频率动作按所选量填写rpm或Hz
dht11、dht22DHT协议temperature 或 humidity°C、%
ds18b20OneWire温度；deviceIndex 选择探头°C
ultrasonic已保存的Trig/Echo引脚距离，建议字段 distancecm
currentADC与灵敏度、零点校准电流，建议字段 currentA
current_loopADC与4–20mA前端校准默认电流；启用工程映射后输出配置范围内的工程值默认mA，映射后填写工程单位
voltageADC与分压比例校准电压，建议字段 voltageV
ntcADC与热敏电阻参数温度，建议字段 temperature°C
SHT30、SHT31、AHT20已注册I2C驱动temperature、humidity°C、%
BH1750已注册I2C驱动illuminancelx
BMP280已注册I2C驱动temperature、pressure、altitude°C、hPa、m
MPU6050已注册I2C驱动mode=0：accelX/Y/Z；mode=1：gyroX/Y/Z；两种模式均有 temperaturem/s²、rad/s、°C
INA226已注册I2C驱动与分流校准voltage、current、powerV、A、W
ADS1115已注册I2C ADC驱动默认 voltage、rawCode；可选扫描为配置选中的 voltage_mux0～voltage_mux7，最多4路默认V、count；扫描V

ADS1115多路读取：同一地址只建一个外设，整轮成功才发布，各通道保留实际采样时间；4路8SPS的配置最小间隔为1200ms。见多路配置与验收边界。

current_loop 也兼容 4-20ma、4_20ma。DHT、DS18B20、超声波、电流、电流环、电压和NTC路径需要固件包含 FASTBEE_ENABLE_SENSOR_DRIVER。I2C路径还要求相应驱动已注册、i2cSensors 功能已启用，外设配置及总线资源有效；表格不表示每块板、每种固件都包含所有驱动，以设备返回的驱动与通道列表为准。

推荐先保存并启用 SENSOR_GENERIC 外设，再在动作中选择“已配置传感器”。执行时以该外设保存的驱动、模式、地址和总线为准，动作中的类别或 driverParams 不会覆盖它。“已配置传感器”是表单选项，保存时会换成实际驱动名，不应手写 sensorCategory: "configured"。

参数说明 ​

字段说明
targetPeriphId目标传感器外设 ID
actionType19
actionValue非空JSON对象字符串，描述下面的读取参数；空串或仅写字段名无法执行

actionValue 内的字段：

字段说明
periphId必须指向已保存并启用的外设；应与动作的 targetPeriphId 一致
sensorCategory上表中的字符串；导入时不应省略，缺省会走 analog
channelField可显式选择实际读取通道，优先于 dataField
dataField显式的MQTT物模型字段；未填写时上报ID回退为外设ID，不自动拼接 periphId.field
sensorLabel本地显示名称
unit记录及上报的单位；为空时使用驱动检测的单位（若有）
scaleFactor、offset数值转换 读数 × scaleFactor + offset，缺省分别为1、0；填写JSON数字
decimalPlaces小数位数，执行端缺省2，最多6
deviceIndexDS18B20探头索引，缺省0
driverParams旧版I2C动作的参数对象或JSON对象字符串；推荐新配置将驱动参数保存到外设

注册驱动未显式填写 channelField 时，会先尝试把 dataField 解释为有效通道；若它只是物模型别名，则使用当前模式的第一个通道。MPU6050接受 accel_x/y/z、gyro_x/y/z 通道别名，并解析为 accelX/Y/Z、gyroX/Y/Z；旧版 driverParams.mode 接受0/1、数字字符串及 accel/gyro。例如BMP280的默认物理通道是温度；物模型字段叫 pressureValue 并不自动选择气压，须显式填写 channelField: "pressure"。

DHT的实际通道只能是 temperature 或 humidity，不能用任意物模型别名代替通道名。若需要自定义上报字段，应同时显式指定 channelField。驱动单位只在动作 unit 为空时补入；手写单位标签不会改变物理量，也不代表已校准。当前表单为DHT和“已配置传感器”同步实际通道单位。

actionValue 推荐格式 ​

DHT11/DHT22动作的 actionValue 同样是下面格式的JSON字符串，不能只写 temperature 或 humidity。使用 sensorCategory=dht11/dht22，温度字段配 °C、湿度字段配 %。新开发候选的表单会自动同步两种固定单位，温控还核对真实通道，单位标签不能改变物理量。

下面读取已配置SHT31外设的温度，并映射到物模型字段 roomTemperature：

json
{
  "periphId": "sht31_i2c",
  "sensorCategory": "SHT31",
  "channelField": "temperature",
  "dataField": "roomTemperature",
  "sensorLabel": "温度",
  "unit": "°C",
  "decimalPlaces": 1,
  "scaleFactor": 1,
  "offset": 0
}

如需兼容绑定到已保存I2C主机总线的旧版动作，可以使用 driverParams: {"address": 68}（SHT31地址0x44）。SDA、SCL和总线频率从目标外设配置解析，不能靠在动作中填写 driverParams.sda/scl 临时接线。旧版动作只接受I2C总线或通用传感器外设作为这一驱动路径的目标。

ADC 电流/电压类传感器可以在同一 JSON 中增加校准参数：

json
{
  "periphId": "current_01",
  "sensorCategory": "current",
  "dataField": "current",
  "sensorLabel": "电流",
  "unit": "A",
  "decimalPlaces": 3,
  "sensitivity": 0.100,
  "zeroOffset": 1.65,
  "vRef": 3.3,
  "adcMax": 4095
}

配置示例 ​

方式1：Web界面配置（推荐） ​

传感器动作配置时重点核对外设ID、传感器类别、实际通道、物模型字段和单位；周期采集间隔在规则触发器中设置，I2C驱动的最小采样间隔还受已保存外设配置约束。

示例1：读取 DHT11 温湿度 ​

场景：读取DHT11传感器的温度和湿度数据

配置步骤：

  1. 在外设执行管理页面编辑规则

  2. 点击 添加动作 按钮

  3. 选择传感器类别 dht11，填写动作配置：

    字段填写内容说明
    动作类型选择 传感器读取读取传感器
    目标外设选择 dht1DHT11外设ID
    数据字段temperature 或 humidity读取的字段
    显示名称温度 或 湿度上报时的名称
    单位℃ 或 %数据单位
    小数位数1保留1位小数

  4. 点击 保存 按钮

一次DHT物理采样可取得温湿度，但每个动作只发布所选通道。需要两项缓存或上报时，分别添加温度、湿度两个读取动作。

示例2：读取超声波距离 ​

场景：读取HC-SR04超声波传感器的距离数据

配置步骤：

  1. 编辑规则，添加动作

  2. 填写：

    • 动作类型：选择 传感器读取
    • 传感器类别：选择 ultrasonic
    • 目标外设：选择 ultrasonic1
    • 数据字段：distance
    • 显示名称：距离
    • 单位：cm
    • 小数位数：1

  3. 点击 保存

示例3：读取电流传感器（带校准） ​

场景：读取ACS712电流传感器数据

配置步骤：

  1. 编辑规则，添加动作

  2. 填写：

    • 动作类型：选择 传感器读取
    • 传感器类别：选择 current
    • 目标外设：选择 current_sensor
    • 数据字段：current
    • 显示名称：电流
    • 单位：A
    • 小数位数：3
    • 灵敏度：0.100（根据模块填写）
    • 零点偏移：1.65（VCC/2）
    • 参考电压：3.3
    • ADC最大值：4095（ESP32为12位）

  3. 点击 保存

💡 提示：电流/电压传感器需要校准参数才能准确转换

方式2：JSON配置文件导入 ​

可参考下方完整规则。先保存对应外设，并将每个动作的读取参数序列化为 actionValue 字符串；示例规则保持停用，核对物模型字段、接线与采样周期后再启用。

数据上报格式 ​

上报ID优先取显式 dataField，否则取 periphId。例如两个DHT动作分别配置 dataField: "temperature"、dataField: "humidity" 时，上报核心字段如下（省略 remark 和 sample 元数据）：

json
[
  {"id": "temperature", "value": "25.6"},
  {"id": "humidity", "value": "65.2"}
]

实际传感器上报结果还携带 remark 和 sample，记录单位、采样质量、启动内单调采样时间及最大年龄；接收时的新鲜度标为未验证，不能把MQTT接收时间当成采样时间。读取失败的结果保留失败原因，值为空，不把旧缓存当作当前读数。配置了 reportAfterExec 也不等于平台已收到，仍受MQTT功能、实例及发送队列状态约束。

传感器缓存 ​

成功发布的数据存入传感器缓存（SensorReadCache），键为 periphId_实际通道。例如 dht1_temperature 可用显示模板 ${dht1.temperature} 引用，${dht1.temperature.unit} 读取单位。数据源选择器中可能显示带 ds: 前缀的引用；它也不是MQTT物模型字段。

DS18B20、NTC等单值路径没有显式通道或数据字段时，缓存后缀沿用外设ID，例如 probe1_probe1；它们不会自动改为 probe1_temperature。表单通常会显式保存温度字段，导入规则应核对实际缓存键。注册I2C驱动则使用解析后的物理通道名；不同物模型别名可能仍对应同一个缓存键。

完整规则示例 ​

定时采集并上报 ​

json
{
  "id": "exec_sensor_poll",
  "name": "定时采集传感器",
  "enabled": false,
  "execMode": 0,
  "triggers": [
    {
      "triggerType": 1,
      "triggerPeriphId": "",
      "operatorType": 0,
      "compareValue": "",
      "timerMode": 0,
      "intervalSec": 60,
      "timePoint": "",
      "eventId": "",
      "pollResponseTimeout": 1000,
      "pollMaxRetries": 2,
      "pollInterPollDelay": 100
    }
  ],
  "actions": [
    {
      "targetPeriphId": "dht1",
      "actionType": 19,
      "actionValue": "{\"periphId\":\"dht1\",\"sensorCategory\":\"dht11\",\"dataField\":\"temperature\",\"sensorLabel\":\"温度\",\"unit\":\"°C\",\"decimalPlaces\":1}",
      "useReceivedValue": false,
      "syncDelayMs": 0,
      "execMode": 0
    },
    {
      "targetPeriphId": "dht1",
      "actionType": 19,
      "actionValue": "{\"periphId\":\"dht1\",\"sensorCategory\":\"dht11\",\"dataField\":\"humidity\",\"sensorLabel\":\"湿度\",\"unit\":\"%\",\"decimalPlaces\":1}",
      "useReceivedValue": false,
      "syncDelayMs": 0,
      "execMode": 0
    },
    {
      "targetPeriphId": "ultrasonic1",
      "actionType": 19,
      "actionValue": "{\"periphId\":\"ultrasonic1\",\"sensorCategory\":\"ultrasonic\",\"dataField\":\"distance\",\"sensorLabel\":\"距离\",\"unit\":\"cm\",\"decimalPlaces\":1}",
      "useReceivedValue": false,
      "syncDelayMs": 200,
      "execMode": 0
    }
  ],
  "protocolType": 0,
  "scriptContent": "",
  "reportAfterExec": true
}

注意事项 ​

将数值保存到SD ​

使用独立的“SD持续数值记录”动作40规则引用本页传感器读取规则产生的来源。生产来源须唯一、启用并勾选数值历史；记录器自身禁止数值历史和屏幕控制，也不直接发起传感器采样。Web来源目录仅描述已保存配置，不能代表新鲜有效样本。模板默认禁用；保存启用才开始持续记录，手动执行仅查看状态。来源变化或SD故障须检查并明确恢复；文件轮转会覆盖旧记录，SDK写入成功不代表断电持久性。具体步骤见SD卡存储。

  1. 采样间隔：专用驱动的最小间隔为DHT 2000ms、DS18B20 1000ms、超声波100ms、电流/电压/电流环/NTC 200ms。analog 通用模拟输入路径不同，不应套用专用ADC驱动的缓存间隔；I2C按设备驱动与外设配置执行。
  2. 缓存机制：可复用的成功缓存保留原采样时间；缓存返回、页面刷新或重新排队均不能把旧值变成新样本。
  3. 错误处理：失败不发布有效新样本。规则通常继续处理其它动作，但截止时间、来源变化或资源不足等条件可终止后续执行。
  4. 单位与标定：模拟量、电流、电压及4–20mA工程映射应按实物接线与标定配置；写入 °C 标签本身不证明温度测量正确。作为温控来源还须满足本地温控规则的准入条件。

蜂信物联 | fastbee.cn

Copyright © 2026-present 曲靖蜂信科技有限公司