@onekeyfe/hardware-cli 1.2.0-alpha.8 → 1.2.0-alpha.9

package/dist/cli.d.ts

@@ -1 +1,3 @@
-export {};
+import { Command } from 'commander';
+declare const program: Command;
+export { program };

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.program = void 0;
 const node_fs_1 = require("node:fs");
 const commander_1 = require("commander");
 const hd_core_1 = require("@onekeyfe/hd-core");
@@ -33,6 +34,7 @@ function extractPassphraseSession(payload) {
     return { passphraseState, sessionId };
 }
 const program = new commander_1.Command();
+exports.program = program;
 program
     .name('onekey-hw')
     .description('OneKey hardware wallet CLI for AI agent integration')
@@ -418,15 +420,15 @@ program
     .action(() => respondAndExit({
     success: false,
     payload: {
-        error: 'Use `onekey-hw --transport ble firmware-update-v4-debug` for BLE Protocol V2 firmware update debugging.',
-        code: 'USE_FIRMWARE_UPDATE_V4_DEBUG',
+        error: 'Use `onekey-hw --transport ble firmware-update-v4` for BLE Protocol V2 firmware updates.',
+        code: 'USE_FIRMWARE_UPDATE_V4',
     },
 }));
 program
-    .command('firmware-update-v4-debug')
-    .description('Debug Protocol V2 firmware update through sdk.firmwareUpdateV4')
+    .command('firmware-update-v4')
+    .description('Run Protocol V2 firmware update through sdk.firmwareUpdateV4')
     .option('--chunk-size <bytes>', 'Transfer chunk size in bytes')
-    .option('--resource <path>', 'FW_MGMT_TARGET_CRATE resource package path')
+    .option('--resource-bundle <spec...>', 'RESC bundle direct-write spec: <localPath>:<devicePath>, e.g. wallpaper.okpkg:vol0:/bundles/images/wallpaper.okpkg')
     .option('--romloader <path>', 'FW_MGMT_TARGET_ROMLOADER binary path')
     .option('--bootloader <path>', 'FW_MGMT_TARGET_BOOTLOADER binary path')
     .option('--application-p1 <path>', 'FW_MGMT_TARGET_APPLICATION_P1 binary path')
@@ -439,8 +441,8 @@ program
     .option('--forced-update-res', 'Force resource update')
     .option('--retries <count>', 'Retry count for transient Protocol V2 USB probe failures')
     .action(opts => runCommand({}, async ({ sdk, globalOpts }) => {
-    const params = buildFirmwareUpdateV4DebugParams(opts);
-    const result = await runFirmwareUpdateV4DebugWithRetry({
+    const params = buildFirmwareUpdateV4Params(opts);
+    const result = await runFirmwareUpdateV4WithRetry({
         sdk,
         globalOpts,
         params,
@@ -902,9 +904,24 @@ function readBinaryParam(path) {
     const buffer = (0, node_fs_1.readFileSync)(path);
     return new Uint8Array(buffer).buffer;
 }
-function getFirmwareUpdateV4DebugTotalBytes(params) {
+function parseResourceBundleParam(spec) {
+    const sep = spec.indexOf(':');
+    if (sep <= 0 || sep === spec.length - 1) {
+        throw new Error(`Invalid --resource-bundle value: "${spec}". Expected <localPath>:<devicePath>`);
+    }
+    const localPath = spec.slice(0, sep);
+    const devicePath = spec.slice(sep + 1);
+    if (!devicePath.startsWith('vol')) {
+        throw new Error(`Invalid --resource-bundle device path: "${devicePath}". Expected a vol*:/... path`);
+    }
+    return {
+        binary: readBinaryParam(localPath),
+        devicePath,
+    };
+}
+function getFirmwareUpdateV4TotalBytes(params) {
     return [
-        ...(params.resourceBinaries ?? []),
+        ...(params.resourceBundleFiles?.map(item => item.binary) ?? []),
         params.bootloaderBinary,
         params.applicationP1Binary,
         params.applicationP2Binary,
@@ -915,17 +932,17 @@ function getFirmwareUpdateV4DebugTotalBytes(params) {
         params.se04Binary,
     ].reduce((total, binary) => total + (binary?.byteLength ?? 0), 0);
 }
-function getFirmwareUpdateV4DebugErrorText(result) {
+function getFirmwareUpdateV4ErrorText(result) {
     if (!result || typeof result !== 'object')
         return '';
-    const payload = result.payload;
+    const { payload } = result;
     if (!payload || typeof payload !== 'object')
         return '';
-    const error = payload.error;
+    const { error } = payload;
     return typeof error === 'string' ? error : '';
 }
 function isProtocolV2UsbProbeTransientResult(result) {
-    const error = getFirmwareUpdateV4DebugErrorText(result);
+    const error = getFirmwareUpdateV4ErrorText(result);
     return (error.includes('Device protocol mismatch') &&
         error.includes('expected V2') &&
         error.includes('did not respond to expected protocol'));
@@ -933,22 +950,22 @@ function isProtocolV2UsbProbeTransientResult(result) {
 function isSuccessResult(result) {
     return (!!result && typeof result === 'object' && result.success === true);
 }
-function getFirmwareDebugPayload(message) {
+function getFirmwareUpdatePayload(message) {
     if (!message || typeof message !== 'object')
         return undefined;
     return message.payload;
 }
-function formatFirmwareDebugProgress(progress) {
+function formatFirmwareProgress(progress) {
     if (!Number.isFinite(progress))
         return '0%';
     return `${Math.min(Math.max(Math.round(progress), 0), 100)}%`;
 }
-function formatFirmwareDebugBytes(bytes) {
+function formatFirmwareBytes(bytes) {
     if (!Number.isFinite(bytes) || bytes <= 0)
         return '';
     return `${(bytes / 1024).toFixed(1)} KiB`;
 }
-function maybePrintFirmwareDebugProgress({ progressType, progress, payload, lastPrintedProgress, }) {
+function maybePrintFirmwareProgress({ progressType, progress, payload, lastPrintedProgress, }) {
     const printableProgress = Math.floor(progress / 10) * 10;
     if (printableProgress <= lastPrintedProgress && progress < 100) {
         return lastPrintedProgress;
@@ -957,15 +974,15 @@ function maybePrintFirmwareDebugProgress({ progressType, progress, payload, last
     const totalBytes = Number(payload.totalBytes);
     const rateBytesPerSecond = Number(payload.rateBytesPerSecond);
     const sizeText = Number.isFinite(transferredBytes) && Number.isFinite(totalBytes) && totalBytes > 0
-        ? ` ${formatFirmwareDebugBytes(transferredBytes)}/${formatFirmwareDebugBytes(totalBytes)}`
+        ? ` ${formatFirmwareBytes(transferredBytes)}/${formatFirmwareBytes(totalBytes)}`
         : '';
     const speedText = Number.isFinite(rateBytesPerSecond) && rateBytesPerSecond > 0
         ? ` ${(rateBytesPerSecond / 1024).toFixed(2)} KiB/s`
         : '';
-    process.stderr.write(`[onekey-hw] Firmware ${progressType}: ${formatFirmwareDebugProgress(progress)}${sizeText}${speedText}\n`);
+    process.stderr.write(`[onekey-hw] Firmware ${progressType}: ${formatFirmwareProgress(progress)}${sizeText}${speedText}\n`);
     return progress >= 100 ? 100 : printableProgress;
 }
-function buildFirmwareUpdateV4DebugMetrics({ attempt, maxAttempts, totalBytes, totalStartedAt, transferStartedAt, transferEndedAt, installStartedAt, installEndedAt, progressEvents, lastProgress, installProgressEvents, lastInstallProgress, retried, }) {
+function buildFirmwareUpdateV4Metrics({ attempt, maxAttempts, totalBytes, totalStartedAt, transferStartedAt, transferEndedAt, installStartedAt, installEndedAt, progressEvents, lastProgress, installProgressEvents, lastInstallProgress, retried, }) {
     const totalElapsedMs = Date.now() - totalStartedAt;
     const transferElapsedMs = transferStartedAt !== undefined && transferEndedAt !== undefined
         ? transferEndedAt - transferStartedAt
@@ -990,8 +1007,8 @@ function buildFirmwareUpdateV4DebugMetrics({ attempt, maxAttempts, totalBytes, t
         totalSeconds: Number((totalElapsedMs / 1000).toFixed(2)),
     };
 }
-async function runFirmwareUpdateV4DebugWithRetry({ sdk, globalOpts, params, retries, }) {
-    const totalBytes = getFirmwareUpdateV4DebugTotalBytes(params);
+async function runFirmwareUpdateV4WithRetry({ sdk, globalOpts, params, retries, }) {
+    const totalBytes = getFirmwareUpdateV4TotalBytes(params);
     const maxAttempts = Math.max((retries ?? 2) + 1, 1);
     let currentSdk = sdk;
     let lastResult;
@@ -1015,7 +1032,7 @@ async function runFirmwareUpdateV4DebugWithRetry({ sdk, globalOpts, params, retr
             if (!message || typeof message !== 'object')
                 return;
             const messageType = message.type;
-            const payload = getFirmwareDebugPayload(message);
+            const payload = getFirmwareUpdatePayload(message);
             if (messageType === hd_core_1.UI_REQUEST.FIRMWARE_TIP) {
                 const tipMessage = payload?.data?.message;
                 if (typeof tipMessage === 'string') {
@@ -1037,7 +1054,7 @@ async function runFirmwareUpdateV4DebugWithRetry({ sdk, globalOpts, params, retr
                 progressEvents += 1;
                 lastProgress = Math.max(lastProgress, progress);
                 transferStartedAt ?? (transferStartedAt = Date.now());
-                lastPrintedTransferProgress = maybePrintFirmwareDebugProgress({
+                lastPrintedTransferProgress = maybePrintFirmwareProgress({
                     progressType: 'transfer',
                     progress,
                     payload,
@@ -1052,7 +1069,7 @@ async function runFirmwareUpdateV4DebugWithRetry({ sdk, globalOpts, params, retr
                 installProgressEvents += 1;
                 lastInstallProgress = Math.max(lastInstallProgress, progress);
                 installStartedAt ?? (installStartedAt = Date.now());
-                lastPrintedInstallProgress = maybePrintFirmwareDebugProgress({
+                lastPrintedInstallProgress = maybePrintFirmwareProgress({
                     progressType: 'install',
                     progress,
                     payload,
@@ -1073,7 +1090,7 @@ async function runFirmwareUpdateV4DebugWithRetry({ sdk, globalOpts, params, retr
         if (installStartedAt !== undefined && installEndedAt === undefined) {
             installEndedAt = Date.now();
         }
-        const debugMetrics = buildFirmwareUpdateV4DebugMetrics({
+        const metrics = buildFirmwareUpdateV4Metrics({
             attempt,
             maxAttempts,
             totalBytes,
@@ -1094,7 +1111,7 @@ async function runFirmwareUpdateV4DebugWithRetry({ sdk, globalOpts, params, retr
                 ...lastResult,
                 payload: {
                     ...payload,
-                    _debug: debugMetrics,
+                    metrics,
                 },
             };
         }
@@ -1109,18 +1126,20 @@ async function runFirmwareUpdateV4DebugWithRetry({ sdk, globalOpts, params, retr
         retried = true;
         process.stderr.write(`[onekey-hw] Protocol V2 USB probe was transient; retrying firmwareUpdateV4 (${attempt}/${maxAttempts})...\n`);
         await (0, sdk_1.disposeSDK)();
-        await new Promise(resolve => setTimeout(resolve, 3000));
+        await new Promise(resolve => {
+            setTimeout(resolve, 3000);
+        });
         currentSdk = await (0, sdk_1.createSDK)(globalOpts);
     }
     return lastResult;
 }
-function buildFirmwareUpdateV4DebugParams(opts) {
+function buildFirmwareUpdateV4Params(opts) {
     const params = {
         platform: 'desktop',
         connectProtocol: 'V2',
         chunkSize: opts.chunkSize ? safeParseInt(opts.chunkSize, '--chunk-size') : undefined,
         forcedUpdateRes: opts.forcedUpdateRes,
-        resourceBinaries: opts.resource ? [readBinaryParam(opts.resource)] : undefined,
+        resourceBundleFiles: opts.resourceBundle?.map(parseResourceBundleParam),
         romloaderBinary: opts.romloader ? readBinaryParam(opts.romloader) : undefined,
         bootloaderBinary: opts.bootloader ? readBinaryParam(opts.bootloader) : undefined,
         applicationP1Binary: opts.applicationP1 ? readBinaryParam(opts.applicationP1) : undefined,
@@ -1132,7 +1151,7 @@ function buildFirmwareUpdateV4DebugParams(opts) {
         se04Binary: opts.se04 ? readBinaryParam(opts.se04) : undefined,
     };
     const hasPayload = [
-        params.resourceBinaries,
+        params.resourceBundleFiles,
         params.romloaderBinary,
         params.bootloaderBinary,
         params.applicationP1Binary,
@@ -1144,7 +1163,7 @@ function buildFirmwareUpdateV4DebugParams(opts) {
         params.se04Binary,
     ].some(Boolean);
     if (!hasPayload) {
-        const err = new Error('firmware-update-v4-debug requires at least one binary path');
+        const err = new Error('firmware-update-v4 requires at least one binary path');
         err.code = 'MISSING_FIRMWARE_BINARY';
         throw err;
     }
@@ -1160,4 +1179,6 @@ function safeParseInt(input, label) {
     }
     return num;
 }
-program.parse();
+if (require.main === module) {
+    program.parse();
+}

package/dist/transports/nobleBlePlugin.js

@@ -14,6 +14,7 @@ const BLUETOOTH_INIT_TIMEOUT = 10000;
 const DEVICE_SCAN_TIMEOUT = 8000;
 const CONNECTION_TIMEOUT = 8000;
 const SERVICE_DISCOVERY_TIMEOUT = 10000;
+const BLE_CLEANUP_TIMEOUT = 100;
 const BLE_PACKET_SIZE = 192;
 const BLE_WRITE_DELAY = 5;
 const BLE_ENCRYPTION_ERROR_PATTERNS = [/encryption is insufficient/i, /insufficient encryption/i];
@@ -22,8 +23,8 @@ let nobleReadyPromise = null;
 const discoveredDevices = new Map();
 const connectedDevices = new Map();
 const deviceCharacteristics = new Map();
-const notificationQueue = [];
-const pendingReceivers = [];
+const notificationStates = new Map();
+const notificationGenerations = new Map();
 function getBleUuidKey(uuid) {
     const normalized = (uuid ?? '').replace(/-/g, '').toLowerCase();
     return normalized.length >= 8 ? normalized.substring(4, 8) : normalized;
@@ -43,14 +44,63 @@ function isOneKeyPeripheral(peripheral) {
     const deviceName = peripheral.advertisement?.localName || null;
     return (0, hd_shared_1.isOnekeyDevice)(deviceName, peripheral.id) || hasOneKeyAdvertisementService(peripheral);
 }
-function enqueueNotification(data) {
+function enqueueNotification(deviceId, generation, data) {
+    const state = notificationStates.get(deviceId);
+    if (!state || state.generation !== generation)
+        return;
     const hex = data.toString('hex');
-    const receiver = pendingReceivers.shift();
+    const [receiver] = state.pendingReceivers;
     if (receiver) {
-        receiver(hex);
+        state.pendingReceivers.delete(receiver);
+        receiver.resolve(hex);
         return;
     }
-    notificationQueue.push(hex);
+    state.queue.push(hex);
+}
+function createNotificationState(deviceId) {
+    const existing = notificationStates.get(deviceId);
+    if (existing) {
+        const error = new Error(`BLE notification state replaced for ${deviceId}`);
+        existing.pendingReceivers.forEach(receiver => receiver.reject(error));
+    }
+    const generation = (notificationGenerations.get(deviceId) ?? 0) + 1;
+    notificationGenerations.set(deviceId, generation);
+    const state = {
+        generation,
+        queue: [],
+        pendingReceivers: new Set(),
+    };
+    notificationStates.set(deviceId, state);
+    return state;
+}
+function clearNotificationState(deviceId, reason) {
+    const state = notificationStates.get(deviceId);
+    if (!state)
+        return;
+    notificationStates.delete(deviceId);
+    const error = new Error(reason);
+    state.pendingReceivers.forEach(receiver => receiver.reject(error));
+    state.pendingReceivers.clear();
+    state.queue.length = 0;
+}
+function waitForNobleCleanup(registerCallback) {
+    return new Promise(resolve => {
+        let completed = false;
+        const complete = () => {
+            if (completed)
+                return;
+            completed = true;
+            clearTimeout(timeout);
+            resolve();
+        };
+        const timeout = setTimeout(complete, BLE_CLEANUP_TIMEOUT);
+        try {
+            registerCallback(complete);
+        }
+        catch {
+            complete();
+        }
+    });
 }
 async function initializeNoble() {
     if (!noble) {
@@ -210,10 +260,8 @@ async function discoverCharacteristics(peripheral) {
         notify: notifyCharacteristic,
     };
 }
-function subscribeNotifications(deviceId, notifyCharacteristic) {
-    return new Promise(resolve => {
-        notifyCharacteristic.unsubscribe(() => resolve());
-    })
+function subscribeNotifications(deviceId, generation, notifyCharacteristic) {
+    return waitForNobleCleanup(callback => notifyCharacteristic.unsubscribe(callback))
         .then(() => new Promise((resolve, reject) => {
         notifyCharacteristic.subscribe((error) => {
             if (error) {
@@ -230,7 +278,7 @@ function subscribeNotifications(deviceId, notifyCharacteristic) {
     }))
         .then(() => {
         notifyCharacteristic.removeAllListeners('data');
-        notifyCharacteristic.on('data', enqueueNotification);
+        notifyCharacteristic.on('data', data => enqueueNotification(deviceId, generation, data));
     })
         .catch(error => {
         notifyCharacteristic.removeAllListeners('data');
@@ -254,21 +302,16 @@ function writeCharacteristic(characteristic, buffer) {
 async function disconnectDevice(uuid) {
     const peripheral = connectedDevices.get(uuid);
     const characteristics = deviceCharacteristics.get(uuid);
+    clearNotificationState(uuid, `BLE device disconnected: ${uuid}`);
     if (characteristics) {
         characteristics.notify.removeAllListeners('data');
-        await new Promise(resolve => {
-            characteristics.notify.unsubscribe(() => resolve());
-        });
+        await waitForNobleCleanup(callback => characteristics.notify.unsubscribe(callback));
     }
     connectedDevices.delete(uuid);
     deviceCharacteristics.delete(uuid);
-    notificationQueue.length = 0;
-    pendingReceivers.splice(0).forEach(resolve => resolve(''));
     if (!peripheral || peripheral.state === 'disconnected')
         return;
-    await new Promise(resolve => {
-        peripheral.disconnect(() => resolve());
-    });
+    await waitForNobleCleanup(callback => peripheral.disconnect(callback));
 }
 function createNobleBlePlugin() {
     return {
@@ -294,7 +337,14 @@ function createNobleBlePlugin() {
             }
             await connectPeripheral(peripheral);
             const characteristics = await discoverCharacteristics(peripheral);
-            await subscribeNotifications(uuid, characteristics.notify);
+            const notificationState = createNotificationState(uuid);
+            try {
+                await subscribeNotifications(uuid, notificationState.generation, characteristics.notify);
+            }
+            catch (error) {
+                clearNotificationState(uuid, `BLE notification subscription failed: ${uuid}`);
+                throw error;
+            }
             connectedDevices.set(uuid, peripheral);
             deviceCharacteristics.set(uuid, characteristics);
         },
@@ -315,12 +365,21 @@ function createNobleBlePlugin() {
                 }
             }
         },
-        async receive() {
-            const queued = notificationQueue.shift();
+        async receive(uuid) {
+            const resolvedUuid = uuid ??
+                (notificationStates.size === 1 ? notificationStates.keys().next().value : undefined);
+            if (!resolvedUuid) {
+                throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.RuntimeError, 'BLE receive requires a device UUID when multiple devices are connected');
+            }
+            const state = notificationStates.get(resolvedUuid);
+            if (!state) {
+                throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.TransportNotFound, `BLE notification state not found: ${resolvedUuid}`);
+            }
+            const queued = state.queue.shift();
             if (queued !== undefined)
                 return queued;
-            return new Promise(resolve => {
-                pendingReceivers.push(resolve);
+            return new Promise((resolve, reject) => {
+                state.pendingReceivers.add({ resolve, reject });
             });
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hardware-cli",
-  "version": "1.2.0-alpha.8",
+  "version": "1.2.0-alpha.9",
   "description": "OneKey hardware wallet CLI for testing device communication",
   "author": "OneKey",
   "license": "Apache-2.0",
@@ -30,12 +30,12 @@
     "test": "jest"
   },
   "dependencies": {
-    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.8",
-    "@onekeyfe/hd-core": "1.2.0-alpha.8",
-    "@onekeyfe/hd-shared": "1.2.0-alpha.8",
-    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.8",
+    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.9",
+    "@onekeyfe/hd-core": "1.2.0-alpha.9",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.9",
+    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.9",
     "@stoprocent/noble": "2.3.16",
     "commander": "^12.0.0"
   },
-  "gitHead": "d2b1323e5ad9c373e72d4d092f35c9f274c1fd74"
+  "gitHead": "f90ef9921b742f68cce9f4e7a0425e45e8ae7ec9"
 }

package/src/__tests__/firmware-update-v4-command.test.ts

@@ -0,0 +1,19 @@
+import { program } from '../cli';
+
+describe('firmware-update-v4 CLI command', () => {
+  test('exposes firmware-update-v4 as the formal command', () => {
+    const command = program.commands.find(item => item.name() === 'firmware-update-v4');
+
+    expect(command).toBeDefined();
+    expect(command?.description()).toBe(
+      'Run Protocol V2 firmware update through sdk.firmwareUpdateV4'
+    );
+  });
+
+  test('does not expose the pre-release firmware-update-v4-debug command', () => {
+    expect(program.commands.some(item => item.name() === 'firmware-update-v4-debug')).toBe(false);
+    expect(program.commands.some(item => item.aliases().includes('firmware-update-v4-debug'))).toBe(
+      false
+    );
+  });
+});

package/src/__tests__/noble-ble-plugin.test.ts

@@ -0,0 +1,113 @@
+import { EventEmitter } from 'events';
+
+type MockCharacteristic = EventEmitter & {
+  uuid: string;
+  unsubscribe: jest.Mock;
+  subscribe: jest.Mock;
+  write: jest.Mock;
+  removeAllListeners: jest.Mock;
+};
+
+const createCharacteristic = (uuid: string): MockCharacteristic => {
+  const characteristic = new EventEmitter() as MockCharacteristic;
+  characteristic.uuid = uuid;
+  characteristic.unsubscribe = jest.fn(callback => callback());
+  characteristic.subscribe = jest.fn(callback => callback());
+  characteristic.write = jest.fn((_buffer, _withoutResponse, callback) => callback());
+  characteristic.removeAllListeners = jest.fn(
+    characteristic.removeAllListeners.bind(characteristic)
+  );
+  return characteristic;
+};
+
+const createPeripheral = (id: string) => {
+  const write = createCharacteristic('0002');
+  const notify = createCharacteristic('0003');
+  const service = {
+    uuid: '0001',
+    discoverCharacteristics: jest.fn((_uuids, callback) => callback(null, [write, notify])),
+  };
+  return {
+    peripheral: {
+      id,
+      state: 'connected',
+      advertisement: {
+        localName: `OneKey Pro 2 ${id}`,
+        serviceUuids: ['fffd'],
+      },
+      discoverServices: jest.fn((_uuids, callback) => callback(null, [service])),
+      connect: jest.fn(callback => callback()),
+      disconnect: jest.fn(callback => callback()),
+    },
+    notify,
+  };
+};
+
+describe('Noble BLE plugin notification routing', () => {
+  afterEach(() => {
+    jest.resetModules();
+    jest.clearAllMocks();
+  });
+
+  test('routes notifications to the receiver waiting for the same device', async () => {
+    const deviceA = createPeripheral('device-a');
+    const deviceB = createPeripheral('device-b');
+    const noble = new EventEmitter() as EventEmitter & {
+      state: string;
+      startScanning: jest.Mock;
+      stopScanning: jest.Mock;
+    };
+    noble.state = 'poweredOn';
+    noble.startScanning = jest.fn((_services, _duplicates, callback) => {
+      callback?.();
+      noble.emit('discover', deviceA.peripheral);
+      noble.emit('discover', deviceB.peripheral);
+    });
+    noble.stopScanning = jest.fn(callback => callback?.());
+    jest.doMock('@stoprocent/noble', () => noble);
+
+    const { createNobleBlePlugin } = await import('../transports/nobleBlePlugin');
+    const plugin = createNobleBlePlugin();
+    await plugin.init();
+    await plugin.connect('device-a');
+    await plugin.connect('device-b');
+
+    const receiveA = plugin.receive('device-a');
+    const receiveB = plugin.receive('device-b');
+    deviceB.notify.emit('data', Buffer.from('bb', 'hex'));
+    deviceA.notify.emit('data', Buffer.from('aa', 'hex'));
+
+    await expect(Promise.all([receiveA, receiveB])).resolves.toEqual(['aa', 'bb']);
+  });
+
+  test('finishes disconnect cleanup when Noble never calls unsubscribe back', async () => {
+    const device = createPeripheral('device-a');
+    const noble = new EventEmitter() as EventEmitter & {
+      state: string;
+      startScanning: jest.Mock;
+      stopScanning: jest.Mock;
+    };
+    noble.state = 'poweredOn';
+    noble.startScanning = jest.fn((_services, _duplicates, callback) => {
+      callback?.();
+      noble.emit('discover', device.peripheral);
+    });
+    noble.stopScanning = jest.fn(callback => callback?.());
+    jest.doMock('@stoprocent/noble', () => noble);
+
+    const { createNobleBlePlugin } = await import('../transports/nobleBlePlugin');
+    const plugin = createNobleBlePlugin();
+    await plugin.init();
+    await plugin.connect('device-a');
+    device.notify.unsubscribe.mockImplementation(() => undefined);
+
+    const result = await Promise.race([
+      plugin.disconnect('device-a').then(() => 'completed'),
+      new Promise(resolve => {
+        setTimeout(() => resolve('blocked'), 300);
+      }),
+    ]);
+
+    expect(result).toBe('completed');
+  });
+});

package/src/cli.ts

@@ -549,17 +549,20 @@ program
       success: false,
       payload: {
         error:
-          'Use `onekey-hw --transport ble firmware-update-v4-debug` for BLE Protocol V2 firmware update debugging.',
-        code: 'USE_FIRMWARE_UPDATE_V4_DEBUG',
+          'Use `onekey-hw --transport ble firmware-update-v4` for BLE Protocol V2 firmware updates.',
+        code: 'USE_FIRMWARE_UPDATE_V4',
       },
     })
   );
 
 program
-  .command('firmware-update-v4-debug')
-  .description('Debug Protocol V2 firmware update through sdk.firmwareUpdateV4')
+  .command('firmware-update-v4')
+  .description('Run Protocol V2 firmware update through sdk.firmwareUpdateV4')
   .option('--chunk-size <bytes>', 'Transfer chunk size in bytes')
-  .option('--resource <path>', 'FW_MGMT_TARGET_CRATE resource package path')
+  .option(
+    '--resource-bundle <spec...>',
+    'RESC bundle direct-write spec: <localPath>:<devicePath>, e.g. wallpaper.okpkg:vol0:/bundles/images/wallpaper.okpkg'
+  )
   .option('--romloader <path>', 'FW_MGMT_TARGET_ROMLOADER binary path')
   .option('--bootloader <path>', 'FW_MGMT_TARGET_BOOTLOADER binary path')
   .option('--application-p1 <path>', 'FW_MGMT_TARGET_APPLICATION_P1 binary path')
@@ -573,8 +576,8 @@ program
   .option('--retries <count>', 'Retry count for transient Protocol V2 USB probe failures')
   .action(opts =>
     runCommand({}, async ({ sdk, globalOpts }) => {
-      const params = buildFirmwareUpdateV4DebugParams(opts);
-      const result = await runFirmwareUpdateV4DebugWithRetry({
+      const params = buildFirmwareUpdateV4Params(opts);
+      const result = await runFirmwareUpdateV4WithRetry({
         sdk,
         globalOpts,
         params,
@@ -1159,11 +1162,29 @@ function readBinaryParam(path: string): ArrayBuffer {
   return new Uint8Array(buffer).buffer;
 }
 
-function getFirmwareUpdateV4DebugTotalBytes(
-  params: ReturnType<typeof buildFirmwareUpdateV4DebugParams>
-) {
+function parseResourceBundleParam(spec: string): { binary: ArrayBuffer; devicePath: string } {
+  const sep = spec.indexOf(':');
+  if (sep <= 0 || sep === spec.length - 1) {
+    throw new Error(
+      `Invalid --resource-bundle value: "${spec}". Expected <localPath>:<devicePath>`
+    );
+  }
+  const localPath = spec.slice(0, sep);
+  const devicePath = spec.slice(sep + 1);
+  if (!devicePath.startsWith('vol')) {
+    throw new Error(
+      `Invalid --resource-bundle device path: "${devicePath}". Expected a vol*:/... path`
+    );
+  }
+  return {
+    binary: readBinaryParam(localPath),
+    devicePath,
+  };
+}
+
+function getFirmwareUpdateV4TotalBytes(params: ReturnType<typeof buildFirmwareUpdateV4Params>) {
   return [
-    ...(params.resourceBinaries ?? []),
+    ...(params.resourceBundleFiles?.map(item => item.binary) ?? []),
     params.bootloaderBinary,
     params.applicationP1Binary,
     params.applicationP2Binary,
@@ -1175,16 +1196,16 @@ function getFirmwareUpdateV4DebugTotalBytes(
   ].reduce((total, binary) => total + (binary?.byteLength ?? 0), 0);
 }
 
-function getFirmwareUpdateV4DebugErrorText(result: unknown) {
+function getFirmwareUpdateV4ErrorText(result: unknown) {
   if (!result || typeof result !== 'object') return '';
-  const payload = (result as { payload?: unknown }).payload;
+  const { payload } = result as { payload?: unknown };
   if (!payload || typeof payload !== 'object') return '';
-  const error = (payload as { error?: unknown }).error;
+  const { error } = payload as { error?: unknown };
   return typeof error === 'string' ? error : '';
 }
 
 function isProtocolV2UsbProbeTransientResult(result: unknown) {
-  const error = getFirmwareUpdateV4DebugErrorText(result);
+  const error = getFirmwareUpdateV4ErrorText(result);
   return (
     error.includes('Device protocol mismatch') &&
     error.includes('expected V2') &&
@@ -1198,22 +1219,22 @@ function isSuccessResult(result: unknown) {
   );
 }
 
-function getFirmwareDebugPayload(message: unknown) {
+function getFirmwareUpdatePayload(message: unknown) {
   if (!message || typeof message !== 'object') return undefined;
   return (message as { payload?: Record<string, unknown> }).payload;
 }
 
-function formatFirmwareDebugProgress(progress: number) {
+function formatFirmwareProgress(progress: number) {
   if (!Number.isFinite(progress)) return '0%';
   return `${Math.min(Math.max(Math.round(progress), 0), 100)}%`;
 }
 
-function formatFirmwareDebugBytes(bytes: number) {
+function formatFirmwareBytes(bytes: number) {
   if (!Number.isFinite(bytes) || bytes <= 0) return '';
   return `${(bytes / 1024).toFixed(1)} KiB`;
 }
 
-function maybePrintFirmwareDebugProgress({
+function maybePrintFirmwareProgress({
   progressType,
   progress,
   payload,
@@ -1234,7 +1255,7 @@ function maybePrintFirmwareDebugProgress({
   const rateBytesPerSecond = Number(payload.rateBytesPerSecond);
   const sizeText =
     Number.isFinite(transferredBytes) && Number.isFinite(totalBytes) && totalBytes > 0
-      ? ` ${formatFirmwareDebugBytes(transferredBytes)}/${formatFirmwareDebugBytes(totalBytes)}`
+      ? ` ${formatFirmwareBytes(transferredBytes)}/${formatFirmwareBytes(totalBytes)}`
       : '';
   const speedText =
     Number.isFinite(rateBytesPerSecond) && rateBytesPerSecond > 0
@@ -1242,14 +1263,14 @@ function maybePrintFirmwareDebugProgress({
       : '';
 
   process.stderr.write(
-    `[onekey-hw] Firmware ${progressType}: ${formatFirmwareDebugProgress(
+    `[onekey-hw] Firmware ${progressType}: ${formatFirmwareProgress(
       progress
     )}${sizeText}${speedText}\n`
   );
   return progress >= 100 ? 100 : printableProgress;
 }
 
-function buildFirmwareUpdateV4DebugMetrics({
+function buildFirmwareUpdateV4Metrics({
   attempt,
   maxAttempts,
   totalBytes,
@@ -1309,7 +1330,7 @@ function buildFirmwareUpdateV4DebugMetrics({
   };
 }
 
-async function runFirmwareUpdateV4DebugWithRetry({
+async function runFirmwareUpdateV4WithRetry({
   sdk,
   globalOpts,
   params,
@@ -1317,10 +1338,10 @@ async function runFirmwareUpdateV4DebugWithRetry({
 }: {
   sdk: AnySdk;
   globalOpts: Record<string, any>;
-  params: ReturnType<typeof buildFirmwareUpdateV4DebugParams>;
+  params: ReturnType<typeof buildFirmwareUpdateV4Params>;
   retries?: number;
 }) {
-  const totalBytes = getFirmwareUpdateV4DebugTotalBytes(params);
+  const totalBytes = getFirmwareUpdateV4TotalBytes(params);
   const maxAttempts = Math.max((retries ?? 2) + 1, 1);
   let currentSdk = sdk;
   let lastResult: unknown;
@@ -1346,7 +1367,7 @@ async function runFirmwareUpdateV4DebugWithRetry({
     const onUiEvent = (message: unknown) => {
       if (!message || typeof message !== 'object') return;
       const messageType = (message as { type?: string }).type;
-      const payload = getFirmwareDebugPayload(message);
+      const payload = getFirmwareUpdatePayload(message);
 
       if (messageType === UI_REQUEST.FIRMWARE_TIP) {
         const tipMessage = (payload?.data as { message?: unknown } | undefined)?.message;
@@ -1372,7 +1393,7 @@ async function runFirmwareUpdateV4DebugWithRetry({
         progressEvents += 1;
         lastProgress = Math.max(lastProgress, progress);
         transferStartedAt ??= Date.now();
-        lastPrintedTransferProgress = maybePrintFirmwareDebugProgress({
+        lastPrintedTransferProgress = maybePrintFirmwareProgress({
           progressType: 'transfer',
           progress,
           payload,
@@ -1388,7 +1409,7 @@ async function runFirmwareUpdateV4DebugWithRetry({
         installProgressEvents += 1;
         lastInstallProgress = Math.max(lastInstallProgress, progress);
         installStartedAt ??= Date.now();
-        lastPrintedInstallProgress = maybePrintFirmwareDebugProgress({
+        lastPrintedInstallProgress = maybePrintFirmwareProgress({
           progressType: 'install',
           progress,
           payload,
@@ -1410,7 +1431,7 @@ async function runFirmwareUpdateV4DebugWithRetry({
       installEndedAt = Date.now();
     }
 
-    const debugMetrics = buildFirmwareUpdateV4DebugMetrics({
+    const metrics = buildFirmwareUpdateV4Metrics({
       attempt,
       maxAttempts,
       totalBytes,
@@ -1435,7 +1456,7 @@ async function runFirmwareUpdateV4DebugWithRetry({
         ...(lastResult as Record<string, unknown>),
         payload: {
           ...payload,
-          _debug: debugMetrics,
+          metrics,
         },
       };
     }
@@ -1457,16 +1478,18 @@ async function runFirmwareUpdateV4DebugWithRetry({
       `[onekey-hw] Protocol V2 USB probe was transient; retrying firmwareUpdateV4 (${attempt}/${maxAttempts})...\n`
     );
     await disposeSDK();
-    await new Promise(resolve => setTimeout(resolve, 3000));
+    await new Promise(resolve => {
+      setTimeout(resolve, 3000);
+    });
     currentSdk = await createSDK(globalOpts);
   }
 
   return lastResult;
 }
 
-function buildFirmwareUpdateV4DebugParams(opts: {
+function buildFirmwareUpdateV4Params(opts: {
   chunkSize?: string;
-  resource?: string;
+  resourceBundle?: string[];
   romloader?: string;
   bootloader?: string;
   applicationP1?: string;
@@ -1483,7 +1506,7 @@ function buildFirmwareUpdateV4DebugParams(opts: {
     connectProtocol: 'V2' as const,
     chunkSize: opts.chunkSize ? safeParseInt(opts.chunkSize, '--chunk-size') : undefined,
     forcedUpdateRes: opts.forcedUpdateRes,
-    resourceBinaries: opts.resource ? [readBinaryParam(opts.resource)] : undefined,
+    resourceBundleFiles: opts.resourceBundle?.map(parseResourceBundleParam),
     romloaderBinary: opts.romloader ? readBinaryParam(opts.romloader) : undefined,
     bootloaderBinary: opts.bootloader ? readBinaryParam(opts.bootloader) : undefined,
     applicationP1Binary: opts.applicationP1 ? readBinaryParam(opts.applicationP1) : undefined,
@@ -1496,7 +1519,7 @@ function buildFirmwareUpdateV4DebugParams(opts: {
   };
 
   const hasPayload = [
-    params.resourceBinaries,
+    params.resourceBundleFiles,
     params.romloaderBinary,
     params.bootloaderBinary,
     params.applicationP1Binary,
@@ -1509,7 +1532,7 @@ function buildFirmwareUpdateV4DebugParams(opts: {
   ].some(Boolean);
 
   if (!hasPayload) {
-    const err = new Error('firmware-update-v4-debug requires at least one binary path');
+    const err = new Error('firmware-update-v4 requires at least one binary path');
     (err as Error & { code?: string }).code = 'MISSING_FIRMWARE_BINARY';
     throw err;
   }
@@ -1528,4 +1551,8 @@ function safeParseInt(input: string, label: string): number {
   return num;
 }
 
-program.parse();
+export { program };
+
+if (require.main === module) {
+  program.parse();
+}

package/src/transports/nobleBlePlugin.ts

@@ -28,6 +28,17 @@ type CharacteristicPair = {
   notify: Characteristic;
 };
 
+type NoblePendingReceiver = {
+  resolve: (data: string) => void;
+  reject: (error: Error) => void;
+};
+
+type NobleNotificationState = {
+  generation: number;
+  queue: string[];
+  pendingReceivers: Set<NoblePendingReceiver>;
+};
+
 const ONEKEY_SERVICE_UUIDS = [ONEKEY_SERVICE_UUID];
 const PRO2_ADVERTISEMENT_SERVICE_UUID_KEYS = new Set(['fffd']);
 const NORMALIZED_WRITE_UUID = '0002';
@@ -41,6 +52,7 @@ const BLUETOOTH_INIT_TIMEOUT = 10_000;
 const DEVICE_SCAN_TIMEOUT = 8_000;
 const CONNECTION_TIMEOUT = 8_000;
 const SERVICE_DISCOVERY_TIMEOUT = 10_000;
+const BLE_CLEANUP_TIMEOUT = 100;
 const BLE_PACKET_SIZE = 192;
 const BLE_WRITE_DELAY = 5;
 const BLE_ENCRYPTION_ERROR_PATTERNS = [/encryption is insufficient/i, /insufficient encryption/i];
@@ -50,8 +62,8 @@ let nobleReadyPromise: Promise<void> | null = null;
 const discoveredDevices = new Map<string, Peripheral>();
 const connectedDevices = new Map<string, Peripheral>();
 const deviceCharacteristics = new Map<string, CharacteristicPair>();
-const notificationQueue: string[] = [];
-const pendingReceivers: Array<(data: string) => void> = [];
+const notificationStates = new Map<string, NobleNotificationState>();
+const notificationGenerations = new Map<string, number>();
 
 function getBleUuidKey(uuid?: string | null) {
   const normalized = (uuid ?? '').replace(/-/g, '').toLowerCase();
@@ -78,14 +90,65 @@ function isOneKeyPeripheral(peripheral: Peripheral) {
   return isOnekeyDevice(deviceName, peripheral.id) || hasOneKeyAdvertisementService(peripheral);
 }
 
-function enqueueNotification(data: Buffer) {
+function enqueueNotification(deviceId: string, generation: number, data: Buffer) {
+  const state = notificationStates.get(deviceId);
+  if (!state || state.generation !== generation) return;
+
   const hex = data.toString('hex');
-  const receiver = pendingReceivers.shift();
+  const [receiver] = state.pendingReceivers;
   if (receiver) {
-    receiver(hex);
+    state.pendingReceivers.delete(receiver);
+    receiver.resolve(hex);
     return;
   }
-  notificationQueue.push(hex);
+  state.queue.push(hex);
+}
+
+function createNotificationState(deviceId: string) {
+  const existing = notificationStates.get(deviceId);
+  if (existing) {
+    const error = new Error(`BLE notification state replaced for ${deviceId}`);
+    existing.pendingReceivers.forEach(receiver => receiver.reject(error));
+  }
+
+  const generation = (notificationGenerations.get(deviceId) ?? 0) + 1;
+  notificationGenerations.set(deviceId, generation);
+  const state: NobleNotificationState = {
+    generation,
+    queue: [],
+    pendingReceivers: new Set(),
+  };
+  notificationStates.set(deviceId, state);
+  return state;
+}
+
+function clearNotificationState(deviceId: string, reason: string) {
+  const state = notificationStates.get(deviceId);
+  if (!state) return;
+
+  notificationStates.delete(deviceId);
+  const error = new Error(reason);
+  state.pendingReceivers.forEach(receiver => receiver.reject(error));
+  state.pendingReceivers.clear();
+  state.queue.length = 0;
+}
+
+function waitForNobleCleanup(registerCallback: (callback: () => void) => void) {
+  return new Promise<void>(resolve => {
+    let completed = false;
+    const complete = () => {
+      if (completed) return;
+      completed = true;
+      clearTimeout(timeout);
+      resolve();
+    };
+    const timeout = setTimeout(complete, BLE_CLEANUP_TIMEOUT);
+    try {
+      registerCallback(complete);
+    } catch {
+      complete();
+    }
+  });
 }
 
 async function initializeNoble() {
@@ -270,10 +333,12 @@ async function discoverCharacteristics(peripheral: Peripheral): Promise<Characte
   };
 }
 
-function subscribeNotifications(deviceId: string, notifyCharacteristic: Characteristic) {
-  return new Promise<void>(resolve => {
-    notifyCharacteristic.unsubscribe(() => resolve());
-  })
+function subscribeNotifications(
+  deviceId: string,
+  generation: number,
+  notifyCharacteristic: Characteristic
+) {
+  return waitForNobleCleanup(callback => notifyCharacteristic.unsubscribe(callback))
     .then(
       () =>
         new Promise<void>((resolve, reject) => {
@@ -303,7 +368,7 @@ function subscribeNotifications(deviceId: string, notifyCharacteristic: Characte
     )
     .then(() => {
       notifyCharacteristic.removeAllListeners('data');
-      notifyCharacteristic.on('data', enqueueNotification);
+      notifyCharacteristic.on('data', data => enqueueNotification(deviceId, generation, data));
     })
     .catch(error => {
       notifyCharacteristic.removeAllListeners('data');
@@ -329,23 +394,18 @@ function writeCharacteristic(characteristic: Characteristic, buffer: Buffer) {
 async function disconnectDevice(uuid: string) {
   const peripheral = connectedDevices.get(uuid);
   const characteristics = deviceCharacteristics.get(uuid);
+  clearNotificationState(uuid, `BLE device disconnected: ${uuid}`);
   if (characteristics) {
     characteristics.notify.removeAllListeners('data');
-    await new Promise<void>(resolve => {
-      characteristics.notify.unsubscribe(() => resolve());
-    });
+    await waitForNobleCleanup(callback => characteristics.notify.unsubscribe(callback));
   }
 
   connectedDevices.delete(uuid);
   deviceCharacteristics.delete(uuid);
-  notificationQueue.length = 0;
-  pendingReceivers.splice(0).forEach(resolve => resolve(''));
 
   if (!peripheral || peripheral.state === 'disconnected') return;
 
-  await new Promise<void>(resolve => {
-    peripheral.disconnect(() => resolve());
-  });
+  await waitForNobleCleanup(callback => peripheral.disconnect(callback));
 }
 
 export function createNobleBlePlugin(): LowlevelTransportSharedPlugin {
@@ -376,7 +436,13 @@ export function createNobleBlePlugin(): LowlevelTransportSharedPlugin {
 
       await connectPeripheral(peripheral);
       const characteristics = await discoverCharacteristics(peripheral);
-      await subscribeNotifications(uuid, characteristics.notify);
+      const notificationState = createNotificationState(uuid);
+      try {
+        await subscribeNotifications(uuid, notificationState.generation, characteristics.notify);
+      } catch (error) {
+        clearNotificationState(uuid, `BLE notification subscription failed: ${uuid}`);
+        throw error;
+      }
       connectedDevices.set(uuid, peripheral);
       deviceCharacteristics.set(uuid, characteristics);
     },
@@ -404,11 +470,28 @@ export function createNobleBlePlugin(): LowlevelTransportSharedPlugin {
       }
     },
 
-    async receive() {
-      const queued = notificationQueue.shift();
+    async receive(uuid?: string) {
+      const resolvedUuid =
+        uuid ??
+        (notificationStates.size === 1 ? notificationStates.keys().next().value : undefined);
+      if (!resolvedUuid) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          'BLE receive requires a device UUID when multiple devices are connected'
+        );
+      }
+
+      const state = notificationStates.get(resolvedUuid);
+      if (!state) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.TransportNotFound,
+          `BLE notification state not found: ${resolvedUuid}`
+        );
+      }
+      const queued = state.queue.shift();
       if (queued !== undefined) return queued;
-      return new Promise<string>(resolve => {
-        pendingReceivers.push(resolve);
+      return new Promise<string>((resolve, reject) => {
+        state.pendingReceivers.add({ resolve, reject });
       });
     },
   };