@onekeyfe/hd-core 1.2.8-alpha.13 → 1.2.8-alpha.131

package/src/api/FirmwareUpdateV4.ts

@@ -1,11 +1,13 @@
 import { EDeviceType, ERRORS, HardwareError, HardwareErrorCode, wait } from '@onekeyfe/hd-shared';
 import JSZip from 'jszip';
+import semver from 'semver';
 import {
   DeviceRebootType,
   DeviceSessionPinType,
   PROTOCOL_V2_BLE_FILE_CHUNK_SIZE,
   PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE,
   PROTOCOL_V2_BLE_FIRMWARE_FILE_CHUNK_SIZE,
+  PROTOCOL_V2_FILE_WRITE_PIPELINE_WINDOW,
   PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE,
 } from '@onekeyfe/hd-transport';
 import { sha256 } from '@noble/hashes/sha256';
@@ -34,6 +36,7 @@ import { requestProtocolV2DeviceInfo } from '../protocols/protocol-v2/features';
 import {
   PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH,
   PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_STAGING_PATH,
+  PROTOCOL_V2_RESOURCE_PACKAGE_COMPARE_SIZE,
   PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_SIZE,
   type ProtocolV2ResourcePackageHeader,
   isProtocolV2ResourceArchiveEntryName,
@@ -75,6 +78,7 @@ import type {
 import type { FirmwareByteSource } from './firmware/FirmwareArtifactSource';
 
 const Log = getLogger(LoggerNames.Method);
+const TransferLog = getLogger(LoggerNames.Core);
 
 // Restored after a rebase dropped the declaration while keeping its use in
 // fileWriteChunk; without it that error branch throws ReferenceError instead of
@@ -101,7 +105,16 @@ const PROTOCOL_V2_CONNECT_POLL_INTERVAL = 500;
 const PROTOCOL_V2_CONNECT_SINGLE_TIMEOUT = 75 * 1000;
 const PROTOCOL_V2_DEVICE_INFO_READY_TIMEOUT = 30 * 1000;
 const PROTOCOL_V2_FILE_TRANSFER_RETRY_COUNT = 3;
+const PROTOCOL_V2_RESOURCE_HEADER_RECOVERY_LIMIT = 2;
+// Minimum running bootloader that receives two in-flight BLE FilesystemFileWrite frames.
+// Bootloaders with the 2048-byte BLE UART FIFO have no room beside one waiting FileWrite frame,
+// so a second frame can overflow it. Released bootloaders report 1.0.2 with that FIFO and stay
+// serial. Firmware has been asked to ship the 4096-byte FIFO from 1.0.3 but has not confirmed it,
+// nor the BLE coprocessor margin for two frames; any bootloader reporting 1.0.3 or later gets the
+// window. Set it to undefined to keep every transfer serial.
+const PROTOCOL_V2_BLE_FILE_WRITE_WINDOW_MIN_BOOTLOADER_VERSION: string | undefined = '1.0.3';
 const PROTOCOL_V2_TRANSFER_PROGRESS_HEARTBEAT_MS = 1000;
+const PROTOCOL_V2_TRANSFER_LOG_INTERVAL_MS = 10_000;
 const PROTOCOL_V2_INSTALL_STATUS_CONFLICT_CODE = 'FirmwareInstallStatusConflict';
 const PROTOCOL_V2_INSTALL_FAILED_CODE = 'FirmwareInstallFailed';
 const PROTOCOL_V2_INSTALL_TIMEOUT_CODE = 'FirmwareInstallTimeout';
@@ -170,6 +183,18 @@ export function assertProtocolV2FirmwareTargetsSupported(
   throw ERRORS.TypedError(HardwareErrorCode.DeviceNotSupportMethod, message);
 }
 
+/** Whether the running bootloader accepts a second in-flight BLE FilesystemFileWrite. */
+export function supportsProtocolV2BleFileWriteWindow(
+  bootloaderVersion: string,
+  minBootloaderVersion = PROTOCOL_V2_BLE_FILE_WRITE_WINDOW_MIN_BOOTLOADER_VERSION
+) {
+  return (
+    !!minBootloaderVersion &&
+    !!semver.valid(bootloaderVersion) &&
+    semver.gte(bootloaderVersion, minBootloaderVersion)
+  );
+}
+
 const getProtocolV2DeviceTransferProgress = (
   bytesBeforeChunk: number,
   bytesAfterChunk: number,
@@ -184,6 +209,12 @@ const getProtocolV2DeviceTransferProgress = (
   return Math.min(Math.max(Math.ceil((bytesAfterChunk / totalBytes) * 100), 1), 99);
 };
 
+const getProtocolV2TransferRate = (bytes: number, elapsedMs: number) =>
+  elapsedMs > 0 ? Math.round((bytes / elapsedMs) * 1000) : undefined;
+
+const getProtocolV2ElapsedMs = (startedAt: number, now = Date.now()) =>
+  Math.max(now - startedAt, 0);
+
 type ProtocolV2FirmwareUpdateStatusTarget = {
   target_id: number | string;
   status?: number | string;
@@ -352,13 +383,10 @@ const PROTOCOL_V2_TARGET_STATUS_BY_DECODED_NAME = new Map<string, number>([
   ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_ENTRY_OUT_OF_BOUNDS', 10],
 ]);
 
-const isProtocolV2ReconnectProbeError = (error: unknown) => {
-  const message = getProtocolV2UnknownErrorText(error).toLowerCase();
-  return (
-    (message.includes('device protocol mismatch') && message.includes('expected v2')) ||
-    message.includes('did not respond to expected protocol')
-  );
-};
+const isProtocolV2ReconnectProbeError = (error: unknown) =>
+  getProtocolV2ErrorCode(error) === HardwareErrorCode.TransportProtocolProbeFailed &&
+  (error as { params?: { expectedProtocol?: unknown } } | undefined)?.params?.expectedProtocol ===
+    'V2';
 
 const isProtocolV2FirmwareStatusEndpointUnavailable = (error: unknown) => {
   const message = getProtocolV2UnknownErrorText(error).toLowerCase();
@@ -385,6 +413,23 @@ const getProtocolV2ErrorCode = (error: unknown): number | string | undefined =>
   return typeof causeCode === 'number' || typeof causeCode === 'string' ? causeCode : undefined;
 };
 
+/** Errors that mean the link is gone, so the read says nothing about the installed bundle. */
+const isProtocolV2ResourceHeaderLinkError = (error: unknown) => {
+  if (isProtocolV2DeviceDisconnectedError(error)) return true;
+  const errorCode = getProtocolV2ErrorCode(error);
+  if (errorCode === HardwareErrorCode.BleTimeoutError) return true;
+  const message = getProtocolV2UnknownErrorText(error);
+  if (errorCode === HardwareErrorCode.TransportNotFound && /not connected/i.test(message)) {
+    return true;
+  }
+  return (
+    message.includes('ProtocolV2LinkError') ||
+    message.includes('Device protocol has not been detected') ||
+    message.includes('Electron BLE device state cleaned') ||
+    message.includes('Electron BLE transport released')
+  );
+};
+
 const isProtocolV2TerminalInstallStatusError = (error: unknown) =>
   error instanceof HardwareError &&
   (error.errorCode === HardwareErrorCode.ActionCancelled ||
@@ -589,6 +634,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
   private protocolV2LastTransferredBytes = 0;
 
+  private protocolV2FileWriteWindowDisabled = false;
+
   init() {
     this.allowDeviceMode = [UI_REQUEST.BOOTLOADER, UI_REQUEST.NOT_INITIALIZE];
     this.requireDeviceMode = [];
@@ -778,7 +825,11 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     };
   }
 
-  private getProtocolV2FirmwareChunkSize(direction: 'read' | 'write', filePath?: string) {
+  private getProtocolV2FirmwareChunkSize(
+    direction: 'read' | 'write',
+    filePath?: string,
+    fileWriteWindow = false
+  ) {
     const payloadChunkSize = Number(this.params?.chunkSize);
     const env = DataManager.getSettings('env');
     const isBle = this.params?.platform === 'native' || (env && DataManager.isBleConnect(env));
@@ -786,6 +837,10 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     if (isBle) {
       if (direction === 'read') {
         maxChunkSize = PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE;
+      } else if (fileWriteWindow) {
+        // Skip the larger staging chunk so two in-flight frames fit the UART FIFO; see
+        // PROTOCOL_V2_FILE_WRITE_PIPELINE_WINDOW.
+        maxChunkSize = PROTOCOL_V2_BLE_FILE_CHUNK_SIZE;
       } else {
         // Firmware staging writes tolerate a larger BLE chunk than generic filesystem writes.
         maxChunkSize = PROTOCOL_V2_FIRMWARE_STAGING_PATHS.has(filePath ?? '')
@@ -1815,8 +1870,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     const chunkSize = this.getProtocolV2FirmwareChunkSize('read');
     const chunks: Uint8Array[] = [];
     let offset = 0;
-    while (offset < PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_SIZE) {
-      const readLen = Math.min(chunkSize, PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_SIZE - offset);
+    while (offset < PROTOCOL_V2_RESOURCE_PACKAGE_COMPARE_SIZE) {
+      const readLen = Math.min(chunkSize, PROTOCOL_V2_RESOURCE_PACKAGE_COMPARE_SIZE - offset);
       const res = await typedCall('FilesystemFileRead', 'FilesystemFile', {
         file: {
           path: filePath,
@@ -1827,7 +1882,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
         ui_percentage: undefined,
       });
       const data = toProtocolV2Bytes(res.message?.data);
-      if (data.byteLength === 0) return null;
+      if (data.byteLength === 0 || data.byteLength > readLen) return null;
       chunks.push(data);
       offset += data.byteLength;
     }
@@ -1872,11 +1927,47 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       if (!expectedHeaderHash || header.headerHash !== expectedHeaderHash) return false;
       return true;
     } catch (error) {
+      if (isProtocolV2ResourceHeaderLinkError(error)) throw error;
       Log.log(`[FirmwareUpdateV4] RESC bundle ${bundle.name} header check failed: `, error);
       return false;
     }
   }
 
+  /**
+   * A lost link would fail every remaining header check and resend bundles that are already
+   * installed, so reconnect (a bounded number of times per transfer phase) and ask again.
+   * Header reads have no side effects. Once the budget is used up the bundle is resent as before.
+   * A failed reconnect aborts the update like a failed file-transfer recovery: reconnecting
+   * replaces the session, and nothing may be written to a device whose identity was not
+   * re-verified.
+   */
+  private async isProtocolV2ResourceBundleUpToDateWithRecovery(
+    bundle: ProtocolV2ResourceBundleSource,
+    recovery: { remaining: number }
+  ): Promise<boolean> {
+    for (;;) {
+      try {
+        return await this.isProtocolV2ResourceBundleUpToDate(bundle);
+      } catch (error) {
+        this.throwIfAborted();
+        if (recovery.remaining <= 0) {
+          Log.log(
+            `[FirmwareUpdateV4] RESC bundle ${bundle.name} header check lost the link; reconnect budget used up: `,
+            getProtocolV2UnknownErrorText(error)
+          );
+          return false;
+        }
+        recovery.remaining -= 1;
+        Log.log(
+          `[FirmwareUpdateV4] RESC bundle ${bundle.name} header check lost the link; reconnecting: `,
+          getProtocolV2UnknownErrorText(error)
+        );
+      }
+      await this.recoverProtocolV2FileTransfer();
+      this.throwIfAborted();
+    }
+  }
+
   private isProtocolV2BootloaderMode() {
     if (typeof this.device.isBootloader === 'function') {
       return !!this.device.isBootloader();
@@ -1906,6 +1997,9 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       this.postTipMessage(FirmwareUpdateTipMessage.AutoRebootToBootloader);
       await this.protocolV2Reboot(DeviceRebootType.Bootloader);
       await wait(1000);
+      if (this.isBleReconnect()) {
+        await this.device.deviceConnector?.disconnect(this.device.originalDescriptor.id);
+      }
       await this.waitForProtocolV2BootloaderMode();
       this.protocolV2ExecutionInLoader = true;
       this.postTipMessage(FirmwareUpdateTipMessage.GoToBootloaderSuccess);
@@ -1948,12 +2042,19 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     while (Date.now() - startTime < timeout) {
       try {
         if (shouldReconnect) {
-          await this.reconnectProtocolV2Device();
+          if (this.isBleReconnect()) {
+            await this.reconnectProtocolV2Device({ skipProtocolProbe: true });
+          } else {
+            await this.reconnectProtocolV2Device();
+          }
           shouldReconnect = false;
         }
         const deviceInfo = await requestProtocolV2DeviceInfo({
           commands: this.device.getCommands(),
-          timeoutMs: this.getProtocolV2DeviceInfoTimeout(),
+          timeoutMs: Math.min(
+            this.getProtocolV2DeviceInfoTimeout(),
+            PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT
+          ),
         });
         this.assertProtocolV2DeviceInfoIdentity(deviceInfo);
         const features = await this.device.probeProtocolV2RuntimeState(
@@ -2115,8 +2216,9 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
   }: ProtocolV2TransferBatch) {
     let totalSize = installSources.reduce((total, item) => total + item.source.size, 0);
     const resourcesToSync: ProtocolV2ResourceBundleSource[] = [];
+    const headerRecovery = { remaining: PROTOCOL_V2_RESOURCE_HEADER_RECOVERY_LIMIT };
     for (const resource of resourceSources) {
-      if (await this.isProtocolV2ResourceBundleUpToDate(resource)) {
+      if (await this.isProtocolV2ResourceBundleUpToDateWithRecovery(resource, headerRecovery)) {
         Log.log(`[FirmwareUpdateV4] skip RESC bundle ${resource.name}; already up to date`);
       } else {
         resourcesToSync.push(resource);
@@ -2165,13 +2267,20 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     }
 
     if (totalSize > 0) {
-      const elapsedMs = Math.max(Date.now() - transferStartedAt, 0);
+      const elapsedMs = getProtocolV2ElapsedMs(transferStartedAt);
+      const rateBytesPerSecond = getProtocolV2TransferRate(totalSize, elapsedMs);
       this.postProgressMessage(100, 'transferData', {
         transferredBytes: totalSize,
         totalBytes: totalSize,
-        rateBytesPerSecond: elapsedMs > 0 ? Math.round((totalSize / elapsedMs) * 1000) : undefined,
+        rateBytesPerSecond,
         elapsedMs,
       });
+      Log.debug('[FirmwareUpdateV4] Protocol V2 transfer completed', {
+        files: resourcesToSync.length + installSources.length,
+        totalBytes: totalSize,
+        elapsedMs,
+        rateBytesPerSecond,
+      });
     }
     if (stagedInstallTargets.length === 0) {
       return;
@@ -2182,10 +2291,16 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       target_id: item.targetId,
       path: item.path,
     }));
+    // Includes the wait for on-device confirmation.
+    const installStartedAt = Date.now();
     try {
       await this.protocolV2StartFirmwareUpdate({ targets });
       await wait(PROTOCOL_V2_INSTALL_STATUS_INITIAL_DELAY);
       await this.waitForProtocolV2FirmwareUpdateComplete(targets, true);
+      Log.debug('[FirmwareUpdateV4] Protocol V2 install completed', {
+        targets: targets.length,
+        elapsedMs: getProtocolV2ElapsedMs(installStartedAt),
+      });
     } finally {
       this.device?.clearCancelableAction();
     }
@@ -2204,66 +2319,121 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     totalSize: number;
     transferStartedAt?: number;
   }) {
+    const reportConfirmedChunk = (chunkEnd: number) => {
+      const transferredBytes = processedSize + chunkEnd;
+      const now = Date.now();
+      const elapsedMs = getProtocolV2ElapsedMs(transferStartedAt, now);
+      const progress = Math.min(Math.ceil((transferredBytes / totalSize) * 100), 99);
+      const shouldPostProgress =
+        transferredBytes >= this.protocolV2LastTransferredBytes &&
+        (progress !== this.protocolV2LastTransferProgress ||
+          now - this.protocolV2LastTransferProgressAt >=
+            PROTOCOL_V2_TRANSFER_PROGRESS_HEARTBEAT_MS ||
+          chunkEnd === source.size);
+      if (shouldPostProgress) {
+        this.protocolV2LastTransferProgress = progress;
+        this.protocolV2LastTransferProgressAt = now;
+        this.protocolV2LastTransferredBytes = transferredBytes;
+        this.postProgressMessage(progress, 'transferData', {
+          transferredBytes,
+          totalBytes: totalSize,
+          rateBytesPerSecond: getProtocolV2TransferRate(transferredBytes, elapsedMs),
+          elapsedMs,
+        });
+      }
+    };
     let lastError: unknown;
     for (let attempt = 1; attempt <= PROTOCOL_V2_FILE_TRANSFER_RETRY_COUNT; attempt += 1) {
       this.throwIfAborted();
+      const attemptStartedAt = Date.now();
+      let windowed = false;
+      let chunkSize = 0;
+      let confirmedBytes = 0;
+      let lastMetricsAt = attemptStartedAt;
+      const logTransfer = (status: 'started' | 'progress' | 'completed' | 'failed') => {
+        const elapsedMs = getProtocolV2ElapsedMs(attemptStartedAt);
+        TransferLog.log('[FirmwareUpdateV4] FileWrite metrics', {
+          status,
+          path: filePath,
+          fileWriteWindow: windowed ? PROTOCOL_V2_FILE_WRITE_PIPELINE_WINDOW : 1,
+          chunkSize,
+          attempt,
+          retryCount: attempt - 1,
+          transferredBytes: confirmedBytes,
+          totalBytes: source.size,
+          elapsedMs,
+          rateBytesPerSecond: getProtocolV2TransferRate(confirmedBytes, elapsedMs),
+        });
+      };
+      const reportAttemptChunk = (chunkEnd: number) => {
+        confirmedBytes = chunkEnd;
+        reportConfirmedChunk(chunkEnd);
+        const now = Date.now();
+        if (now - lastMetricsAt >= PROTOCOL_V2_TRANSFER_LOG_INTERVAL_MS && chunkEnd < source.size) {
+          logTransfer('progress');
+          lastMetricsAt = now;
+        }
+      };
       try {
-        await writeFirmwareByteSource({
-          source,
-          chunkSize: this.getProtocolV2FirmwareChunkSize('write', filePath),
-          write: async ({ data, sourceOffset, length, first }) => {
-            this.throwIfAborted();
-            const chunkEnd = sourceOffset + length;
-            const deviceProgress = getProtocolV2DeviceTransferProgress(
-              processedSize + sourceOffset,
-              processedSize + chunkEnd,
-              totalSize
-            );
-            const response = await this.fileWriteChunk(
-              filePath,
-              source.size,
-              sourceOffset,
-              data,
-              first,
-              deviceProgress
-            );
-            const rawProcessedByte = response.message.processed_byte;
-            const nextOffset = rawProcessedByte === undefined ? chunkEnd : Number(rawProcessedByte);
-            if (!Number.isFinite(nextOffset) || nextOffset !== chunkEnd) {
-              throw ERRORS.TypedError(
-                HardwareErrorCode.EmmcFileWriteFirmwareError,
-                `invalid processed_byte ${rawProcessedByte} for offset ${sourceOffset}`
+        windowed =
+          !this.protocolV2FileWriteWindowDisabled && this.shouldUseProtocolV2BleFileWriteWindow();
+        chunkSize = this.getProtocolV2FirmwareChunkSize('write', filePath, windowed);
+        logTransfer('started');
+        if (windowed) {
+          await this.writeProtocolV2SourceWindowed({
+            source,
+            filePath,
+            chunkSize,
+            processedSize,
+            totalSize,
+            onChunkConfirmed: reportAttemptChunk,
+          });
+        } else {
+          await writeFirmwareByteSource({
+            source,
+            chunkSize,
+            write: async ({ data, sourceOffset, length, first }) => {
+              this.throwIfAborted();
+              const chunkEnd = sourceOffset + length;
+              const deviceProgress = getProtocolV2DeviceTransferProgress(
+                processedSize + sourceOffset,
+                processedSize + chunkEnd,
+                totalSize
               );
-            }
-            const transferredBytes = processedSize + chunkEnd;
-            const now = Date.now();
-            const elapsedMs = Math.max(now - transferStartedAt, 0);
-            const progress = Math.min(Math.ceil((transferredBytes / totalSize) * 100), 99);
-            const shouldPostProgress =
-              transferredBytes >= this.protocolV2LastTransferredBytes &&
-              (progress !== this.protocolV2LastTransferProgress ||
-                now - this.protocolV2LastTransferProgressAt >=
-                  PROTOCOL_V2_TRANSFER_PROGRESS_HEARTBEAT_MS ||
-                chunkEnd === source.size);
-            if (shouldPostProgress) {
-              this.protocolV2LastTransferProgress = progress;
-              this.protocolV2LastTransferProgressAt = now;
-              this.protocolV2LastTransferredBytes = transferredBytes;
-              this.postProgressMessage(progress, 'transferData', {
-                transferredBytes,
-                totalBytes: totalSize,
-                rateBytesPerSecond:
-                  elapsedMs > 0 ? Math.round((transferredBytes / elapsedMs) * 1000) : undefined,
-                elapsedMs,
-              });
-            }
-            return length;
-          },
-        });
+              const response = await this.fileWriteChunk(
+                filePath,
+                source.size,
+                sourceOffset,
+                data,
+                first,
+                deviceProgress
+              );
+              const rawProcessedByte = response.message.processed_byte;
+              const nextOffset =
+                rawProcessedByte === undefined ? chunkEnd : Number(rawProcessedByte);
+              if (!Number.isFinite(nextOffset) || nextOffset !== chunkEnd) {
+                throw ERRORS.TypedError(
+                  HardwareErrorCode.EmmcFileWriteFirmwareError,
+                  `invalid processed_byte ${rawProcessedByte} for offset ${sourceOffset}`
+                );
+              }
+              reportAttemptChunk(chunkEnd);
+              return length;
+            },
+          });
+        }
+        logTransfer('completed');
         return processedSize + source.size;
       } catch (error) {
         this.throwIfAborted();
         lastError = error;
+        logTransfer('failed');
+        TransferLog.debug('[FirmwareUpdateV4] Protocol V2 file transfer attempt failed', {
+          path: filePath,
+          attempt,
+          fileWriteWindow: windowed ? PROTOCOL_V2_FILE_WRITE_PIPELINE_WINDOW : 1,
+          error: getProtocolV2UnknownErrorText(error),
+        });
         if (attempt < PROTOCOL_V2_FILE_TRANSFER_RETRY_COUNT) {
           await this.recoverProtocolV2FileTransfer();
           this.throwIfAborted();
@@ -3195,15 +3365,129 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     return writeRes;
   }
 
-  private async recoverProtocolV2FileTransfer() {
+  private shouldUseProtocolV2BleFileWriteWindow(
+    minBootloaderVersion = PROTOCOL_V2_BLE_FILE_WRITE_WINDOW_MIN_BOOTLOADER_VERSION
+  ) {
     const env = DataManager.getSettings('env');
-    if (DataManager.isBleConnect(env)) {
-      await wait(3000);
+    // These adapters queue frames that arrive while no read is pending. LowLevel plugins are not
+    // required to keep notifications between receive() calls, so they stay serial.
+    if (
+      (env !== 'react-native' && env !== 'desktop-web-ble') ||
+      !this.isProtocolV2BootloaderMode()
+    ) {
+      return false;
+    }
+    // The transfer runs in the device's current bootloader, not the one being installed. The
+    // parsed version keeps major.minor.patch only, so a 1.0.3 prerelease counts as 1.0.3.
+    const bootloaderVersion = getDeviceBootloaderVersion(this.device.features).join('.');
+    const enabled = supportsProtocolV2BleFileWriteWindow(bootloaderVersion, minBootloaderVersion);
+    TransferLog.debug('[FirmwareUpdateV4] BLE FileWrite window', {
+      enabled,
+      bootloaderVersion,
+      bootloaderBuildId: this.device.features?.verify?.bootloaderBuildId,
+    });
+    return enabled;
+  }
+
+  /**
+   * Streams one staged file as a single ordered FilesystemFileWrite pipeline. Every chunk is
+   * still confirmed by the device; a failure restarts the whole file like the serial path.
+   * Cancellation and source errors only stop the pipeline and are raised after the transport
+   * call returns: an error thrown inside it would invalidate the BLE link.
+   */
+  private async writeProtocolV2SourceWindowed({
+    source,
+    filePath,
+    chunkSize,
+    processedSize,
+    totalSize,
+    onChunkConfirmed,
+  }: {
+    source: FirmwareByteSource;
+    filePath: string;
+    chunkSize: number;
+    processedSize: number;
+    totalSize: number;
+    onChunkConfirmed: (chunkEnd: number) => void;
+  }) {
+    let sendOffset = 0;
+    let sourceError: Error | undefined;
+    const readRequest = async () => {
+      const offset = sendOffset;
+      const length = Math.min(chunkSize, source.size - offset);
+      const data = await source.readAt(offset, length);
+      sendOffset += length;
+      return {
+        file: { path: filePath, offset, total_size: source.size, data },
+        overwrite: offset === 0,
+        append: false,
+        ui_percentage: getProtocolV2DeviceTransferProgress(
+          processedSize + offset,
+          processedSize + sendOffset,
+          totalSize
+        ),
+      };
+    };
+    const nextRequest = async () => {
+      if (this.abortSignal?.aborted || sendOffset >= source.size) return undefined;
+      try {
+        return await readRequest();
+      } catch (error) {
+        sourceError = error;
+        return undefined;
+      }
+    };
+    this.throwIfAborted();
+    if (source.size === 0) return;
+    const firstRequest = await readRequest();
+
+    // A failed exchange disables the window for the rest of this update. Source read
+    // failures are raised separately and do not change the bootloader capability decision.
+    const response = await this.device
+      .getCommands()
+      .typedCall('FilesystemFileWrite', 'FilesystemFile', firstRequest, {
+        // Both windowed transports (React Native and Electron BLE) invalidate a timed-out link,
+        // so a lost chunk is retried after 10 s instead of the 5-minute default.
+        timeoutMs: PROTOCOL_V2_FILE_WRITE_RESPONSE_TIMEOUT,
+        writeWithResponse: false,
+        fileWritePipeline: {
+          next: nextRequest,
+          onResponse: confirmed => {
+            onChunkConfirmed(Number(confirmed.message.processed_byte));
+          },
+        },
+      })
+      .catch((error: unknown) => {
+        this.protocolV2FileWriteWindowDisabled = true;
+        throw error;
+      });
+    this.throwIfAborted();
+    if (sourceError) throw sourceError;
+    const rawProcessedByte = response.message.processed_byte;
+    if (Number(rawProcessedByte) !== source.size) {
+      this.protocolV2FileWriteWindowDisabled = true;
+      throw ERRORS.TypedError(
+        HardwareErrorCode.EmmcFileWriteFirmwareError,
+        `invalid processed_byte ${rawProcessedByte} for file size ${source.size}`
+      );
+    }
+  }
+
+  private async recoverProtocolV2FileTransfer() {
+    try {
+      const env = DataManager.getSettings('env');
+      if (DataManager.isBleConnect(env)) {
+        await wait(3000);
+      }
+      await this.reconnectProtocolV2Device();
+      await this.verifyProtocolV2ReconnectIdentity();
+      await this.device.initialize();
+      await wait(2000);
+    } catch (error) {
+      // A cancel disposes the link mid-recovery; report the cancel rather than its side effect.
+      this.throwIfAborted();
+      throw error;
     }
-    await this.reconnectProtocolV2Device();
-    await this.verifyProtocolV2ReconnectIdentity();
-    await this.device.initialize();
-    await wait(2000);
   }
 
   private async acquireProtocolV2BleDevice(skipProtocolProbe = false) {