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

package/src/api/BaseMethod.ts

@@ -11,7 +11,7 @@ import { UI_REQUEST } from '../constants/ui-request';
 import { DEVICE, FIRMWARE, createFirmwareMessage, createUiMessage } from '../events';
 import { getHDPath, toHardened } from './helpers/pathUtils';
 import { getBleFirmwareReleaseInfo, getFirmwareReleaseInfo } from './firmware/releaseHelper';
-import { LoggerNames, getFirmwareType, getLogger, isMethodVersionRangeUnsupported } from '../utils';
+import { LoggerNames, getLogger, isMethodVersionRangeUnsupported } from '../utils';
 import { generateInstanceId } from '../utils/tracing';
 import { DeviceModelToTypes } from '../types';
 
@@ -25,6 +25,7 @@ import type { CoreContext } from '../core';
 
 export type UnlockPolicy = 'none' | 'retry-on-locked';
 export type ProtocolV2UiMode = 'auto' | 'none';
+export type MethodExecutionPriority = 'normal' | 'background';
 
 const Log = getLogger(LoggerNames.Method);
 
@@ -101,6 +102,12 @@ export abstract class BaseMethod<Params = undefined> {
    */
   useDevice: boolean;
 
+  /** Background methods must not block user-initiated device interactions. */
+  executionPriority: MethodExecutionPriority = 'normal';
+
+  /** Maximum time a background method may need to observe abort and release the device. */
+  maxAbortLatencyMs?: number;
+
   /**
    * 允许的设备模式。当前设备模式在该数组中，则可以允许运行。
    * eg. NOT_INITIALIZE, BOOTLOADER, SEEDLESS
@@ -163,20 +170,20 @@ export abstract class BaseMethod<Params = undefined> {
   strictCheckDeviceSupport = false;
 
   /**
-   * 方法是否仅支持 Protocol V2 设备（Pro2）。
-   * core 调度在设备协议确定（acquire + initialize）后统一守卫，
-   * 非 V2 设备直接抛出 NotSupport 错误，方法内部不必重复判断。
+   * Whether this method supports Protocol V2 devices (Pro2) only.
+   * Core enforces this after the protocol is established during acquire and initialize,
+   * so implementations do not need to repeat the check.
    * @default false
    */
   requireProtocolV2 = false;
 
-  /** Protocol V2 业务方法锁定时默认由 Core 自动解锁并重试一次。 */
+  /** Core unlocks and retries Protocol V2 business methods once when the device is locked. */
   unlockPolicy: UnlockPolicy = 'retry-on-locked';
 
-  /** Protocol V2 由 SDK 合成的非阻塞设备交互提示；未声明时不生成交互 Event。 */
+  /** Non-blocking Protocol V2 interaction synthesized by the SDK. */
   protocolV2UiInteraction?: ProtocolV2InteractionDescriptor;
 
-  /** 特殊后台方法可关闭包括自动解锁提示在内的全部 Protocol V2 合成 UI Event。 */
+  /** Special background methods may suppress all synthesized Protocol V2 UI events. */
   protocolV2UiMode: ProtocolV2UiMode = 'auto';
 
   protected throwIfAborted() {
@@ -251,11 +258,11 @@ export abstract class BaseMethod<Params = undefined> {
   }
 
   checkFirmwareRelease() {
-    // 固件 release 元数据（DataManager remote config）目前只覆盖 Protocol V1 设备；
-    // Pro2 的更新流程由 firmwareUpdateV4 自行管理，这里显式跳过而不是依赖 features 为空。
+    // DataManager release metadata currently covers Protocol V1 devices only.
+    // firmwareUpdateV4 manages Pro2 updates, so skip them explicitly.
     if (!this.device || this.device.isProtocolV2()) return;
     if (!this.device.features) return;
-    const firmwareType = getFirmwareType(this.device.features);
+    const firmwareType = this.device.getCurrentFirmwareType();
     const releaseInfo = getFirmwareReleaseInfo(this.device.features, firmwareType);
     this.postMessage(
       createFirmwareMessage(FIRMWARE.RELEASE_INFO, {

package/src/api/CheckBootloaderRelease.ts

@@ -1,7 +1,6 @@
 import { BaseMethod } from './BaseMethod';
 import { UI_REQUEST } from '../constants/ui-request';
 import { getBootloaderReleaseInfo } from './firmware/releaseHelper';
-import { getFirmwareType } from '../utils';
 
 import type { CheckBootloaderReleaseParams } from '../types/api/checkBootloaderRelease';
 
@@ -19,7 +18,7 @@ export default class CheckBootloaderRelease extends BaseMethod {
     const { features } = this.device;
     const payload = this.payload as CheckBootloaderReleaseParams;
 
-    const deviceFirmwareType = getFirmwareType(features);
+    const deviceFirmwareType = this.device.getCurrentFirmwareType();
     const firmwareType = payload.firmwareType ?? deviceFirmwareType;
 
     const releaseInfo = getBootloaderReleaseInfo({

package/src/api/CheckFirmwareRelease.ts

@@ -1,7 +1,6 @@
 import { BaseMethod } from './BaseMethod';
 import { UI_REQUEST } from '../constants/ui-request';
 import { getFirmwareReleaseInfo } from './firmware/releaseHelper';
-import { getFirmwareType } from '../utils';
 
 import type { CheckFirmwareReleaseParams } from '../types/api/checkFirmwareRelease';
 
@@ -20,7 +19,7 @@ export default class CheckFirmwareRelease extends BaseMethod {
     const payload = this.payload as CheckFirmwareReleaseParams;
 
     if (this.device.features) {
-      const deviceFirmwareType = getFirmwareType(this.device.features);
+      const deviceFirmwareType = this.device.getCurrentFirmwareType();
       const firmwareType = payload.firmwareType ?? deviceFirmwareType;
 
       const releaseInfo = getFirmwareReleaseInfo(this.device.features, firmwareType);

package/src/api/ClearSessionCache.ts

@@ -1,5 +1,4 @@
 import { BaseMethod } from './BaseMethod';
-import { DevicePool } from '../device/DevicePool';
 import { deviceWalletSessionStore } from '../device/DeviceWalletSessionStore';
 
 import type { ClearSessionCacheParams } from '../types/api/sessionCache';
@@ -24,9 +23,6 @@ export default class ClearSessionCache extends BaseMethod<ClearSessionCacheParam
     } else {
       deviceWalletSessionStore.delete(deviceId, passphraseState);
     }
-    Object.values(DevicePool.devicesCache).forEach(device => {
-      device.clearCachedSession(deviceId, passphraseState);
-    });
     return Promise.resolve({ cleared: true as const });
   }
 }

package/src/api/DirList.ts

@@ -1,7 +1,7 @@
 import { BaseMethod } from './BaseMethod';
 import {
-  validateNonEmptyString,
   validateOptionalNonNegativeInteger,
+  validateProtocolV2FilesystemPath,
 } from './helpers/filesystemValidation';
 
 export type DirListParams = {
@@ -11,12 +11,14 @@ export type DirListParams = {
 
 export default class DirList extends BaseMethod<DirListParams> {
   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'),
+      path: validateProtocolV2FilesystemPath(this.payload.path, 'path', {
+        allowVolumeRoot: true,
+      }),
       depth: validateOptionalNonNegativeInteger(this.payload.depth, 'depth'),
     };
   }

package/src/api/DirMake.ts

@@ -1,5 +1,5 @@
 import { BaseMethod } from './BaseMethod';
-import { validateNonEmptyString } from './helpers/filesystemValidation';
+import { validateProtocolV2FilesystemPath } from './helpers/filesystemValidation';
 
 export type DirMakeParams = {
   path: string;
@@ -7,11 +7,11 @@ export type DirMakeParams = {
 
 export default class DirMake extends BaseMethod<DirMakeParams> {
   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/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

@@ -6,10 +6,10 @@ 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';
@@ -69,7 +69,11 @@ function toUint8Array(value: unknown): Uint8Array {
   return new Uint8Array(0);
 }
 
-function getDeviceTransferProgress(bytesBeforeChunk: number, bytesAfterChunk: number, totalBytes: number) {
+function getDeviceTransferProgress(
+  bytesBeforeChunk: number,
+  bytesAfterChunk: number,
+  totalBytes: number
+) {
   if (!Number.isFinite(totalBytes) || totalBytes <= 0) {
     return 100;
   }
@@ -84,11 +88,11 @@ function getDeviceTransferProgress(bytesBeforeChunk: number, bytesAfterChunk: nu
 
 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),
@@ -136,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 ??
-        getDeviceTransferProgress(read, read + readLen, totalLength);
+        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,9 +1,9 @@
 import { BaseMethod } from './BaseMethod';
 import {
-  validateNonEmptyString,
   validateNonNegativeInteger,
   validateOptionalNonNegativeInteger,
   validateOptionalPercentage,
+  validateProtocolV2FilesystemPath,
   validateRequiredData,
 } from './helpers/filesystemValidation';
 import { writeProtocolV2File } from './helpers/protocolV2FileWrite';
@@ -25,12 +25,12 @@ export type FileWriteParams = {
 
 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,

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;