深度睡眠组件

deep_sleep 组件可用于在 ESP8266/ESP32/BK72xx 上经过一定时间后自动进入深度睡眠模式。这对于使用电池运行并因此需要尽可能节省能量的节点特别有用。

要使用 deep_sleep，首先使用 run_duration 选项指定节点应该活动多长时间，即它应该检查传感器值并报告它们多长时间。

接下来，告诉节点它应该如何唤醒。在 ESP8266 上，您只能使用 sleep_duration 让节点进入深度睡眠一段持续时间，注意在 ESP8266 上 GPIO16 必须连接到 RST 引脚以便它能再次唤醒。在 ESP32 上，您还可以选择在任何 RTC 引脚（GPIO0、GPIO2、GPIO4、GPIO12、GPIO13、GPIO14、GPIO15、GPIO25、GPIO26、GPIO27、GPIO32、GPIO39）上唤醒。BK72xx 可以使用定时器（最大值为 36 小时）和/或一个或多个非引导引脚唤醒。

在深度睡眠模式下，节点不会执行任何工作，也不会响应任何网络流量，包括空中下载（OTA）更新。如果设备的实体在您的设备主动睡眠时显示为不可用，此组件可能是在设备添加到 Home Assistant 之后添加的。为了防止这种行为，您可以在 Home Assistant 中删除并重新添加设备。

# 示例配置项
deep_sleep:
  run_duration: 10s
  sleep_duration: 10min

NOTE

某些 ESP8266 有一个板载 USB 芯片（例如 D1 mini），其控制线连接到 RST 引脚。这使得刷写器可以在需要时重启 ESP。这可能会干扰某些设备上的深度睡眠，并阻止 ESP 在通过 USB 连接器供电时唤醒。从连接到 3.3V 引脚和 GND 的独立 3.3V 电源为 ESP 供电将解决此问题。在这些情况下，使用 USB 转 TTL 适配器将允许您记录 ESP 活动。

配置变量

run_duration (Optional, Time): 节点应该活动的时间持续时间，即运行代码的时间。

仅在 ESP32 上，可以不使用时间，而是根据深度睡眠的唤醒原因指定运行持续时间：
- default (Required, Time): 定时器唤醒和任何未指定唤醒原因的默认运行持续时间。
- gpio_wakeup_reason (Optional, Time): 如果被 GPIO 唤醒的运行持续时间。
- touch_wakeup_reason (Optional, Time): 如果被触摸唤醒的运行持续时间。
sleep_duration (Optional, Time): 保持在深度睡眠模式的时间持续时间。在 BK72xx 上，最大值为 36 小时。
touch_wakeup (Optional, boolean): 仅限 ESP32。使用触摸事件从深度睡眠唤醒。要能够从触摸事件唤醒，必须正确配置二值传感器。
wakeup_pin (Optional, Pin Schema / list): 仅限 ESP32/BK72xx。一旦进入深度睡眠模式后唤醒的单个引脚。使用 inverted 属性来唤醒于 LOW 信号。如果您想指定多个唤醒引脚（仅限 BK72xx），请在 wakeup_pin 下使用以下条目列表：
- pin (Required, Pin Schema)
- wakeup_pin_mode (Optional) 见下文
wakeup_pin_mode (Optional): 仅限 ESP32/BK72xx。指定如果尝试进入深度睡眠时唤醒引脚已经处于它会唤醒的状态，如何处理从 wakeup_pin 唤醒。请参阅唤醒引脚模式。默认为 IGNORE
id (Optional, ID): 手动指定用于代码生成的 ID。

高级功能：

esp32_ext1_wakeup (Optional): 使用 ESP32 的 EXT1 唤醒源从深度睡眠唤醒，以便在多个引脚上唤醒。这不能与唤醒引脚一起使用。
- pins (Required, 引脚编号列表): 要唤醒的引脚。
- mode (Required): 用于唤醒源的模式。必须是以下之一：
  - ANY_LOW: 当任何选定引脚为 LOW 时唤醒（仅限 ESP32‑C5/C6/C61/H2/P4/S2/S3）
  - ALL_LOW: 当所有选定引脚为 LOW 时唤醒（仅限 ESP32）
  - ANY_HIGH: 当任何选定引脚为 HIGH 时唤醒

NOTE

只能配置一个深度睡眠组件。

ESP32/BK72xx 唤醒引脚模式

在 ESP32（和 BK72xx）上，您可以选择在任何 RTC 引脚上唤醒。但是，有一种情况您需要告诉 ESPHome 如何处理：如果深度睡眠应该开始时，唤醒引脚已经处于它会唤醒的状态怎么办？使用 wakeup_pin_mode 选项有三种处理方式：

IGNORE（默认）：忽略我们会立即退出深度睡眠模式的事实，因为唤醒引脚已经活动。
KEEP_AWAKE: 在唤醒引脚仍然活动时保持 ESP32 唤醒。换句话说：推迟深度睡眠的激活，直到唤醒引脚不再活动。
INVERT_WAKEUP: 当深度睡眠设置为在 HIGH 信号上唤醒，但唤醒引脚已经是 HIGH 时，重新配置深度睡眠以在 LOW 信号上唤醒，反之亦然。当您想使用深度睡眠观察引脚的状态变化，且 ON/OFF 值持续时间较长时很有用。

# BK72xx 单引脚唤醒示例配置
deep_sleep:
  wakeup_pin: P8  # 当 P8 为高电平时唤醒
  wakeup_pin_mode: IGNORE # 进入睡眠时刻 P8 的状态不影响唤醒场景

# BK72xx 多引脚唤醒示例配置
deep_sleep:
  wakeup_pin:
    - pin:
        number: P8
        inverted: True  # 当 P8 为低电平时唤醒
      wakeup_pin_mode: KEEP_AWAKE # 只要 P8 为低电平就阻止睡眠
    - pin: P24 # 当 P24 变为高电平时唤醒
      wakeup_pin_mode: INVERT_WAKEUP # 每次唤醒后翻转触发电平

ESP32 唤醒原因

在 ESP32 上，可以使用 esp_sleep_get_wakeup_cause() 函数检查哪个唤醒源触发了从睡眠模式唤醒。

sensor:
  - platform: template
    name: "唤醒原因"
    accuracy_decimals: 0
    lambda: return esp_sleep_get_wakeup_cause();

以下整数是唤醒原因：

0 - ESP_SLEEP_WAKEUP_UNDEFINED: 对于深度睡眠，复位不是由深度睡眠退出引起的
1 - ESP_SLEEP_WAKEUP_ALL: 不是唤醒原因，用于使用 esp_sleep_disable_wakeup_source 禁用所有唤醒源
2 - ESP_SLEEP_WAKEUP_EXT0: 由使用 RTC_IO 的外部信号引起的唤醒
3 - ESP_SLEEP_WAKEUP_EXT1: 由使用 RTC_CNTL 的外部信号引起的唤醒
4 - ESP_SLEEP_WAKEUP_TIMER: 由定时器引起的唤醒
5 - ESP_SLEEP_WAKEUP_TOUCHPAD: 由触摸板引起的唤醒
6 - ESP_SLEEP_WAKEUP_ULP: 由 ULP 程序引起的唤醒
7 - ESP_SLEEP_WAKEUP_GPIO: 由 GPIO 引起的唤醒（仅限 ESP32、S2 和 S3 上的浅睡眠）
8 - ESP_SLEEP_WAKEUP_UART: 由 UART 引起的唤醒（仅限浅睡眠）
9 - ESP_SLEEP_WAKEUP_WIFI: 由 WIFI 引起的唤醒（仅限浅睡眠）
10 - ESP_SLEEP_WAKEUP_COCPU: 由 COCPU 中断引起的唤醒
11 - ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG: 由 COCPU 崩溃引起的唤醒
12 - ESP_SLEEP_WAKEUP_BT: 由 BT 引起的唤醒（仅限浅睡眠）

`deep_sleep.enter` 动作

此动作使给定的深度睡眠组件立即进入深度睡眠。

on_...:
  then:
    - deep_sleep.enter:
        id: deep_sleep_1
        sleep_duration: 20min

# 睡眠持续时间也可以模板化
on_...:
  then:
    - deep_sleep.enter:
        id: deep_sleep_1
        sleep_duration: !lambda "return 20 * 60 * 1000;"

# ESP32 可以睡眠到一天中的特定时间。
on_...:
  then:
    - deep_sleep.enter:
        id: deep_sleep_1
        until: "16:00:00"
        time_id: sntp_id

配置选项：

sleep_duration (Optional, templatable, Time): 保持在深度睡眠模式的时间持续时间。如果使用模板，它应该返回以毫秒为单位的值。
until (Optional, string): 一天中唤醒的时间。仅限 ESP32。
time_id (Optional, ID): 用于 until 选项的时间组件的 ID。仅限 ESP32。

`deep_sleep.prevent` 动作

此动作阻止给定的深度睡眠组件进入深度睡眠。用于在数据传输或 OTA 更新期间保持 ESP 活动（有关更多信息，请参阅下面的注释）。

on_...:
  then:
    - deep_sleep.prevent: deep_sleep_1

NOTE

例如，如果您想在深度睡眠模式下通过 OTA 上传二进制文件，可能很难捕捉到 ESP 处于活动状态。

您可以使用此自动化在收到主题 livingroom/ota_mode 上的 MQTT 消息时自动阻止深度睡眠。然后，要进行 OTA 更新，只需使用 MQTT 客户端发布下面描述的保留 MQTT 消息。当节点再次唤醒时，它将不再进入深度睡眠模式，您可以上传您的 OTA 更新。

记得在 OTA 更新后通过发送负载为 OFF 的 MQTT 消息再次关闭”OTA 模式”。要在 OTA 更新后再次进入深度睡眠，在主题 livingroom/sleep_mode 上发送负载为 ON 的消息。深度睡眠将立即开始。不要忘记在节点再次唤醒之前删除负载。

deep_sleep:
  # ...
  id: deep_sleep_1
mqtt:
  # ...
  on_message:
    - topic: livingroom/ota_mode
      payload: 'ON'
      then:
        - deep_sleep.prevent: deep_sleep_1
    - topic: livingroom/sleep_mode
      payload: 'ON'
      then:
        - deep_sleep.enter: deep_sleep_1

`deep_sleep.allow` 动作

此动作允许先前被阻止的给定深度睡眠组件进入深度睡眠。

on_...:
  then:
    - deep_sleep.allow: deep_sleep_1

深度睡眠组件

配置变量

ESP32/BK72xx 唤醒引脚模式

ESP32 唤醒原因

deep_sleep.enter 动作

deep_sleep.prevent 动作

deep_sleep.allow 动作

另见

`deep_sleep.enter` 动作

`deep_sleep.prevent` 动作

`deep_sleep.allow` 动作