feat(firmware): Confirm local firmware files before flashing (#6083)

Author: jeremiah-k

.skills/compose-ui/strings-index.txt

@@ -615,9 +615,14 @@
     <string name="firmware_too_old">Firmware update required.</string>
     <string name="firmware_update_almost_there">Almost there...</string>
     <string name="firmware_update_alpha">Alpha</string>
+    <string name="firmware_update_archive_missing_target">No firmware for %2$s (%3$s) was found in \"%1$s\".</string>
     <string name="firmware_update_battery_low">Battery too low (%1$d%). Please charge your device before updating.</string>
     <string name="firmware_update_checking">Checking for updates...</string>
+    <string name="firmware_update_confirm_file_button">Start Flashing</string>
+    <string name="firmware_update_confirm_file_message">Review the full selected filename before flashing. Flashing starts only after you confirm.</string>
+    <string name="firmware_update_confirm_file_title">Confirm Firmware File</string>
     <string name="firmware_update_connecting_attempt">Connecting to device (attempt %1$d/%2$d)...</string>
+    <string name="firmware_update_context_changed">Device connection changed while confirming. Please reselect the firmware file.</string>
     <string name="firmware_update_copying">High-five! Wait, copying firmware...</string>
     <string name="firmware_update_currently_installed">Currently Installed: %1$s</string>
     <string name="firmware_update_device">Device: %1$s</string>
@@ -633,23 +638,29 @@
     <string name="firmware_update_error">Error: %1$s</string>
     <string name="firmware_update_extracting">Extracting firmware...</string>
     <string name="firmware_update_failed">Update failed</string>
+    <string name="firmware_update_filename_unavailable">Could not read the selected file name. Choose a local firmware file with a visible filename.</string>
     <string name="firmware_update_flashing">Flashing device, please wait...</string>
     <string name="firmware_update_hang_tight">Hang tight, we are working on it...</string>
     <string name="firmware_update_hash_rejected">Firmware hash rejected. Device may require hash provisioning or bootloader update.</string>
+    <string name="firmware_update_invalid_local_file_detail">The selected file \"%1$s\" does not match %2$s (%3$s). Choose the firmware file for this target.</string>
     <string name="firmware_update_keep_device_close">Keep your device close to your phone.</string>
     <string name="firmware_update_latest">Update To: %1$s</string>
     <string name="firmware_update_local_file">Local File</string>
     <string name="firmware_update_method_ble">BLE OTA</string>
     <string name="firmware_update_method_detail">Update via %1$s</string>
     <string name="firmware_update_method_usb">USB File Transfer</string>
     <string name="firmware_update_method_wifi">WiFi OTA</string>
+    <string name="firmware_update_missing_target">Firmware target information is unavailable for this device.</string>
     <string name="firmware_update_no_device">No device connected</string>
     <string name="firmware_update_node_info_missing">Node user information is missing.</string>
     <string name="firmware_update_not_found_in_release">Could not find firmware for %1$s in release.</string>
     <string name="firmware_update_ota_failed">OTA update failed: %1$s</string>
     <string name="firmware_update_rak4631_bootloader_hint">For RAK WisBlock RAK4631, use the vendor's serial DFU tool (for example, adafruit-nrfutil dfu serial with the provided bootloader .zip file). Copying the .uf2 file alone will not update the bootloader.</string>
     <string name="firmware_update_rebooting">Rebooting to DFU...</string>
     <string name="firmware_update_release_notes">Release Notes</string>
+    <string name="firmware_update_requires_bin">%1$s requires a target-matching .bin file.</string>
+    <string name="firmware_update_requires_ota_zip">%1$s requires a target-matching OTA .zip file.</string>
+    <string name="firmware_update_requires_uf2">%1$s requires a target-matching .uf2 file.</string>
     <string name="firmware_update_retrieval_failed">Could not retrieve firmware file.</string>
     <string name="firmware_update_retry">Retry</string>
     <string name="firmware_update_save_dfu_file">Please save the .uf2 file to your device's DFU drive.</string>
@@ -667,6 +678,7 @@
     <string name="firmware_update_unknown_hardware">Unknown hardware model: %1$d</string>
     <string name="firmware_update_unknown_release">Unknown remote release</string>
     <string name="firmware_update_unsupported_transport">Firmware updates are not supported over this connection for this device. Connect a different way (e.g. Bluetooth) to update.</string>
+    <string name="firmware_update_unsupported_update_method">Local firmware files are not supported for this update method.</string>
     <string name="firmware_update_uploading">Uploading firmware...</string>
     <string name="firmware_update_usb_bootloader_warning">%1$s usually ships with a bootloader that does not support OTA updates. You may need to flash an OTA-capable bootloader over USB before flashing OTA.</string>
     <string name="firmware_update_usb_failed">USB Update failed</string>

core/resources/src/commonMain/composeResources/values/strings.xml

@@ -17,6 +17,7 @@
 package org.meshtastic.feature.firmware
 
 import android.content.Context
+import android.provider.OpenableColumns
 import co.touchlab.kermit.Logger
 import com.eygraber.uri.toAndroidUri
 import io.ktor.client.HttpClient
@@ -134,7 +135,7 @@ class AndroidFirmwareFileHandler(private val context: Context, private val clien
         preferredFilename: String?,
     ): FirmwareArtifact? = withContext(ioDispatcher) {
         val localZipFile = zipFile.toLocalFileOrNull() ?: return@withContext null
-        val target = hardware.platformioTarget.ifEmpty { hardware.hwModelSlug }
+        val target = hardware.effectiveTarget
         if (target.isEmpty() && preferredFilename == null) return@withContext null
 
         val targetLowerCase = target.lowercase()
@@ -169,6 +170,8 @@ class AndroidFirmwareFileHandler(private val context: Context, private val clien
                 entry = zipInput.nextEntry
             }
         }
+        // Prefer the shortest matching entry name — official release bundles contain one
+        // matching firmware per target; the heuristic picks the canonical name if multiple match.
         matchingEntries.minByOrNull { it.first.name.length }?.second?.toFirmwareArtifact()
     }
 
@@ -178,7 +181,7 @@ class AndroidFirmwareFileHandler(private val context: Context, private val clien
         fileExtension: String,
         preferredFilename: String?,
     ): FirmwareArtifact? = withContext(ioDispatcher) {
-        val target = hardware.platformioTarget.ifEmpty { hardware.hwModelSlug }
+        val target = hardware.effectiveTarget
         if (target.isEmpty() && preferredFilename == null) return@withContext null
 
         val targetLowerCase = target.lowercase()
@@ -255,6 +258,37 @@ class AndroidFirmwareFileHandler(private val context: Context, private val clien
         tempFile.toFirmwareArtifact()
     }
 
+    override suspend fun getDisplayName(uri: CommonUri): String? = withContext(ioDispatcher) {
+        val platformUri = uri.toAndroidUri()
+        if (platformUri.scheme == "content") {
+            // query() can throw SecurityException (revoked permission) or IllegalArgumentException
+            // (malformed URI) even after the scheme guard; fall through to the file-scheme branch on failure.
+            runCatching {
+                context.contentResolver.query(
+                    platformUri,
+                    arrayOf(OpenableColumns.DISPLAY_NAME),
+                    null,
+                    null,
+                    null,
+                )
+            }
+                .onFailure { e -> Logger.w(e) { "Failed to query display name from content provider" } }
+                .getOrNull()
+                ?.use { cursor ->
+                    val nameIndex = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME)
+                    if (nameIndex >= 0 && cursor.moveToFirst()) {
+                        cursor
+                            .getString(nameIndex)
+                            ?.takeIf { it.isNotBlank() }
+                            ?.let {
+                                return@withContext it
+                            }
+                    }
+                }
+        }
+        if (platformUri.scheme == "file") uri.pathSegments.lastOrNull()?.takeIf { it.isNotBlank() } else null
+    }
+
     override suspend fun extractZipEntries(artifact: FirmwareArtifact): Map<String, ByteArray> =
         withContext(ioDispatcher) {
             val entries = mutableMapOf<String, ByteArray>()

feature/firmware/src/androidMain/kotlin/org/meshtastic/feature/firmware/AndroidFirmwareFileHandler.kt

@@ -64,6 +64,9 @@ interface FirmwareFileHandler {
      */
     suspend fun importFromUri(uri: CommonUri): FirmwareArtifact?
 
+    /** Resolve a user-visible display filename for [uri], or `null` when the provider does not expose one. */
+    suspend fun getDisplayName(uri: CommonUri): String?
+
     /** Copy [source] to the platform URI [destinationUri], returning the number of bytes written. */
     suspend fun copyToUri(source: FirmwareArtifact, destinationUri: CommonUri): Long
 
@@ -111,18 +114,192 @@ interface FirmwareFileHandler {
  * Check whether [filename] is a valid firmware binary for [target] with the expected [fileExtension]. Excludes
  * non-firmware binaries that share the same extension (e.g. `littlefs-*`, `bleota*`).
  */
-@Suppress("ComplexCondition")
+@Suppress("ComplexCondition") // excluded-binary + target/extension guards collapsed to one early-out
 internal fun isValidFirmwareFile(filename: String, target: String, fileExtension: String): Boolean {
     if (
         filename.startsWith("littlefs-") ||
         filename.startsWith("bleota") ||
         filename.startsWith("mt-") ||
-        filename.contains(".factory.")
+        filename.contains(".factory.") ||
+        target.isBlank() ||
+        !filename.endsWith(fileExtension)
     ) {
         return false
     }
-    val regex = Regex(".*[\\-_]${Regex.escape(target)}[\\-_.].*")
-    return filename.endsWith(fileExtension) &&
-        filename.contains(target) &&
-        (regex.matches(filename) || filename.startsWith("$target-") || filename.startsWith("$target."))
+
+    val targetToken = Regex.escape(target)
+    val extensionToken = Regex.escape(fileExtension)
+    val targetPattern = Regex("(^|.*[\\-_])$targetToken(([\\-_.](v?\\d|firmware)).*$extensionToken$|$extensionToken$)")
+    return targetPattern.matches(filename)
+}
+
+data class PendingLocalFirmwareFile(
+    val uri: CommonUri,
+    val fileName: String,
+    val deviceName: String,
+    val platformioTarget: String,
+    val updateMethod: FirmwareUpdateMethod,
+    val address: String,
+)
+
+/** pioEnv-aware target: falls back to [DeviceHardware.hwModelSlug] when [DeviceHardware.platformioTarget] is unset. */
+internal val DeviceHardware.effectiveTarget: String
+    get() = platformioTarget.ifEmpty { hwModelSlug }
+
+internal fun validatePendingLocalFirmwareFile(
+    pendingFile: PendingLocalFirmwareFile,
+    currentState: FirmwareUpdateState.Ready,
+): LocalFirmwareFileValidation {
+    val currentTarget = currentState.deviceHardware.effectiveTarget
+    return when {
+        // The user selected the file under a different connection (method or address) than the
+        // one active now — the file may still match the target, but the confirmation context is stale.
+        currentState.updateMethod != pendingFile.updateMethod || currentState.address != pendingFile.address ->
+            LocalFirmwareFileValidation.Invalid(LocalFirmwareFileValidationReason.ConfirmationContextChanged)
+
+        currentTarget != pendingFile.platformioTarget ->
+            LocalFirmwareFileValidation.Invalid(LocalFirmwareFileValidationReason.TargetMismatch)
+
+        // Context matches — revalidate the filename against the current method before flashing.
+        else ->
+            validateLocalFirmwareFileName(pendingFile.fileName, currentState.deviceHardware, currentState.updateMethod)
+    }
+}
+
+@Suppress("ReturnCount") // two guard-clause early returns + trailing when; refactor would harm clarity
+internal fun preferredLocalFirmwareArchiveFilenames(
+    archiveFileName: String,
+    hardware: DeviceHardware,
+    updateMethod: FirmwareUpdateMethod,
+): List<String> {
+    val target = hardware.effectiveTarget.takeIf { it.isNotBlank() } ?: return emptyList()
+    val version = extractFirmwareVersion(archiveFileName) ?: return emptyList()
+    return when (updateMethod) {
+        FirmwareUpdateMethod.Ble ->
+            if (hardware.isEsp32Arc) {
+                listOf("firmware-$target-$version-update.bin", "firmware-$target-$version.bin")
+            } else {
+                listOf("firmware-$target-$version-ota.zip")
+            }
+
+        FirmwareUpdateMethod.Wifi -> listOf("firmware-$target-$version-update.bin", "firmware-$target-$version.bin")
+
+        FirmwareUpdateMethod.Usb -> listOf("firmware-$target-$version.uf2")
+
+        FirmwareUpdateMethod.Unknown -> emptyList()
+    }
+}
+
+private fun extractFirmwareVersion(fileName: String): String? {
+    val baseName = fileName.substringAfterLast('/').substringAfterLast('\\')
+    return FIRMWARE_VERSION_PATTERN.find(baseName)?.groupValues?.getOrNull(1)
+}
+
+private val FIRMWARE_VERSION_PATTERN = Regex("""(?:^|[-_])v?(\d+(?:\.[0-9A-Za-z]+)+)(?=(?:[-_][A-Za-z]+)?\.[^.]+$)""")
+
+internal sealed interface LocalFirmwareFileValidation {
+    data object Valid : LocalFirmwareFileValidation
+
+    data class Invalid(val reason: LocalFirmwareFileValidationReason) : LocalFirmwareFileValidation
+}
+
+internal enum class LocalFirmwareFileValidationReason {
+    MissingTarget,
+    MissingArchiveFirmware,
+    RequiresOtaZip,
+    RequiresBin,
+    RequiresUf2,
+    TargetMismatch,
+    ConfirmationContextChanged,
+    UnsupportedUpdateMethod,
+}
+
+internal fun validateLocalFirmwareFileName(
+    fileName: String,
+    hardware: DeviceHardware,
+    updateMethod: FirmwareUpdateMethod,
+): LocalFirmwareFileValidation {
+    val normalizedFileName = fileName.substringAfterLast('/').substringAfterLast('\\').lowercase()
+    val target = hardware.effectiveTarget.lowercase()
+    if (target.isBlank()) {
+        return LocalFirmwareFileValidation.Invalid(LocalFirmwareFileValidationReason.MissingTarget)
+    }
+
+    return when (updateMethod) {
+        FirmwareUpdateMethod.Ble ->
+            if (hardware.isEsp32Arc) {
+                validateEsp32LocalFirmware(normalizedFileName, target)
+            } else {
+                validateNrf52LocalFirmware(normalizedFileName, target)
+            }
+
+        FirmwareUpdateMethod.Wifi -> validateEsp32LocalFirmware(normalizedFileName, target)
+
+        FirmwareUpdateMethod.Usb -> validateUsbLocalFirmware(normalizedFileName, target)
+
+        FirmwareUpdateMethod.Unknown ->
+            LocalFirmwareFileValidation.Invalid(LocalFirmwareFileValidationReason.UnsupportedUpdateMethod)
+    }
+}
+
+/**
+ * Returns the firmware payload file extension this platform's update handler expects to receive.
+ *
+ * nRF52 BLE consumes the Nordic DFU `.zip` package directly via [SecureDfuHandler]; ESP32 (BLE or WiFi) streams a raw
+ * `.bin`; USB copies a `.uf2` to the mass-storage drive. Returns `null` for [FirmwareUpdateMethod.Unknown], which does
+ * not support local files.
+ */
+internal fun localFirmwarePayloadExtension(hardware: DeviceHardware, updateMethod: FirmwareUpdateMethod): String? =
+    when (updateMethod) {
+        FirmwareUpdateMethod.Ble -> if (hardware.isEsp32Arc) ".bin" else ".zip"
+        FirmwareUpdateMethod.Wifi -> ".bin"
+        FirmwareUpdateMethod.Usb -> ".uf2"
+        FirmwareUpdateMethod.Unknown -> null
+    }
+
+private fun validateNrf52LocalFirmware(fileName: String, target: String): LocalFirmwareFileValidation =
+    validateSuffixedLocalFirmware(
+        fileName = fileName,
+        target = target,
+        requiredSuffix = "-ota.zip",
+        fileExtension = ".zip",
+        missingSuffixReason = LocalFirmwareFileValidationReason.RequiresOtaZip,
+    )
+
+private fun validateEsp32LocalFirmware(fileName: String, target: String): LocalFirmwareFileValidation =
+    validateSuffixedLocalFirmware(
+        fileName = fileName,
+        target = target,
+        requiredSuffix = ".bin",
+        fileExtension = ".bin",
+        missingSuffixReason = LocalFirmwareFileValidationReason.RequiresBin,
+    )
+
+private fun validateUsbLocalFirmware(fileName: String, target: String): LocalFirmwareFileValidation =
+    validateSuffixedLocalFirmware(
+        fileName = fileName,
+        target = target,
+        requiredSuffix = ".uf2",
+        fileExtension = ".uf2",
+        missingSuffixReason = LocalFirmwareFileValidationReason.RequiresUf2,
+    )
+
+private fun validateSuffixedLocalFirmware(
+    fileName: String,
+    target: String,
+    requiredSuffix: String,
+    fileExtension: String,
+    missingSuffixReason: LocalFirmwareFileValidationReason,
+): LocalFirmwareFileValidation {
+    if (!fileName.endsWith(requiredSuffix)) {
+        return LocalFirmwareFileValidation.Invalid(missingSuffixReason)
+    }
+    return validateTargetMatch(fileName, target, fileExtension)
 }
+
+private fun validateTargetMatch(fileName: String, target: String, fileExtension: String): LocalFirmwareFileValidation =
+    if (isValidFirmwareFile(fileName, target, fileExtension)) {
+        LocalFirmwareFileValidation.Valid
+    } else {
+        LocalFirmwareFileValidation.Invalid(LocalFirmwareFileValidationReason.TargetMismatch)
+    }

feature/firmware/src/commonMain/kotlin/org/meshtastic/feature/firmware/FirmwareFileHandler.kt

@@ -23,6 +23,8 @@ data class FirmwareUpdateActions(
     val onStartUpdate: () -> Unit,
     val onPickFile: () -> Unit,
     val onSaveFile: (String) -> Unit,
+    val onConfirmLocalFile: () -> Unit,
+    val onDismissLocalFile: () -> Unit,
     val onRetry: () -> Unit,
     val onCancel: () -> Unit,
     val onDone: () -> Unit,