@onekeyfe/hd-core 1.2.0-alpha.2 → 1.2.0-alpha.20

package/src/api/DirRemove.ts

@@ -1,5 +1,5 @@
 import { BaseMethod } from './BaseMethod';
-import { validateNonEmptyString } from './helpers/filesystemValidation';
+import { validateProtocolV2FilesystemPath } from './helpers/filesystemValidation';
 
 export type DirRemoveParams = {
   path: string;
@@ -7,11 +7,11 @@ export type DirRemoveParams = {
 
 export default class DirRemove extends BaseMethod<DirRemoveParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
-    this.params = { path: validateNonEmptyString(this.payload.path, 'path') };
+    this.params = { path: validateProtocolV2FilesystemPath(this.payload.path, 'path') };
   }
 
   async run() {

package/src/api/FileDelete.ts

@@ -1,5 +1,5 @@
 import { BaseMethod } from './BaseMethod';
-import { validateNonEmptyString } from './helpers/filesystemValidation';
+import { validateProtocolV2FilesystemPath } from './helpers/filesystemValidation';
 
 export type FileDeleteParams = {
   path: string;
@@ -7,11 +7,11 @@ export type FileDeleteParams = {
 
 export default class FileDelete extends BaseMethod<FileDeleteParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
-    this.params = { path: validateNonEmptyString(this.payload.path, 'path') };
+    this.params = { path: validateProtocolV2FilesystemPath(this.payload.path, 'path') };
   }
 
   async run() {

package/src/api/FileRead.ts

@@ -1,15 +1,15 @@
 import {
-  PROTOCOL_V2_BLE_FILE_CHUNK_SIZE,
+  PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE,
   PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE,
 } from '@onekeyfe/hd-transport';
 import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
 
 import { BaseMethod } from './BaseMethod';
 import {
-  validateNonEmptyString,
   validateNonNegativeInteger,
   validateOptionalNonNegativeInteger,
   validateOptionalPercentage,
+  validateProtocolV2FilesystemPath,
 } from './helpers/filesystemValidation';
 import { hexToBytes, isHexString, stripHexPrefix } from './helpers/hexUtils';
 import { DataManager } from '../data-manager';
@@ -27,7 +27,7 @@ const MIN_FILE_READ_CHUNK_SIZE = 64;
 function getProtocolV2FileReadChunkLimit() {
   const env = DataManager.getSettings('env');
   if (env && DataManager.isBleConnect(env)) {
-    return PROTOCOL_V2_BLE_FILE_CHUNK_SIZE;
+    return PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE;
   }
   return PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE;
 }
@@ -69,13 +69,30 @@ function toUint8Array(value: unknown): Uint8Array {
   return new Uint8Array(0);
 }
 
+function getDeviceTransferProgress(
+  bytesBeforeChunk: number,
+  bytesAfterChunk: number,
+  totalBytes: number
+) {
+  if (!Number.isFinite(totalBytes) || totalBytes <= 0) {
+    return 100;
+  }
+  if (bytesBeforeChunk <= 0 && bytesAfterChunk < totalBytes) {
+    return 0;
+  }
+  if (bytesAfterChunk >= totalBytes) {
+    return 100;
+  }
+  return Math.min(Math.max(Math.ceil((bytesAfterChunk / totalBytes) * 100), 1), 99);
+}
+
 export default class FileRead extends BaseMethod<FileReadParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
-    const path = validateNonEmptyString(this.payload.path, 'path');
+    const path = validateProtocolV2FilesystemPath(this.payload.path, 'path');
     this.params = {
       path,
       offset: validateNonNegativeInteger(this.payload.offset, 'offset', 0),
@@ -123,8 +140,7 @@ export default class FileRead extends BaseMethod<FileReadParams> {
       const readLen = Math.min(chunkSize, totalLength - read);
       const offset = startOffset + read;
       const progress =
-        this.params.uiPercentage ??
-        Math.min(Math.ceil(((read + readLen) / Math.max(totalLength, 1)) * 100), 99);
+        this.params.uiPercentage ?? getDeviceTransferProgress(read, read + readLen, totalLength);
       const res = await this.device.commands.typedCall('FilesystemFileRead', 'FilesystemFile', {
         file: {
           path: this.params.path,

package/src/api/FileWrite.ts

@@ -1,19 +1,13 @@
-import {
-  PROTOCOL_V2_BLE_FILE_CHUNK_SIZE,
-  PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE,
-} from '@onekeyfe/hd-transport';
-import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
-
 import { BaseMethod } from './BaseMethod';
 import {
-  validateNonEmptyString,
   validateNonNegativeInteger,
   validateOptionalNonNegativeInteger,
   validateOptionalPercentage,
+  validateProtocolV2FilesystemPath,
   validateRequiredData,
 } from './helpers/filesystemValidation';
+import { writeProtocolV2File } from './helpers/protocolV2FileWrite';
 import { UI_REQUEST, createUiMessage } from '../events/ui-request';
-import { DataManager } from '../data-manager';
 
 export type FileWriteParams = {
   path: string;
@@ -24,74 +18,19 @@ export type FileWriteParams = {
   chunkLen?: number;
   overwrite?: boolean;
   append?: boolean;
+  emitProgress?: boolean;
   uiPercentage?: number;
   timeoutMs?: number | string;
 };
 
-const MIN_FILE_CHUNK_SIZE = 64;
-
-function getProtocolV2FileChunkLimit() {
-  const env = DataManager.getSettings('env');
-  if (env && DataManager.isBleConnect(env)) {
-    return PROTOCOL_V2_BLE_FILE_CHUNK_SIZE;
-  }
-  return PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE;
-}
-
-async function dataToUint8Array(data: FileWriteParams['data'] | Blob): Promise<Uint8Array> {
-  if (typeof data === 'string') {
-    return new TextEncoder().encode(data);
-  }
-
-  if (data instanceof ArrayBuffer) {
-    return new Uint8Array(data);
-  }
-
-  if (ArrayBuffer.isView(data)) {
-    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-  }
-
-  if (typeof Blob !== 'undefined' && data instanceof Blob) {
-    return new Uint8Array(await data.arrayBuffer());
-  }
-
-  throw ERRORS.TypedError(
-    HardwareErrorCode.CallMethodInvalidParameter,
-    'Unsupported FilesystemFileWrite data'
-  );
-}
-
-function normalizeChunkSize(value: unknown, maxChunkSize: number): number {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric) || numeric <= 0) return maxChunkSize;
-  return Math.min(Math.max(Math.floor(numeric), MIN_FILE_CHUNK_SIZE), maxChunkSize);
-}
-
-function getConfirmedProgress(
-  processedByte: number,
-  totalSize: number,
-  written: number,
-  dataLength: number
-) {
-  if (Number.isFinite(processedByte) && Number.isFinite(totalSize) && totalSize > 0) {
-    if (processedByte >= totalSize) return 100;
-    return Math.min(Math.max(Math.floor((processedByte / totalSize) * 100), 0), 99);
-  }
-  if (dataLength > 0) {
-    if (written >= dataLength) return 100;
-    return Math.min(Math.max(Math.floor((written / dataLength) * 100), 0), 99);
-  }
-  return 100;
-}
-
 export default class FileWrite extends BaseMethod<FileWriteParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
     validateRequiredData(this.payload.data, 'data');
-    const path = validateNonEmptyString(this.payload.path, 'path');
+    const path = validateProtocolV2FilesystemPath(this.payload.path, 'path');
     const offset = validateNonNegativeInteger(this.payload.offset, 'offset', 0);
     this.params = {
       path,
@@ -102,115 +41,31 @@ export default class FileWrite extends BaseMethod<FileWriteParams> {
       chunkLen: validateOptionalNonNegativeInteger(this.payload.chunkLen, 'chunkLen'),
       overwrite: this.payload.overwrite ?? offset === 0,
       append: this.payload.append ?? false,
+      emitProgress: this.payload.emitProgress ?? true,
       uiPercentage: validateOptionalPercentage(this.payload.uiPercentage, 'uiPercentage'),
       timeoutMs: validateOptionalNonNegativeInteger(this.payload.timeoutMs, 'timeoutMs'),
     };
   }
 
   async run() {
-    const data = await dataToUint8Array(this.params.data);
-    const dataLength = data.byteLength;
-    const offsetValue = Number(this.params.offset ?? 0);
-    const startOffset = Number.isFinite(offsetValue) && offsetValue > 0 ? offsetValue : 0;
-    const payloadTotalSize = Number(this.params.totalSize);
-    const totalSize =
-      Number.isFinite(payloadTotalSize) && payloadTotalSize > 0
-        ? payloadTotalSize
-        : startOffset + dataLength;
-
-    if (totalSize < startOffset + dataLength) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        `FilesystemFileWrite totalSize ${totalSize} is smaller than offset + data length ${
-          startOffset + dataLength
-        }`
-      );
-    }
-
-    const chunkSize = normalizeChunkSize(
-      this.params.chunkSize ?? this.params.chunkLen,
-      getProtocolV2FileChunkLimit()
-    );
-    const overwrite = this.params.overwrite ?? false;
-    const append = this.params.append ?? false;
-    let written = 0;
-    let chunkIndex = 0;
-    let lastMessage: Record<string, unknown> | undefined;
-    const startTime = Date.now();
-    const timeoutMs =
-      this.params.timeoutMs === undefined ? undefined : Number(this.params.timeoutMs);
-
-    while (written < dataLength) {
-      const chunkEnd = Math.min(written + chunkSize, dataLength);
-      const chunk = data.slice(written, chunkEnd);
-      const offset = startOffset + written;
-      const isFirstChunk = chunkIndex === 0;
-      const progress =
-        this.params.uiPercentage ??
-        Math.min(Math.ceil(((written + chunk.byteLength) / dataLength) * 100), 99);
-
-      const res = await this.device.commands.typedCall(
-        'FilesystemFileWrite',
-        'FilesystemFile',
-        {
-          file: {
-            path: this.params.path,
-            offset,
-            total_size: totalSize,
-            data: chunk,
-          },
-          overwrite: isFirstChunk ? overwrite : false,
-          append,
-          ui_percentage: progress,
-        },
-        {
-          timeoutMs,
-        }
-      );
-
-      lastMessage = res.message;
-      const processedByte = Number(res.message?.processed_byte);
-      if (Number.isFinite(processedByte) && processedByte > offset) {
-        written = processedByte - startOffset;
-      } else {
-        written += chunk.byteLength;
-      }
-
-      if (written > dataLength) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.RuntimeError,
-          `FilesystemFileWrite invalid processed_byte ${processedByte}`
-        );
-      }
-
-      const confirmedProcessedByte =
-        Number.isFinite(processedByte) && processedByte > offset
-          ? processedByte
-          : startOffset + written;
-      if (typeof this.postMessage === 'function') {
-        const elapsedMs = Date.now() - startTime;
-        const transferredBytes = Math.min(written, dataLength);
-        this.postMessage(
-          createUiMessage(UI_REQUEST.DEVICE_PROGRESS, {
-            progress: getConfirmedProgress(confirmedProcessedByte, totalSize, written, dataLength),
-            transferredBytes,
-            totalBytes: dataLength,
-            rateBytesPerSecond:
-              elapsedMs > 0 ? Math.round((transferredBytes / elapsedMs) * 1000) : undefined,
-            elapsedMs,
-          })
-        );
-      }
-      chunkIndex += 1;
-    }
-
-    return Promise.resolve({
-      ...lastMessage,
+    return writeProtocolV2File({
+      commands: this.device.commands,
       path: this.params.path,
-      offset: startOffset,
-      total_size: totalSize,
-      processed_byte: startOffset + written,
-      chunks: chunkIndex,
+      data: this.params.data,
+      offset: this.params.offset,
+      totalSize: this.params.totalSize,
+      chunkSize: this.params.chunkSize,
+      chunkLen: this.params.chunkLen,
+      overwrite: this.params.overwrite,
+      append: this.params.append,
+      uiPercentage: this.params.uiPercentage,
+      timeoutMs: this.params.timeoutMs === undefined ? undefined : Number(this.params.timeoutMs),
+      throwIfAborted: () => this.throwIfAborted(),
+      onProgress: payload => {
+        if (this.params.emitProgress && typeof this.postMessage === 'function') {
+          this.postMessage(createUiMessage(UI_REQUEST.DEVICE_PROGRESS, payload));
+        }
+      },
     });
   }
 }

package/src/api/FirmwareUpdate.ts

@@ -14,7 +14,7 @@ import { uploadFirmware } from './firmware/uploadFirmware';
 import { createUiMessage } from '../events';
 import { DeviceModelToTypes, type KnownDevice } from '../types';
 import { isEnteredManuallyBoot } from './firmware/bootloaderHelper';
-import { LoggerNames, getDeviceUUID, getLogger, wait } from '../utils';
+import { LoggerNames, getLogger, wait } from '../utils';
 import { DataManager } from '../data-manager';
 import { DevicePool } from '../device/DevicePool';
 
@@ -133,7 +133,7 @@ export default class FirmwareUpdate extends BaseMethod<Params> {
     const { features, commands } = device;
     const deviceType = device.getCurrentDeviceType();
 
-    // Protocol V2 (Pro2) 固件升级走 DeviceFirmwareUpdate 流程，禁止进入 legacy 入口
+    // Protocol V2 (Pro2) uses DeviceFirmwareUpdate and must not enter this legacy flow.
     if (device.isProtocolV2()) {
       throw ERRORS.TypedError(
         HardwareErrorCode.RuntimeError,
@@ -142,7 +142,7 @@ export default class FirmwareUpdate extends BaseMethod<Params> {
     }
 
     if (!device.isBootloader() && features) {
-      const uuid = getDeviceUUID(features);
+      const serialNo = device.getCurrentSerialNo();
       // should go to bootloader mode manually
       if (isEnteredManuallyBoot(features, params.updateType)) {
         return Promise.reject(ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateManuallyEnterBoot));
@@ -161,7 +161,7 @@ export default class FirmwareUpdate extends BaseMethod<Params> {
 
         // force clean classic device cache so that the device can initialize again
         if (DeviceModelToTypes.model_classic.includes(deviceType)) {
-          DevicePool.clearDeviceCache(uuid);
+          DevicePool.clearDeviceCache(serialNo);
         }
         delete DevicePool.devicesCache[''];
         await this.checkPromise?.promise;

package/src/api/FirmwareUpdateV2.ts

@@ -15,20 +15,14 @@ import { validateParams } from './helpers/paramsValidator';
 import { DevicePool } from '../device/DevicePool';
 import { getBinary, getInfo, getSysResourceBinary } from './firmware/getBinary';
 import { updateResources, uploadFirmware } from './firmware/uploadFirmware';
-import {
-  LoggerNames,
-  getDeviceBootloaderVersion,
-  getDeviceFirmwareVersion,
-  getDeviceUUID,
-  getLogger,
-  wait,
-} from '../utils';
+import { LoggerNames, getLogger, wait } from '../utils';
 import { FirmwareUpdateTipMessage, createUiMessage } from '../events/ui-request';
 import { DeviceModelToTypes } from '../types';
 import { DataManager } from '../data-manager';
 import { DEVICE } from '../events';
 
 import type { Features, KnownDevice } from '../types';
+import type { FirmwareBinary } from './firmware/getBinary';
 
 type Params = {
   binary?: ArrayBuffer;
@@ -41,6 +35,77 @@ type Params = {
 
 const Log = getLogger(LoggerNames.Method);
 
+const FIRMWARE_DOWNLOAD_REQUEST_OPTIONS = {
+  connectTimeoutMs: 60_000,
+  readTimeoutMs: 60_000,
+  overallTimeoutMs: 180_000,
+  maxRetries: 2,
+  retryDelayMs: 500,
+} as const;
+
+const normalizeFirmwareBinary = (binary: unknown): FirmwareBinary | undefined => {
+  if (typeof binary !== 'object' || binary === null) {
+    return undefined;
+  }
+
+  const isNodeBuffer =
+    typeof Buffer !== 'undefined' &&
+    typeof Buffer.isBuffer === 'function' &&
+    Buffer.isBuffer(binary);
+  if (isNodeBuffer) {
+    return binary.byteLength > 0 ? binary : undefined;
+  }
+
+  if (typeof ArrayBuffer !== 'undefined' && binary instanceof ArrayBuffer) {
+    return binary.byteLength > 0 ? binary : undefined;
+  }
+
+  if (
+    typeof ArrayBuffer !== 'undefined' &&
+    typeof ArrayBuffer.isView === 'function' &&
+    ArrayBuffer.isView(binary)
+  ) {
+    if (binary.byteLength <= 0) {
+      return undefined;
+    }
+    const source = new Uint8Array(binary.buffer, binary.byteOffset, binary.byteLength);
+    const normalized = new Uint8Array(binary.byteLength);
+    normalized.set(source);
+    return normalized.buffer;
+  }
+
+  const customBuffer = binary as {
+    [index: number]: unknown;
+    byteLength?: unknown;
+    constructor?: {
+      isBuffer?: (value: unknown) => boolean;
+    };
+    length?: unknown;
+  };
+  if (
+    typeof customBuffer.constructor?.isBuffer !== 'function' ||
+    !customBuffer.constructor.isBuffer(binary) ||
+    typeof customBuffer.byteLength !== 'number' ||
+    !Number.isSafeInteger(customBuffer.byteLength) ||
+    customBuffer.byteLength <= 0 ||
+    typeof customBuffer.length !== 'number' ||
+    customBuffer.length !== customBuffer.byteLength
+  ) {
+    return undefined;
+  }
+
+  const { byteLength } = customBuffer;
+  const normalized = new Uint8Array(byteLength);
+  for (let index = 0; index < byteLength; index += 1) {
+    const { [index]: byte } = customBuffer;
+    if (typeof byte !== 'number' || !Number.isInteger(byte) || byte < 0 || byte > 255) {
+      return undefined;
+    }
+    normalized[index] = byte;
+  }
+  return normalized.buffer;
+};
+
 export default class FirmwareUpdateV2 extends BaseMethod<Params> {
   checkPromise: Deferred<any> | null = null;
 
@@ -223,22 +288,22 @@ export default class FirmwareUpdateV2 extends BaseMethod<Params> {
     return false;
   }
 
-  isEnteredManuallyBoot(features: Features) {
+  isEnteredManuallyBoot() {
     const deviceType = this.device.getCurrentDeviceType();
     const isMini = deviceType === EDeviceType.Mini;
     const isBoot183ClassicUpBle =
       this.params.updateType === 'firmware' &&
       deviceType === EDeviceType.Classic &&
-      getDeviceBootloaderVersion(features).join('.') === '1.8.3';
+      this.device.getCurrentBootloaderVersionString() === '1.8.3';
     return isMini || isBoot183ClassicUpBle;
   }
 
-  isSupportResourceUpdate(features: Features, updateType: string) {
+  isSupportResourceUpdate(updateType: string) {
     if (updateType !== 'firmware') return false;
 
     const deviceType = this.device.getCurrentDeviceType();
     const isTouchMode = deviceType === EDeviceType.Touch || deviceType === EDeviceType.Pro;
-    const currentVersion = getDeviceFirmwareVersion(features).join('.');
+    const currentVersion = this.device.getCurrentFirmwareVersionString() ?? '0.0.0';
 
     return isTouchMode && semver.gte(currentVersion, '3.2.0');
   }
@@ -250,7 +315,7 @@ export default class FirmwareUpdateV2 extends BaseMethod<Params> {
   checkVersionForCopyTouchResource(features: Features | undefined, firmwareType: EFirmwareType) {
     if (!features) return;
     const deviceType = this.device.getCurrentDeviceType();
-    const currentVersion = getDeviceFirmwareVersion(features).join('.');
+    const currentVersion = this.device.getCurrentFirmwareVersionString() ?? '0.0.0';
     const targetVersion = this.params.version?.join('.');
     const { updateType } = this.params;
 
@@ -276,7 +341,7 @@ export default class FirmwareUpdateV2 extends BaseMethod<Params> {
     const { features, commands } = device;
     const deviceType = device.getCurrentDeviceType();
 
-    // Protocol V2 (Pro2) 固件升级走 DeviceFirmwareUpdate 流程，禁止进入 legacy 入口
+    // Protocol V2 (Pro2) uses DeviceFirmwareUpdate and must not enter this legacy flow.
     if (device.isProtocolV2()) {
       throw ERRORS.TypedError(
         HardwareErrorCode.RuntimeError,
@@ -289,15 +354,57 @@ export default class FirmwareUpdateV2 extends BaseMethod<Params> {
 
     this.checkVersionForCopyTouchResource(features, firmwareType);
 
+    let preparedBinary: FirmwareBinary | undefined;
+    const acquireFirmwareBinary = async (): Promise<FirmwareBinary> => {
+      try {
+        if (preparedBinary) {
+          return preparedBinary;
+        }
+
+        if (params.binary !== undefined) {
+          preparedBinary = normalizeFirmwareBinary(params.binary);
+          if (!preparedBinary) {
+            throw new Error('firmware binary is empty or invalid');
+          }
+          return preparedBinary;
+        }
+
+        if (!device.features) {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.RuntimeError,
+            'no features found for this device'
+          );
+        }
+
+        this.postTipMessage('DownloadFirmware');
+        const firmware = await getBinary({
+          features: device.features,
+          version: params.version,
+          updateType: params.updateType,
+          isUpdateBootloader: params.isUpdateBootloader,
+          firmwareType,
+          requestOptions: FIRMWARE_DOWNLOAD_REQUEST_OPTIONS,
+        });
+        preparedBinary = normalizeFirmwareBinary(firmware.binary);
+        if (!preparedBinary) {
+          throw new Error('downloaded firmware binary is empty or invalid');
+        }
+        this.postTipMessage('DownloadFirmwareSuccess');
+        return preparedBinary;
+      } catch (err) {
+        throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateDownloadFailed, err.message ?? err);
+      }
+    };
+
     if (!device.isBootloader() && features) {
-      const uuid = getDeviceUUID(features);
+      const serialNo = device.getCurrentSerialNo();
       // should go to bootloader mode manually
-      if (this.isEnteredManuallyBoot(features)) {
+      if (this.isEnteredManuallyBoot()) {
         return Promise.reject(ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateManuallyEnterBoot));
       }
 
       // check & upgrade firmware resource
-      if (features && this.isSupportResourceUpdate(features, params.updateType)) {
+      if (this.isSupportResourceUpdate(params.updateType)) {
         this.postTipMessage('CheckLatestUiResource');
         const resourceUrl = DataManager.getSysResourcesLatestRelease({
           features,
@@ -322,6 +429,12 @@ export default class FirmwareUpdateV2 extends BaseMethod<Params> {
       // check if the device commands has been disposed
       this.device?.commands?.checkDisposed();
 
+      // A failed firmware download must leave the device in normal mode.
+      await acquireFirmwareBinary();
+
+      // The request may outlive the current transport command instance.
+      this.device?.commands?.checkDisposed();
+
       // auto go to bootloader mode
       try {
         this.postTipMessage('AutoRebootToBootloader');
@@ -335,7 +448,7 @@ export default class FirmwareUpdateV2 extends BaseMethod<Params> {
 
         // force clean classic device cache so that the device can initialize again
         if (DeviceModelToTypes.model_classic.includes(deviceType)) {
-          DevicePool.clearDeviceCache(uuid);
+          DevicePool.clearDeviceCache(serialNo);
         }
         delete DevicePool.devicesCache[''];
         await this.checkPromise?.promise;
@@ -360,33 +473,8 @@ export default class FirmwareUpdateV2 extends BaseMethod<Params> {
       }
     }
 
-    let binary;
-
-    try {
-      if (params.binary) {
-        binary = this.params.binary;
-      } else {
-        if (!device.features) {
-          throw ERRORS.TypedError(
-            HardwareErrorCode.RuntimeError,
-            'no features found for this device'
-          );
-        }
-        this.postTipMessage('DownloadFirmware');
-
-        const firmware = await getBinary({
-          features: device.features,
-          version: params.version,
-          updateType: params.updateType,
-          isUpdateBootloader: params.isUpdateBootloader,
-          firmwareType,
-        });
-        binary = firmware.binary;
-        this.postTipMessage('DownloadFirmwareSuccess');
-      }
-    } catch (err) {
-      throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateDownloadFailed, err.message ?? err);
-    }
+    // Devices already in bootloader mode still acquire through the same helper.
+    const binary = await acquireFirmwareBinary();
 
     // check if the device commands has been disposed
     this.device?.commands?.checkDisposed();

package/src/api/FirmwareUpdateV3.ts

@@ -9,8 +9,6 @@ import {
   getDeviceBLEFirmwareVersion,
   getDeviceBootloaderVersion,
   getDeviceFirmwareVersion,
-  getDeviceType,
-  getFirmwareType,
   getLogger,
 } from '../utils';
 import { getBinary, getSysResourceBinary } from './firmware/getBinary';
@@ -97,8 +95,8 @@ export default class FirmwareUpdateV3 extends FirmwareUpdateBaseMethod<FirmwareU
     const { device } = this;
     const { features } = device;
 
-    const deviceType = getDeviceType(features);
-    const bootloaderCurrVersion = getDeviceBootloaderVersion(features).join('.');
+    const deviceType = device.getCurrentDeviceType();
+    const bootloaderCurrVersion = device.getCurrentBootloaderVersionString() ?? '0.0.0';
 
     this.validateDeviceAndVersion(deviceType, bootloaderCurrVersion);
 
@@ -106,7 +104,7 @@ export default class FirmwareUpdateV3 extends FirmwareUpdateBaseMethod<FirmwareU
       throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Device features not available');
     }
 
-    const deviceFirmwareType = getFirmwareType(features);
+    const deviceFirmwareType = device.getCurrentFirmwareType();
     const firmwareType = this.params.firmwareType ?? deviceFirmwareType;
     this.isSwitchFirmware = firmwareType !== deviceFirmwareType;