ADC 模拟输入

GPIO 模拟输入 type 15 和 ADC type 26 用于读取原始计数或按配置转换成工程量。芯片允许输入电压、衰减档测量范围和校准曲线不同；attenuation: 3 不能理解成所有 ESP32 芯片都保证 0～3.3V 的精确量程。

配置

GPIO34 为经典 ESP32 ADC1 示例，不能直接用于 ESP32-C3/C6/S3：

{
  "id": "analog1",
  "name": "模拟输入",
  "type": 15,
  "enabled": false,
  "pinCount": 1,
  "pins": [34],
  "params": {
    "attenuation": 3,
    "resolution": 12,
    "sampleCount": 8,
    "filterMode": 0
  }
}

参数	说明
attenuation	0～3；对应衰减档与有效量程按目标芯片核对
resolution	配置分辨率；不等于测量精度
sampleCount	1～16 次，多采样
filterMode	0=均值、1=中值
sampleRate	保留的配置字段，不创建后台周期采集任务

经典 ESP32 的 ADC2 与 WiFi 存在限制，优先核对 ADC1 引脚；其他芯片按自身 ADC 能力和固件资源检查处理，不把经典 ESP32 引脚表推广到 C3/C6/S3。前端分压、分流、输入阻抗、共地及保护均按实际电路核验。

读取规则

保存配置不自动采集。启用外设后建立定时规则，动作 19 的 actionValue 必须包含读取参数，不能留空：

{
  "id": "exec_analog_read",
  "name": "模拟输入定时采集",
  "enabled": false,
  "triggers": [{ "triggerType": 1, "timerMode": 0, "intervalSec": 5 }],
  "actions": [{
    "targetPeriphId": "analog1",
    "actionType": 19,
    "actionValue": "{\"periphId\":\"analog1\",\"sensorCategory\":\"analog\",\"channelField\":\"analog\",\"dataField\":\"analogRaw\",\"decimalPlaces\":0}",
    "useReceivedValue": false
  }],
  "reportAfterExec": true
}

dataField 是平台属性标识；配置适配后查看读取结果和上报。变化事件订阅 ds:analog1_analog，模板使用 ${analog1.analog}；不要用平台触发器代替本地采集变化事件。缓存源与实际通道名称以页面/读取结果为准。

工程量与质量

工业 AI 可通过 signalMode、conversionEnabled、calibratedVoltage、inputMin/inputMax、engineeringMin/engineeringMax 等持久参数完成转换。缺省配置保留原始 ADC 行为；前端参数与工程量范围必须匹配，转换失败、断线或越界的质量不能当作正常零值。

转换字段

选择 0-10V、0-20mA、4-20mA 或自定义线性模式后，Web 会自动启用工程量转换并填入常用输入范围；高级校准项默认折叠，通常只需填写工程量上下限。

字段	默认值	说明
signalMode	0	0=原始值，1=0-10V，2=0-20mA，3=4-20mA，4=自定义线性
conversionEnabled	false	是否输出工程量；关闭时保持原始 ADC 上报
inputMin / inputMax	按信号类型推导	输入信号量程，4-20mA 默认 4/20
engineeringMin / engineeringMax	0/100	传感器铭牌对应的工程量范围
engineeringOffset	0	转换结果的现场校准偏移
clampEnabled	false	越界时钳位；关闭时本次读数无效并停止上报
vRef	3.3	ADC 参考电压
voltageRatio	1	0-10V 前端的分压还原倍数
shuntResistance	165	电流环分流电阻，单位 Ω
inputGain / inputOffset	1/0	模拟前端增益和电压偏移

转换公式为 EU=(INPUT-INPUTmin)/(INPUTmax-INPUTmin)×(EUmax-EUmin)+EUmin+engineeringOffset。4-20mA 模式先按分流电阻和前端增益把 ADC 电压换算为 mA；0-10V 模式先按分压还原倍数换算为输入电压。ESP32 引脚不能直接接 10V 或电流环，必须使用合适的分压、隔离或分流前端。

新增字段向后兼容：旧配置缺少新字段时使用安全默认值，保持原有行为。

采集质量与上报

工程量转换启用后，数值和采集质量分开处理：

quality	qualityCode	含义
valid	0	输入在配置量程内
low	1	输入低于量程，但未达到 4-20mA 断线阈值
high	2	输入高于量程，但未达到 4-20mA 短路/过驱阈值
disconnected	3	4-20mA 输入小于 inputMin - 1mA；标准量程即小于 3mA
short	4	4-20mA 输入大于 inputMax + 1mA；标准量程即大于 21mA
invalid_config	5	信号类型或量程、工程量范围等配置无效

GET /api/peripherals/read?id=<外设ID> 同时返回 rawValue、value、valueValid、quality 和 qualityCode。关闭钳位时，异常读数的 value 为 null 且 valueValid=false；开启钳位时仍保留原异常质量，只把数值限制到工程量端点。周期 MQTT 在转换启用且不是原始值模式时额外上报 <外设ID>_quality 属性，例如 ai_soil_temp_quality=disconnected；异常且未钳位时省略数值属性，但仍上报质量属性。

外设执行中的普通 analog 读取会直接复用外设配置的转换结果，量程和校准参数只维护一份；动作自己的 scaleFactor/offset 仍可用于最终的二次修正。

电压分压及电流传感器的旧读取类别另有动作校准参数，见电压、电流，避免重复转换；NTC 热敏电阻测温见 NTC 热敏电阻。ADC 资源生命周期、采样失败及多消费者行为见 ADC 生命周期。

先保存禁用草稿，完成接线/资源审核，再启用外设、读取、验证质量，最后启用周期规则。校准使用万用表或标准源的实际测量，不能把 raw * 3.3 / 4095 当作实测电压。