舵机（Servo）

PWM_SERVO（type 41）使用配置的角度/脉宽映射产生PWM信号。当前角度和脉宽是软件最后接受的角度命令值，未测量机械位置；raw duty命令不伪造新的角度读数。

2026-10-04 motion候选：命名舵机接入普通来源仲裁、受检释放计时器及LEDC租约清理。此页描述候选代码语义；集中Host/固件/设备验收分别登记，尚无新增实物通过结论。

配置

下例保持禁用；引脚、电源、限位及具体型号的频率/脉宽需在现场核对后再启用。

json

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

字段	语义及配置约束
frequency	默认50Hz，允许40～400Hz；须符合舵机规格
minPulse / maxPulse	默认500/2500μs；最小至少100、最大至多5000，最小小于最大，最大严格小于一个PWM周期
minAngle / maxAngle	默认0/180°，在0～360°内且最小小于最大；现场机械范围可以更窄
initialAngle	默认90°，在配置角度范围内；字段名为initialAngle
pwmChannel / pwmResolution	默认通道0/16位；分辨率1～16，实际可用通道及频率组合取决于芯片与SDK
inverted	在配置的角度范围内反向映射脉宽
releaseAfterMove	默认false；true时角度或raw duty写入后安排约500ms后的信号释放，锁繁忙可推迟

初始化会按initialAngle申请信号输出，不能将“仅保存配置”与“启用/重新初始化”视作同一操作。通道/引脚冲突或SDK附着失败会拒绝初始化。普通仲裁终态不是机械急停。

角度与raw duty

入口	参数解释
HTTP `POST /api/peripherals/write`，`id=servo1&angle=90`	按配置的角度范围、脉宽、反向、频率、位宽映射
同一路径 `id=servo1&pwm=4915`	raw duty计数，范围0～2^pwmResolution-1
`ACTION_SET_PWM(4)` 的actionValue	raw duty计数
CALL命令 `{"periphId":"servo1","action":"pwm","value":"4915"}`	raw duty计数
命令脚本 `PERIPH servo1 PWM 4915`	raw duty计数

HTTP只允许angle或pwm其中一个；越界、负值、非整数和重复/未知字段会被拒绝。HTTP由已登录会话生成来源身份，默认手动保持30秒，可显式设置有效holdMs；普通调用方不能提交自造actor/source/operation。请求冲突和写入未知分别返回结构化control结果；不能把失败请求自动重试。

例如上表默认配置，90°→1500μs→四舍五入的4915 duty。raw duty的90、脉宽的90μs、角度的90°是三个不同量。通用MQTT数值消息不自动获得“舵机角度”语义；平台应触发已配置且类型正确的规则动作。

规则动作示例（4915仅对应上述频率/位宽/映射）：

json

{
  "targetPeriphId": "servo1",
  "actionType": 4,
  "actionValue": "4915",
  "useReceivedValue": false
}

来源与释放边界

同一actor的新操作须先受检退休旧producer；另一actor冲突时不会自行抢占。符合优先级的手动接管需要当前目标、配置版本和generation的明确复核。规则版本、UART来源、配置或屏幕身份失效后，不再执行旧动作。

未启用releaseAfterMove时，操作终态或保持到期仅退休软件控制权，保留最后PWM信号。启用时，旧释放计时器先被封禁并核对stop/delete，之后核对写零和LEDC detach；任一失败保留资源/清理证据并阻止接管。正常释放回调遇忙锁或SDK失败会保留，重试只针对已接受的释放，不重放移动命令。故障不会因后续成功而清空历史错误。

信号释放仅证明相应SDK调用被接受，不证明断电、卸载、机械停止或到位。独立供电并共地；按板型核对信号脚的输出能力、保留用途与已有外设，不能假定任意GPIO或板载5V供电均适用。

舵机（Servo） ​

配置 ​

角度与raw duty ​

来源与释放边界 ​

舵机（Servo）

配置

角度与raw duty

来源与释放边界