From 163a5ef81dee402501183a93e886f73cfd160fc0 Mon Sep 17 00:00:00 2001 From: Flo Date: Fri, 14 Nov 2025 16:56:47 +0100 Subject: [PATCH 01/15] Update api.md with API connection check example Added YAML example for API connection check and configuration variable details. --- content/components/api.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/content/components/api.md b/content/components/api.md index 65c2a6bcb2..5cebc2d812 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -389,6 +389,18 @@ This [Condition](/automations/actions#all-conditions) checks if at least one cli native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output if logs are shown remotely. +```yaml +on_...: + if: + condition: + api.connected: + homeassistant_only: False + then: + - logger.log: API is connected! +``` + +The lambda equivalent for this is `id(api_id).is_connected(true)`. + ```yaml on_...: if: @@ -400,6 +412,11 @@ on_...: The lambda equivalent for this is `id(api_id).is_connected()`. +#### Configuration variables + +- **homeassistant_only** (*Optional*, boolean): If enabled, the condition checks for Home Assistant clients only. + Defaults to `false`. + {{< anchor "api-device-actions" >}} ## User-defined Actions From a2ab4cc4dc646503aba813ba67b5424d9bd3dd7d Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 14:13:34 +0100 Subject: [PATCH 02/15] Change header level for Configuration variables section --- content/components/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/api.md b/content/components/api.md index 5cebc2d812..7927eba5ef 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -412,7 +412,7 @@ on_...: The lambda equivalent for this is `id(api_id).is_connected()`. -#### Configuration variables +### Configuration variables - **homeassistant_only** (*Optional*, boolean): If enabled, the condition checks for Home Assistant clients only. Defaults to `false`. From 43284c13f4376349f45c0783f5f964e53fef4535 Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 14:18:45 +0100 Subject: [PATCH 03/15] Refactor API conditions documentation Updated formatting and structure of API conditions section. --- content/components/api.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/components/api.md b/content/components/api.md index 7927eba5ef..f7a93119f9 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -381,9 +381,11 @@ api: - logger.log: "API client disconnected!" ``` +## Conditions + {{< anchor "api-connected_condition" >}} -## `api.connected` Condition +### `api.connected` Condition This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output @@ -412,7 +414,7 @@ on_...: The lambda equivalent for this is `id(api_id).is_connected()`. -### Configuration variables +#### Configuration variables - **homeassistant_only** (*Optional*, boolean): If enabled, the condition checks for Home Assistant clients only. Defaults to `false`. From 965d70310e33fe7a25649679f527266748e5b954 Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 14:25:59 +0100 Subject: [PATCH 04/15] Clarify api.connected condition and logging messages --- content/components/api.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/content/components/api.md b/content/components/api.md index f7a93119f9..d31a64ecf3 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -388,31 +388,32 @@ api: ### `api.connected` Condition This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome -native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output -if logs are shown remotely. +native API. Please note `client` refers to any connection to the API, including Home Assistant, ESPHome's remote log viewer, and other API consumers. +Check if any client is connected: ```yaml on_...: if: condition: api.connected: - homeassistant_only: False then: - - logger.log: API is connected! + - logger.log: Client is connected to API! ``` -The lambda equivalent for this is `id(api_id).is_connected(true)`. +The lambda equivalent for this is `id(api_id).is_connected()`. +Check if Home Assistant specifically is connected: ```yaml on_...: if: condition: api.connected: + homeassistant_only: True then: - - logger.log: API is connected! + - logger.log: Home Assistant is connected to API! ``` -The lambda equivalent for this is `id(api_id).is_connected()`. +The lambda equivalent for this is `id(api_id).is_connected(true)`. #### Configuration variables From c1893bea1abd5dd9a29133ff990edaf3701e83f5 Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 14:32:15 +0100 Subject: [PATCH 05/15] Update api.md with client connection checks Added examples for checking client connections to the ESPHome API. --- content/components/api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/components/api.md b/content/components/api.md index d31a64ecf3..a21683f8ef 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -391,6 +391,7 @@ This [Condition](/automations/actions#all-conditions) checks if at least one cli native API. Please note `client` refers to any connection to the API, including Home Assistant, ESPHome's remote log viewer, and other API consumers. Check if any client is connected: + ```yaml on_...: if: @@ -403,6 +404,7 @@ on_...: The lambda equivalent for this is `id(api_id).is_connected()`. Check if Home Assistant specifically is connected: + ```yaml on_...: if: From 50694f6700270e51b1565f6b176056cca0bb2b6c Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 14:39:46 +0100 Subject: [PATCH 06/15] Update api.md From 4857e53be08e9c555a2ddac55dcffb15ad75e3fb Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 14:54:42 +0100 Subject: [PATCH 07/15] Update api.md --- content/components/api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/components/api.md b/content/components/api.md index a21683f8ef..03b5ad31cc 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -403,23 +403,23 @@ on_...: The lambda equivalent for this is `id(api_id).is_connected()`. -Check if Home Assistant specifically is connected: +Check if a client with state subscription (Home Assistant, Node-RED library) is connected: ```yaml on_...: if: condition: api.connected: - homeassistant_only: True + state_subscription_only: True then: - - logger.log: Home Assistant is connected to API! + - logger.log: Client with state subscription is connected to API! ``` The lambda equivalent for this is `id(api_id).is_connected(true)`. #### Configuration variables -- **homeassistant_only** (*Optional*, boolean): If enabled, the condition checks for Home Assistant clients only. +- **state_subscription_only** (*Optional*, boolean): If enabled, the condition checks for clients with state subscription (Home Assistant, Node-RED library) only. Defaults to `false`. {{< anchor "api-device-actions" >}} From 2b1b2402d8df3a7f76e3a6a2a9aeac490d2b5ea7 Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 17:03:27 +0100 Subject: [PATCH 08/15] Apply suggestion from @bdraco Co-authored-by: J. Nick Koston --- content/components/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/api.md b/content/components/api.md index 03b5ad31cc..da5b76638a 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -387,7 +387,7 @@ api: ### `api.connected` Condition -This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome +This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome native API. native API. Please note `client` refers to any connection to the API, including Home Assistant, ESPHome's remote log viewer, and other API consumers. Check if any client is connected: From f73b0a2444ee4dae09565c5c355a5813969192f4 Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 17:04:11 +0100 Subject: [PATCH 09/15] Apply suggestion from @bdraco Co-authored-by: J. Nick Koston --- content/components/api.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/components/api.md b/content/components/api.md index da5b76638a..c8bb5beb8c 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -388,10 +388,11 @@ api: ### `api.connected` Condition This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome native API. -native API. Please note `client` refers to any connection to the API, including Home Assistant, ESPHome's remote log viewer, and other API consumers. ++#### Configuration variables -Check if any client is connected: +- **state_subscription_only** (*Optional*, boolean): If enabled, only counts clients that have subscribed to entity tate updates. This filters out logger-only connections (such as `esphome logs` command), which can cause false ositives when waiting for Home Assistant. Defaults to `false`. +**Check if any client is connected:** ```yaml on_...: if: From 969f77448eb00f0e7d8a4e1b86b5ffda2413dae2 Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 17:04:37 +0100 Subject: [PATCH 10/15] Apply suggestion from @bdraco Co-authored-by: J. Nick Koston --- content/components/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/api.md b/content/components/api.md index c8bb5beb8c..0c0b4bb724 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -404,7 +404,7 @@ on_...: The lambda equivalent for this is `id(api_id).is_connected()`. -Check if a client with state subscription (Home Assistant, Node-RED library) is connected: +**Check if a client subscribed to entity states is connected (typically Home Assistant):** ```yaml on_...: From a7f0903ed85d6523e57cfc0e584a11ced947facb Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 17:04:51 +0100 Subject: [PATCH 11/15] Apply suggestion from @bdraco Co-authored-by: J. Nick Koston --- content/components/api.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/content/components/api.md b/content/components/api.md index 0c0b4bb724..38de428033 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -407,13 +407,14 @@ The lambda equivalent for this is `id(api_id).is_connected()`. **Check if a client subscribed to entity states is connected (typically Home Assistant):** ```yaml -on_...: - if: - condition: - api.connected: - state_subscription_only: True - then: - - logger.log: Client with state subscription is connected to API! +on_boot: + - wait_until: + condition: + api.connected: + state_subscription_only: true + - logger.log: Home Assistant is connected! + - homeassistant.event: + event: esphome.device_booted ``` The lambda equivalent for this is `id(api_id).is_connected(true)`. From 6d1ecd176aadd0e5512328ec669df7c99b03ffc1 Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 17:05:46 +0100 Subject: [PATCH 12/15] Apply suggestion from @bdraco Co-authored-by: J. Nick Koston --- content/components/api.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/content/components/api.md b/content/components/api.md index 38de428033..3e9a799a22 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -419,11 +419,10 @@ on_boot: The lambda equivalent for this is `id(api_id).is_connected(true)`. -#### Configuration variables - -- **state_subscription_only** (*Optional*, boolean): If enabled, the condition checks for clients with state subscription (Home Assistant, Node-RED library) only. - Defaults to `false`. - +**Use Cases:** + +- Use `state_subscription_only: false` (default) to detect any API connection +- Use `state_subscription_only: true` when you need to ensure Home Assistant (or other connections that subscribe to states) is connected before sending events or calling services, preventing errors from logger-only connections {{< anchor "api-device-actions" >}} ## User-defined Actions From ff33fefd842f23eaa9d26a30e921cfe61392e193 Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 17:09:19 +0100 Subject: [PATCH 13/15] Fix typos Corrected typos and improved clarity in the api.md documentation. --- content/components/api.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/components/api.md b/content/components/api.md index 3e9a799a22..8dbe4c2957 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -388,9 +388,10 @@ api: ### `api.connected` Condition This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome native API. -+#### Configuration variables -- **state_subscription_only** (*Optional*, boolean): If enabled, only counts clients that have subscribed to entity tate updates. This filters out logger-only connections (such as `esphome logs` command), which can cause false ositives when waiting for Home Assistant. Defaults to `false`. +#### Configuration variables + +- **state_subscription_only** (*Optional*, boolean): If enabled, only counts clients that have subscribed to entity state updates. This filters out logger-only connections (such as `esphome logs` command), which can cause false positives when waiting for Home Assistant. Defaults to `false`. **Check if any client is connected:** ```yaml @@ -423,6 +424,7 @@ The lambda equivalent for this is `id(api_id).is_connected(true)`. - Use `state_subscription_only: false` (default) to detect any API connection - Use `state_subscription_only: true` when you need to ensure Home Assistant (or other connections that subscribe to states) is connected before sending events or calling services, preventing errors from logger-only connections + {{< anchor "api-device-actions" >}} ## User-defined Actions From e619411e30e88743186fe858c48d4f766d549e3e Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 17:10:07 +0100 Subject: [PATCH 14/15] Update api.md with state_subscription_only details Added a note about the 'state_subscription_only' option and its default value. --- content/components/api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/components/api.md b/content/components/api.md index 8dbe4c2957..0636f077b5 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -394,6 +394,7 @@ This [Condition](/automations/actions#all-conditions) checks if at least one cli - **state_subscription_only** (*Optional*, boolean): If enabled, only counts clients that have subscribed to entity state updates. This filters out logger-only connections (such as `esphome logs` command), which can cause false positives when waiting for Home Assistant. Defaults to `false`. **Check if any client is connected:** + ```yaml on_...: if: From 3a22b94f7344ba6c32db975475d1aa1619ad24bf Mon Sep 17 00:00:00 2001 From: Flo Date: Sat, 15 Nov 2025 17:15:46 +0100 Subject: [PATCH 15/15] update --- content/components/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/api.md b/content/components/api.md index 0636f077b5..65ea37e9c0 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -422,7 +422,7 @@ on_boot: The lambda equivalent for this is `id(api_id).is_connected(true)`. **Use Cases:** - + - Use `state_subscription_only: false` (default) to detect any API connection - Use `state_subscription_only: true` when you need to ensure Home Assistant (or other connections that subscribe to states) is connected before sending events or calling services, preventing errors from logger-only connections