旋转编码器

fastbee大约 3 分钟

旋转编码器

功能说明

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

支持的外设类型

类型	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：进入外设管理页面

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

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

点击 新增外设 按钮

填写配置：

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

点击保存

步骤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界面配置步骤

创建编码器计数控制规则

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

创建编码器按键事件规则

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

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

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
  }
}

注意事项

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