步进电机

功能说明

当前本地4引脚驱动采用8相半步序列，可设置方向和1～30 RPM目标转速；最短调度间隔为2ms，实际速度受步数及任务调度限制。没有位置反馈或到位确认，不应视为精确定位保证。

2026-10-04 motion候选（尚待集中验证/部署）：启动、方向、调速及stop使用实际普通来源上下文。旧timer先封禁数值token，并核对SDK停止/删除，再逐脚受检释放原IN1～IN4；失败保留剩余脚与错误证据，阻止新owner。来源失效、保持到期或取消会申请同样的清理；“停止后续相位”和“四脚清理被SDK接受”均不证明机械已经停止。

初始化及每次相位核对IDF返回值。部分相位写入失败后不重放、不自动回滚，后续维护只尝试原四脚清理。运行资源快照保留retainedMask/cleanupPending和历史错误，不能由软件登记推断电流、实际转角或物理停止。完整Host、固件构建及设备验收分别登记。

支持的外设类型

类型	type值	说明
STEPPER_MOTOR	42	步进电机（4引脚驱动）

硬件接线

ULN2003 驱动板 + 28BYJ-48 步进电机

驱动板引脚	ESP32 GPIO	说明
IN1	GPIO 32	A 相
IN2	GPIO 33	B 相
IN3	GPIO 25	C 相
IN4	GPIO 26	D 相
VCC	5V	电源（需外部供电）
GND	GND	地

此表为经典ESP32示例，不适用于所有S3/C3/C6或PSRAM板卡；须按实际板型核对保留脚和已有外设，不能直接套用。

步进电机电流较大，建议使用外部 5V 电源，不要直接从 ESP32 取电。

配置方式

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

步进电机保存前重点核对驱动板 IN1-IN4 引脚顺序、步数和速度参数。

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

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

步骤2：添加步进电机外设

1. 点击 新增外设 按钮

2. 填写配置：

   字段	填写内容	说明
   外设ID	stepper1	唯一标识符
   名称	28BYJ-48步进电机	显示名称
   外设类型	步进电机 (type: 42)	4引脚驱动
   引脚配置	32,33,25,26	IN1-IN4对应GPIO
   每转步数	2048	默认调度参数，须按实际电机/减速器校准
   转速	10	RPM（建议≤15）

3. 点击 保存

步骤3：验证配置

1. 在外设列表中找到刚添加的外设
2. 点击 启用 开关
3. 在接线与负载安全确认后，用 forward/reverse 启动连续转动，再用 stop 停止；此处不支持输入步数后自动到位

⚠️ 重要：步进电机需外部5V电源，引脚顺序必须对应IN1-IN4

---

方式2：JSON配置文件导入

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

{
  "id": "stepper1",
  "name": "步进电机",
  "type": 42,
  "enabled": false,
  "pins": [32, 33, 25, 26],
  "params": {
    "stepsPerRevolution": 2048,
    "speed": 10
  }
}

参数说明

参数	说明
stepsPerRevolution	计算调度间隔的每转步数参数，默认2048；实际需按电机与减速器校准
speed	转速（RPM）
halfStep	历史配置字段；当前驱动固定8相半步，不因false改用全步

pins[0]-pins[3] 分别对应驱动板的 IN1-IN4

控制命令

在外设执行的“电机控制”（actionType=12）动作参数中使用以下格式：

{"periphId":"stepper1","action":"forward"}

动作参数	含义
{"periphId":"stepper1","action":"forward"}	开始连续正转
{"periphId":"stepper1","action":"reverse"}	开始连续反转
{"periphId":"stepper1","action":"stop"}	停止后续相位并申请受检释放线圈
{"periphId":"stepper1","action":"setSpeed","value":"10"}	设置目标RPM；idle时不启动运动

direction只接受forward/cw/1或reverse/backward/ccw/-1；未知值不会默认为正转。speed/setspeed及faster/slower系列接受0～65535整数参数，再按1～30 RPM范围收敛；空值或0保留该命令既有默认语义。forward/reverse/start/stop不接受多余value字段。

普通来源仲裁不会允许独立的另一条规则自动接管正在转动的owner；停止动作应属于实际拥有运动的同一执行上下文，或经过已复核的合法接管流程。它不是无条件紧急停机接口。

纯数字 2048/-2048/0 不是此驱动的定步数接口。动作返回只反映命令准入或受检停止，不表示完成一个角度或圈数；连续运动必须安排明确的停止条件。

与外设执行联动

Web界面配置步骤

创建步进电机控制规则

1. 点击左侧菜单 外设执行
2. 点击 新增规则 按钮
3. 配置触发器（定时触发或事件触发）
4. 添加步进电机动作：
   • 动作类型：电机控制（actionType=12）
   • 目标外设：stepper1
   • 动作值：forward 或 reverse；另一明确停止动作使用 stop
5. 点击 保存

连续运动不自动停止。应先准备停止条件，再在安全接线条件下测试。

---

JSON配置示例

同一规则内启动后申请停止

{
  "name": "一次有界转动",
  "enabled": false,
  "triggers": [
    { "triggerType": 4, "triggerPeriphId": "btn1", "eventId": "button_click" }
  ],
  "actions": [
    { "actionType": 12, "targetPeriphId": "stepper1", "actionValue": "forward" },
    { "actionType": 12, "targetPeriphId": "stepper1", "actionValue": "stop", "syncDelayMs": 1000 }
  ]
}

示例要求执行器保持同一可信上下文；延迟期间取消、来源失效或清理失败按相应结果处理。1000ms为软件调度时间，不代表固定步数或一圈，不能用独立的stop规则绕过来源冲突。SDK清理失败仍须保留并处置，不能以动作序列结束断言机械停止。

注意事项

1. 供电要求：步进电机需独立 5V 电源，切勿从 ESP32 USB 口直接供电
2. 发热问题：长时间锁定（保持通电）会导致驱动板和电机发热，不用时建议断电
3. 步数参数：2048是当前默认调度参数；本实现无位置反馈，不保证指定角度或实际圈数
4. 速度限制：速度过快会导致丢步，建议 RPM ≤ 15
5. 引脚顺序：4 个引脚顺序必须与驱动板 IN1-IN4 对应，接反会导致电机振动不转