电压型传感器配置（分压器 ADC）

fastbee大约 6 分钟

电压型传感器配置（分压器 ADC）

1. 功能说明

电压型传感器通过电阻分压网络将高于 ESP32 ADC 量程（3.3V）的被测电压降低到安全范围，再由 ADC 采集并通过分压比还原实际电压值。

适用场景

电池电压监测（3.7V/7.4V/12V/24V 锂电池）
太阳能板电压检测
电源供电电压监控
工业传感器 0_5V/010V 信号采集

工作原理

Vin ─── R1 ──┬── R2 ─── GND
              │
              └── ADC Pin (Vout)

Vout = Vin × R2 / (R1 + R2)
Vin = Vout × (R1 + R2) / R2 = Vout × ratio
ratio = (R1 + R2) / R2

常用分压比

R1	R2	ratio	最大可测电压 (ADC满量程3.3V)
30KΩ	7.5KΩ	5.0	16.5V
100KΩ	10KΩ	11.0	36.3V
47KΩ	10KΩ	5.7	18.8V
10KΩ	10KΩ	2.0	6.6V

特性

10 次多采样平均，减少 ADC 噪声
200ms 最小读取间隔缓存
惰性初始化，首次调用自动配置 ADC（12位/11dB衰减）
支持自定义分压比和参考电压参数

电压采集属于 ADC 输入，接线前必须确认分压后电压不超过 ESP32 ADC 量程；调试时同时记录原始 ADC 值和换算后的实际电压。

2. 接线说明

被测电压源 (Vin)
    │
    ├── R1 (如 30KΩ)
    │
    ├──────────────── GPIO34 (ESP32 ADC引脚)
    │
    ├── R2 (如 7.5KΩ)
    │
    └── GND ─────── ESP32 GND

注意：
- R1 + R2 组成分压器，Vout = Vin × R2/(R1+R2)
- 确保 Vout ≤ 3.3V，否则会损坏 ESP32
- 推荐在 ADC 引脚和 GND 之间并联 100nF 电容滤波
- 推荐使用 GPIO34/35/36/39（仅输入，ADC精度更好）

商用电压检测模块

常见的 DC 0-25V 电压检测模块已内置分压电路（通常 ratio=5.0）：

电压检测模块             ESP32
┌─────────────┐
│  VCC (+)    │───────── 被测电压正极 (≤25V)
│  GND (-)    │───────── 被测电压负极 + ESP32 GND
│  S (Signal) │───────── GPIO34 (ADC引脚)
└─────────────┘

3. 配置方式

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

电压传感器保存前重点核对 ADC 引脚、分压比例和输入电压上限。

步骤1：进入外设管理页面

打开浏览器访问 ESP32 IP 地址
登录后点击左侧菜单 外设配置

步骤2：添加电压传感器外设

点击 新增外设 按钮

填写配置：

字段	填写内容	说明
外设ID	`voltage_01` 或 `battery_12v`	唯一标识符
名称	`电压检测(0-25V)` 或 `12V电池电压`	显示名称
外设类型	GPIO模拟输入 (type: 15)	ADC采集
引脚配置	`34` 或 `35`	ADC引脚（推荐34-39）
衰减系数	`3`	11dB(0-3.3V)
分辨率	`12`	12位(0-4095)

点击保存

步骤3：验证配置

在外设列表中找到刚添加的外设
点击启用开关
查看实时电压数据

💡 提示：分压比根据实际电阻计算，商用模块通常ratio=5.0

方式2：JSON配置文件导入

{
  "id": "voltage_01",
  "name": "电压检测(0-25V)",
  "type": 15,
  "enabled": false,
  "pinCount": 1,
  "pins": [34, 255, 255, 255, 255, 255, 255, 255],
  "params": {
    "attenuation": 3,
    "resolution": 12,
    "sampleRate": 5
  }
}

12V 电池监测配置

{
  "id": "battery_12v",
  "name": "12V电池电压",
  "type": 15,
  "enabled": false,
  "pinCount": 1,
  "pins": [35, 255, 255, 255, 255, 255, 255, 255],
  "params": {
    "attenuation": 3,
    "resolution": 12,
    "sampleRate": 5
  }
}

4. 外设执行联动

Web界面配置步骤

创建电压采集规则

切换到 外设执行管理 标签
点击 新增规则 按钮
配置定时触发器：
- 触发类型：定时触发
- 执行间隔：30 秒
添加动作：
- 动作类型：传感器读取
- 目标外设：voltage_01
- 数据字段：voltage
- 分压比：5.0（根据实际调整）
开启 执行后上报数据
点击保存

创建电池欠压报警规则

创建新规则
配置事件触发器：
- 触发类型：事件触发
- 事件ID：ds:battery_12v_voltage
- 比较操作：小于
- 比较值：10.5（V）
添加动作：
- 动作1：触发低电量事件
  - 动作类型：触发事件
  - 事件ID：low_battery
- 动作2：关闭负载
  - 动作类型：低电平
  - 目标外设：load_relay
点击保存

💡 提示：12V锂电池欠压保护阈值通常为10.5V

JSON配置示例

电压定时采集规则

{
  "id": "exec_voltage_read",
  "name": "电压定时采集",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 1,
      "timerMode": 0,
      "intervalSec": 30
    }
  ],
  "actions": [
    {
      "targetPeriphId": "voltage_01",
      "actionType": 19,
      "actionValue": "{\"periphId\":\"voltage_01\",\"sensorCategory\":\"voltage\",\"dataField\":\"voltage\",\"sensorLabel\":\"电压\",\"unit\":\"V\",\"decimalPlaces\":2,\"ratio\":5.0,\"vRef\":3.3,\"adcMax\":4095}"
    }
  ],
  "reportAfterExec": true
}

actionValue 格式

电压传感器的 actionValue 使用 JSON 字符串传递读取目标和校准参数：

{
  "periphId": "voltage_01",
  "sensorCategory": "voltage",
  "dataField": "voltage",
  "sensorLabel": "电压",
  "unit": "V",
  "decimalPlaces": 2,
  "ratio": 5.0,
  "vRef": 3.3,
  "adcMax": 4095
}

参数	说明	示例
ratio	分压比 (R1+R2)/R2	5.0 (30K/7.5K)
vRef	ADC参考电压 (V)	3.3
adcMax	ADC最大值	4095

低电压报警规则（电池欠压保护）

{
  "id": "exec_low_voltage",
  "name": "电池欠压报警",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "ds:battery_12v_voltage",
      "operatorType": 3,
      "compareValue": "10.5"
    }
  ],
  "actions": [
    {
      "targetPeriphId": "",
      "actionType": 21,
      "actionValue": "low_battery"
    },
    {
      "targetPeriphId": "load_relay",
      "actionType": 1,
      "actionValue": ""
    }
  ],
  "reportAfterExec": true
}