PWM 输出

功能说明

PWM（脉冲宽度调制）输出用于控制LED亮度、舵机角度、电机调速等。通过改变占空比实现模拟控制效果。

支持的外设类型

类型	type值	说明
GPIO_PWM_OUTPUT	17	通用PWM输出（LED调光/电机调速）
PWM_SERVO	41	舵机控制（默认50Hz，可配置）

参数说明

PWM 输出参数

参数	说明	默认值
pwmChannel	PWM通道（以当前芯片及空闲通道为准）	0
pwmFrequency	PWM频率（Hz）	1000
pwmResolution	分辨率（位数，1-16）	8
defaultDuty	默认占空比	0

Servo 参数

参数	说明	默认值
frequency	PWM频率（Hz，配置范围40～400，须匹配实际舵机）	50
minPulse	最小脉宽(μs)	500
maxPulse	最大脉宽(μs)	2500
minAngle / maxAngle	角度映射范围，须在0～360内且最小值小于最大值	0 / 180
initialAngle	初始化角度，须在配置范围内	90
pwmResolution	raw duty位宽（1～16）	16
pwmChannel	当前芯片可用的LEDC通道	0
inverted / releaseAfterMove	反向映射 / 移动后释放信号	false / false

更多约束及角度/raw duty区别见舵机说明。

PWM 调试先从低占空比或中位角度开始，确认电源和负载响应正常后，再接入自动规则；舵机和电机建议使用独立供电并共地。

占空比范围

占空比范围由 pwmResolution 决定：

8位分辨率：0 ~ 255
10位分辨率：0 ~ 1023
12位分辨率：0 ~ 4095

模拟量输出（AO）模式

真 DAC（type=27）仅经典 ESP32 的 GPIO25/26 具备；其他芯片（S3/C3/C6 等）使用 PWM-as-AO（type=17 PWM 输出 / type=16 模拟输出）。启用 AO 模式后，PWM 外设把 0～100% 的输入线性映射到占空比，配合 RC 滤波或执行器自身的模拟输入即可当作 AO 通道使用：

参数	默认值	说明
aoMode	false	启用 AO 百分比映射模式（缺省保持原 PWM 行为）
aoMinPct	0	输入 0% 对应的输出百分比下限
aoMaxPct	100	输入 100% 对应的输出百分比上限

映射公式：

text

mappedPct = aoMinPct + (aoMaxPct − aoMinPct) × input / 100
duty      = maxDuty × mappedPct / 100

输入超范围自动钳位到 0～100。
aoMinPct > aoMaxPct 时自动交换，配置仍然可用。
工业执行器常见 20%～80% 有效窗口：设置 aoMinPct=20、aoMaxPct=80 后，写入 0% → 20% 占空比（信号下限），写入 100% → 80% 占空比（信号上限）。
映射在统一写入路径实现，Web 控制、规则引擎、MQTT 下发等所有 PWM 写入路径自动生效。

json

{
  "id": "ao_valve",
  "name": "调节阀",
  "type": 17,
  "enabled": false,
  "pins": [2],
  "params": {
    "pwmFrequency": 1000,
    "pwmResolution": 12,
    "aoMode": true,
    "aoMinPct": 20,
    "aoMaxPct": 80
  }
}

配置方式

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

PWM 输出保存前重点核对引脚、频率、分辨率和初始占空比。

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

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

步骤2：添加PWM输出外设

点击 新增外设 按钮

填写配置：

字段	填写内容	说明
外设ID	`led_pwm` 或 `motor_pwm`	唯一标识符
名称	`LED调光灯` 或 `直流电机调速`	显示名称
外设类型	GPIO PWM输出 (type: 17)	通用PWM
引脚配置	`5` 或 `18`	根据实际接线填写
PWM频率	`1000`	LED用1000Hz，电机用5000Hz
PWM分辨率	`8`	8位=0-255，12位=0-4095
默认占空比	`0`	初始亮度/速度

点击保存

步骤3：验证配置

在外设列表中找到刚添加的外设
点击启用开关
使用控制面板调整PWM值

💡 提示：舵机请选择 PWM舵机 (type: 41)，默认50Hz，须按实际舵机规格配置频率、角度和脉宽

方式2：JSON配置文件导入

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

LED 调光（8位 PWM）

json

{
  "id": "led_pwm",
  "name": "LED调光灯",
  "type": 17,
  "enabled": false,
  "pins": [5],
  "params": {
    "initialState": 0,
    "pwmChannel": 0,
    "pwmFrequency": 1000,
    "pwmResolution": 8,
    "defaultDuty": 0
  }
}

电机调速（12位 PWM）

json

{
  "id": "motor_pwm",
  "name": "直流电机调速",
  "type": 17,
  "enabled": false,
  "pins": [18],
  "params": {
    "initialState": 0,
    "pwmChannel": 1,
    "pwmFrequency": 5000,
    "pwmResolution": 12,
    "defaultDuty": 0
  }
}

SG90 舵机

json

{
  "id": "servo1",
  "name": "SG90舵机",
  "type": 41,
  "enabled": false,
  "pins": [16],
  "params": {
    "frequency": 50,
    "minPulse": 500,
    "maxPulse": 2500,
    "minAngle": 0,
    "maxAngle": 180,
    "initialAngle": 90,
    "pwmResolution": 16,
    "pwmChannel": 0
  }
}

与外设执行联动

设置PWM占空比

json

{
  "targetPeriphId": "led_pwm",
  "actionType": 4,
  "actionValue": "128",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

Web界面配置步骤

创建PWM控制规则

点击左侧菜单 外设执行
创建规则并配置触发器（如定时触发、平台触发）
添加PWM动作：
- 动作类型：设置PWM
- 目标外设：led_pwm
- 动作值：128（50%占空比，8位分辨率）
点击保存

💡 提示：呼吸灯效果可选择“呼吸灯”动作类型，actionValue为周期毫秒数

JSON配置示例

呼吸灯效果

json

{
  "targetPeriphId": "led_pwm",
  "actionType": 3,
  "actionValue": "2000",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

actionValue 为呼吸周期（毫秒）

舵机角度控制

舵机的 ACTION_SET_PWM(4)、CALL pwm 及 PERIPH servo1 PWM n 都接受 raw duty计数，范围为 0～2^pwmResolution-1，不把参数解释为角度或微秒。HTTP手动控制通过 /api/peripherals/write 的 angle 字段使用配置角度映射；也可用 pwm 字段发送raw duty，两者不能同时发送。

例如50Hz、16位、500～2500μs对应0～180°时，90°映射到1500μs，再经整数舍入得到4915 duty；raw duty 90 不表示90°。改变频率、分辨率或映射参数后必须重新计算。软件回执不证明机械到位。

2026-10-04 motion候选开发边界：命名舵机的上述入口使用实际会话/规则/脚本上下文仲裁；未知或失败写入不自动重放。集中测试与设备部署结论另行登记。

脚本联动示例

以下渐变示例要求目标配置为12位通用PWM；8位目标会拒绝超过255的值：

PERIPH motor_pwm PWM 0
DELAY 500
PERIPH motor_pwm PWM 1000
DELAY 500
PERIPH motor_pwm PWM 2000
DELAY 500
PERIPH motor_pwm PWM 4095

注意事项

通道冲突：同一 PWM 通道不可被多个外设共用，配置时确保 pwmChannel 唯一
频率选择：LED调光建议 1000Hz，电机驱动建议 5000-25000Hz，舵机默认50Hz，频率与脉宽必须符合型号规格
分辨率与频率：频率与分辨率组合取决于具体芯片、时钟源及SDK；配置范围通过不等于实际LEDC附着成功，不应套用统一80MHz公式
舵机供电：舵机需独立供电，不要直接从ESP32 3.3V引脚取电
平台下发：平台可通过 [{"id":"led_pwm","value":"128"}] 设置占空比

PWM 输出 ​

功能说明 ​

支持的外设类型 ​

参数说明 ​

PWM 输出参数 ​

Servo 参数 ​

占空比范围 ​

模拟量输出（AO）模式 ​

配置方式 ​

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

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

步骤2：添加PWM输出外设 ​

步骤3：验证配置 ​

方式2：JSON配置文件导入 ​

LED 调光（8位 PWM） ​

电机调速（12位 PWM） ​

SG90 舵机 ​

与外设执行联动 ​

设置PWM占空比 ​

Web界面配置步骤 ​

JSON配置示例 ​

呼吸灯效果 ​

舵机角度控制 ​

脚本联动示例 ​

注意事项 ​

PWM 输出

功能说明

支持的外设类型

参数说明

PWM 输出参数

Servo 参数

占空比范围

模拟量输出（AO）模式

配置方式

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

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

步骤2：添加PWM输出外设

步骤3：验证配置

方式2：JSON配置文件导入

LED 调光（8位 PWM）

电机调速（12位 PWM）

SG90 舵机

与外设执行联动

设置PWM占空比

Web界面配置步骤

JSON配置示例

呼吸灯效果

舵机角度控制

脚本联动示例

注意事项