Stepper 组件

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

NOTE

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

基础 Stepper 配置

所有 stepper 配置模式都继承这些选项。

配置变量：

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 (必填, Pin Schema): A4988 步进驱动器的 STEP 引脚。
dir_pin (必填, Pin Schema): A4988 步进驱动器的 DIRECTION 引脚。
sleep_pin (可选, Pin Schema): 可选地也使用 A4988 步进驱动器的 SLEEP 引脚。如果指定，一旦步进电机达到目标步数，驱动器将进入睡眠模式。
基础 Stepper 配置中的所有其他选项。

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 (必填, Pin Schema): 步进控制板的引脚 a。
pin_b (必填, Pin Schema): 步进控制板的引脚 b。
pin_c (必填, Pin Schema): 步进控制板的引脚 c。
pin_d (必填, Pin Schema): 步进控制板的引脚 d。
sleep_when_done (可选, boolean): 当步进电机达到目标位置时，是否关闭所有线圈
step_mode (可选, string): 驱动电机的步进模式。可选值为：
- FULL_STEP（默认）
- HALF_STEP
- WAVE_DRIVE
基础 Stepper 配置中的所有其他选项。

`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。

number:
  - platform: template
    name: Stepper Control
    min_value: -100
    max_value: 100
    step: 1
    set_action:
      then:
        - stepper.set_target:
            id: my_stepper
            target: !lambda 'return x;'

stepper:
  - platform: ...
    # [...] stepper 配置
    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 参考：stepper.h

Stepper 组件

基础 Stepper 配置

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` 动作