[Feature]: Schedule OTA update for sleepy/battery devices

[tashda]

What problem does this solve?

OTA updates for battery-powered devices (remotes, battery sensors, some Legrand devices) almost always fail because the device is asleep and unreachable when the user taps Update. Today the only workaround is to physically press a button on the device at the exact moment the OTA request is sent, to wake it up long enough to start the transfer. This is awkward for remotes that aren't on hand and impossible for embedded sensors.

The original headline I had in mind was "Force Update" — but after investigating, there is no way to force a sleepy Zigbee End Device awake from the coordinator side. The radio is off by spec until the device itself polls its parent. Z2M's docs even confirm the button-press trick is the canonical workaround:

"For battery powered end-devices you may need to trigger them by e.g. pushing a button right before checking for an OTA."
— Z2M OTA docs

However, Z2M already exposes the right primitive for this: schedule. It tells Z2M "next time this device wakes up on its own and asks for an image, give it one." This is persisted in the coordinator's database, survives Z2M restart, retries automatically forever, and adds a scheduled state to the device's update field. The Z2M web frontend already wires this up.

What would you like Shellbee to do?

Add Schedule update and Cancel scheduled update actions to the OTA UI, alongside the existing "Check for updates" and "Update now" actions. Surface the new scheduled state in device cards.

MQTT plumbing (already in Z2M, no bridge changes needed):

• Schedule: POST bridge/request/device/ota_update/schedule payload {"id": "<friendlyName>"}
• Unschedule: POST bridge/request/device/ota_update/unschedule payload {"id": "<friendlyName>"}
• Downgrade variant: bridge/request/device/ota_update/schedule/downgrade
• New device state: update.state can be scheduled (joins idle | available | updating)

UX behavior:

• Battery devices (power_source: "Battery"): primary CTA becomes Schedule update. Show a hint: "This device is battery-powered. After scheduling, press a button on the device to trigger the update." Secondary action: Update now (kept as an escape hatch for users who want to try the immediate path or are about to physically wake the device).
• Mains-powered devices: primary CTA stays Update now. Schedule still available as a secondary option.
• Scheduled state: device card shows a "Scheduled" badge. OTA list view includes a Scheduled section. Tapping a scheduled device exposes Cancel scheduled update.
• Optimistic UI: tapping Schedule should immediately show Scheduled badge while waiting for bridge/response/device/ota_update/schedule (consistent with the optimistic remove/rename pattern already used in Shellbee).

Reference implementation:

The Z2M web frontend (zigbee2mqtt-windfront) already implements this in src/pages/OtaPage.tsx — the actOnFilteredSelected handler wires all four topics: check, update, schedule, unschedule. Mirror its terminology for consistency (translation keys live under i18n namespace "ota").

Does the Z2M web frontend already do this?

Yes — and Shellbee should match it. See OtaPage.tsx / OtaControlGroup.tsx / OtaUpdateButton.tsx in zigbee2mqtt-windfront.

Alternatives you've considered

• "Force Update" button that loops update requests — wouldn't help. The device still has to wake up on its own; spamming update from the coordinator just wastes bandwidth and times out repeatedly.
• Keep doing the manual button-press workaround — works but unergonomic for remotes that are stored away or sensors that don't have buttons.
• Wait for Z2M / firmware to add a wake-on-rx mechanism — not coming. This is a fundamental Zigbee protocol property for sleepy ZEDs.

[tashda]

Extend behavior to "Check all devices for updates" bulk action

The same battery-aware logic should apply to the bulk Check all devices for updates action:

• For mains-powered devices: send bridge/request/device/ota_update/check as today (or whatever the current bulk implementation does).
• For battery-powered devices (power_source: "Battery"): send bridge/request/device/ota_update/schedule instead of check. Otherwise the bulk check fails for every battery device — same root cause as the per-device case: the device is asleep when the request fires.
• After the bulk action, every battery device that was scheduled should display a Scheduled status badge in the device list, matching the per-device flow described above.

This is part of the same feature — scope it together rather than splitting into a second issue. The dispatcher that decides "schedule vs. update" by power_source should be a single helper used by both the per-device CTA and the bulk action.

[tashda]

Follow-up changes added on dev while testing PR #25, beyond the original scope:

• Updates Available filter now keeps scheduled/updating devices. DeviceCondition.matches for .updatesAvailable now also returns true when the in-memory or persisted OTA phase is scheduled, requested, or updating. Previously the device dropped out of the filter the moment Z2M flipped update.state from available → scheduled. (Shellbee/Core/Models/NetworkAnalysis.swift, Shellbee/Features/Devices/DeviceListViewModel.swift)
• Auto-recheck after Cancel Scheduled Update. Z2M leaves update.state at idle after unschedule, so the device used to disappear from the Updates filter on cancel. We now fire device/ota_update/check immediately after unschedule so the bridge restores update.state = "available". (DeviceListViewModel.unscheduleDeviceUpdate, DeviceDetailView.unscheduleUpdate)
• Home Devices card shows scheduled / updating counts. New "N scheduled for update" and "N updating now" alert rows on the Home Devices card, threaded through HomeSnapshot via a new otaStatuses parameter. Tap-routes to the Updates Available quick filter.
• Scheduled-state badge no longer animates as if in progress. DeviceUpgradeBadgeView now renders a static faint ring with a clock.badge center icon for the scheduled phase instead of the rotating quarter-arc, since scheduled is parked-waiting, not active.

[tashda]

Correction to the earlier "scope-extending follow-ups" comment: the 'Check All for Updates' bulk action no longer routes battery devices through device/ota_update/schedule. That conflated two distinct Z2M operations — schedule queues an update for the device's next wake, while check is a synchronous "is there a newer firmware?" query. Z2M offers no scheduled equivalent of check. Battery devices now flow through the same rate-limited device/ota_update/check queue as mains devices; sleepy ones that aren't awake surface the standard "Device didn't respond to OTA" error, matching windfront's behaviour. (Shellbee/Features/Devices/DeviceFirmwareMenu.swift)

[tashda]

Added a settings toggle to suppress scheduled OTAs from the Live Activity. A scheduled OTA can sit pending for hours waiting for the device to wake, so a Lock-Screen surface for it is unwanted by default. Settings → General → Connection now exposes "Show Scheduled OTAs" (default off, disabled when "OTA Live Activity" is off). The OTA Live Activity coordinator filters .scheduled phases out of sync(...) unless the toggle is on; updating / requested OTAs are unaffected.

Files: Shellbee/App/ConnectionSessionController.swift (new key), Shellbee/LiveActivities/OTAUpdateLiveActivityCoordinator.swift (filter), Shellbee/Features/Settings/AppGeneralView.swift (toggle + footer copy).