The integration implements a single custom service retry.call
. This service warps an inner service call with background retries on failure. It can be useful to mitigate temporary issues of connectivity or invalid device states.
For example, instead of:
service: homeassistant.turn_on
target:
entity_id: light.kitchen
The following should be used:
service: retry.call
data:
service: homeassistant.turn_on
target:
entity_id: light.kitchen
The service
parameter (inside the data
section) supports templates. It's possible to add any other data parameters needed by the inner service call.
The inner service call will get called again if one of the following happens:
- The inner service call raised an exception.
- One of the target entities is unavailable. Note that this is important since HA silently skips unavailable entities (here).
By default there are 7 retries. It can be changed by passing the optional parameter retries
:
service: retry.call
data:
service: homeassistant.turn_on
retries: 10
target:
entity_id: light.kitchen
The retries
parameter is not passed to the inner service call.
The service implements exponential backoff mechanism. These are the delay times of the first 7 attempts: [0, 1, 2, 4, 8, 16, 32] (each delay is twice than the previous one). The following are the offsets from the initial call [0, 1, 3, 7, 15, 31, 63].
expected_state
is another optional parameter which can be used to validate the new state of the entities after the inner service call:
service: retry.call
data:
service: homeassistant.turn_on
expected_state: "on"
target:
entity_id: light.kitchen
If the new state is different than expected, the attempt is considered a failure and the loop of retries continues. The expected_state
parameter supports templates, and is not passed to the inner service call.
Notes:
- The service does not propagate inner service failures (exceptions) since the retries are done in the background. However, the service logs a warning when the inner function fails (on every attempt). It also logs an error when the maximum amount of retries is reached.
- This service can be used for absolute state changes (like turning on the lights). But it has limitations by nature. For example, it shouldn't be used for sequence of actions, when the order matters.
HACS is the preferred and easier way to install the component, and can be done by using this My button:
Otherwise, download retry.zip
from the latest release, extract and copy the content under custom_components
directory.
Home Assistant restart is required once the integration files were copied (either by HACS or manually).
Adding Retry integration to your Home Assistant instance can be done via the user interface, by using this My button:
It's also possible to add the integration via configuration.yaml
by adding the single line retry:
.
If you want to contribute to this please read the Contribution guidelines