[api] Add new feature changes for Power Management PR 12325

[rwrozelle]

What does this implement/fix?

These are api component changes for the new power_management that enables esp-idf power management. See https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/system/power_management.html

Types of changes

• [ ] Bugfix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [ ] Developer breaking change (an API change that could break external components)
• [ ] Code quality improvements to existing code or addition of tests
• [ ] Other

Related issue or feature (if applicable):

• fixes

Pull request in esphome-docs with documentation (if applicable):

• esphome/esphome-docs#5736

Depends on to use new functionality:

• esphome/esphome#12325

Test Environment

• [ ] ESP32
• [x] ESP32 IDF
• [ ] ESP8266
• [ ] RP2040
• [ ] BK72xx
• [ ] RTL87xx
• [ ] nRF52840

Example entry for config.yaml:

# Example config.yaml

Checklist:

• [x] The code change is tested and works locally.
• [x] Tests have been added to verify that the new code works (under tests/ folder).

If user exposed functionality or configuration variables are added/changed:

• [x] Documentation added/updated in esphome-docs.

[github-actions[bot]]

To use the changes from this PR as an external component, add the following to your ESPHome configuration YAML file:

external_components:
  - source: github://pr#12327
    components: [api]
    refresh: 1h

---

(Added by the PR bot)

[codecov-commenter]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 72.57%. Comparing base (e0ce66e) to head (83a6be4).

Additional details and impacted files

@@            Coverage Diff             @@
##              dev   #12327      +/-   ##
==========================================
- Coverage   72.60%   72.57%   -0.03%     
==========================================
  Files          53       53              
  Lines       11192    11192              
  Branches     1517     1517              
==========================================
- Hits         8126     8123       -3     
- Misses       2674     2676       +2     
- Partials      392      393       +1     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions[bot]]

Memory Impact Analysis

Components: api Platform: esp8266-ard

Metric	Target Branch	This PR	Change
RAM	33,588 bytes	33,588 bytes	➡️ +0 bytes (0.00%)
Flash	452,447 bytes	452,447 bytes	➡️ +0 bytes (0.00%)

---

Note: This analysis measures static RAM and Flash usage only (compile-time allocation). Dynamic memory (heap) cannot be measured automatically. ⚠️ You must test this PR on a real device to measure free heap and ensure no runtime memory issues.

This analysis runs automatically when components change. Memory usage is measured from a representative test configuration.

[luar123]

Are you sure this is needed? Wifi and websockets should work with power management.

[rwrozelle]

Are you sure this is needed? Wifi and websockets should work with power management.

I built this based on openthread where tasks were not completing (device was going to sleep) and not finishing until next polling cycle. I'm looking for collaborators to flesh this out. https://discord.com/channels/429907082951524364/1446957955156021258 My thinking is that power_management component is robust enough to help with openthread light sleep use cases and if an audience could be found for wifi/ethernet, we could improve via future PR's. I separated these API changes because it is most likely this PR of the api component would end up back in draft while it is improved.

[luar123]

In #12325 I stated that api works without this PR, but that might be only true for wifi. If sleep mode in thread is implemented like it is in the zigbee sdk, then there might be the issue that the thread task activates sleep mode even if other tasks could still run and only locks can prevent this. If that is true maybe guard the locks here with USE_OPENTHREAD.

Edit: quick test with the zigbee light sleep example suggests that at least there it is no issue.

[rwrozelle]

I will go back and test esp32-h2 openthread without this PR and see if its functional without.

[rwrozelle]

Closing request, functionality is no longer needed.