[flowcool]

Summary

Make the native-API profile wait for a Home Assistant state subscriber before its full acquisition, so a short wake does not measure and sleep before the first client can receive the readings.

boot -> battery sample -> low-battery bypass? -> wait for state subscriber (max api_connection_timeout)
                                              -> acquire once -> display -> sleep

The wait runs at boot priority 399, after sensor setup (600) and display setup (400), and is asynchronous: Wi-Fi setup at priority 250 proceeds while it is pending. api_connection_timeout bounds it (default 10 s). The condition is api.connected: {state_subscription_only: true}, so a client that only requests logs does not release the wait. Acquisition then runs once, on subscription or on timeout.

The wait is optional network time, so it is skipped under critical battery or a restored low-battery latch until a valid reading reaches the exit threshold. A missing reading keeps the bypass when the latch is set and the bounded wait otherwise. The MQTT profile and the shared core sequence do not change. docs/api-wake-window.md documents the sequence.

Evidence

• Before: the API profile acquires at boot without waiting for a subscriber.
  After: 88 tests pass on current upstream V2R1 (79 existing + 9 new in tests/test_api_boot.py). They execute the real package actions for early and late subscribers, a logs-only client, no Home Assistant (single acquisition after timeout), a disconnect during acquisition, critical battery, a restored latch with and without a valid exit reading, and an unavailable battery.
• esphome config docs/source/files/configuration.yaml and scripts/validate_public_examples.py pass with ESPHome 2026.9.0 (the same steps as CI), using synthetic secrets. The new condition is accepted by that release's schema.
• The change adds one file of tests and one document, and touches the API profile and the shared test helper only. YAML parses and original line endings are preserved.
• Not claimed: no firmware build was run for this PR, and no device, broker, Home Assistant instance or build server was contacted. Tests do not prove real subscription timing on hardware.

Merge Danger

Door: two-way. Revert this PR; it does not touch the core or the MQTT profile. A source revert does not deploy firmware.

Blast Radius: firmware, API profile only. Affects users who later adopt this package: wake time can grow by up to api_connection_timeout (default 10 s) when no client subscribes, which costs battery on devices that wake with no Home Assistant reachable. The low-battery bypass limits that cost near depletion. No deployment is included.

AI assistance: Claude Code rebased and validated this contribution on current V2R1. Upstream review is requested; local tests do not constitute maintainer approval.

🤖 Generated with Claude Code

https://claude.ai/code/session_017fn1KdJJTY7LedVqZ7SxcA