Deep Sleep Component

The deep_sleep component can be used to automatically enter a deep sleep mode on the ESP8266/ESP32 after a certain amount of time. This is especially useful with nodes that operate on batteries and therefore need to conserve as much energy as possible.

To use deep_sleep first specify how long the node should be active, i.e. how long it should check sensor values and report them, using the run_duration option.

Next, tell the node how it should wakeup. On the ESP8266, you can only put the node into deep sleep for a duration using sleep_duration, note that on the ESP8266 GPIO16 must be connected to the RST pin so that it will wake up again. On the ESP32, you additionally have the option to wake up on any RTC pin (GPIO0, GPIO2, GPIO4, GPIO12, GPIO13, GPIO14, GPIO15, GPIO25, GPIO26, GPIO27, GPIO32, GPIO39).

While in deep sleep mode, the node will not do any work and not respond to any network traffic, even Over The Air updates.

# Example configuration entry
  run_duration: 10s
  sleep_duration: 10min

Configuration variables:

  • run_duration (Optional, Time): The time duration the node should be active, i.e. run code.
  • sleep_duration (Optional, Time): The time duration to stay in deep sleep mode.
  • wakeup_pin (Optional, Pin Schema): Only on ESP32. A pin to wake up to once in deep sleep mode. Use the inverted property to wake up to LOW signals.
  • wakeup_pin_mode (Optional): Only on ESP32. Specify how to handle waking up from a wakeup_pin if the wakeup pin is already in the state with which it would wake up when attempting to enter deep sleep. See ESP32 Wakeup Pin Mode. Defaults to IGNORE
  • id (Optional, ID): Manually specify the ID used for code generation.

Advanced features:

  • esp32_ext1_wakeup (Optional): Use the EXT1 wakeup source of the ESP32 to wake from deep sleep to wake up on multiple pins. This cannot be used together with wakeup pin.
    • pins (Required, list of pin numbers): The pins to wake up on.
    • mode (Optional): The mode to use for the wakeup source. Must be one of ALL_LOW (wake up when all pins go LOW) or ANY_HIGH (wake up when any pin goes HIGH).


Only one deep sleep component may be configured.

ESP32 Wakeup Pin Mode

On the ESP32, you have the option of waking up on any RTC pin. However, there’s one scenario that you need to tell ESPHome how to handle: What if the wakeup pin is already in the state with which it would wake up when the deep sleep should start? There are three ways of handling this using the wakeup_pin_mode option:

  • IGNORE (Default): Ignore the fact that we will immediately exit the deep sleep mode because the wakeup pin is already active.
  • KEEP_AWAKE: Keep the ESP32 awake while the wakeup pin is still active. Or in other words: defer the activation of the deep sleep until the wakeup pin is no longer active.
  • INVERT_WAKEUP: When deep sleep was set up to wake up on a HIGH signal, but the wakeup pin is already HIGH, then re-configure deep sleep to wake up on a LOW signal and vice versa. Useful in situations when you want to use observe the state changes of a pin using deep sleep and the ON/OFF values last longer.

deep_sleep.enter Action

This action makes the given deep sleep component enter deep sleep immediately.

    - deep_sleep.enter: deep_sleep_1

deep_sleep.prevent Action

This action prevents the given deep sleep component from entering deep sleep. Useful for

    - deep_sleep.prevent: deep_sleep_1


For example, if you want to upload a binary via OTA with deep sleep mode it can be difficult to catch the ESP being active.

You can use this automation to automatically prevent deep sleep when a MQTT message on the topic livingroom/ota_mode is received. Then, to do the OTA update, just use a MQTT client to publish a retained MQTT message described below. When the node wakes up again it will no longer enter deep sleep mode and you can upload your OTA update.

Remember to turn “OTA mode” off again after the OTA update by sending a MQTT message with the payload OFF. Note that the device won’t enter deep sleep again until the next reboot.

  # ...
  id: deep_sleep_1
  # ...
    topic: livingroom/ota_mode
    payload: 'ON'
      - deep_sleep.prevent: deep_sleep_1