Deep sleep docs update with guard switch #4410
Conversation
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
WalkthroughThe documentation for the "Deep Sleep Component" has been updated to include new features and configuration options. Notably, a "Deep Sleep Guard" switch has been introduced, allowing users to prevent the device from entering deep sleep mode. The configuration now includes optional parameters Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant DeepSleepComponent
participant GuardSwitch
User->>DeepSleepComponent: Request to enter deep sleep
alt Guard is enabled
GuardSwitch-->>DeepSleepComponent: Prevent deep sleep
DeepSleepComponent-->>User: Ignored request
else Guard is disabled
DeepSleepComponent-->>User: Enter deep sleep
end
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (3)
components/deep_sleep.rst (3)
196-197: Improve clarity and structure of the guard feature explanation.The explanation could be clearer with better structure and grammar. Consider this revision:
-You may have calls to deep_sleep.allow or enter from other places which can re-enable deep sleep. An on_value handler based on a periodically checked sensor value (battery level okay: prevent, low: allow), or some other automation from Home Assistant. In that case this can be overriden and the device goes to deep sleep nevertheless. To be absolutely sure, you can use this switch. When enabled and the timer reaches run_duration, deep sleep will be postponed until it is disabled again. Any call to deep_sleep.enter will be ignored, too. +The Deep Sleep Guard switch provides absolute control over deep sleep behavior. When enabled: + +- Deep sleep will be postponed even if the run_duration timer expires +- All calls to deep_sleep.enter will be ignored +- The device will remain awake until the guard is disabled + +This is particularly useful when: +- Multiple automations might trigger deep sleep (e.g., battery level checks, Home Assistant automations) +- You need to ensure the device stays awake during critical operations
198-205: Enhance the code example with comments and additional use cases.The example could be more helpful with explanatory comments and common use cases. Consider expanding it:
.. code-block:: yaml switch: - platform: deep_sleep deep_sleep_id: deep_sleep_1 guard: name: Deep Sleep Guard + # Optional: Additional switch configuration + icon: mdi:sleep-off # Custom icon + inverted: false # Switch behavior (ON = guard enabled) + + # Example: Prevent deep sleep during OTA updates + on_...: + then: + - switch.turn_on: deep_sleep_guard_id + # Perform OTA update + - switch.turn_off: deep_sleep_guard_id
196-208: Consider restructuring the Deep Sleep Guard documentation.While the content is technically accurate, consider reorganizing it into a dedicated section for better visibility and clarity:
- Move the guard feature documentation into a new section titled "Deep Sleep Guard" before the "ESP32 Wakeup Pin Mode" section
- Structure the section with clear subsections:
- Overview and Use Cases
- Configuration
- Examples
- Integration with Other Features
This would make the new feature more discoverable and easier to understand.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
components/deep_sleep.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
components/deep_sleep.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
| - **deep_sleep_id** (*Optional*, :ref:`config-id`): ID of the deep_sleep component. | ||
| - **guard** (*Optional*, switch): This is the switch to guard the device from deep sleep. All properties from sensor, at least the name is required to show up in HA. Defaults to off. |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Expand configuration documentation with more details.
The configuration options need more detailed explanations:
-**deep_sleep_id** (*Optional*, :ref:`config-id`): ID of the deep_sleep component.
-**guard** (*Optional*, switch): This is the switch to guard the device from deep sleep. All properties from sensor, at least the name is required to show up in HA. Defaults to off.
+**deep_sleep_id** (*Optional*, :ref:`config-id`): The ID of the deep sleep component this guard switch controls. If not specified, it will control the default deep sleep component.
+
+**guard** (*Optional*, :ref:`Switch <config-switch>`): Configuration for the guard switch:
+
+ - **name** (**Required**, string): The name of the switch in Home Assistant
+ - All other options from :ref:`Switch <config-switch>` are supported (icon, inverted, etc.)
+ - The switch defaults to OFF (guard disabled)
+ - When ON, prevents the device from entering deep sleep regardless of other conditions📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **deep_sleep_id** (*Optional*, :ref:`config-id`): ID of the deep_sleep component. | |
| - **guard** (*Optional*, switch): This is the switch to guard the device from deep sleep. All properties from sensor, at least the name is required to show up in HA. Defaults to off. | |
| **deep_sleep_id** (*Optional*, :ref:`config-id`): The ID of the deep sleep component this guard switch controls. If not specified, it will control the default deep sleep component. | |
| **guard** (*Optional*, :ref:`Switch <config-switch>`): Configuration for the guard switch: | |
| - **name** (**Required**, string): The name of the switch in Home Assistant | |
| - All other options from :ref:`Switch <config-switch>` are supported (icon, inverted, etc.) | |
| - The switch defaults to OFF (guard disabled) | |
| - When ON, prevents the device from entering deep sleep regardless of other conditions |
WalkthroughThe documentation for the "Deep Sleep Component" has been updated to include new features and configuration options. A new "Deep Sleep Guard" switch has been introduced, which prevents the device from entering deep sleep mode when enabled. This update includes new configuration parameters: Changes
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
components/deep_sleep.rst (3)
196-197: Improve the explanation's structure and formatting.While the explanation is accurate, its readability could be enhanced by structuring it into bullet points or paragraphs. Consider this restructuring:
-You may have calls to deep_sleep.allow or enter from other places which can re-enable deep sleep. An on_value handler based on a periodically checked sensor value (battery level okay: prevent, low: allow), or some other automation from Home Assistant. In that case this can be overriden and the device goes to deep sleep nevertheless. To be absolutely sure, you can use this switch. When enabled and the timer reaches run_duration, deep sleep will be postponed until it is disabled again. Any call to deep_sleep.enter will be ignored, too. +The Deep Sleep Guard switch provides absolute control over deep sleep behavior: + +- It overrides any calls to ``deep_sleep.allow`` or ``deep_sleep.enter`` from other sources (like sensor-based handlers or Home Assistant automations) +- When enabled: + - Deep sleep is postponed if the timer reaches ``run_duration`` + - All calls to ``deep_sleep.enter`` are ignored +- The device will only enter deep sleep when the guard is disabled
198-205: Enhance the code example with more configuration scenarios.The current example shows the basic configuration. Consider adding examples that demonstrate:
switch: - platform: deep_sleep deep_sleep_id: deep_sleep_1 guard: name: Deep Sleep Guard + # Optional configurations + id: deep_sleep_guard_1 + icon: mdi:sleep-off + disabled_by_default: false + + # Example with automation + automation: + - trigger: + platform: mqtt + topic: "device/maintenance_mode" + then: + - switch.turn_on: deep_sleep_guard_1
206-207: Expand the configuration documentation with more details.The configuration documentation could be more comprehensive. Consider adding:
- **deep_sleep_id** (*Optional*, :ref:`config-id`): ID of the deep_sleep component. - - **guard** (*Optional*, switch): This is the switch to guard the device from deep sleep. All properties from sensor, at least the name is required to show up in HA. Defaults to off. + - **guard** (*Optional*, switch): A switch to prevent the device from entering deep sleep mode. + - **name** (**Required**, string): The name of the switch in Home Assistant + - **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this switch + - **icon** (*Optional*, icon): Icon to display. Defaults to ``mdi:sleep-off`` + - **disabled_by_default** (*Optional*, boolean): If true, the switch will be disabled by default. Defaults to ``false``
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
components/deep_sleep.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
components/deep_sleep.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
🔇 Additional comments (1)
components/deep_sleep.rst (1)
196-207: Verify documentation completeness with related PR.
The documentation looks complete and well-structured. However, please verify that all features mentioned in the related esphome PR #7718 are covered in this documentation update.
Description:
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable): esphome/esphome#7718
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/index.rstwhen creating new documents for new components or cookbook.