ESPHome camera availability: why HA showed the panel's camera as unavailable after a restart
Status (2026-11-20): fixed in the library, panel run pending. Home Assistant's ESPHome integration
writes an entity back from "unavailable" only when a state for that entity arrives, and a camera's only
state is an image. The panel sent images only on request, so the camera stayed unavailable until
something asked for one. ApiServer now sends each camera one empty image (no bytes) when a client
subscribes to states.
Device: Pixel Tablet, Glassworks for generic Android 0.2.0 test build (seen by the root, 2026-11-21).
Tools: Home Assistant core dev at 908a1056e3 (2026-10-27), aioesphomeapi 46.25.0 (the version HA
pins).
Question
After the app restarts, HA shows the panel's ESPHome camera entity as unavailable. Reloading the ESPHome
entry doesn't help. One camera_proxy request makes it idle at once. Why, and what is the least the
panel can send to fix it without sending a picture nobody asked for?
What we tried
-
Read HA's ESPHome entity code (2026-11-20, read:
homeassistant/components/esphome/entity.py)_on_entry_data_changedsets_attr_available = entry_data.available, in memory only._on_device_update(called on connect and on disconnect) writes the state only when the device went unavailable: "since_on_state_updatewill be called if the device is available when the full state arrives through the next entity state packet"._on_state_updateis the only other writer, and it runs when a state for the entity's key arrives.
So the written state stays "unavailable" from the disconnect until the entity's own state arrives. Sensors and switches send theirs on
SubscribeStatesRequest. A camera has none. -
Read HA's ESPHome camera (2026-11-20, read:
homeassistant/components/esphome/camera.py)EsphomeCamera._on_state_updatecalls the base one (which writes the state) and resolves pending image requests. Its state type isCameraState, the image bytes. -
Read why a reload doesn't help (2026-11-20, read:
manager.pyon_connect,entry_data.py) On setup, the entities are created from the stored entity list before the device connects, so they are written as unavailable.async_on_connectsetsavailable = True, andasync_update_device_state()calls_on_device_update, which doesn't write. The same holds as for a restart. -
Read how aioesphomeapi turns camera chunks into a state (2026-11-20, read:
aioesphomeapi/client_base.py,on_state_msg) EveryCameraImageResponsechunk is appended to a buffer per key, anddone=TrueemitsCameraState(key, data=bytes(buf)). Nothing checks the length, so an emptydonechunk is a state withdata=b"". -
An empty image on subscribe, against the real client (2026-11-20, verified:
EspHomeActionsCameraTestwith aioesphomeapi 46.25.0) The client subscribes to states and, before any request, gets aCameraStatewith zero bytes. Without the change it gets nothing within 5 s. -
What a real ESPHome camera does (2026-11-20, read: ESPHome
esp32_camera/__init__.py,CONF_IDLE_FRAMERATE)idle_framerate(0.1 fps by default) sends a frame every 10 s to every API client unasked. That is why ESPHome cameras don't stay unavailable. We don't copy it: a picture would leave the panel without a request.
Result
| Claim | Evidence | Confidence |
|---|---|---|
| The entity stays unavailable until its own state arrives | entity.py _on_device_update, _on_state_update |
read |
A camera's state is an image, and an empty done image is a state |
client_base.py on_state_msg |
read, verified with the real client |
| One empty image per camera on subscribe makes HA show it available | the two above | read; panel run pending |
The empty image carries no bytes and doesn't call the camera's frame function, so it needs no privacy
gate: it goes out in Presence only and with privacy on too, and nothing from the camera leaves the
panel. A camera_proxy request still gets the empty image there ("Unable to get image"), as before.
How to reproduce
Off-device, read-only: with a Python 3.11+ venv from libs/esphome-api/test-requirements.txt,
ESPHOME_PYTHON=<venv>/bin/python ./gradlew :esphome-api:test --tests dev.glassworks.esphome.EspHomeActionsCameraTest --rerun
The client's output, with on_subscribe, is in the test report.
Open questions
- Whether HA ever drops the
CameraStatewith empty data in a later version (aioesphomeapi or the camera platform could start ignoring empty images).EspHomeActionsCameraTestwould catch the first.