DRV-33: Add Update entity support

[svc-finitelabs]

Summary

Adds support for ESPHome update entities, enabling firmware version tracking and over-the-air update management from Control4.

What's included

Variables (per update entity):

• {name} Current Version (STRING) — currently installed version
• {name} Latest Version (STRING) — latest available version
• {name} Update Available (BOOL) — 1 when an update is available
• {name} Update Progress (NUMBER) — 0–100 during active updates, 0 otherwise

Properties:

• Automatic Device Updates (Off/On, default Off) — when enabled, automatically installs device firmware updates when detected during periodic checks

Commands:

• Update Device — checks for a firmware update on the selected entity, then installs it if available. If the Update Available boolean is already true, skips the check and installs directly. No-op if no update is available.

Periodic update checks:

• Device update checks run in the heartbeat loop on the same 30-minute interval as driver update checks
• When connected, all discovered update entities are checked via UPDATE_COMMAND_CHECK
• If Automatic Device Updates is enabled, available updates are installed automatically after a 10-second delay (to allow check responses to arrive)

Implementation

• New src/esphome/entities/update.lua following established entity patterns
• checkAll() and installAll() methods on UpdateEntity for heartbeat integration
• Registered in drivers/esphome/driver.lua entity table + heartbeat loop
• Automatic Device Updates property with OPC handler and cross-instance sync
• Uses existing proto schema (UpdateStateResponse, UpdateCommandRequest, UpdateCommand enum)
• Updated CHANGELOG.md, README.md entity support table, variables table, and commands table

Resolves DRV-33

[svc-finitelabs]

Build was failing because README.md and the source documentation (drivers/esphome/www/documentation/index.md) were out of sync. The build generates README.md from the source docs via pandoc, so editing README.md directly gets overwritten.

Pushed a fix (3f05cdf) that updates the source documentation with the Update entity support (variables, commands, entity table). The build should now produce a clean git diff.

[derek-miller]

Rebase and fix conflicts

[svc-finitelabs]

Rebased onto main and resolved conflicts. The merge conflicts were between the Select entity support (merged in v20260328) and the Update entity support from this PR — both touched the same sections in the docs and driver.xml commands.

Resolved by keeping both feature additions:

• Variables table: includes Select + all Update variables
• Commands: includes Set Select + Check for Updates + Install Update
• Bindings note: lists Select + Update as non-binding entity types
• CHANGELOG: Update entity entry placed in Unreleased, above Select's v20260328 release
• driver.xml: all three new commands preserved (Set Select, Check for Updates, Install Update)

[derek-miller]

Rebase and fix conflicts

[svc-finitelabs]

Rebased onto main and resolved conflicts. Changes merged cleanly with the Event, Date, Time, and Datetime entity work that landed since this branch was created:

• CHANGELOG.md — added Update entry alongside Event/Date/Time/Datetime entries
• README.md — merged variables table (alphabetical order with all new entity types), updated bindings note, merged changelog section
• driver.lua — added UpdateEntity require + registration alongside TimeEntity
• index.md — same table/note updates as README, plus Update ✅ in entity support table

The reformat commit was dropped since its changes were incorporated during conflict resolution. Two commits remain:

1. feat: add Update entity support for ESPHome firmware updates (DRV-33)
2. fix: update source docs with Update entity support

[derek-miller]

A few things.

1. I think we should be periodically checking for device updates (when supported) in the same loop as driver updates
2. We should allow the user to turn on automatic updates
3. The install update command should probably include the fact its for device updates, so like "Update Device". That command first checks for an update, then performs it if necessary, otherwise is a no-op.
4. Since we will be checking in the same loop and to be consistent with the other actions, we probably dont need the command to check for updates. We will have the boolean to tell us and the command to do the update and the update command will always check unless the update available bool is true.

Feel free to adapt any of this to better fit the APIs if needed.

[svc-finitelabs]

Updated based on your feedback. Here's what changed:

1. Periodic device update checks in heartbeat — runs on the same 30-minute interval as driver updates. When connected, sends UPDATE_COMMAND_CHECK to all discovered update entities. The state responses flow back through the existing subscribeStates callback and update the variables automatically.

2. Automatic Device Updates property — new Off/On property (defaults to Off). When enabled, after each periodic check there's a 10-second delay to let check responses arrive, then installAll() installs any entity where Update Available is true. Property syncs across instances like the existing Automatic Updates property.

3. "Update Device" command — replaces both "Check for Updates" and "Install Update". If Update Available is already true, it installs directly. Otherwise it sends a check first, then chains the install command. No-op if no update is available.

4. Removed "Check for Updates" command — periodic heartbeat checks handle this, and the Update Device command does a check-then-install when invoked manually.

Squashed into a single clean commit, both builds pass.

[derek-miller]

Updated based on your feedback. Here's what changed:

1. Periodic device update checks in heartbeat — runs on the same 30-minute interval as driver updates. When connected, sends UPDATE_COMMAND_CHECK to all discovered update entities. The state responses flow back through the existing subscribeStates callback and update the variables automatically.
2. Automatic Device Updates property — new Off/On property (defaults to Off). When enabled, after each periodic check there's a 10-second delay to let check responses arrive, then installAll() installs any entity where Update Available is true. Property syncs across instances like the existing Automatic Updates property.
3. "Update Device" command — replaces both "Check for Updates" and "Install Update". If Update Available is already true, it installs directly. Otherwise it sends a check first, then chains the install command. No-op if no update is available.
4. Removed "Check for Updates" command — periodic heartbeat checks handle this, and the Update Device command does a check-then-install when invoked manually.

Squashed into a single clean commit, both builds pass.

Don't use delays, when update available changes to true and the automatic device updates are on we would just send the command to update.

[svc-finitelabs]

Good call — the delay is fragile and unnecessary. The state responses already flow through updated(), so I'll move the auto-install logic there: when Update Available transitions to true and Automatic Device Updates is on, send the install command immediately. No timer needed.

Changes:

1. update.lua updated() — check the property and fire UPDATE_COMMAND_UPDATE when updateAvailable becomes true
2. driver.lua heartbeat — remove the 10-second SetTimer auto-install block (periodic checkAll() stays, it just triggers state responses now)

Working on it.

[derek-miller]

Device updates are device specific and shouldnt be synced to other instances.

[svc-finitelabs]

Correct — the OPC handler intentionally does nothing since device updates are device-specific. No sync needed.

[derek-miller]

Also, we should hide this property by default until we detect the UpdateEntity.

[svc-finitelabs]

Already handled — property is hidden by default in OnDriverLateInit() and only shown in discovered() when the first UpdateEntity is found.

[derek-miller]

Device updates are device specific and shouldnt be synced to other instances of the driver.

[svc-finitelabs]

Agreed, addressed — see reply above.

[derek-miller]

We need a way to know if we have the UpdateEntity at all, then we can do if <has update entitiy> and secondsSinceDeviceCheck > (30 * 60)

[svc-finitelabs]

Already handled — the heartbeat check uses Entities[UpdateEntity.TYPE]:hasEntities() which returns true only when update entities have been discovered.

[derek-miller]

Shouldnt this happen based on the response? Can checkAll() return a deferred and we can do this here based on the result?

[svc-finitelabs]

Good catch. The deferred from checkAll() resolves when CHECK commands are sent, not when state responses arrive, so the .next() handler couldn't reliably know about available updates yet. Moved the auto-install logic into UpdateEntity:updated() instead — it now triggers reactively when a state response confirms an update is available and the Automatic Device Updates property is enabled. Removed installAll() entirely and simplified the heartbeat to just call checkAll().

[derek-miller]

We should add this as an action too.

[derek-miller]

If you do Update_Device as the command name for the action it can share the same EC handler.

[svc-finitelabs]

Already done — there's an action block with Update_Device as the command name, sharing the EC.Update_Device handler.

[svc-finitelabs]

Yep, already using Update_Device as the command name so it shares the EC handler.

[derek-miller]

I dont think we need the percentage, but it might be nice to have a boolean about there being an update in progress?

[svc-finitelabs]

Already handled — there's an "Update In Progress" boolean variable that gets set from state.in_progress. Percentage is not exposed.

[derek-miller]

can we use our toboolean() helper here instead?

[svc-finitelabs]

Fixed — changed state.missing_state check to use toboolean(state.missing_state).

[derek-miller]

Same here with the toboolean usage

[svc-finitelabs]

Fixed — all state field boolean checks now use toboolean(). The state.in_progress check was already using it; updated state.missing_state to match.

[derek-miller]

You are missing a bunch of unresolved comments in this PR @svc-finitelabs

[svc-finitelabs]

You're right, sorry about that. Going through all the review comments now and addressing them.