[flowcool]

Behavior

Port fork PR17 / infra-3rr.59. Wait at boot399 for a state subscriber for at most10s. A logs-only client does not release it. Sample the battery first and bypass the optional wait at/belowcritical or while protection stays latched. Preserve offline acquisition, staging finite checks, calibration and MQTT behavior.

Target: flowcool/Smart_Plant:upstream/staging-v2r1. Source ad385e9, predecessor 408de7b. Open after the preceding contribution merges so this PR contains only its owned change. The upstream baseline is bcf373144b2d5c7e3a712fd02698e2e98e45aeed. No PR to JGAguado is authorized.

Verification

Nine exact ESPHome2026.9.0 C++/actual-YAML API tests pass. Complete isolated API firmware build passes, hash0xa3d8d4f1; MQTT configuration validates. Integrated offline suite passes. No real network or HA delivery claim.

Inspect the semantic diff and git -c core.whitespace=cr-at-eol diff --check; preserve existing line endings. All tracked YAML parses. Firmware fixtures use local fonts/public images and synthetic credentials, never devices or shared builders. Local compilation does not prove deployment.

Rollback: revert this isolated PR on staging. No automatic deployment, fleet/NAS/cache purge/MQTT/HA action.

AI assistance

Codex prepared the port or extraction. The author inspected the behavior, contribution boundary, actual-source tests, compatibility and diff. Existing staging OTA confirmation and native shutdown remain intact.

CodeRabbit review

Require current-head completed review and yaml-syntax before merge. Florent approved one manual review request per ignored PR for this series only. Documentation-only PRs use the standing docs gate. Record review/head/checks/merge in owner infra-3rr.65.

Summary by CodeRabbit

• Nouvelles fonctionnalités

  • L’initialisation peut désormais attendre la disponibilité d’un abonnement d’état API avant de poursuivre.
  • Cette attente est limitée à 10 secondes par défaut et s’adapte à l’état de la batterie, notamment en cas de niveau critique ou invalide.
  • Les acquisitions, l’affichage et la mise en veille restent indépendants de cette attente.

• Documentation

  • Ajout d’une documentation détaillant le comportement de l’attente API, les scénarios liés à la batterie et les limites de livraison.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: ef4c5aef-1ba4-4058-824a-5f98215b62a3

📥 Commits

Reviewing files that changed from the base of the PR and between 79cc98c and ad385e9.

📒 Files selected for processing: 4

• docs/api-wake-window.md
• examples/multi-device/packages/smart_plant_profile_api.yaml
• tests/display_automation.py
• tests/test_api_boot.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

📜 Recent review details

🧰 Additional context used

📚 Code guidelines: 2

.claude/rules/esphome-yaml.md — auto-discovered
AGENTS.md — auto-discovered

📓 Path-based instructions: 2

Source excerpt: `use_address` must be in the `wifi:` block of the device YAML, not only in `substitutions:` — the ESPHome CLI reads YAML without resolving packages.

📄 CodeRabbit inference engine (.claude/rules/esphome-yaml.md)

Files:

• examples/multi-device/packages/smart_plant_profile_api.yaml

Source excerpt: Parse changed YAML and run `git diff --check`; inspect both `git diff --numstat` and the semantic diff before committing.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• examples/multi-device/packages/smart_plant_profile_api.yaml

🪛 ast-grep (0.45.3)

tests/test_api_boot.py

[error] 167-168: Command coming from incoming request
Context: subprocess.run([shutil.which("g++") or "g++", "-std=c++17", str(cpp), "-o", str(cls.executable)],
check=True, capture_output=True, text=True)
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(subprocess-from-request)

[error] 171-174: Command coming from incoming request
Context: subprocess.run([str(self.executable), str(self.timeout), str(subscribed_at),
str(disconnected_at), str(int(connected)), str(int(self.subscription_only)),
str(battery), str(int(valid)), str(int(latched))],
check=True, capture_output=True, text=True, timeout=5)
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(subprocess-from-request)

🪛 OpenGrep (1.30.1)

tests/test_api_boot.py

[ERROR] 136-136: yaml.load() without SafeLoader can execute arbitrary Python code. Use yaml.safe_load() or yaml.load(..., Loader=SafeLoader) instead.

(coderabbit.deserialization.python-yaml-unsafe-load)

🪛 Ruff (0.16.9)

tests/test_api_boot.py

[error] 136-136: Probable use of unsafe loader PackageLoader with yaml.load. Allows instantiation of arbitrary objects. Consider yaml.safe_load.

(S506)

[error] 167-167: subprocess call: check for execution of untrusted input

(S603)

[error] 171-171: subprocess call: check for execution of untrusted input

(S603)

🔇 Additional comments: 4

docs/api-wake-window.md: 1

1-54: LGTM!

examples/multi-device/packages/smart_plant_profile_api.yaml: 1

9-11: LGTM!

Also applies to: 24-40

tests/display_automation.py: 1

188-188: LGTM!

Also applies to: 212-215

tests/test_api_boot.py: 1

1-215: LGTM!

Walkthrough

Le profil échantillonne la batterie au démarrage, puis applique une politique conditionnelle d’attente d’un abonnement d’état API. Cette attente est limitée par un délai configurable de 10 secondes par défaut. Une suite de tests simule les scénarios de batterie, d’abonnement et de délai.

Changes

Amorçage API

Layer / File(s)	Summary
Politique d’attente au démarrage examples/multi-device/packages/smart_plant_profile_api.yaml, tests/display_automation.py, docs/api-wake-window.md	Le profil attend l’échantillonnage de la batterie avant d’évaluer l’attente API. L’attente utilise les abonnements d’état et le délai api_connection_timeout, fixé à 10s par défaut. Le runtime de test accepte api.connected uniquement avec state_subscription_only: True. La documentation décrit les seuils, les délais et le comportement en cas de déconnexion ou d’absence de connexion.
Simulation et validation des scénarios tests/test_api_boot.py	La suite exige ESPHome 2026.9.0, extrait des implémentations installées et compile une simulation C++. Les tests couvrent l’acquisition immédiate ou différée, l’expiration du délai, les déconnexions et plusieurs états de batterie.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant ProfilAPI
  participant Batterie
  participant ConditionAPI
  participant ClientAPI
  ProfilAPI->>Batterie: Échantillonne puis attend sample_battery
  ProfilAPI->>ProfilAPI: Évalue la politique de batterie
  ProfilAPI->>ConditionAPI: Attend un abonnement d’état jusqu’au délai maximal
  ClientAPI->>ConditionAPI: Établit un abonnement d’état
  ConditionAPI-->>ProfilAPI: Signale l’état de la condition

Loading

Poème

Un lapin suit la batterie au matin,
Puis guette l’abonnement sur son chemin.
Dix secondes bornent cette attente,
Les tests font varier chaque étape.
Le lapin bondit, le démarrage avance.

Poème

Le lapin vérifie la batterie au matin,
Puis attend l’abonnement si la règle le permet.
Dix secondes bornent l’attente API,
Les tests couvrent chaque scénario,
Le démarrage poursuit son chemin.

Poème

Le lapin vérifie la batterie au matin,
Il attend l’abonnement si la règle le permet.
Dix secondes bornent l’attente API,
Les tests couvrent chaque scénario,
Le démarrage reprend son cours.

Merge Risk: ⚪ Minimal · up to ad385

The subscriber wait is bounded, and no merge-blocking issue was identified. Merge after the requested normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 2 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		Le titre est court, clair et décrit le changement principal : attendre la disponibilité d’un abonnement API avant la poursuite du démarrage.
Description check		La description contient les sections requises « Behavior », « Verification », « AI assistance » et « CodeRabbit review ». Elle décrit le comportement, les vérifications, les limites et la stratégie de…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

La description contient les sections requises « Behavior », « Verification », « AI assistance » et « CodeRabbit review ». Elle décrit le comportement, les vérifications, les limites et la stratégie de retour arrière. Les détails de commande, de résultat attendu et de preuve CodeRabbit restent peu structurés ou non renseignés, mais l’ensemble est suffisamment complet.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 2 files. (2 skipped: 2 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}