舵机组件

servo 组件允许您在 ESPHome 中使用舵机电机。舵机是包含驱动电机所需所有电子设备的电机控制器，并提供简单的 PWM 接口来控制电机。

此组件同时支持连续旋转舵机和绝对位置舵机，并具有与 Arduino Servo 库类似的接口。

首先，为舵机连接的引脚创建一个 输出组件（此处为 esp8266_pwm）。然后通过分配 ID 将该输出连接到舵机组件。请注意，输出的频率应约为 50Hz，因为大多数舵机控制器仅在此频率范围内工作。

NOTE

此组件不会自动显示在 Home Assistant 前端，因为 Home Assistant 不支持舵机。请参阅 Home Assistant 配置。

# 示例配置项
servo:
  - id: my_servo
    output: pwm_output

# 示例输出平台
# 在 ESP32 上，使用 ledc 输出
output:
  - platform: esp8266_pwm
    id: pwm_output
    pin: GPIOXX
    frequency: 50Hz

配置变量

• output (必填, ID): 用于此舵机的 输出组件 ID。

• id (必填, ID): 此舵机的 ID，以便可以控制它。

高级选项：

• min_level (可选, percentage): 最小值（-100%）将映射到的 PWM 占空比。默认为 3%。

• idle_level (可选, percentage): 空闲值（0%）将映射到的 PWM 占空比。这也是启动时舵机的状态。默认为 7.5%。

• max_level (可选, percentage): 最大值（100%）将映射到的 PWM 占空比。默认为 12.0%。

• restore (可选, boolean): 是否在启动时恢复舵机状态。如果您有绝对位置舵机并且它在启动时回到 0 位置，这很有用。默认为 false。

• auto_detach_time (可选, 时间): 到达目标值后舵机分离的时间，如果设置为零，舵机将不会分离。默认为 0s。

• transition_length (可选, 时间): 完全移动（-1.0 到 1.0）所需的时间。这将有效地限制舵机的速度，值越大，舵机移动越慢。默认为 0s。 这可以使舵机减速以避免噪音或使运动更平稳。

NOTE

某些舵机支持更大的电平范围。对于连续旋转舵机，这可以稍微加快速度；对于绝对位置舵机，这可以扩展其角度范围。您可以配置 min_level 和 max_level 选项来调整电平范围以匹配您的舵机（请试验这些值）。

servo.write 动作

要在自动化或模板中使用舵机，您可以使用此动作将舵机的目标电平设置为 -100% 到 100%。

• -100%（= -1.0）是舵机的最小值。对于连续旋转舵机，这将使舵机反向旋转。

• 0%（= 0.0）是舵机的空闲电平。对于连续旋转舵机，这将停止舵机。

• 100%（= 1.0）是舵机的最大值。对于连续旋转舵机，这将使舵机正向旋转。

on_...:
  then:
  - servo.write:
      id: my_servo
      level: -100.0%

  # 使用模板
  - servo.write:
      id: my_servo
      # 对于模板值，范围为 [-1; 1]
      level: !lambda |-
        if (id(my_binary_sensor).state) {
          return 1.0;
        } else {
          return -1.0;
        }

配置选项：

• id (必填, ID): 舵机的 ID。
• level (可选, percentage, 可模板化): 目标电平。范围从 -100% 到 100%（-1.0 到 1.0）。

NOTE

此动作也可以表示为 lambda：

id(my_servo).write(1.0);

servo.detach 动作

此动作允许您禁用舵机上的输出——这将使舵机立即停止并禁用其主动控制。

on_...:
  then:
  - servo.detach: my_servo

NOTE

此动作也可以表示为 lambda：

id(my_servo).detach();

Home Assistant 配置

从 Home Assistant 控制舵机的最简单方法是在 ESPHome 配置中添加一个 number。更多信息请参阅 数值。

number:
  - platform: template
    name: 舵机控制
    min_value: -100
    initial_value: 0
    max_value: 100
    step: 1
    optimistic: true
    set_action:
      then:
        - servo.write:
            id: my_servo
            level: !lambda 'return x / 100.0;'

servo:
  - platform: ...
    # [...] 舵机配置
    id: my_servo

另见

• API Reference: servo.h