Restore pre-migration preset state per speaker (recovery button)

[tostmann]

Problem / motivation

There used to be an "auf Original zurücksetzen" button per speaker. It was removed when SixBack became the only viable cloud — the Bose cloud is offline since 2026-05-06, so reverting envswitch boseurls to the original Bose URL is no longer meaningful (it would just point the speaker at a dead endpoint).

But a useful form of "back to original" is still possible: restoring the pre-migration preset state on the speaker, while keeping SixBack as the cloud. This is a recovery path for users who have inadvertently overwritten or lost presets while experimenting with SixBack.

Asked indirectly by @fred_feuerstein in the FHEM forum thread: "Aber kann es sein, dass man anfangs die Lautsprecher wieder auf 'original' zurücksetzen konnte und das aktuell in SixBack nicht mehr per 'Knopf' geht?"

What is already there

SixBack already captures and persists everything needed for a restore, locally on the ESP:

• During first migrate, auto_mode.cpp:292 sets setState_("pre-migrate-snapshot") and writes a JSON snapshot via speaker_diagnostic.cpp
• Storage: local LittleFS /snapshots/<dev>.json, rotated as .prev.json, .prev2.json (see speaker_diagnostic.cpp:78)
• Snapshot content (verified on a real sample, snapshot_kind: "pre_migrate"):

  speaker.{device_id, ip, name, model, firmware, cloud_url}
  bmx.presets           ← all 6 slots, complete pre-migration ContentItems
  bmx.sources           ← sources.xml including STORED_MUSIC (DLNA)
  bmx.{now_playing, getZone, getGroup, listMediaServers, sourceServiceList}
  telnet.getpdo_currentsystemconfiguration
  

• Existing read endpoint: GET /api/speaker/{id}/diagnostic-snapshot (api_endpoints.cpp:2065+) — exposes both live and stored snapshots

What is missing

No restore code path exists. Grep for restoreSnapshot|restorePreset|/restore in src/ returns zero. Snapshots are read-only today.

Proposed solution

1. Backend: new POST /api/speaker/{id}/restore-pre-migration
   • Reads /snapshots/<dev>.json (or .prev.json if a newer post-migration snapshot has already overwritten it)
   • For each of the 6 slots, extracts bmx.presets[N].ContentItem
   • Pushes through the existing doPush_ pipeline (same path as the manual push-to-device button)
   • OPAQUE / DLNA slots use the same rawContentItem passthrough that is already wired
2. UI: per-speaker card → ⏮ Restore pre-migration button (only enabled when a snapshot_kind=pre_migrate snapshot is present locally). Confirm dialog with slot-by-slot diff before pushing.
3. Out of scope for v1: rewriting telnet.getpdo-based cloud URL (envswitch). Just preset state.

Alternatives considered

• Cross-speaker DLNA source transplant (Fred's actual underlying need: get STORED_MUSIC onto a virgin speaker by injecting another speaker's bmx.sources): related but separate problem — source IDs are speaker-specific positional indices, not 1:1 transplantable. Separate experiment.
• "Back to Bose Cloud" button: pointless since the cloud is dead — would just brick the speaker against unreachable endpoints.

Acceptance

• A speaker that has lost a slot via SixBack edits can be restored to its pre-migration state with one button + confirm
• Works for TUNEIN, LOCAL_INTERNET_RADIO, and OPAQUE (DLNA) slots equivalently
• No regression on speakers without a pre-migration snapshot (button just disabled)

[tostmann]

Implemented in commits fffdc49 + 356feef.

Backend:

• GET /api/speaker/{id}/restore-pre-migration/preview — slot-by-slot diff vs current store: {restorable_count, abandoned_count, snapshot_kind, captured_at_ms, slots:[{slot, source, name, stationId, opaque, abandoned, will_push, sync_via}]}.
• POST /api/speaker/{id}/restore-pre-migration — writes all reconstructed slots to PresetStore in one setSlots batch, enqueues doPush_ for non-OPAQUE / non-abandoned slots via the existing push-worker queue. OPAQUE/STORED_MUSIC slots are picked up by the speaker on its next /full poll (~30s).
• Extracted ensurePushQueueReady_() + enqueuePushJob_() so the new endpoint reuses the existing queue + worker without duplicating lazy-init.
• XML parsing mirrors importPresetsFromSpeaker_ (xmlExtractAttr/Tag + normalizePreset → OPAQUE rawContentItem extraction).

Snapshot kind validation: spec originally required snapshot_kind=pre_migrate. Relaxed to accept any captured kind (pre_migrate, manual from ?save=1, live). The preview surfaces snapshot_kind so the user can decide; a manual snapshot is equally valid recovery material if the user captured it before the bad edits.

UI:

• New per-speaker ⏮ Restore button.
• Modal with 6-row table: slot / source / pre-migrate name / current store name / restore action.
• Snapshot kind shown in info line, highlighted if not pre_migrate.
• Confirm → POST commit + markDirty + reload presets + kickPoll for instant feedback.

Verified end-to-end with both kinds of snapshot (manual capture via ?save=1 and pre_migrate from a POST /migrate cycle): preview parses presets correctly, commit enqueues push jobs, push pipeline completes.

Not in v1:

• Cross-speaker DLNA source transplant — related but separate problem; source IDs are speaker-specific positional indices.
• 'Back to Bose cloud' button — Bose cloud is shut down, would just point speakers at unreachable endpoints.
• OPAQUE slot restore wasn't directly exercised in the live test (test speaker had only TUNEIN presets). The code path is identical to the speaker's existing /full-OPAQUE-sync.