AB 相旋转编码器

外设 type 43 使用 GPIO ISR 采集 AB 相，当前没有 PCNT 或轮询回退。A 相电平变化中断结合 B 相判断方向，计数、边沿频率及转速都是软件估算，不是机械位置反馈保证。

配置与接线

示例适用于核对后的经典 ESP32 板卡；按具体模块确认供电、AB 上拉和电平：

{
  "id": "encoder1",
  "name": "旋转编码器",
  "type": 43,
  "enabled": false,
  "pinCount": 2,
  "pins": [32, 33],
  "params": { "resolution": 20, "useInterrupt": true }
}

pins[0] 为 A，pins[1] 为 B，必须不同且通过资源检查。resolution 是按当前边沿计数方式标定的每转脉冲数，不能直接假设等于模块印刷标称。按压 SW 作为另一 GPIO 输入外设配置；不存在自动占用第三脚的按压输入。

先禁用保存，核对接线，再启用并检查正反转、计数符号及一次整圈计数。机械抖动、最高脉冲频率、长线及多实例必须实测。

读数与规则

读数	含义
count	64 位累计计数，边界饱和
delta	自上一次完整读取后的增量，读取时清零
direction	最近方向
frequencyHz	最近有效边沿间隔估算，超时降为 0
rpm	frequencyHz × 60 / resolution

动作 19 类别 pulse 读取 count/delta/direction；类别 frequency 读取频率或 rpm。单独读取引脚电平不等同于读取累计计数。

{
  "targetPeriphId": "encoder1",
  "actionType": 19,
  "actionValue": "{\"periphId\":\"encoder1\",\"sensorCategory\":\"pulse\",\"channelField\":\"count\",\"dataField\":\"encoderCount\",\"decimalPlaces\":0}",
  "useReceivedValue": false
}

在定时规则中使用上面动作才产生周期读数和可配置上报；事件来源为 ds:encoder1_count。平台触发器响应云端消息，不能把本地 count 上报当作自动返回的平台控制消息。多个读取者会共同消费 delta，依赖增量时应安排单一采集者，再分发缓存结果。

生命周期与验证边界

最多四个固定 ISR 槽，清理失败的槽继续占用容量。配置、IRQ 附加或释放失败会保留故障/清理记录；故障期间不能把计数快照当作可信读数。旧 ISR 令牌不会沿用到新代次，重复健康初始化不清空计数。复位计数不代表物理回零。

真实生产入口的主机回归见 test/unit/test_encoder_checked_lifecycle.py，涵盖受检初始化、ISR、读取/复位与故障清理。用例存在不表示本次已运行通过；实际中断上限、机械抖动、方向、并发采集、MQTT 联动与长期运行仍须对应硬件验收。