分压电压采集

动作读取类别 voltage 通过 ADC 多采样均值和分压比换算输入电压，单位 V。分压比是动作参数；单独保存模拟输入外设不会自动周期采集。

分压及量程

Vin ── R1 ──┬── R2 ── GND
            └── ADC
ratio = (R1 + R2) / R2
Vin = averageRaw * vRef / adcMax * ratio

ADC 允许输入及有效测量范围按芯片、衰减和校准条件确认，不能统一以 3.3V 作为精确满量程。“0～25V 模块”若分压比为 5，在输入 25V 时输出 5V，不能直接连接 ESP32 ADC。应按最坏输入、供电波动和前端保护选择电阻、滤波及安全余量。

分压仅适用于具有安全共地条件的直流电压，市电或高压测量使用适用的隔离测量方案。GPIO34～39 是经典 ESP32 的部分 ADC 引脚，不是跨芯片通用推荐。

配置与采集

{
  "id": "voltage1",
  "name": "分压电压",
  "type": 15,
  "enabled": false,
  "pinCount": 1,
  "pins": [34],
  "params": { "attenuation": 3, "resolution": 12 }
}

检查前端和资源后单独启用外设，然后建立读取规则：

{
  "id": "exec_voltage_read",
  "name": "电压采集",
  "enabled": false,
  "triggers": [{ "triggerType": 1, "timerMode": 0, "intervalSec": 30 }],
  "actions": [{
    "targetPeriphId": "voltage1",
    "actionType": 19,
    "actionValue": "{\"periphId\":\"voltage1\",\"sensorCategory\":\"voltage\",\"channelField\":\"voltage\",\"dataField\":\"batteryVoltage\",\"ratio\":5,\"vRef\":3.3,\"adcMax\":4095,\"decimalPlaces\":2}",
    "useReceivedValue": false
  }],
  "reportAfterExec": true
}

ratio: 5 和 vRef: 3.3 仅为参数示例，不能据此证明输入上限和测量精度。驱动采用 10 次采样均值，最小缓存间隔为 200ms；规则间隔另行配置。

变化事件为 ds:voltage1_voltage，模板为 ${voltage1.voltage}；平台属性名由 dataField 指定。欠压阈值根据电池化学体系、串数、负载及厂家要求制定，10.5V 不能作为所有“12V 锂电池”的通用阈值。

若发射欠压事件，动作 21 的目标应为已配置的事件 ID，例如 low_battery，数据描述本次欠压；不要把目标留空，见 设备事件。切断负载时核对继电器的实际有效电平与触点。

校准与失败

用万用表同时测量实际 Vin 和 ADC 输入 Vout，确认实际电阻比及多个测试点。软件公式 raw * 3.3 / 4095 是估算，不是“实测 Vout”。经典 ADC 非线性不能仅靠调整一个分压比在全量程完全消除；精度要求较高时使用当前工业 AI 校准或合适的外部 ADC。

检查原始计数、转换值、采样时间及失败状态，满量程截顶、接线断开和无效配置不视为正常零值。ADC 生命周期见 ADC 输入及ADC 生命周期。