Rotary Encoder

Synchronized Device Documentation

This page corresponds to the synchronized Chinese source. Commands, JSON examples, API paths, field names, and screenshots are kept aligned with the Chinese device-side source documentation.

What This Page Covers

• Peripheral capability, supported device types, and wiring constraints.
• Web console configuration fields and recommended parameter values.
• PeriphExec integration, validation steps, and troubleshooting notes.

Source Reference

The detailed operational source is preserved below so implementation details stay exact while the English navigation, titles, and reading path remain available.

旋转编码器

功能说明

旋转编码器用于检测旋转方向和角度，支持正转/反转计数和按键功能。适用于音量调节、菜单导航、位置控制等场景。

支持的外设类型

类型	type值	说明
ENCODER	43	旋转编码器（双引脚：A/B相）

硬件接线

编码器引脚	连接	说明
CLK (A)	GPIO	A 相信号
DT (B)	GPIO	B 相信号
SW	GPIO（可选）	按键（单独配置为输入）
VCC	3.3V	电源
GND	GND	地

配置方式

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

旋转编码器保存前重点核对 A/B 相引脚、按键引脚和输入上拉方式。

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

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

步骤2：添加旋转编码器外设

1. 点击 新增外设 按钮

2. 填写配置：

   字段	填写内容	说明
   外设ID	encoder1	唯一标识符
   名称	旋转编码器	显示名称
   外设类型	旋转编码器 (type: 43)	双引脚AB相
   CLK引脚(A)	32	A相信号
   DT引脚(B)	33	B相信号
   每转脉冲数	20	通常20
   使用中断	true	推荐启用

3. 点击 保存

步骤3：验证配置

1. 在外设列表中找到刚添加的外设
2. 点击 启用 开关
3. 旋转编码器，查看计数值变化

💡 提示：编码器按键(SW引脚)需单独配置为GPIO数字输入

---

方式2：JSON配置文件导入

将以下配置添加到 data/config/peripherals.json 的 peripherals 数组中：

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

参数说明

参数	说明
resolution	每转脉冲数（通常 20）
useInterrupt	是否使用中断模式（推荐 true）

pins[0] = CLK(A相) 引脚，pins[1] = DT(B相) 引脚

数据上报格式

编码器计数值通过 MQTT 上报：

[{"id": "encoder1", "value": "42"}]

正转计数递增，反转计数递减。

与外设执行联动

Web界面配置步骤

创建编码器计数控制规则

1. 切换到 外设执行管理 标签
2. 点击 新增规则 按钮
3. 配置平台触发器：
   • 触发类型：平台触发
   • 数据源：encoder1
   • 比较操作：大于
   • 比较值：100
4. 添加动作（如控制电机、调节亮度等）
5. 点击 保存

创建编码器按键事件规则

1. 将编码器SW引脚配置为GPIO数字输入（type: 13）
2. 创建事件触发规则：
   • 触发类型：事件触发
   • 事件源：encoder1_btn
   • 事件类型：button_click
3. 添加动作
4. 点击 保存

💡 提示：推荐使用中断模式，轮询模式可能高速旋转时丢步

---

JSON配置示例

作为平台触发数据源

编码器计数值变化可触发规则：

{
  "triggerType": 0,
  "triggerPeriphId": "encoder1",
  "operatorType": 2,
  "compareValue": "100"
}

编码器按键事件

将编码器 SW 引脚配置为独立的输入外设（PULLUP），即可使用按键事件：

{
  "id": "encoder1_btn",
  "name": "编码器按键",
  "type": 13,
  "enabled": false,
  "pins": [25],
  "params": {
    "initialState": 0,
    "pwmChannel": 0,
    "pwmFrequency": 1000,
    "pwmResolution": 8,
    "defaultDuty": 0
  }
}

注意事项

1. 中断模式：推荐使用中断模式，轮询模式在高速旋转时可能丢步
2. 消抖：机械编码器需要软件消抖，系统已内置处理
3. 引脚选择：建议使用支持中断的 GPIO 引脚
4. 计数溢出：长时间运行注意计数值溢出，必要时定期复位