Servo

fastbeeAbout 3 min

Servo

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.

舵机（Servo）

功能说明

舵机外设使用 PWM 信号控制舵机角度（0°-180°），适用于机械臂、云台、门锁、机器人关节等场景。

支持的外设类型

类型	type值	说明
PWM_SERVO	41	舵机（PWM 角度控制）

硬件接线

SG90 / MG996R 舵机

舵机线色	连接	说明
橙/黄（信号）	GPIO	PWM 信号引脚
红（VCC）	5V	电源（外部供电）
棕/黑（GND）	GND	地

SG90 小舵机可直接用 ESP32 的 5V 引脚供电，MG996R 等大扭矩舵机需外部独立电源。

配置方式

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

舵机保存前重点核对 PWM 引脚、角度范围和独立供电能力。

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

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

步骤2：添加舵机外设

点击 新增外设 按钮

填写配置：

字段	填写内容	说明
外设ID	`servo1`	唯一标识符
名称	`SG90舵机` 或 `门锁舵机`	显示名称
外设类型	PWM舵机 (type: 41)	舵机控制
引脚配置	`27`	信号引脚
最小脉宽	`544`	对应0°（微秒）
最大脉宽	`2400`	对应180°（微秒）
默认角度	`90`	上电初始角度

点击保存

步骤3：验证配置

在外设列表中找到刚添加的外设
点击启用开关
使用控制面板测试角度（0-180）

⚠️ 提示：MG996R等大扭矩舵机需外部5V/2A电源，不可直接从ESP32取电

方式2：JSON配置文件导入

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

{
  "id": "servo1",
  "name": "舵机",
  "type": 41,
  "enabled": false,
  "pins": [27],
  "params": {
    "minPulse": 544,
    "maxPulse": 2400,
    "defaultAngle": 90
  }
}

参数说明

参数	说明
minPulse	最小脉冲宽度（μs），对应 0°，默认 544
maxPulse	最大脉冲宽度（μs），对应 180°，默认 2400
defaultAngle	上电后默认角度（0-180）

pins[0] = 舵机信号引脚

控制命令

通过 MQTT 或 Web 界面发送角度值：

[{"id": "servo1", "value": "90"}]

值范围：0 ~ 180（单位：度）
发送 0 转到最小角度，180 转到最大角度

与外设执行联动

Web界面配置步骤

创建舵机控制规则

切换到 外设执行管理 标签
点击 新增规则 按钮
配置触发器（事件触发、定时触发或平台触发）
添加舵机动作：
- 动作类型：设置PWM（舵机使用PWM控制）
- 目标外设：servo1
- 动作值：90（角度0-180）
点击保存

💡 提示：可使用脚本动作实现舵机摆动效果（PERIPH servo1 PWM 角度）

JSON配置示例

按键控制舵机角度

{
  "name": "按键开门",
  "enabled": true,
  "triggers": [
    {
      "type": "event",
      "params": { "periphId": "btn1", "event": "pressed" }
    }
  ],
  "actions": [
    {
      "type": "servo_write",
      "params": {
        "periphId": "servo1",
        "value": "180"
      }
    }
  ]
}

定时摆动

{
  "name": "舵机摆动",
  "enabled": true,
  "triggers": [
    {
      "type": "timer",
      "params": { "interval": 2000 }
    }
  ],
  "actions": [
    {
      "type": "servo_write",
      "params": {
        "periphId": "servo1",
        "value": "0"
      }
    },
    { "type": "delay", "params": { "ms": 1000 } },
    {
      "type": "servo_write",
      "params": {
        "periphId": "servo1",
        "value": "180"
      }
    }
  ]
}

数据上报格式

当前角度通过 MQTT 上报：

[{"id": "servo1", "value": "90"}]

注意事项

供电要求：大扭矩舵机（MG996R）需独立 5V/2A 电源，USB 供电可能导致 ESP32 重启
信号电平：ESP32 输出 3.3V PWM，大部分舵机可正常识别，无需电平转换
抖动问题：如出现微小抖动，可调整 minPulse/maxPulse 参数匹配具体舵机型号
角度限制：避免机械卡死，根据实际安装限制角度范围
引脚选择：ESP32 任意 GPIO 均可输出 PWM，建议避开 Strapping 引脚（GPIO 0/2/12/15）