Feat: auto offline sync on device connect

[mdmohsin7]

Summary

• Adds automatic offline sync when an Omi device connects with pending audio files on its SD/LittleFS storage
• Implements the new multi-file firmware protocol (CMD_LIST_FILES 0x10, CMD_READ_FILE 0x11, CMD_DELETE_FILE 0x12) from PR Feat - refactor SD card, improve bluetooth throughput, remove wifi feature, fix issues #5897
• Creates a new StorageSyncImpl alongside the existing SDCardWalSync — old firmware devices continue using the legacy sync unchanged
• On device connect: reads storage status → if files exist → triggers syncProvider.syncWals() automatically (no user action needed)
• Downloads each file individually from device to phone local storage, then hands to LocalWalSync for upload to backend via existing /v1/sync-local-files endpoint

Flow

Device connects → read storage status (16 bytes)
  → fileCount > 0 → auto-trigger syncWals()
  → Phase 0: StorageSync downloads files via BLE (new protocol)
  → Phase 2: LocalWalSync uploads to backend (unchanged)

What's new

• StorageStatus / StorageFileInfo models in device_connection.dart
• performGetStorageFileStats(), performListStorageFiles(), performDeleteStorageFile() in omi_connection.dart
• StorageSyncImpl in new storage_sync.dart — multi-file BLE sync
• StorageSync interface in wal_interfaces.dart
• Phase 0 in WalSyncs.syncAll() before legacy SD card sync
• _checkAndStartAutoSync() in DeviceProvider._onDeviceConnected()
• Auto-sync callback wiring in home page

What's unchanged

• sdcard_wal_sync.dart — legacy firmware sync untouched
• local_wal_sync.dart — phone→backend upload untouched
• Backend /v1/sync-local-files — same endpoint
• Native BLE managers — no changes needed
• BLE UUIDs — same service/characteristics

Test plan

• Connect new firmware device with offline files → verify auto-sync triggers and files download
• Connect old firmware device → verify legacy manual sync still works, no auto-sync attempt
• Start realtime recording → verify offline sync runs simultaneously without audio drops
• Kill app mid-sync → reconnect → verify files are re-detected and re-synced
• Swipe app away → bring device in range → verify background wake triggers auto-sync

Depends on firmware PR #5897

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR introduces automatic offline sync when an Omi device connects with pending audio files on its LittleFS storage. It adds StorageSyncImpl for the new multi-file firmware protocol (CMD_LIST_FILES 0x10, CMD_READ_FILE 0x11, CMD_DELETE_FILE 0x12), wires it as Phase 0 in WalSyncs.syncAll() ahead of the legacy SD-card sync, and exposes a new AutoSyncPage UI. The overall architecture follows the proven patterns from the SD-card sync path and is well-structured.\n\nThree concrete bugs need attention before merging:\n\n- Unreliable firmware-version heuristic (omi_connection.dart): The guard fileCount > totalBytes intended to detect old firmware almost never triggers — a byte offset is always ≤ total used bytes — so old-firmware devices are misidentified as new, wasting 10 s per connect on a CMD_LIST_FILES timeout and persisting deviceSupportsMultiFileSync = true incorrectly.\n- Audio duplication on BLE disconnect mid-transfer (storage_sync.dart): _syncSingleFile flushes partial frames to disk and registers them with LocalWalSync regardless of whether transferComplete is true. On next reconnect the same file is re-downloaded from offset 0, creating duplicate audio chunks uploaded to the cloud.\n- Subscription leak on write failure (omi_connection.dart): In performListStorageFiles (and performDeleteStorageFile), sub.cancel() is placed after — not in a finally block around — writeCharacteristic, leaving a live BLE notification listener if the write throws.

Confidence Score: 3/5

Not safe to merge as-is — the partial-transfer data-duplication bug and unreliable firmware heuristic can cause real user-facing issues (duplicate cloud conversations, wrong UI for legacy devices).

Two P1 bugs affect correctness on both old and new firmware paths: the firmware-detection heuristic means old-firmware users see the wrong sync page and waste 10 s on every connect, while the incomplete-transfer flush path can silently produce duplicate audio in the cloud. The subscription leak is an additional reliability issue. The overall design is solid and the fixes are targeted, so confidence would jump to 4-5 once those three issues are resolved.

app/lib/services/devices/omi_connection.dart (firmware heuristic + subscription leak) and app/lib/services/wals/storage_sync.dart (partial-transfer flush)

Important Files Changed

Filename	Overview
app/lib/services/wals/storage_sync.dart	New StorageSyncImpl for LittleFS multi-file BLE protocol; partial-transfer data is flushed to disk before the transfer-complete check, risking audio duplication on retry
app/lib/services/devices/omi_connection.dart	New CMD_LIST_FILES/READ/DELETE BLE commands added; firmware-version heuristic (fileCount > totalBytes) is unreliable and stream subscription is leaked if writeCharacteristic throws
app/lib/providers/device_provider.dart	Adds _checkAndStartAutoSync on connect and onOfflineDataDetected callback; unawaited future should be explicitly marked with unawaited()
app/lib/providers/sync_provider.dart	Adds _autoUploadPendingPhoneFiles with a 3 s delay that can race with device auto-sync and silently skip device file downloads
app/lib/services/wals/wal_syncs.dart	Phase 0 (StorageSync) correctly wired before legacy SD-card phase; cancellation and WAL list aggregation look correct
app/lib/pages/conversations/auto_sync_page.dart	New AutoSyncPage with three-tier pipeline visualization (Device → Phone → Cloud); UI logic looks sound
app/lib/pages/home/page.dart	Auto-sync callback registered/cleaned up correctly; cloud icon routes to AutoSyncPage or SyncPage based on firmware capability flag

Sequence Diagram

sequenceDiagram
    participant Device as Omi Device (LittleFS)
    participant DP as DeviceProvider
    participant SP as SyncProvider
    participant SS as StorageSyncImpl
    participant LS as LocalWalSyncImpl
    participant Cloud as Backend /v1/sync-local-files

    Device->>DP: BLE connect
    DP->>Device: getStorageFileStats() → [totalBytes, fileCount]
    alt new firmware (fileCount ≤ totalBytes)
        DP->>SP: onOfflineDataDetected(fileCount, totalBytes)
        SP->>SS: syncWals() → syncAll()
        SS->>Device: stopStorageSync() (STOP 0x03)
        SS->>Device: listStorageFiles() (CMD_LIST_FILES 0x10)
        Device-->>SS: [count][ts:4][sz:4]... file list
        loop each file
            SS->>Device: writeToStorage(fileNum, 0x11, 0) (CMD_READ_FILE)
            Device-->>SS: BLE notifications [ts:4][audio_440]...
            Device-->>SS: [0x64] end signal
            SS->>SS: _flushToDisk(frames)
            SS->>LS: addExternalWal(localWal)
            SS->>Device: deleteStorageFile(fileNum) (CMD_DELETE_FILE 0x12)
        end
        SS->>SP: syncAll() complete
        SP->>LS: phone.syncAll()
        LS->>Cloud: POST /v1/sync-local-files
        Cloud-->>SP: newConversationIds[]
    else old firmware (or no files)
        DP->>DP: supportsMultiFileSync = false
    end

Loading

Comments Outside Diff (1)

1. app/lib/providers/sync_provider.dart, line 77-90 (link)

   Auto-phone-upload can block device auto-sync on first connect

   _autoUploadPendingPhoneFiles delays 3 seconds then starts uploading stale phone WALs. _checkAndStartAutoSync in DeviceProvider awaits several BLE round-trips (storage-status read + stop command + list-files) before calling onOfflineDataDetected. If those BLE ops take more than ~3 s, the phone-upload is already marked isProcessing = true when the device-sync callback fires.

   The callback in _registerAutoSyncCallback guards with !syncProvider.isSyncing, so the device's offline files are silently skipped until the next disconnect-reconnect cycle.

   Consider checking whether a device is connected and has files before starting the phone-side upload, or give the device-sync path a higher priority.

_{Reviews (1): Last reviewed commit: "Auto-upload pending phone WALs to cloud ..." | Re-trigger Greptile}

[greptile-apps]

Unreliable old-vs-new firmware heuristic

The condition fileCount > totalBytes && totalBytes > 0 is meant to catch old firmware where field[1] is a byte offset. But a byte offset into the file is always ≤ totalBytes (an offset cannot exceed the total used bytes), so this guard will almost never be true. As a result, any old-firmware device that returns two LE uint32 fields will be misclassified as new firmware, leading to the new LittleFS protocol being attempted against it.

For example, an old-firmware device with [totalUsedBytes=1048576, offset=524288] evaluates 524288 > 1048576 → false → incorrectly treated as new firmware. The subsequent CMD_LIST_FILES (0x10) times out after 10 s, wastes the user's time, and (due to SharedPreferencesUtil().deviceSupportsMultiFileSync = true) permanently shows AutoSyncPage for a device that doesn't support it.

Consider using a more robust signal — e.g., a distinct magic byte returned by the new firmware in the response, a firmware version characteristic, or a length check on the response payload that's unique to each protocol.

[greptile-apps]

Partial data flushed to disk before transfer-complete check, causing audio duplication on retry

_syncSingleFile always calls _flushToDisk + _registerWithLocalSync at the end with whatever frames were received, even for an incomplete transfer (transferComplete = false). Back in syncAll, the code sets wal.status = WalStatus.synced and then breaks but does not delete the file from the device.

On the next reconnect, refreshWalsFromDevice() discovers the file is still on device and creates a fresh WAL with storageOffset = 0. _syncSingleFile is then called again from the start, and the same audio frames are written to a new disk file and registered with LocalWalSync again — producing duplicate audio chunks uploaded to the cloud.

A simple guard is to skip _flushToDisk/_registerWithLocalSync when transferComplete is false:

// at the end of _syncSingleFile, before the flush loop:
if (!transferComplete && bytesData.isNotEmpty) {
  Logger.debug('StorageSync: Discarding ${bytesData.length} partial frames for file ${wal.fileNum}');
  return false;
}

[greptile-apps]

Stream subscription leak when writeCharacteristic throws

sub is created before the writeCharacteristic call but is only cancelled in the happy path (after the timeout). If writeCharacteristic throws an exception, execution jumps to the outer catch block and sub.cancel() is never called, leaving a live BLE notification listener open.

Fix with a try/finally:

try {
  await transport.writeCharacteristic(
      storageDataStreamServiceUuid, storageDataStreamCharacteristicUuid, [0x10]);
  final result = await completer.future.timeout(
    const Duration(seconds: 10),
    onTimeout: () {
      Logger.debug('OmiDeviceConnection: listFiles timeout');
      return <StorageFileInfo>[];
    },
  );
  return result;
} finally {
  await sub?.cancel();
}

The same pattern applies to performDeleteStorageFile where subscription.cancel() is also outside a finally.

[greptile-apps]

Unawaited future should be explicitly marked

_checkAndStartAutoSync(device) is fire-and-forget, which is intentional, but the Dart linter will warn about the unawaited Future. Mark it explicitly so the intent is clear and the warning is suppressed:

Suggested change

	// Wals
	unawaited(_checkAndStartAutoSync(device));