From 70844ae59046edc506f763b8dfaca2cdb4c32c1b Mon Sep 17 00:00:00 2001 From: David Friedland Date: Tue, 18 Nov 2025 19:09:31 -0800 Subject: [PATCH 1/2] light: document transition_state_publish_interval guidance --- content/components/light/_index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/components/light/_index.md b/content/components/light/_index.md index 910c1d87e7..76207eeed0 100644 --- a/content/components/light/_index.md +++ b/content/components/light/_index.md @@ -44,6 +44,14 @@ light: - **flash_transition_length** (*Optional*, [Time](/guides/configuration-types#time)): The transition length to use when flash is called. Defaults to `0s`. +- **transition_state_publish_interval** (*Optional*, [Time](/guides/configuration-types#time)): How often to publish state updates while a transition or flash is in progress. + + - `0s` (default) – interval publishing is disabled. No extra state updates are scheduled during a transition or flash because of this option. Home Assistant and other consumers typically only see the final result of the transition or flash, not the intermediate progress. + + - Values `>0` – interval publishing is enabled. The starting state is published at the beginning of the transition or flash, intermediate states are published roughly every `transition_state_publish_interval` while it is running, and a final state is published at the end. If the light call includes `save: true`, the stored state is updated when the transition finishes instead of on each intermediate update. + + Shorter intervals create more frequent publishes and therefore more network and CPU load. In testing on ESP8266-class devices, values below about `150ms` rarely produce smoother visible transitions but can generate a large number of API/MQTT updates and push the device toward its CPU limits. For ESP8266-class devices, defaults in the range of `200ms` to `250ms` (around 4–5 Hz) generally provide smooth updates without excessive overhead. + - **initial_state** (*Optional*): The initial state the light should be set to on bootup. This state will be applied when the state is **not** restored based on `restore_mode` (below). From b4b8827928e1039d4853faf21f1841e9c073d20a Mon Sep 17 00:00:00 2001 From: David Friedland Date: Tue, 18 Nov 2025 19:58:28 -0800 Subject: [PATCH 2/2] Update content/components/light/_index.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- content/components/light/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/light/_index.md b/content/components/light/_index.md index 76207eeed0..c003bfbc9d 100644 --- a/content/components/light/_index.md +++ b/content/components/light/_index.md @@ -50,7 +50,7 @@ light: - Values `>0` – interval publishing is enabled. The starting state is published at the beginning of the transition or flash, intermediate states are published roughly every `transition_state_publish_interval` while it is running, and a final state is published at the end. If the light call includes `save: true`, the stored state is updated when the transition finishes instead of on each intermediate update. - Shorter intervals create more frequent publishes and therefore more network and CPU load. In testing on ESP8266-class devices, values below about `150ms` rarely produce smoother visible transitions but can generate a large number of API/MQTT updates and push the device toward its CPU limits. For ESP8266-class devices, defaults in the range of `200ms` to `250ms` (around 4–5 Hz) generally provide smooth updates without excessive overhead. + Shorter intervals create more frequent publishes and therefore more network and CPU load. In testing on ESP8266-class devices, values below about `150ms` rarely produce smoother visible transitions but can generate a large number of API/MQTT updates and push the device toward its CPU limits. For ESP8266-class devices, recommended values in the range of `200ms` to `250ms` (around 4–5 Hz) generally provide smooth updates without excessive overhead. - **initial_state** (*Optional*): The initial state the light should be set to on bootup. This state will be applied when the state is **not** restored based on `restore_mode` (below).