@onekeyfe/hd-core 1.2.0-alpha.3 → 1.2.0-alpha.4

package/src/api/FirmwareUpdateV4.ts

@@ -1,6 +1,6 @@
 import { ERRORS, HardwareError, HardwareErrorCode, wait } from '@onekeyfe/hd-shared';
 import {
-  DevRebootType,
+  DeviceRebootType,
   PROTOCOL_V2_BLE_FILE_CHUNK_SIZE,
   PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE,
 } from '@onekeyfe/hd-transport';
@@ -15,14 +15,13 @@ import {
   getFirmwareType,
   getLogger,
 } from '../utils';
-import { getBinary, getSysResourceBinary } from './firmware/getBinary';
+import { getSysResourceBinary } from './firmware/getBinary';
 import { DataManager } from '../data-manager';
 import { FirmwareUpdateBaseMethod } from './firmware/FirmwareUpdateBaseMethod';
 import { DevicePool } from '../device/DevicePool';
 import {
   PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
   ProtocolV2FirmwareTargetType,
-  protocolV2FileNameToTargetId,
 } from '../protocols/protocol-v2';
 import { requestProtocolV2DeviceInfo } from '../protocols/protocol-v2/features';
 import {
@@ -35,31 +34,162 @@ import type { FirmwareUpdateV4Params } from '../types/api/firmwareUpdate';
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
 import type { PROTO } from '../constants';
 import type { TypedResponseMessage } from '../device/DeviceCommands';
-import type { Features } from '../types';
+import type {
+  Features,
+  IFirmwareReleaseInfo,
+  IProtocolV2FirmwareComponent,
+  IProtocolV2ResourceManifestPackage,
+  IVersionArray,
+} from '../types';
 
 const Log = getLogger(LoggerNames.Method);
 
 const SESSION_ERROR = 'session not found';
 const PROTOCOL_V2_BOOTLOADER_RECONNECT_TIMEOUT = 60 * 1000;
 const PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT = 5 * 1000;
+const PROTOCOL_V2_START_UPDATE_TIMEOUT = 60 * 1000;
 const PROTOCOL_V2_INSTALL_TIMEOUT = 5 * 60 * 1000;
-const PROTOCOL_V2_TARGET_STATUS_FINISHED = 0;
+const PROTOCOL_V2_TARGET_STATUS_PENDING = 0;
 const PROTOCOL_V2_TARGET_STATUS_IN_PROGRESS = 1;
-const PROTOCOL_V2_TARGET_STATUS_FAILED = 2;
+const PROTOCOL_V2_TARGET_STATUS_FINISHED = 2;
+const PROTOCOL_V2_TARGET_STATUS_FAILED_MIN = 3;
 const PROTOCOL_V2_CONNECT_PROTOCOL = 'V2';
 const PROTOCOL_V2_FIRMWARE_STAGING_VOLUME = 'vol1:';
 const PROTOCOL_V2_MIN_FILE_CHUNK_SIZE = 64;
+const PROTOCOL_V2_CONNECT_RETRY_COUNT = 10;
+const PROTOCOL_V2_CONNECT_POLL_INTERVAL = 500;
+const PROTOCOL_V2_CONNECT_SINGLE_TIMEOUT = 75 * 1000;
+const PROTOCOL_V2_DEVICE_INFO_READY_TIMEOUT = 60 * 1000;
+const PROTOCOL_V2_OKPP_HEADER_SIZE = 0x52a0;
+const PROTOCOL_V2_OKPP_PAYLOAD_HASH_OFFSET = 0x200;
+const PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET = 0x240;
+const PROTOCOL_V2_OKPP_HASH_SIZE = 64;
+
+const getProtocolV2DeviceTransferProgress = (
+  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);
+};
+
+const formatProtocolV2TransferSpeed = (bytes: number, elapsedMs: number) => {
+  const safeElapsedMs = Math.max(elapsedMs, 1);
+  return (bytes / 1024 / (safeElapsedMs / 1000)).toFixed(2);
+};
 
 type ProtocolV2FirmwareUpdateStatusTarget = {
-  target_id: number;
-  status: number;
+  target_id: number | string;
+  status?: number | string;
+  payload_version?: number;
+  path?: string;
 };
 
 type ProtocolV2FirmwareUpdateStartResponse =
   | TypedResponseMessage<'Success'>
-  | TypedResponseMessage<'DevFirmwareUpdateStatus'>
+  | TypedResponseMessage<'DeviceFirmwareUpdateStatus'>
   | undefined;
 
+type ProtocolV2TargetBinary = { fileName: string; binary: ArrayBuffer; targetId: number };
+
+type ProtocolV2RemoteComponentBinary = ProtocolV2RemoteComponentTarget & {
+  binary: ArrayBuffer;
+};
+
+type ProtocolV2RemoteComponentTarget = {
+  fileName: string;
+  targetId: number;
+  kind: 'bootloader' | 'firmware' | 'resource';
+};
+
+type ProtocolV2OkppHeader = {
+  type: string;
+  version: IVersionArray;
+  payloadHash: string;
+  headerHash: string;
+};
+
+const PROTOCOL_V2_REMOTE_COMPONENT_TARGETS: Readonly<
+  Record<string, ProtocolV2RemoteComponentTarget>
+> = {
+  BOOTLOADER: {
+    fileName: 'bootloader.bin',
+    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_BOOTLOADER,
+    kind: 'bootloader',
+  },
+  APPLICATION_P1: {
+    fileName: 'application_p1.bin',
+    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P1,
+    kind: 'firmware',
+  },
+  APPLICATION_P2: {
+    fileName: 'application_p2.bin',
+    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P2,
+    kind: 'firmware',
+  },
+  COPROCESSOR: {
+    fileName: 'coprocessor.bin',
+    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_COPROCESSOR,
+    kind: 'firmware',
+  },
+  SE01: {
+    fileName: 'se01.bin',
+    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE01,
+    kind: 'firmware',
+  },
+  SE02: {
+    fileName: 'se02.bin',
+    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE02,
+    kind: 'firmware',
+  },
+  SE03: {
+    fileName: 'se03.bin',
+    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE03,
+    kind: 'firmware',
+  },
+  SE04: {
+    fileName: 'se04.bin',
+    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE04,
+    kind: 'firmware',
+  },
+  CRATE: {
+    fileName: 'resource.bin',
+    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_CRATE,
+    kind: 'resource',
+  },
+};
+
+const PROTOCOL_V2_ROMLOADER_UNSUPPORTED_MESSAGE =
+  'FW_MGMT_TARGET_ROMLOADER is not accepted by the current Pro2 bootloader update request. Flash romloader with the loader-specific flow instead of firmwareUpdateV4.';
+
+// hd-transport 的历史 decode 行为会把单值 enum 输出为枚举名字符串；
+// Protocol V2 沿用这个 SDK 语义，内部比较前再映射回固件协议数值。
+const PROTOCOL_V2_TARGET_ID_BY_DECODED_NAME = new Map<string, number>(
+  Object.entries(ProtocolV2FirmwareTargetType).map(([key, value]) => [key, value])
+);
+const PROTOCOL_V2_TARGET_STATUS_BY_DECODED_NAME = new Map<string, number>([
+  ['FW_MGMT_UPDATER_TASK_STATUS_PENDING', PROTOCOL_V2_TARGET_STATUS_PENDING],
+  ['FW_MGMT_UPDATER_TASK_STATUS_IN_PROGRESS', PROTOCOL_V2_TARGET_STATUS_IN_PROGRESS],
+  ['FW_MGMT_UPDATER_TASK_STATUS_FINISHED', PROTOCOL_V2_TARGET_STATUS_FINISHED],
+  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_FILE_NOT_FOUND', 3],
+  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_FILE_READ', 4],
+  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_FILE_WRITE', 5],
+  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_VERIFY', 6],
+  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_INSTALL', 7],
+  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_ABORT', 8],
+  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_BUSY', 9],
+  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_ENTRY_OUT_OF_BOUNDS', 10],
+]);
+
 const isProtocolV2ReconnectProbeError = (error: unknown) => {
   const message = getProtocolV2UnknownErrorText(error).toLowerCase();
   return (
@@ -73,19 +203,165 @@ const isProtocolV2PollingTransientError = (error: unknown) => {
   return (
     isProtocolV2DeviceDisconnectedError(error) ||
     isProtocolV2ReconnectProbeError(error) ||
-    (message.includes('response timeout') && message.includes('devicegetfirmwareupdatestatus')) ||
+    message.includes('libusb_transfer_timed_out') ||
+    (message.includes('response timeout') && message.includes('devicefirmwareupdatestatusget')) ||
     message.includes('device not found') ||
     message.includes('transportnotfound')
   );
 };
 
+const isProtocolV2StartUpdateTransientError = (error: unknown) => {
+  const message = getProtocolV2UnknownErrorText(error).toLowerCase();
+  return (
+    isProtocolV2DeviceDisconnectedError(error) ||
+    isProtocolV2ReconnectProbeError(error) ||
+    message.includes('libusb_transfer_timed_out') ||
+    (message.includes('response timeout') && message.includes('devicefirmwareupdaterequest'))
+  );
+};
+
+const isProtocolV2TargetStatusFinished = (status: ProtocolV2FirmwareUpdateStatusTarget['status']) =>
+  normalizeProtocolV2TargetStatus(status) === PROTOCOL_V2_TARGET_STATUS_FINISHED;
+
+const isProtocolV2TargetStatusInProgress = (
+  status: ProtocolV2FirmwareUpdateStatusTarget['status']
+) =>
+  normalizeProtocolV2TargetStatus(status) === PROTOCOL_V2_TARGET_STATUS_PENDING ||
+  normalizeProtocolV2TargetStatus(status) === PROTOCOL_V2_TARGET_STATUS_IN_PROGRESS;
+
+const isProtocolV2TargetStatusFailed = (status: ProtocolV2FirmwareUpdateStatusTarget['status']) => {
+  const normalizedStatus = normalizeProtocolV2TargetStatus(status);
+  return (
+    typeof normalizedStatus === 'number' && normalizedStatus >= PROTOCOL_V2_TARGET_STATUS_FAILED_MIN
+  );
+};
+
+const normalizeProtocolV2TargetId = (targetId: number | string) => {
+  if (typeof targetId === 'number') {
+    return targetId;
+  }
+  return PROTOCOL_V2_TARGET_ID_BY_DECODED_NAME.get(targetId);
+};
+
+const normalizeProtocolV2TargetStatus = (
+  status: ProtocolV2FirmwareUpdateStatusTarget['status']
+) => {
+  if (typeof status === 'number') {
+    return status;
+  }
+  if (typeof status === 'string') {
+    return PROTOCOL_V2_TARGET_STATUS_BY_DECODED_NAME.get(status);
+  }
+  return undefined;
+};
+
+const normalizeProtocolV2Hex = (value?: string) => value?.replace(/^0x/i, '').toLowerCase();
+
+const versionArrayToNumber = (version?: IVersionArray) => {
+  if (!version) return undefined;
+  return version[0] * 0x10000 + version[1] * 0x100 + version[2];
+};
+
+const versionStringToArray = (version?: string | null): IVersionArray | undefined => {
+  if (!version) return undefined;
+  const parts = version.split('.').map(part => Number(part));
+  if (parts.length !== 3 || parts.some(part => !Number.isFinite(part))) return undefined;
+  return parts as IVersionArray;
+};
+
+const compareProtocolV2Versions = (current?: IVersionArray, target?: IVersionArray) => {
+  const currentNumber = versionArrayToNumber(current);
+  const targetNumber = versionArrayToNumber(target);
+  if (currentNumber === undefined || targetNumber === undefined) return undefined;
+  return currentNumber - targetNumber;
+};
+
+const bytesToHex = (bytes: Uint8Array) =>
+  Array.from(bytes)
+    .map(byte => byte.toString(16).padStart(2, '0'))
+    .join('');
+
+const hexToProtocolV2Bytes = (hex: string) => {
+  const normalized = hex.replace(/^0x/i, '');
+  if (!normalized || normalized.length % 2 !== 0 || /[^0-9a-f]/i.test(normalized)) {
+    return new Uint8Array(0);
+  }
+  const bytes = new Uint8Array(normalized.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(normalized.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+};
+
+const toProtocolV2Bytes = (value: unknown): Uint8Array => {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (typeof value === 'string') return hexToProtocolV2Bytes(value);
+  return new Uint8Array(0);
+};
+
+const toProtocolV2FiniteNumber = (value: unknown) => {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : undefined;
+  }
+  if (value && typeof value === 'object') {
+    const longLike = value as { toNumber?: () => number };
+    if (typeof longLike.toNumber === 'function') {
+      const numeric = longLike.toNumber();
+      return Number.isFinite(numeric) ? numeric : undefined;
+    }
+  }
+  return undefined;
+};
+
+const readProtocolV2Ascii = (bytes: Uint8Array, offset: number, length: number) =>
+  Array.from(bytes.slice(offset, offset + length))
+    .map(byte => String.fromCharCode(byte))
+    .join('');
+
+const parseProtocolV2OkppHeader = (bytes: Uint8Array): ProtocolV2OkppHeader | null => {
+  if (bytes.byteLength < PROTOCOL_V2_OKPP_HEADER_SIZE) return null;
+  if (readProtocolV2Ascii(bytes, 0, 4) !== 'OKPP') return null;
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const headerLen = view.getUint32(0x0c, true);
+  if (headerLen !== PROTOCOL_V2_OKPP_HEADER_SIZE) return null;
+
+  const packedVersion = view.getUint32(0x10, true);
+  return {
+    type: readProtocolV2Ascii(bytes, 0x08, 4),
+    version: [
+      Math.floor(packedVersion / 0x10000) % 0x100,
+      Math.floor(packedVersion / 0x100) % 0x100,
+      packedVersion % 0x100,
+    ],
+    payloadHash: bytesToHex(
+      bytes.slice(
+        PROTOCOL_V2_OKPP_PAYLOAD_HASH_OFFSET,
+        PROTOCOL_V2_OKPP_PAYLOAD_HASH_OFFSET + PROTOCOL_V2_OKPP_HASH_SIZE
+      )
+    ),
+    headerHash: bytesToHex(
+      bytes.slice(
+        PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET,
+        PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET + PROTOCOL_V2_OKPP_HASH_SIZE
+      )
+    ),
+  };
+};
+
 /**
  * FirmwareUpdateV4 is the complete Protocol V2 firmware update flow.
  *
  * It intentionally does not fall back to FirmwareUpdateV3/V1 behavior:
  * - upload uses FilesystemFileWrite
- * - install uses DevFirmwareUpdate
- * - completion reboots to normal, then polls Ping
+ * - install uses DeviceFirmwareUpdateRequest
+ * - completion waits for target status to finish, reboots to normal, then polls DeviceInfo
  */
 export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareUpdateV4Params> {
   init() {
@@ -96,15 +372,23 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
     const { payload } = this;
 
+    if (typeof payload.retryCount !== 'number') {
+      payload.retryCount = PROTOCOL_V2_CONNECT_RETRY_COUNT;
+    }
+    if (typeof payload.pollIntervalTime !== 'number') {
+      payload.pollIntervalTime = PROTOCOL_V2_CONNECT_POLL_INTERVAL;
+    }
+    if (typeof payload.timeout !== 'number') {
+      payload.timeout = PROTOCOL_V2_CONNECT_SINGLE_TIMEOUT;
+    }
+    if (typeof payload.protocolV2DeviceInfoTimeoutMs !== 'number') {
+      payload.protocolV2DeviceInfoTimeoutMs = PROTOCOL_V2_DEVICE_INFO_READY_TIMEOUT;
+    }
+
     validateParams(payload, [
-      { name: 'bleVersion', type: 'array' },
-      { name: 'bleBinary', type: 'buffer' },
       { name: 'chunkSize', type: 'number' },
-      { name: 'firmwareVersion', type: 'array' },
-      { name: 'firmwareBinary', type: 'buffer' },
-      { name: 'resourceBinary', type: 'buffer' },
+      { name: 'resourceBinaries', type: 'array', allowEmpty: true },
       { name: 'forcedUpdateRes', type: 'boolean' },
-      { name: 'bootloaderVersion', type: 'array' },
       { name: 'bootloaderBinary', type: 'buffer' },
       { name: 'romloaderBinary', type: 'buffer' },
       { name: 'applicationP1Binary', type: 'buffer' },
@@ -119,12 +403,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     ]);
 
     this.params = {
-      bleBinary: payload.bleBinary,
       chunkSize: payload.chunkSize,
-      firmwareBinary: payload.firmwareBinary,
       forcedUpdateRes: payload.forcedUpdateRes,
-      bleVersion: payload.bleVersion,
-      bootloaderVersion: payload.bootloaderVersion,
       bootloaderBinary: payload.bootloaderBinary,
       romloaderBinary: payload.romloaderBinary,
       applicationP1Binary: payload.applicationP1Binary,
@@ -134,8 +414,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       se02Binary: payload.se02Binary,
       se03Binary: payload.se03Binary,
       se04Binary: payload.se04Binary,
-      firmwareVersion: payload.firmwareVersion,
-      resourceBinary: payload.resourceBinary,
+      resourceBinaries: payload.resourceBinaries,
       firmwareType: payload.firmwareType,
       platform: payload.platform,
     };
@@ -174,33 +453,39 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     const deviceFirmwareType = getFirmwareType(deviceFeatures);
     const firmwareType = this.params.firmwareType ?? deviceFirmwareType;
 
-    let resourceBinary: ArrayBuffer | null = null;
-    let fwBinaryMap: { fileName: string; binary: ArrayBuffer; targetId?: number }[] = [];
+    let resourceBinaryMap: ProtocolV2TargetBinary[] = [];
+    let fwBinaryMap: ProtocolV2TargetBinary[] = [];
     let bootloaderBinary: ArrayBuffer | null = null;
     try {
       this.postTipMessage(FirmwareUpdateTipMessage.StartDownloadFirmware);
-      resourceBinary = await this.prepareResourceBinary(firmwareType, deviceFeatures);
-      fwBinaryMap = await this.prepareFirmwareAndBleBinary(firmwareType, deviceFeatures);
-      bootloaderBinary = await this.prepareBootloaderBinary(firmwareType, deviceFeatures);
-      // 按 DevFirmwareTargetType 拆分的目标二进制（显式 target_id，不走文件名推断）
-      fwBinaryMap.push(...this.collectExplicitTargetBinaries());
+      resourceBinaryMap = await this.prepareResourceBinaries(firmwareType, deviceFeatures);
+      fwBinaryMap = this.collectExplicitTargetBinaries();
+      bootloaderBinary = this.prepareBootloaderBinary();
+      if (!this.hasExplicitProtocolV2Payload(fwBinaryMap)) {
+        const remoteBinaries = await this.prepareRemoteProtocolV2Binaries(
+          firmwareType,
+          deviceFeatures
+        );
+        resourceBinaryMap = remoteBinaries.resourceBinaryMap;
+        bootloaderBinary = remoteBinaries.bootloaderBinary;
+        fwBinaryMap = remoteBinaries.fwBinaryMap;
+      }
       this.postTipMessage(FirmwareUpdateTipMessage.FinishDownloadFirmware);
     } catch (err) {
       throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateDownloadFailed, err.message ?? err);
     }
 
-    if (!resourceBinary && !bootloaderBinary && fwBinaryMap.length === 0) {
+    if (resourceBinaryMap.length === 0 && !bootloaderBinary && fwBinaryMap.length === 0) {
       throw ERRORS.TypedError(
         HardwareErrorCode.FirmwareUpdateDownloadFailed,
         'No firmware to update'
       );
     }
 
-    // TODO: 当前 firmware-pro2 子模块的 reboot/bootloader 流程还未稳定，先暂停自动进 bootloader。
-    // await this.enterProtocolV2BootloaderMode();
+    await this.enterProtocolV2BootloaderMode();
 
     await this.executeProtocolV2Update({
-      resourceBinary,
+      resourceBinaryMap,
       fwBinaryMap,
       bootloaderBinary,
     });
@@ -215,19 +500,32 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
   }
 
   private async getProtocolV2DeviceFeatures(): Promise<Features> {
+    if (this.device.features) {
+      return this.device.features;
+    }
     if (typeof this.device.getFeatures === 'function') {
       const features = await this.device.getFeatures();
       if (features) return features;
     }
-    if (this.device.features) {
-      return this.device.features;
-    }
     throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Device features not available');
   }
 
-  private async prepareResourceBinary(firmwareType: EFirmwareType, features: Features) {
-    if (this.params.resourceBinary) {
-      return this.params.resourceBinary;
+  private async prepareResourceBinaries(firmwareType: EFirmwareType, features: Features) {
+    if (this.params.resourceBinaries?.length) {
+      this.params.resourceBinaries.forEach((binary, index) => {
+        if (!(binary instanceof ArrayBuffer)) {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.CallMethodInvalidParameter,
+            `Parameter [resourceBinaries.${index}] is of type invalid and should be [buffer].`
+          );
+        }
+      });
+
+      return this.params.resourceBinaries.map((binary, index) => ({
+        fileName: `resource-${index + 1}.bin`,
+        binary,
+        targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_CRATE,
+      }));
     }
     const resourceUrl = DataManager.getSysResourcesLatestRelease({
       features,
@@ -237,28 +535,332 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
     if (resourceUrl) {
       const resource = (await getSysResourceBinary(resourceUrl)).binary;
-      return resource;
+      return [
+        {
+          fileName: 'resource.bin',
+          binary: resource,
+          targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_CRATE,
+        },
+      ];
     }
     Log.warn('No resource url found');
-    return null;
+    return [];
+  }
+
+  private prepareBootloaderBinary(): ArrayBuffer | null {
+    return this.params.bootloaderBinary ?? null;
+  }
+
+  private hasExplicitProtocolV2Payload(fwBinaryMap: ProtocolV2TargetBinary[]) {
+    return (
+      !!this.params.resourceBinaries?.length ||
+      !!this.params.bootloaderBinary ||
+      fwBinaryMap.length > 0
+    );
+  }
+
+  private getRemoteComponentEntries(release: IFirmwareReleaseInfo) {
+    const { components } = release;
+    if (!components) return [];
+
+    const orderedKeys = [
+      ...(release.installOrder ?? []),
+      ...Object.keys(components).filter(key => !release.installOrder?.includes(key)),
+    ];
+
+    return orderedKeys
+      .map(key => {
+        const component = components[key];
+        return component ? ([key, component] as const) : undefined;
+      })
+      .filter((entry): entry is readonly [string, IProtocolV2FirmwareComponent] => !!entry);
+  }
+
+  private getRemoteComponentTarget(key: string, component: IProtocolV2FirmwareComponent) {
+    const targetName = component.target?.toUpperCase();
+    if (targetName === 'ROMLOADER') {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        PROTOCOL_V2_ROMLOADER_UNSUPPORTED_MESSAGE
+      );
+    }
+    const target = PROTOCOL_V2_REMOTE_COMPONENT_TARGETS[targetName];
+    if (!target) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        `Unsupported Protocol V2 firmware component target: ${key}/${component.target}`
+      );
+    }
+    return target;
+  }
+
+  private getProtocolV2ComponentTargetVersion(
+    release: IFirmwareReleaseInfo,
+    component: IProtocolV2FirmwareComponent,
+    target: ProtocolV2RemoteComponentTarget
+  ) {
+    if (component.version) return component.version;
+    if (target.targetId === ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_BOOTLOADER) {
+      return release.bootloaderVersion;
+    }
+    if (
+      target.targetId === ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P1 ||
+      target.targetId === ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P2
+    ) {
+      return release.version;
+    }
+    return undefined;
+  }
+
+  private getProtocolV2ComponentCurrentVersion(
+    features: Features,
+    target: ProtocolV2RemoteComponentTarget
+  ) {
+    switch (target.targetId) {
+      case ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_BOOTLOADER:
+        return getDeviceBootloaderVersion(features);
+      case ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P1:
+      case ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P2:
+        return getDeviceFirmwareVersion(features);
+      case ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_COPROCESSOR:
+        return getDeviceBLEFirmwareVersion(features);
+      case ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE01:
+        return versionStringToArray(features.se01Version);
+      case ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE02:
+        return versionStringToArray(features.se02Version);
+      case ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE03:
+        return versionStringToArray(features.se03Version);
+      case ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE04:
+        return versionStringToArray(features.se04Version);
+      default:
+        return undefined;
+    }
+  }
+
+  private isProtocolV2ComponentVersionSatisfied(
+    release: IFirmwareReleaseInfo,
+    component: IProtocolV2FirmwareComponent,
+    target: ProtocolV2RemoteComponentTarget,
+    features: Features
+  ) {
+    const targetVersion = this.getProtocolV2ComponentTargetVersion(release, component, target);
+    if (!targetVersion) return false;
+
+    const currentVersion = this.getProtocolV2ComponentCurrentVersion(features, target);
+    const compareResult = compareProtocolV2Versions(currentVersion, targetVersion);
+    return compareResult !== undefined && compareResult >= 0;
+  }
+
+  private getProtocolV2ResourceFilePath(path: string) {
+    if (path.startsWith('vol')) return path;
+    if (path.startsWith('/')) return `vol0:${path}`;
+    return `vol0:/${path}`;
+  }
+
+  private async readProtocolV2DeviceFileHeader(path: string) {
+    const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
+    const filePath = this.getProtocolV2ResourceFilePath(path);
+    const pathInfoRes = await typedCall('FilesystemPathInfoQuery', 'FilesystemPathInfo', {
+      path: filePath,
+    });
+    const fileSize = toProtocolV2FiniteNumber(pathInfoRes.message?.size);
+    if (
+      !pathInfoRes.message?.exist ||
+      pathInfoRes.message?.directory ||
+      fileSize === undefined ||
+      fileSize < PROTOCOL_V2_OKPP_HEADER_SIZE
+    ) {
+      return null;
+    }
+
+    const chunkSize = this.getProtocolV2FirmwareChunkSize();
+    const chunks: Uint8Array[] = [];
+    let offset = 0;
+    while (offset < PROTOCOL_V2_OKPP_HEADER_SIZE) {
+      const readLen = Math.min(chunkSize, PROTOCOL_V2_OKPP_HEADER_SIZE - offset);
+      const res = await typedCall('FilesystemFileRead', 'FilesystemFile', {
+        file: {
+          path: filePath,
+          offset,
+          total_size: 0,
+        },
+        chunk_len: readLen,
+        ui_percentage: undefined,
+      });
+      const data = toProtocolV2Bytes(res.message?.data);
+      if (data.byteLength === 0) return null;
+      chunks.push(data);
+      offset += data.byteLength;
+    }
+
+    const headerBytes = new Uint8Array(offset);
+    let cursor = 0;
+    chunks.forEach(chunk => {
+      headerBytes.set(chunk, cursor);
+      cursor += chunk.byteLength;
+    });
+    return parseProtocolV2OkppHeader(headerBytes);
+  }
+
+  private async isProtocolV2ResourcePackageMatched(
+    pkg: IProtocolV2ResourceManifestPackage,
+    manifestVersion?: IVersionArray
+  ) {
+    try {
+      const header = await this.readProtocolV2DeviceFileHeader(pkg.path);
+      if (!header) return false;
+
+      const expectedType = pkg.type ?? 'RESC';
+      const expectedVersion = pkg.version ?? manifestVersion;
+      if (header.type !== expectedType) return false;
+      if (expectedVersion && compareProtocolV2Versions(header.version, expectedVersion) !== 0) {
+        return false;
+      }
+
+      const expectedPayloadHash = normalizeProtocolV2Hex(pkg.payloadHash);
+      if (expectedPayloadHash && header.payloadHash !== expectedPayloadHash) return false;
+
+      const expectedHeaderHash = normalizeProtocolV2Hex(pkg.headerHash);
+      if (expectedHeaderHash && header.headerHash !== expectedHeaderHash) return false;
+
+      return true;
+    } catch (error) {
+      Log.log(`Protocol V2 resource package check failed for ${pkg.path}: `, error);
+      return false;
+    }
+  }
+
+  private async isProtocolV2ResourceManifestSatisfied(
+    manifest: IFirmwareReleaseInfo['resourceManifest']
+  ) {
+    if (!manifest?.packages?.length) return false;
+
+    for (const pkg of manifest.packages) {
+      if (!(await this.isProtocolV2ResourcePackageMatched(pkg, manifest.version))) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  private getProtocolV2ResourceManifest(
+    release: IFirmwareReleaseInfo,
+    component: IProtocolV2FirmwareComponent
+  ) {
+    return component.resourceManifest ?? release.resourceManifest;
   }
 
-  private async prepareBootloaderBinary(
-    firmwareType: EFirmwareType,
+  private getProtocolV2ResourceComponentFileName(key: string) {
+    const safeKey = key.replace(/[^a-z0-9_-]/gi, '_') || 'resource';
+    return `resource-${safeKey}.bin`;
+  }
+
+  private async shouldInstallRemoteProtocolV2Component(
+    release: IFirmwareReleaseInfo,
+    key: string,
+    component: IProtocolV2FirmwareComponent,
+    target: ProtocolV2RemoteComponentTarget,
     features: Features
-  ): Promise<ArrayBuffer | null> {
-    if (this.params.bootloaderBinary) {
-      return this.params.bootloaderBinary;
+  ) {
+    if (target.kind === 'resource') {
+      if (
+        this.params.forcedUpdateRes ||
+        features.bootloaderMode ||
+        features.mode === 'bootloader'
+      ) {
+        return true;
+      }
+      const resourceMatched = await this.isProtocolV2ResourceManifestSatisfied(
+        this.getProtocolV2ResourceManifest(release, component)
+      );
+      if (resourceMatched) {
+        Log.log(`[FirmwareUpdateV4] skip Protocol V2 resource component ${key}; manifest matched`);
+      }
+      return !resourceMatched;
     }
 
-    if (this.params.bootloaderVersion) {
-      const bootResourceUrl = DataManager.getBootloaderResource(features, firmwareType);
-      if (bootResourceUrl) {
-        const bootBinary = (await getSysResourceBinary(bootResourceUrl)).binary;
-        return bootBinary;
+    const versionSatisfied = this.isProtocolV2ComponentVersionSatisfied(
+      release,
+      component,
+      target,
+      features
+    );
+    if (versionSatisfied) {
+      Log.log(`[FirmwareUpdateV4] skip Protocol V2 component ${key}; version is up to date`);
+    }
+    return !versionSatisfied;
+  }
+
+  private async downloadRemoteProtocolV2Component(
+    key: string,
+    component: IProtocolV2FirmwareComponent
+  ): Promise<ProtocolV2RemoteComponentBinary> {
+    const target = this.getRemoteComponentTarget(key, component);
+    if (!component.url) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        `Missing Protocol V2 firmware component url: ${key}/${component.target}`
+      );
+    }
+
+    const { binary } = await getSysResourceBinary(component.url);
+    return {
+      ...target,
+      binary,
+    };
+  }
+
+  private async prepareRemoteProtocolV2Binaries(firmwareType: EFirmwareType, features: Features) {
+    const release = DataManager.getFirmwareLatestRelease(features, firmwareType);
+
+    const resourceBinaryMap: ProtocolV2TargetBinary[] = [];
+    let bootloaderBinary: ArrayBuffer | null = null;
+    const fwBinaryMap: ProtocolV2TargetBinary[] = [];
+
+    if (!release) {
+      return {
+        resourceBinaryMap,
+        bootloaderBinary,
+        fwBinaryMap,
+      };
+    }
+
+    const entries = this.getRemoteComponentEntries(release);
+
+    for (const [key, component] of entries) {
+      const target = this.getRemoteComponentTarget(key, component);
+      const shouldInstall = await this.shouldInstallRemoteProtocolV2Component(
+        release,
+        key,
+        component,
+        target,
+        features
+      );
+      if (shouldInstall) {
+        const remoteBinary = await this.downloadRemoteProtocolV2Component(key, component);
+        if (remoteBinary.kind === 'resource') {
+          resourceBinaryMap.push({
+            fileName: this.getProtocolV2ResourceComponentFileName(key),
+            binary: remoteBinary.binary,
+            targetId: remoteBinary.targetId,
+          });
+        } else if (remoteBinary.kind === 'bootloader') {
+          bootloaderBinary = remoteBinary.binary;
+        } else {
+          fwBinaryMap.push({
+            fileName: remoteBinary.fileName,
+            binary: remoteBinary.binary,
+            targetId: remoteBinary.targetId,
+          });
+        }
       }
     }
-    return null;
+
+    return {
+      resourceBinaryMap,
+      bootloaderBinary,
+      fwBinaryMap,
+    };
   }
 
   private isProtocolV2BootloaderMode() {
@@ -270,18 +872,16 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
   async enterProtocolV2BootloaderMode() {
     if (this.isProtocolV2BootloaderMode()) {
+      Log.debug('Protocol V2 device is already in bootloader mode, skip reboot to bootloader');
       return false;
     }
 
     try {
       this.postTipMessage(FirmwareUpdateTipMessage.AutoRebootToBootloader);
-      await this.protocolV2Reboot(DevRebootType.Bootloader);
+      await this.protocolV2Reboot(DeviceRebootType.Bootloader);
       this.postTipMessage(FirmwareUpdateTipMessage.GoToBootloaderSuccess);
-      this.checkDeviceToBootloader(this.payload.connectId);
-      await this.checkPromise?.promise;
-      this.checkPromise = null;
-      await wait(1500);
-      await this.device.acquire?.();
+      await wait(1000);
+      await this.waitForProtocolV2BootloaderMode();
       return true;
     } catch (error) {
       if (error instanceof HardwareError) {
@@ -292,160 +892,212 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     }
   }
 
+  private async waitForProtocolV2BootloaderMode(
+    timeout = PROTOCOL_V2_BOOTLOADER_RECONNECT_TIMEOUT,
+    retryInterval = 1000
+  ) {
+    const startTime = Date.now();
+    let lastError: unknown;
+
+    while (Date.now() - startTime < timeout) {
+      try {
+        await this.reconnectProtocolV2Device();
+        const deviceInfo = await requestProtocolV2DeviceInfo({
+          commands: this.device.getCommands(),
+          timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT,
+        });
+        const features = this.device.updateProtocolV2Features(deviceInfo);
+        if (features?.bootloaderMode) {
+          return features;
+        }
+        lastError = new Error('Protocol V2 device is reachable but is not in bootloader mode');
+      } catch (error) {
+        lastError = error;
+        Log.log('Protocol V2 bootloader mode not ready, polling reconnect: ', error);
+      }
+      await wait(retryInterval);
+    }
+
+    throw ERRORS.TypedError(
+      HardwareErrorCode.FirmwareUpdateAutoEnterBootFailure,
+      `Protocol V2 bootloader not ready within ${timeout / 1000}s: ${this.normalizeErrorMessage(
+        lastError
+      )}`
+    );
+  }
+
   /**
-   * 收集按 DevFirmwareTargetType 拆分的显式目标二进制。
+   * 收集按 DeviceFirmwareTargetType 拆分的显式目标二进制。
    * 文件名仅用于 staging 路径展示，target_id 已显式给定。
    */
   private collectExplicitTargetBinaries() {
-    const entries: { fileName: string; binary: ArrayBuffer; targetId: number }[] = [];
+    const entries: ProtocolV2TargetBinary[] = [];
     const push = (binary: ArrayBuffer | undefined, fileName: string, targetId: number) => {
       if (binary) entries.push({ fileName, binary, targetId });
     };
 
-    push(
-      this.params.romloaderBinary,
-      'romloader.bin',
-      ProtocolV2FirmwareTargetType.TARGET_MAIN_BOOT
-    );
+    if (this.params.romloaderBinary) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        PROTOCOL_V2_ROMLOADER_UNSUPPORTED_MESSAGE
+      );
+    }
     push(
       this.params.applicationP1Binary,
       'application_p1.bin',
-      ProtocolV2FirmwareTargetType.TARGET_MAIN_APP
+      ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P1
     );
     push(
       this.params.applicationP2Binary,
       'application_p2.bin',
-      ProtocolV2FirmwareTargetType.TARGET_MAIN_APP
+      ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P2
+    );
+    push(
+      this.params.coprocessorBinary,
+      'coprocessor.bin',
+      ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_COPROCESSOR
     );
-    push(this.params.coprocessorBinary, 'coprocessor.bin', ProtocolV2FirmwareTargetType.TARGET_BT);
-    push(this.params.se01Binary, 'se01.bin', ProtocolV2FirmwareTargetType.TARGET_SE1);
-    push(this.params.se02Binary, 'se02.bin', ProtocolV2FirmwareTargetType.TARGET_SE2);
-    push(this.params.se03Binary, 'se03.bin', ProtocolV2FirmwareTargetType.TARGET_SE3);
-    push(this.params.se04Binary, 'se04.bin', ProtocolV2FirmwareTargetType.TARGET_SE4);
+    push(this.params.se01Binary, 'se01.bin', ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE01);
+    push(this.params.se02Binary, 'se02.bin', ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE02);
+    push(this.params.se03Binary, 'se03.bin', ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE03);
+    push(this.params.se04Binary, 'se04.bin', ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE04);
     return entries;
   }
 
-  private async prepareFirmwareAndBleBinary(firmwareType: EFirmwareType, features: Features) {
-    const fwBinaryMap: { fileName: string; binary: ArrayBuffer; targetId?: number }[] = [];
-    if (this.params.firmwareBinary) {
-      fwBinaryMap.push({
-        fileName: 'firmware.bin',
-        binary: this.params.firmwareBinary,
-      });
-    } else if (this.params.firmwareVersion) {
-      const firmwareBinary = (
-        await getBinary({
-          features,
-          version: this.params.firmwareVersion,
-          updateType: 'firmware',
-          isUpdateBootloader: false,
-          firmwareType,
-        })
-      ).binary;
-      fwBinaryMap.push({
-        fileName: 'firmware.bin',
-        binary: firmwareBinary,
-      });
-    }
-
-    if (this.params.bleBinary) {
-      fwBinaryMap.push({
-        fileName: 'ble-firmware.bin',
-        binary: this.params.bleBinary,
-      });
-    } else if (this.params.bleVersion) {
-      const bleBinary = await getBinary({
-        features,
-        version: this.params.bleVersion,
-        updateType: 'ble',
-        firmwareType,
-      });
-      fwBinaryMap.push({
-        fileName: 'ble-firmware.bin',
-        binary: bleBinary.binary,
-      });
-    }
-
-    return fwBinaryMap;
-  }
-
   private async executeProtocolV2Update({
-    resourceBinary,
+    resourceBinaryMap,
     fwBinaryMap,
     bootloaderBinary,
   }: {
-    resourceBinary: ArrayBuffer | null;
-    fwBinaryMap: { fileName: string; binary: ArrayBuffer; targetId?: number }[];
+    resourceBinaryMap: ProtocolV2TargetBinary[];
+    fwBinaryMap: ProtocolV2TargetBinary[];
     bootloaderBinary: ArrayBuffer | null;
   }) {
     let totalSize = 0;
     let processedSize = 0;
+    let transferredSize = 0;
 
-    if (resourceBinary) totalSize += resourceBinary.byteLength;
+    for (const resource of resourceBinaryMap) totalSize += resource.binary.byteLength;
     for (const fwbinary of fwBinaryMap) totalSize += fwbinary.binary.byteLength;
     if (bootloaderBinary) totalSize += bootloaderBinary.byteLength;
 
     this.postTipMessage(FirmwareUpdateTipMessage.StartTransferData);
+    const transferStartTime = Date.now();
+    const transferTransport = this.getProtocolV2FirmwareTransferTransport();
+    const chunkSize = this.getProtocolV2FirmwareChunkSize();
+    const onTransferredBytes = (bytes: number) => {
+      transferredSize = bytes;
+    };
+    Log.log(
+      `[FirmwareUpdateV4] transfer started transport=${transferTransport} total=${totalSize} bytes chunk=${chunkSize} bytes`
+    );
 
+    const resourceTargets: Array<{ target_id: number; path: string }> = [];
     const targets: Array<{ target_id: number; path: string }> = [];
 
-    if (resourceBinary) {
-      // resource 仅支持单文件 .bin：整文件一次上传，target path 指向该文件
-      const resourceFilePath = `${PROTOCOL_V2_FIRMWARE_STAGING_VOLUME}resource.bin`;
-      processedSize = await this.protocolV2CommonUpdateProcess({
-        payload: resourceBinary,
-        filePath: resourceFilePath,
-        processedSize,
-        totalSize,
-      });
-      targets.push({
-        target_id: ProtocolV2FirmwareTargetType.TARGET_RESOURCE,
-        path: resourceFilePath,
-      });
-    }
+    try {
+      for (const resource of resourceBinaryMap) {
+        const resourceFilePath = `${PROTOCOL_V2_FIRMWARE_STAGING_VOLUME}${resource.fileName}`;
+        Log.log(
+          `[FirmwareUpdateV4] staging resource via FilesystemFileWrite target=${resource.targetId} path=${resourceFilePath} bytes=${resource.binary.byteLength}`
+        );
+        processedSize = await this.protocolV2CommonUpdateProcess({
+          payload: resource.binary,
+          filePath: resourceFilePath,
+          processedSize,
+          totalSize,
+          onTransferredBytes,
+        });
+        transferredSize = processedSize;
+        resourceTargets.push({
+          target_id: resource.targetId,
+          path: resourceFilePath,
+        });
+      }
 
-    if (bootloaderBinary) {
-      const bootloaderPath = `${PROTOCOL_V2_FIRMWARE_STAGING_VOLUME}bootloader.bin`;
-      processedSize = await this.protocolV2CommonUpdateProcess({
-        payload: bootloaderBinary,
-        filePath: bootloaderPath,
-        processedSize,
-        totalSize,
-      });
-      targets.push({
-        target_id: ProtocolV2FirmwareTargetType.TARGET_MAIN_BOOT,
-        path: bootloaderPath,
-      });
-    }
+      if (bootloaderBinary) {
+        const bootloaderPath = `${PROTOCOL_V2_FIRMWARE_STAGING_VOLUME}bootloader.bin`;
+        Log.log(
+          `[FirmwareUpdateV4] staging bootloader via FilesystemFileWrite target=${ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_BOOTLOADER} path=${bootloaderPath} bytes=${bootloaderBinary.byteLength}`
+        );
+        processedSize = await this.protocolV2CommonUpdateProcess({
+          payload: bootloaderBinary,
+          filePath: bootloaderPath,
+          processedSize,
+          totalSize,
+          onTransferredBytes,
+        });
+        transferredSize = processedSize;
+        targets.push({
+          target_id: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_BOOTLOADER,
+          path: bootloaderPath,
+        });
+      }
 
-    for (const fwbinary of fwBinaryMap) {
-      const firmwarePath = `${PROTOCOL_V2_FIRMWARE_STAGING_VOLUME}${fwbinary.fileName}`;
-      processedSize = await this.protocolV2CommonUpdateProcess({
-        payload: fwbinary.binary,
-        filePath: firmwarePath,
-        processedSize,
-        totalSize,
-      });
-      targets.push({
-        target_id: fwbinary.targetId ?? protocolV2FileNameToTargetId(fwbinary.fileName),
-        path: firmwarePath,
-      });
-    }
+      for (const fwbinary of fwBinaryMap) {
+        const firmwarePath = `${PROTOCOL_V2_FIRMWARE_STAGING_VOLUME}${fwbinary.fileName}`;
+        Log.log(
+          `[FirmwareUpdateV4] staging firmware via FilesystemFileWrite target=${fwbinary.targetId} path=${firmwarePath} bytes=${fwbinary.binary.byteLength}`
+        );
+        processedSize = await this.protocolV2CommonUpdateProcess({
+          payload: fwbinary.binary,
+          filePath: firmwarePath,
+          processedSize,
+          totalSize,
+          onTransferredBytes,
+        });
+        transferredSize = processedSize;
+        targets.push({
+          target_id: fwbinary.targetId,
+          path: firmwarePath,
+        });
+      }
 
-    if (totalSize > 0) {
-      this.postProgressMessage(100, 'transferData');
+      if (totalSize > 0) {
+        this.postProgressMessage(100, 'transferData');
+      }
+
+      const elapsedMs = Date.now() - transferStartTime;
+      Log.log(
+        `[FirmwareUpdateV4] transfer finished transport=${transferTransport} bytes=${totalSize} elapsed=${(
+          elapsedMs / 1000
+        ).toFixed(2)}s speed=${formatProtocolV2TransferSpeed(totalSize, elapsedMs)} KB/s`
+      );
+    } catch (error) {
+      const elapsedMs = Date.now() - transferStartTime;
+      Log.warn(
+        `[FirmwareUpdateV4] transfer failed transport=${transferTransport} bytes=${transferredSize}/${totalSize} elapsed=${(
+          elapsedMs / 1000
+        ).toFixed(2)}s speed=${formatProtocolV2TransferSpeed(transferredSize, elapsedMs)} KB/s`
+      );
+      throw error;
     }
 
     this.postTipMessage(FirmwareUpdateTipMessage.ConfirmOnDevice);
-    const startResponse = await this.protocolV2StartFirmwareUpdate({ targets });
-    await this.waitForProtocolV2FirmwareUpdateComplete(targets, startResponse);
+    for (const resourceTarget of resourceTargets) {
+      const resourceTargetsBatch = [resourceTarget];
+      Log.log(
+        `[FirmwareUpdateV4] DeviceFirmwareUpdateRequest resources=${JSON.stringify(
+          resourceTargetsBatch
+        )}`
+      );
+      const startResponse = await this.protocolV2StartFirmwareUpdate({
+        targets: resourceTargetsBatch,
+      });
+      await this.waitForProtocolV2FirmwareUpdateComplete(resourceTargetsBatch, startResponse);
+    }
+    if (targets.length > 0) {
+      Log.log(`[FirmwareUpdateV4] DeviceFirmwareUpdateRequest targets=${JSON.stringify(targets)}`);
+      const startResponse = await this.protocolV2StartFirmwareUpdate({ targets });
+      await this.waitForProtocolV2FirmwareUpdateComplete(targets, startResponse);
+    }
   }
 
   private async queryProtocolV2FirmwareUpdateStatus() {
     const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
     return typedCall(
-      'DevGetFirmwareUpdateStatus',
-      'DevFirmwareUpdateStatus',
+      'DeviceFirmwareUpdateStatusGet',
+      'DeviceFirmwareUpdateStatus',
       {},
       {
         timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT,
@@ -465,14 +1117,32 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     );
   }
 
+  private isProtocolV2NormalModeFeatures(features?: Features | null) {
+    return !!features && !features.bootloaderMode && features.mode !== 'bootloader';
+  }
+
+  private async probeProtocolV2NormalMode() {
+    const deviceInfo = await requestProtocolV2DeviceInfo({
+      commands: this.device.getCommands(),
+      timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT,
+      request: PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
+    });
+    const features = this.device.updateProtocolV2Features(deviceInfo);
+    if (this.isProtocolV2NormalModeFeatures(features)) {
+      Log.log('Protocol V2 firmware install finished; device is back in normal mode');
+      return true;
+    }
+    return false;
+  }
+
   private assertProtocolV2TargetStatus(
     statusTargets: ProtocolV2FirmwareUpdateStatusTarget[],
     expectedTargetIds: Set<number>
   ) {
     const failedTarget = statusTargets.find(
       target =>
-        expectedTargetIds.has(target.target_id) &&
-        target.status === PROTOCOL_V2_TARGET_STATUS_FAILED
+        expectedTargetIds.has(normalizeProtocolV2TargetId(target.target_id) ?? -1) &&
+        isProtocolV2TargetStatusFailed(target.status)
     );
     if (failedTarget) {
       throw ERRORS.TypedError(
@@ -483,8 +1153,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
     const completedTargets = statusTargets.filter(
       target =>
-        expectedTargetIds.has(target.target_id) &&
-        target.status === PROTOCOL_V2_TARGET_STATUS_FINISHED
+        expectedTargetIds.has(normalizeProtocolV2TargetId(target.target_id) ?? -1) &&
+        isProtocolV2TargetStatusFinished(target.status)
     );
     if (completedTargets.length === expectedTargetIds.size && expectedTargetIds.size > 0) {
       return true;
@@ -492,8 +1162,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
     const inProgressTarget = statusTargets.find(
       target =>
-        expectedTargetIds.has(target.target_id) &&
-        target.status === PROTOCOL_V2_TARGET_STATUS_IN_PROGRESS
+        expectedTargetIds.has(normalizeProtocolV2TargetId(target.target_id) ?? -1) &&
+        isProtocolV2TargetStatusInProgress(target.status)
     );
     if (inProgressTarget) {
       this.postProgressMessage(99, 'installingFirmware');
@@ -507,11 +1177,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     startResponse?: ProtocolV2FirmwareUpdateStartResponse
   ) {
     const expectedTargetIds = new Set(targets.map(target => target.target_id));
-    if (startResponse?.type === 'Success') {
-      return;
-    }
-    if (startResponse?.type === 'DevFirmwareUpdateStatus') {
-      const statusTargets = (startResponse.message.targets ??
+    if (startResponse?.type === 'DeviceFirmwareUpdateStatus') {
+      const statusTargets = (startResponse.message.records ??
         []) as ProtocolV2FirmwareUpdateStatusTarget[];
       if (this.assertProtocolV2TargetStatus(statusTargets, expectedTargetIds)) {
         return;
@@ -524,7 +1191,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     while (Date.now() - startTime < PROTOCOL_V2_INSTALL_TIMEOUT) {
       try {
         const statusRes = await this.queryProtocolV2FirmwareUpdateStatus();
-        const statusTargets = (statusRes.message.targets ??
+        const statusTargets = (statusRes.message.records ??
           []) as ProtocolV2FirmwareUpdateStatusTarget[];
         if (this.assertProtocolV2TargetStatus(statusTargets, expectedTargetIds)) {
           return;
@@ -538,17 +1205,19 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
         if (isProtocolV2PollingTransientError(error)) {
           try {
             await this.reconnectProtocolV2Device();
+            if (await this.probeProtocolV2NormalMode()) {
+              return;
+            }
           } catch (reconnectError) {
             lastError = reconnectError;
             Log.log(
-              'Protocol V2 firmware install reconnect/status polling failed: ',
+              'Protocol V2 firmware install reconnect/normal-mode probe failed: ',
               reconnectError
             );
           }
           try {
             await this.pingProtocolV2Device();
             Log.log('Protocol V2 firmware status unavailable, Ping is ready');
-            return;
           } catch (pingError) {
             lastError = pingError;
             Log.log('Protocol V2 firmware install Ping polling failed: ', pingError);
@@ -566,7 +1235,16 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
 
   private async exitProtocolV2BootloaderToNormal() {
     this.postTipMessage(FirmwareUpdateTipMessage.SwitchFirmwareReconnectDevice);
-    await this.protocolV2Reboot(DevRebootType.Normal);
+    try {
+      await this.reconnectProtocolV2Device();
+      if (await this.probeProtocolV2NormalMode()) {
+        Log.log('Protocol V2 device is already in normal mode, skip normal reboot');
+        return;
+      }
+    } catch (error) {
+      Log.log('Protocol V2 normal-mode probe before reboot failed: ', error);
+    }
+    await this.protocolV2Reboot(DeviceRebootType.Normal);
   }
 
   private async waitForProtocolV2FinalFeatures() {
@@ -603,7 +1281,14 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
           // 更新完成判定只需要各 target 版本号；scope 与请求内容保持一致
           request: PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
         });
-        return this.device.updateProtocolV2Features(deviceInfo);
+        const features = this.device.updateProtocolV2Features(deviceInfo);
+        if (features.bootloaderMode || features.mode === 'bootloader') {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.DeviceNotFound,
+            'Protocol V2 device is still in bootloader mode'
+          );
+        }
+        return features;
       } catch (error) {
         lastError = error;
         Log.log('Protocol V2 normal mode not ready, polling Ping: ', error);
@@ -628,15 +1313,42 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     const deviceDiff = await this.device.deviceConnector?.enumerate();
     const devicesDescriptor = deviceDiff?.descriptors ?? [];
 
-    const { deviceList } = await DevicePool.getDevices(devicesDescriptor, this.connectId);
+    if (
+      DataManager.isBrowserWebUsb(DataManager.getSettings('env')) &&
+      devicesDescriptor.length === 1
+    ) {
+      this.device.updateDescriptor(
+        {
+          ...devicesDescriptor[0],
+          protocolType: PROTOCOL_V2_CONNECT_PROTOCOL,
+        },
+        true
+      );
+      await this.device.acquire(PROTOCOL_V2_CONNECT_PROTOCOL, { throwOnRunPromiseError: true });
+      this.device.commands.disposed = false;
+      this.device.getCommands().mainId = this.device.mainId ?? '';
+      await this.device.initialize();
+      return;
+    }
+
+    // App 与 bootloader 序列号暂时可能不一致。V4 升级重连阶段只接受唯一枚举设备，
+    // 避免继续按旧 app connectId 查缓存导致反复输出 path mismatch 日志。
+    const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined, {
+      connectProtocol: PROTOCOL_V2_CONNECT_PROTOCOL,
+    });
     if (deviceList.length !== 1) {
       throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound);
     }
 
+    Log.debug(
+      'Protocol V2 firmware reconnect using single enumerated device:',
+      deviceList[0].getConnectId()
+    );
     this.device.updateFromCache(deviceList[0]);
-    await this.device.acquire();
+    await this.device.acquire(PROTOCOL_V2_CONNECT_PROTOCOL, { throwOnRunPromiseError: true });
     this.device.commands.disposed = false;
     this.device.getCommands().mainId = this.device.mainId ?? '';
+    await this.device.initialize();
   }
 
   private async protocolV2CommonUpdateProcess({
@@ -644,10 +1356,12 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     filePath,
     processedSize,
     totalSize,
+    onTransferredBytes,
   }: PROTO.FirmwareUpload & {
     filePath: string;
     processedSize?: number;
     totalSize?: number;
+    onTransferredBytes?: (transferredBytes: number) => void;
   }) {
     const chunkSize = this.getProtocolV2FirmwareChunkSize();
     let offset = 0;
@@ -663,7 +1377,11 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       const chunkLength = chunkEnd - offset;
       const chunk = payload.slice(offset, chunkEnd);
       const overwrite = offset === 0;
-      const progress = getUploadProgress(chunkEnd);
+      const progress = getProtocolV2DeviceTransferProgress(
+        (processedSize ?? 0) + offset,
+        (processedSize ?? 0) + chunkEnd,
+        totalSize ?? payload.byteLength
+      );
 
       const writeRes = await this.fileWriteWithRetry(
         filePath,
@@ -685,12 +1403,27 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
         );
       }
       offset = nextOffset;
+      onTransferredBytes?.((processedSize ?? 0) + offset);
       this.postProgressMessage(getUploadProgress(offset), 'transferData');
     }
 
     return totalSize !== undefined ? (processedSize ?? 0) + payload.byteLength : 0;
   }
 
+  private getProtocolV2FirmwareTransferTransport() {
+    const env = DataManager.getSettings('env');
+    if (env && DataManager.isBleConnect(env)) {
+      return 'BLE';
+    }
+    if (
+      env &&
+      (DataManager.isBrowserWebUsb(env) || DataManager.isDesktopWebUsb(env) || env === 'web')
+    ) {
+      return 'WebUSB';
+    }
+    return env ?? 'unknown';
+  }
+
   private async fileWriteWithRetry(
     filePath: string,
     totalFileSize: number,
@@ -770,24 +1503,27 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     let response: ProtocolV2FirmwareUpdateStartResponse;
     try {
       response = await commands.typedCall(
-        'DevFirmwareUpdate',
+        'DeviceFirmwareUpdateRequest',
         PROTOCOL_V2_FIRMWARE_UPDATE_RESPONSE_TYPES,
         {
           targets,
         },
         {
-          intermediateTypes: ['DevFirmwareInstallProgress'],
-          onIntermediateResponse: (response: { message?: { progress?: number } }) => {
-            const progress = Number(response.message?.progress);
-            if (Number.isFinite(progress)) {
-              this.postProgressMessage(Math.min(progress, 99), 'installingFirmware');
+          intermediateTypes: ['DeviceFirmwareUpdateStatus'],
+          timeoutMs: PROTOCOL_V2_START_UPDATE_TIMEOUT,
+          onIntermediateResponse: (response: { type?: string }) => {
+            if (response.type === 'DeviceFirmwareUpdateStatus') {
+              this.postProgressMessage(99, 'installingFirmware');
             }
           },
         }
       );
     } catch (error) {
-      if (isProtocolV2DeviceDisconnectedError(error)) {
-        Log.log('Rebooting device');
+      if (isProtocolV2StartUpdateTransientError(error)) {
+        Log.log(
+          'Protocol V2 firmware update request did not return; continue status polling',
+          error
+        );
       } else {
         throw error;
       }
@@ -796,10 +1532,10 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     return response;
   }
 
-  private async protocolV2Reboot(rebootType: DevRebootType) {
+  private async protocolV2Reboot(rebootType: DeviceRebootType) {
     const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
     try {
-      const res = await typedCall('DevReboot', 'Success', {
+      const res = await typedCall('DeviceReboot', 'Success', {
         reboot_type: rebootType,
       });
       return res.message;