diff --git a/docs/core/entity/image.md b/docs/core/entity/image.md index 61fb8e4d..44a37311 100644 --- a/docs/core/entity/image.md +++ b/docs/core/entity/image.md @@ -18,20 +18,22 @@ Properties should always only return information from memory and not do I/O (lik | Name | Type | Default | Description | | -------------------| --------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- | | content_type | str | `image/jpeg` | The content-type of the image, set automatically if the image entity provides a URL. | -| image_last_updated | datetime.datetime | None | `None` | Timestamp of when the image was last updated. Used to determine `state`. Frontend will refetch the image when this changes. | +| image_last_updated | datetime.datetime | None | `None` | Timestamp of when the image was last updated. Used to determine `state`. Frontend will call `image` or `async_image` after this changes. | | image_url | str | None | `UNDEFINED` | Optional URL from where the image should be fetched. | ## Methods ### Image -Implement `async_image` or `image` if your entity returns bytes of the image instead of providing a URL. +Implement `async_image` or `image` if your entity returns bytes of the image instead of providing a URL. Frontend will call `async_image` or `image` to fetch the image. If the image is fetched remotely, image data should be cached and the cache invalidated when `image_last_updated` is changed. Note that: - The image entity's `async_image` or `image` method is only called when frontend fetches the image. -- Frontend will only refetch the image when the image entity's state changes. +- Frontend will: + - Fetch the image once when a page with an image entity is loaded + - Refetch the image when the image entity's state changed by the image entity changing `image_last_updated` -This means it's incorrect to bump the `image_last_updated` property inside `async def async_image`. It should instead be done as part of a state update to signal that an updated image is available. +This means it's incorrect to bump the `image_last_updated` property inside `async def async_image`. Instead, the image entity should, when an updated image is available or periodically if the image should be refetched after some time, update the `image_last_updated` timestamp. This can for example happen as part of an entity coordinator update. ```python class MyImage(ImageEntity):