步进电机组件

stepper 组件允许您在 ESPHome 中使用步进电机。目前仅支持 A4988 步进驱动器（数据手册）和 ULN2003（数据手册）。

NOTE

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

基本步进电机配置

所有步进电机配置模式继承这些选项。

配置变量：

max_speed (必填, float)：驱动步进电机的最大速度，单位为 steps/s（每秒步数）。请注意，大多数步进电机无法以高于 250 steps/s 的速度正常步进。
acceleration (可选, float)：开始移动时使用的加速度，单位为 steps/s^2（每秒平方步数）。默认为 inf，表示无限加速度，因此步进电机将尝试立即以全速驱动。如果电机的第一次运动对于它所移动的内容来说太急促，此值很有帮助。如果将其设置为较小的数值，电机需要片刻才能加速到速度。
deceleration (可选, float)：与 acceleration 相同，但用于电机在达到设定位置前不久减速时。默认为 inf（立即减速）。

A4988 组件

将此代码放入此设备的 ESPHome 配置文件中。

stepper:
  - platform: a4988
    id: my_stepper
    step_pin: GPIOXX
    dir_pin: GPIOXX
    max_speed: 250 steps/s

    # 可选：
    sleep_pin: GPIOXX
    acceleration: inf
    deceleration: inf

配置变量：

id (必填, ID)：指定步进电机的 ID，以便您可以控制它。
step_pin (必填, 引脚模式)：A4988 步进驱动器的 STEP 引脚。
dir_pin (必填, 引脚模式)：A4988 步进驱动器的 DIRECTION 引脚。
sleep_pin (可选, 引脚模式)：可选地同时使用 A4988 步进驱动器的 SLEEP 引脚。如果指定，当步进电机达到目标步数时，驱动器将立即进入睡眠模式。
基本步进电机配置的所有其他选项。

NOTE

如果步进电机朝错误方向驱动，您可以反转 dir_pin：

stepper:
  - platform: a4988
    # ...
    dir_pin:
      number: GPIOXX
      inverted: true

NOTE

TMC 驱动器与 A4988 引脚兼容，但不是 SLEEP 引脚，它们暴露的是 ENABLE 引脚。当使用 TMC 驱动器与 a4988 平台时，您需要反转 sleep_pin：

stepper:
  - platform: a4988
    # ...
    sleep_pin:
      number: GPIOXX
      inverted: true

ULN2003 组件

将此代码放入此设备的 ESPHome 配置文件中。

# 示例配置条目
stepper:
  - platform: uln2003
    id: my_stepper
    pin_a: GPIOXX
    pin_b: GPIOXX
    pin_c: GPIOXX
    pin_d: GPIOXX
    max_speed: 250 steps/s

    # 可选：
    acceleration: inf
    deceleration: inf

配置变量：

id (必填, ID)：指定步进电机的 ID，以便您可以控制它。
pin_a (必填, 引脚模式)：步进控制板的引脚 a。
pin_b (必填, 引脚模式)：步进控制板的引脚 b。
pin_c (必填, 引脚模式)：步进控制板的引脚 c。
pin_d (必填, 引脚模式)：步进控制板的引脚 d。
sleep_when_done (可选, boolean)：当步进电机达到目标位置时是否关闭所有线圈
step_mode (可选, string)：操作电机的步进模式。可选：
- FULL_STEP（默认）
- HALF_STEP
- WAVE_DRIVE
基本步进电机配置的所有其他选项。

`stepper.set_target` 动作

要在自动化或模板中使用步进电机，可以使用此动作设置目标位置（以步数为单位）。步进电机将始终朝目标位置运行，并在达到目标后停止。

on_...:
  then:
  - stepper.set_target:
      id: my_stepper
      target: 250

  # 使用模板
  - stepper.set_target:
      id: my_stepper
      target: !lambda |-
        if (id(my_binary_sensor).state) {
          return 1000;
        } else {
          return -1000;
        }

配置选项：

id (必填, ID)：步进电机的 ID。
target (必填, int, 可模板化)：目标位置，以步数为单位。

WARNING

这会将步进电机转到绝对位置！要让步进电机相对于当前位置移动，首先重置当前位置，然后将目标设置为相对值。

on_...:
  then:
    # 向前移动 150 步
    - stepper.report_position:
        id: my_stepper
        position: 0
    - stepper.set_target:
        id: my_stepper
        target: 150

`stepper.report_position` 动作

所有步进电机在启动时目标和当前位置都从 0 开始。但是，例如如果您想对步进电机进行归位，报告步进电机当前所在位置可能很有用。

使用此动作，您可以将步进电机的内部位置计数器设置为特定值（以步数为单位）。请注意，报告位置可能会导致步进电机意外移动。例如，如果步进电机的目标和当前位置是 1000 步，而您”报告”位置为 0，步进电机将向前移动 1000 步以再次匹配目标。

on_...:
  then:
  - stepper.report_position:
      id: my_stepper
      position: 250
  # 最好在 report_position 之后直接调用 set_target，这样步进电机就不会移动
  - stepper.set_target:
      id: my_stepper
      target: 250

  # 使用模板
  - stepper.report_position:
      id: my_stepper
      position: !lambda |-
        if (id(my_binary_sensor).state) {
          return 0;
        } else {
          return -1000;
        }

配置变量：

id (必填, ID)：步进电机的 ID。
position (必填, int, 可模板化)：要报告的位置，以步数为单位。

`stepper.set_speed` 动作

此动作允许您在运行时设置步进电机的速度。

on_...:
  - stepper.set_speed:
      id: my_stepper
      speed: 250 steps/s

配置变量：

id (必填, ID)：步进电机的 ID。
speed (必填, 可模板化, float)：驱动步进电机的速度，单位为 steps/s（每秒步数）。

`stepper.set_acceleration` 动作

此动作允许您在运行时设置步进电机的加速度。

on_...:
  - stepper.set_acceleration:
      id: my_stepper
      acceleration: 250 steps/s^2

配置变量：

id (必填, ID)：步进电机的 ID。
acceleration (必填, 可模板化, float)：开始移动时使用的加速度，单位为 steps/s^2（每秒平方步数）。

`stepper.set_deceleration` 动作

此动作允许您在运行时设置步进电机的减速度。

on_...:
  - stepper.set_deceleration:
      id: my_stepper
      deceleration: 250 steps/s^2

配置变量：

id (必填, ID)：步进电机的 ID。
deceleration (必填, 可模板化, float)：与 acceleration 相同，但用于电机在达到设定位置前不久减速时。

Home Assistant 配置

从 Home Assistant 控制步进电机的最简单方法是在 ESPHome 配置中添加一个 number。有关更多信息，请参阅数字。

number:
  - platform: template
    name: 步进电机控制
    min_value: -100
    max_value: 100
    step: 1
    set_action:
      then:
        - stepper.set_target:
            id: my_stepper
            target: !lambda 'return x;'

stepper:
  - platform: ...
    # [...] 步进电机配置
    id: my_stepper

lambda 调用

在 lambda 中，您可以调用步进电机的多种方法来执行一些高级操作（有关更多信息，请参阅完整的 API 参考）。

set_target：将电机的目标位置设置为整数。

        // 参数是整数（有符号 int）
        // 将（绝对）目标位置设置为 250 步
        id(my_stepper).set_target(250);

report_position：将当前位置报告为整数。

        // 将（绝对）当前位置报告为 250 步
        id(my_stepper).report_position(250);

current_position：获取步进电机的当前位置作为整数。

        int pos = id(my_stepper).current_position;

target_position：获取步进电机的设定目标位置作为整数。

        int pos = id(my_stepper).target_position;

另请参阅

API Reference: stepper.h

步进电机组件

基本步进电机配置

A4988 组件

ULN2003 组件

stepper.set_target 动作

stepper.report_position 动作

stepper.set_speed 动作

stepper.set_acceleration 动作

stepper.set_deceleration 动作

Home Assistant 配置

lambda 调用

另请参阅

`stepper.set_target` 动作

`stepper.report_position` 动作

`stepper.set_speed` 动作

`stepper.set_acceleration` 动作

`stepper.set_deceleration` 动作