@onekeyfe/hardware-cli 1.2.0-alpha.16 → 1.2.0-alpha.18

package/dist/cli.d.ts

@@ -1,3 +1,17 @@
 import { Command } from 'commander';
 declare const program: Command;
+export declare function getLegacyFirmwareConnectTimeout(transport: 'usb' | 'ble'): 90000 | undefined;
+export declare function buildWallpaperUploadMetrics({ totalBytes, transferredBytes, startedAt, endedAt, lastProgress, }: {
+    totalBytes: number;
+    transferredBytes: number;
+    startedAt: number;
+    endedAt: number;
+    lastProgress: number;
+}): {
+    totalBytes: number;
+    transferredBytes: number;
+    totalSeconds: number;
+    transferKiBPerSecond: number | null;
+    lastProgress: number;
+};
 export { program };

package/dist/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.program = void 0;
+exports.program = exports.buildWallpaperUploadMetrics = exports.getLegacyFirmwareConnectTimeout = void 0;
 const node_fs_1 = require("node:fs");
 const commander_1 = require("commander");
 const hd_core_1 = require("@onekeyfe/hd-core");
 const hd_shared_1 = require("@onekeyfe/hd-shared");
 const chains_1 = require("./chains");
+const deviceSelection_1 = require("./deviceSelection");
 const sdk_1 = require("./sdk");
 const session_1 = require("./session");
 function extractPassphraseSession(payload) {
@@ -101,6 +102,81 @@ program
     const result = await sdk.getFeatures(connectId || '');
     outputResult(globalOpts, result);
 }));
+program
+    .command('upload-wallpaper')
+    .description('Upload and activate a Pro2 wallpaper')
+    .requiredOption('--rgba <path>', '604x1024 raw RGBA file')
+    .option('--file-name <name>', 'Device wallpaper file name', 'wallpaper-cli')
+    .option('--chunk-size <bytes>', 'Transfer chunk size in bytes')
+    .action(opts => runCommand({}, async ({ sdk, globalOpts, params }) => {
+    const rgba = readBinaryParam(opts.rgba);
+    const expectedBytes = 604 * 1024 * 4;
+    if (rgba.byteLength !== expectedBytes) {
+        throw new Error(`Invalid RGBA size: expected ${expectedBytes} bytes, received ${rgba.byteLength}`);
+    }
+    let transferStartedAt;
+    let transferEndedAt;
+    let lastProgress = -1;
+    let lastPrintedProgress = -10;
+    let progressTotalBytes = 0;
+    let transferredBytes = 0;
+    const totalStartedAt = Date.now();
+    const onUiEvent = (message) => {
+        if (!message || typeof message !== 'object')
+            return;
+        const event = message;
+        if (event.type !== hd_core_1.UI_REQUEST.DEVICE_PROGRESS || !event.payload)
+            return;
+        const progress = Number(event.payload.progress);
+        if (!Number.isFinite(progress))
+            return;
+        transferStartedAt ?? (transferStartedAt = Date.now());
+        lastProgress = Math.max(lastProgress, progress);
+        const totalBytes = Number(event.payload.totalBytes);
+        if (Number.isFinite(totalBytes) && totalBytes > 0)
+            progressTotalBytes = totalBytes;
+        const confirmedBytes = Number(event.payload.transferredBytes);
+        if (Number.isFinite(confirmedBytes) && confirmedBytes >= 0) {
+            transferredBytes = Math.max(transferredBytes, confirmedBytes);
+        }
+        const printableProgress = Math.floor(progress / 10) * 10;
+        if (printableProgress > lastPrintedProgress || progress >= 100) {
+            const rate = Number(event.payload.rateBytesPerSecond);
+            const rateText = Number.isFinite(rate) && rate > 0 ? ` ${(rate / 1024).toFixed(2)} KiB/s` : '';
+            process.stderr.write(`[onekey-hw] Wallpaper transfer: ${Math.round(progress)}%${rateText}\n`);
+            lastPrintedProgress = progress >= 100 ? 100 : printableProgress;
+        }
+        if (progress >= 100)
+            transferEndedAt ?? (transferEndedAt = Date.now());
+    };
+    sdk.on(hd_core_1.UI_EVENT, onUiEvent);
+    let result;
+    try {
+        result = await sdk.deviceUploadWallpaper(globalOpts.connectId, {
+            ...params,
+            width: 604,
+            height: 1024,
+            rgba,
+            fileName: opts.fileName,
+            chunkSize: opts.chunkSize ? safeParseInt(opts.chunkSize, '--chunk-size') : undefined,
+        });
+    }
+    finally {
+        sdk.off?.(hd_core_1.UI_EVENT, onUiEvent);
+    }
+    const endedAt = transferEndedAt ?? Date.now();
+    const totalBytes = Number(result?.payload?.size) || progressTotalBytes;
+    outputResult(globalOpts, {
+        ...result,
+        metrics: buildWallpaperUploadMetrics({
+            totalBytes,
+            transferredBytes: result?.success ? totalBytes : transferredBytes,
+            startedAt: transferStartedAt ?? totalStartedAt,
+            endedAt,
+            lastProgress,
+        }),
+    });
+}));
 // ============================================================
 // Signing Commands
 // ============================================================
@@ -414,6 +490,30 @@ program
         code: 'FIRMWARE_UPDATE_NOT_SUPPORTED',
     },
 }));
+program
+    .command('firmware-update-legacy')
+    .description('Update Classic/Pure firmware through the legacy protocol')
+    .requiredOption('--binary <path>', 'Local firmware binary path')
+    .option('--device-name <name>', 'BLE advertising name, for example K1514')
+    .option('--update-type <type>', 'Firmware component: firmware or ble', 'firmware')
+    .option('--no-reboot', 'Do not reboot the device after a successful update')
+    .action(opts => runCommand({}, async ({ sdk, globalOpts }) => {
+    if (opts.updateType !== 'firmware' && opts.updateType !== 'ble') {
+        throw new Error(`Unsupported --update-type: ${opts.updateType}. Use "firmware" or "ble".`);
+    }
+    const connectId = await resolveLegacyFirmwareConnectId(sdk, globalOpts.connectId, opts.deviceName);
+    const result = await sdk.firmwareUpdate(connectId, {
+        binary: readBinaryParam(opts.binary),
+        updateType: opts.updateType,
+        rebootOnSuccess: opts.reboot,
+        timeout: getLegacyFirmwareConnectTimeout(globalOpts.transport),
+    });
+    outputResult(globalOpts, result);
+}));
+function getLegacyFirmwareConnectTimeout(transport) {
+    return transport === 'usb' ? 90000 : undefined;
+}
+exports.getLegacyFirmwareConnectTimeout = getLegacyFirmwareConnectTimeout;
 program
     .command('firmware-update-ble')
     .description('Run Protocol V2 firmware update over BLE')
@@ -746,18 +846,22 @@ globalOpts) {
         searchResult.payload.length === 0) {
         return undefined;
     }
-    const device = searchResult.payload[0];
-    const connectId = device.connectId || globalOpts.connectId || '';
+    const device = (0, deviceSelection_1.selectSearchDevice)(searchResult.payload, globalOpts.connectId);
+    if (!device) {
+        throw new Error(`未找到指定的 BLE 设备: ${globalOpts.connectId}`);
+    }
+    const selectedDevice = device;
+    const connectId = selectedDevice.connectId || globalOpts.connectId || '';
     if (!globalOpts.connectId && connectId) {
         globalOpts.connectId = connectId;
     }
     // ── Step 2: Get features if searchDevices didn't populate them ──
     // getFeatures failures here are non-fatal — we fall through to Step 3
     // which will fail with a clearer error if the device is truly unreachable.
-    let deviceId = device.features?.deviceId || device.deviceId || '';
-    let deviceType = (0, hd_core_1.getDeviceType)(device.features);
-    let unlocked = device.features?.unlocked;
-    let passphraseProtection = device.features?.passphraseProtection;
+    let deviceId = selectedDevice.features?.deviceId || selectedDevice.deviceId || '';
+    let deviceType = (0, hd_core_1.getDeviceType)(selectedDevice.features);
+    let unlocked = selectedDevice.features?.unlocked;
+    let passphraseProtection = selectedDevice.features?.passphraseProtection;
     if (!deviceId || unlocked == null || passphraseProtection == null) {
         try {
             const featResult = await sdk.getFeatures(connectId);
@@ -904,6 +1008,31 @@ function readBinaryParam(path) {
     const buffer = (0, node_fs_1.readFileSync)(path);
     return new Uint8Array(buffer).buffer;
 }
+async function resolveLegacyFirmwareConnectId(sdk, explicitConnectId, deviceName) {
+    if (explicitConnectId && !deviceName)
+        return explicitConnectId;
+    const searchResult = await sdk.searchDevices();
+    if (!searchResult?.success || !Array.isArray(searchResult.payload)) {
+        throw new Error('Unable to scan BLE devices');
+    }
+    const devices = searchResult.payload;
+    const normalizedName = deviceName?.trim().toLowerCase();
+    const matches = normalizedName
+        ? devices.filter(device => device.name?.trim().toLowerCase() === normalizedName)
+        : devices.filter(device => device.deviceType?.toLowerCase() === 'classic');
+    if (matches.length === 0) {
+        throw new Error(normalizedName ? `BLE device not found by name: ${deviceName}` : 'No Classic/Pure BLE device found');
+    }
+    if (matches.length > 1) {
+        throw new Error(normalizedName
+            ? `Multiple BLE devices found by name: ${deviceName}`
+            : 'Multiple Classic/Pure BLE devices found; specify --device-name');
+    }
+    const connectId = matches[0].connectId;
+    if (!connectId)
+        throw new Error(`BLE device has no connect ID: ${matches[0].name}`);
+    return connectId;
+}
 function parseResourceBundleParam(spec) {
     const sep = spec.indexOf(':');
     if (sep <= 0 || sep === spec.length - 1) {
@@ -965,6 +1094,19 @@ function formatFirmwareBytes(bytes) {
         return '';
     return `${(bytes / 1024).toFixed(1)} KiB`;
 }
+function buildWallpaperUploadMetrics({ totalBytes, transferredBytes, startedAt, endedAt, lastProgress, }) {
+    const elapsedMs = Math.max(endedAt - startedAt, 0);
+    return {
+        totalBytes,
+        transferredBytes,
+        totalSeconds: Number((elapsedMs / 1000).toFixed(2)),
+        transferKiBPerSecond: elapsedMs > 0
+            ? Number((transferredBytes / 1024 / (elapsedMs / 1000)).toFixed(2))
+            : null,
+        lastProgress,
+    };
+}
+exports.buildWallpaperUploadMetrics = buildWallpaperUploadMetrics;
 function maybePrintFirmwareProgress({ progressType, progress, payload, lastPrintedProgress, }) {
     const printableProgress = Math.floor(progress / 10) * 10;
     if (printableProgress <= lastPrintedProgress && progress < 100) {

package/dist/deviceSelection.d.ts

@@ -0,0 +1,3 @@
+export declare function selectSearchDevice<T extends {
+    connectId?: string;
+}>(devices: T[], preferredConnectId?: string): T | undefined;

package/dist/deviceSelection.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectSearchDevice = void 0;
+function selectSearchDevice(devices, preferredConnectId) {
+    if (preferredConnectId) {
+        return (devices.find(device => device.connectId === preferredConnectId) ??
+            { connectId: preferredConnectId });
+    }
+    return devices[0];
+}
+exports.selectSearchDevice = selectSearchDevice;

package/dist/transports/nobleBlePlugin.js

@@ -350,15 +350,16 @@ function createNobleBlePlugin() {
         async disconnect(uuid) {
             await disconnectDevice(uuid);
         },
-        async send(uuid, data) {
+        async send(uuid, data, options) {
             const characteristics = deviceCharacteristics.get(uuid);
             if (!characteristics) {
                 throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleCharacteristicNotFound, `BLE device is not connected: ${uuid}`);
             }
             const buffer = Buffer.from(data, 'hex');
+            const withoutResponse = options?.withoutResponse ?? true;
             for (let offset = 0; offset < buffer.length; offset += BLE_PACKET_SIZE) {
                 const chunk = buffer.subarray(offset, Math.min(offset + BLE_PACKET_SIZE, buffer.length));
-                await writeCharacteristic(characteristics.write, chunk, true);
+                await writeCharacteristic(characteristics.write, chunk, withoutResponse);
             }
         },
         async receive(uuid) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hardware-cli",
-  "version": "1.2.0-alpha.16",
+  "version": "1.2.0-alpha.18",
   "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.16",
-    "@onekeyfe/hd-core": "1.2.0-alpha.16",
-    "@onekeyfe/hd-shared": "1.2.0-alpha.16",
-    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.16",
+    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.18",
+    "@onekeyfe/hd-core": "1.2.0-alpha.18",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.18",
+    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.18",
     "@stoprocent/noble": "2.3.16",
     "commander": "^12.0.0"
   },
-  "gitHead": "2356d951f63a39a46bc995c2090348a383966175"
+  "gitHead": "bdbc5bf74e48ca90f5c56f3079b2b974e61f7aa4"
 }

package/src/__tests__/device-selection.test.ts

@@ -0,0 +1,29 @@
+import { selectSearchDevice } from '../deviceSelection';
+
+describe('selectSearchDevice', () => {
+  it('多设备环境优先选择显式 connectId 对应的设备', () => {
+    const devices = [
+      { connectId: 'first-device', name: 'Pro A9CA' },
+      { connectId: 'target-device', name: 'Pro2 6136' },
+    ];
+
+    expect(selectSearchDevice(devices, 'target-device')).toEqual(devices[1]);
+  });
+
+  it('未指定 connectId 时保持选择第一台设备的兼容行为', () => {
+    const devices = [
+      { connectId: 'first-device', name: 'Pro2 6136' },
+      { connectId: 'second-device', name: 'Pro2 C445' },
+    ];
+
+    expect(selectSearchDevice(devices)).toEqual(devices[0]);
+  });
+
+  it('显式 connectId 暂未出现在扫描结果时仍保留该目标', () => {
+    const devices = [{ connectId: 'other-device', name: 'Pro2 C445' }];
+
+    expect(selectSearchDevice(devices, 'target-device')).toEqual({
+      connectId: 'target-device',
+    });
+  });
+});

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

@@ -0,0 +1,20 @@
+import { getLegacyFirmwareConnectTimeout, program } from '../cli';
+
+describe('firmware-update-legacy CLI command', () => {
+  test('提供 Classic/Pure 的本地固件升级命令', () => {
+    const command = program.commands.find(item => item.name() === 'firmware-update-legacy');
+
+    expect(command).toBeDefined();
+    expect(command?.description()).toBe(
+      'Update Classic/Pure firmware through the legacy protocol'
+    );
+    expect(command?.options.find(option => option.long === '--binary')?.mandatory).toBe(true);
+    expect(command?.options.some(option => option.long === '--device-name')).toBe(true);
+    expect(command?.options.some(option => option.long === '--update-type')).toBe(true);
+  });
+
+  test('USB Classic 固件升级使用足够的设备探测超时', () => {
+    expect(getLegacyFirmwareConnectTimeout('usb')).toBe(90_000);
+    expect(getLegacyFirmwareConnectTimeout('ble')).toBeUndefined();
+  });
+});

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

@@ -141,6 +141,31 @@ describe('Noble BLE plugin notification routing', () => {
     ]);
   });
 
+  test('uses acknowledged writes when requested by firmware upload', 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');
+
+    await (plugin.send as any)('device-a', 'aa', { withoutResponse: false });
+
+    expect(device.write.write).toHaveBeenCalledWith(expect.any(Buffer), false, expect.any(Function));
+  });
+
   test('does not add a fixed delay between 192-byte writes', async () => {
     const device = createPeripheral('device-a');
     const noble = new EventEmitter() as EventEmitter & {
@@ -171,4 +196,30 @@ describe('Noble BLE plugin notification routing', () => {
     expect(device.write.write).toHaveBeenCalledTimes(2);
     expect(wait).not.toHaveBeenCalled();
   });
+
+  test('preserves a short final BLE packet without padding', 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');
+
+    await plugin.send('device-a', 'aabb');
+
+    const packet = device.write.write.mock.calls[0][0] as Buffer;
+    expect(packet).toEqual(Buffer.from('aabb', 'hex'));
+  });
 });

package/src/__tests__/wallpaper-upload-command.test.ts

@@ -0,0 +1,46 @@
+import { buildWallpaperUploadMetrics, program } from '../cli';
+
+describe('upload-wallpaper CLI command', () => {
+  test('exposes a command backed by the SDK wallpaper API', () => {
+    const command = program.commands.find(item => item.name() === 'upload-wallpaper');
+
+    expect(command).toBeDefined();
+    expect(command?.description()).toBe('Upload and activate a Pro2 wallpaper');
+  });
+
+  test('reports effective transfer speed from encoded bytes and elapsed time', () => {
+    expect(
+      buildWallpaperUploadMetrics({
+        totalBytes: 2_473_984,
+        transferredBytes: 2_473_984,
+        startedAt: 1_000,
+        endedAt: 2_000,
+        lastProgress: 100,
+      })
+    ).toEqual({
+      totalBytes: 2_473_984,
+      transferredBytes: 2_473_984,
+      totalSeconds: 1,
+      transferKiBPerSecond: 2416,
+      lastProgress: 100,
+    });
+  });
+
+  test('uses confirmed bytes for an interrupted transfer rate', () => {
+    expect(
+      buildWallpaperUploadMetrics({
+        totalBytes: 1_855_500,
+        transferredBytes: 631_800,
+        startedAt: 1_000,
+        endedAt: 101_000,
+        lastProgress: 34,
+      })
+    ).toEqual({
+      totalBytes: 1_855_500,
+      transferredBytes: 631_800,
+      totalSeconds: 100,
+      transferKiBPerSecond: 6.17,
+      lastProgress: 34,
+    });
+  });
+});

package/src/cli.ts

@@ -10,6 +10,7 @@ import {
   resolveSignMessage,
   resolveSignTransaction,
 } from './chains';
+import { selectSearchDevice } from './deviceSelection';
 import { createSDK, disposeSDK } from './sdk';
 import {
   clearSessionFromKeychain,
@@ -147,6 +148,94 @@ program
     })
   );
 
+program
+  .command('upload-wallpaper')
+  .description('Upload and activate a Pro2 wallpaper')
+  .requiredOption('--rgba <path>', '604x1024 raw RGBA file')
+  .option('--file-name <name>', 'Device wallpaper file name', 'wallpaper-cli')
+  .option('--chunk-size <bytes>', 'Transfer chunk size in bytes')
+  .action(opts =>
+    runCommand({}, async ({ sdk, globalOpts, params }) => {
+      const rgba = readBinaryParam(opts.rgba);
+      const expectedBytes = 604 * 1024 * 4;
+      if (rgba.byteLength !== expectedBytes) {
+        throw new Error(
+          `Invalid RGBA size: expected ${expectedBytes} bytes, received ${rgba.byteLength}`
+        );
+      }
+
+      let transferStartedAt: number | undefined;
+      let transferEndedAt: number | undefined;
+      let lastProgress = -1;
+      let lastPrintedProgress = -10;
+      let progressTotalBytes = 0;
+      let transferredBytes = 0;
+      const totalStartedAt = Date.now();
+      const onUiEvent = (message: unknown) => {
+        if (!message || typeof message !== 'object') return;
+        const event = message as {
+          type?: string;
+          payload?: {
+            progress?: number;
+            transferredBytes?: number;
+            totalBytes?: number;
+            rateBytesPerSecond?: number;
+          };
+        };
+        if (event.type !== UI_REQUEST.DEVICE_PROGRESS || !event.payload) return;
+        const progress = Number(event.payload.progress);
+        if (!Number.isFinite(progress)) return;
+        transferStartedAt ??= Date.now();
+        lastProgress = Math.max(lastProgress, progress);
+        const totalBytes = Number(event.payload.totalBytes);
+        if (Number.isFinite(totalBytes) && totalBytes > 0) progressTotalBytes = totalBytes;
+        const confirmedBytes = Number(event.payload.transferredBytes);
+        if (Number.isFinite(confirmedBytes) && confirmedBytes >= 0) {
+          transferredBytes = Math.max(transferredBytes, confirmedBytes);
+        }
+        const printableProgress = Math.floor(progress / 10) * 10;
+        if (printableProgress > lastPrintedProgress || progress >= 100) {
+          const rate = Number(event.payload.rateBytesPerSecond);
+          const rateText =
+            Number.isFinite(rate) && rate > 0 ? ` ${(rate / 1024).toFixed(2)} KiB/s` : '';
+          process.stderr.write(
+            `[onekey-hw] Wallpaper transfer: ${Math.round(progress)}%${rateText}\n`
+          );
+          lastPrintedProgress = progress >= 100 ? 100 : printableProgress;
+        }
+        if (progress >= 100) transferEndedAt ??= Date.now();
+      };
+
+      sdk.on(UI_EVENT, onUiEvent);
+      let result: any;
+      try {
+        result = await sdk.deviceUploadWallpaper(globalOpts.connectId, {
+          ...params,
+          width: 604,
+          height: 1024,
+          rgba,
+          fileName: opts.fileName,
+          chunkSize: opts.chunkSize ? safeParseInt(opts.chunkSize, '--chunk-size') : undefined,
+        });
+      } finally {
+        sdk.off?.(UI_EVENT, onUiEvent);
+      }
+
+      const endedAt = transferEndedAt ?? Date.now();
+      const totalBytes = Number(result?.payload?.size) || progressTotalBytes;
+      outputResult(globalOpts, {
+        ...result,
+        metrics: buildWallpaperUploadMetrics({
+          totalBytes,
+          transferredBytes: result?.success ? totalBytes : transferredBytes,
+          startedAt: transferStartedAt ?? totalStartedAt,
+          endedAt,
+          lastProgress,
+        }),
+      });
+    })
+  );
+
 // ============================================================
 // Signing Commands
 // ============================================================
@@ -541,6 +630,38 @@ program
     })
   );
 
+program
+  .command('firmware-update-legacy')
+  .description('Update Classic/Pure firmware through the legacy protocol')
+  .requiredOption('--binary <path>', 'Local firmware binary path')
+  .option('--device-name <name>', 'BLE advertising name, for example K1514')
+  .option('--update-type <type>', 'Firmware component: firmware or ble', 'firmware')
+  .option('--no-reboot', 'Do not reboot the device after a successful update')
+  .action(opts =>
+    runCommand({}, async ({ sdk, globalOpts }) => {
+      if (opts.updateType !== 'firmware' && opts.updateType !== 'ble') {
+        throw new Error(`Unsupported --update-type: ${opts.updateType}. Use "firmware" or "ble".`);
+      }
+
+      const connectId = await resolveLegacyFirmwareConnectId(
+        sdk,
+        globalOpts.connectId,
+        opts.deviceName
+      );
+      const result = await sdk.firmwareUpdate(connectId, {
+        binary: readBinaryParam(opts.binary),
+        updateType: opts.updateType,
+        rebootOnSuccess: opts.reboot,
+        timeout: getLegacyFirmwareConnectTimeout(globalOpts.transport),
+      });
+      outputResult(globalOpts, result);
+    })
+  );
+
+export function getLegacyFirmwareConnectTimeout(transport: 'usb' | 'ble') {
+  return transport === 'usb' ? 90_000 : undefined;
+}
+
 program
   .command('firmware-update-ble')
   .description('Run Protocol V2 firmware update over BLE')
@@ -945,7 +1066,26 @@ async function prepareSession(
     return undefined;
   }
 
-  const device = searchResult.payload[0] as {
+  const device = selectSearchDevice(
+    searchResult.payload as Array<{
+      connectId?: string;
+      deviceId?: string;
+      features?: {
+        deviceId?: string | null;
+        deviceType?: string;
+        sessionId?: string | null;
+        passphraseProtection?: boolean | null;
+        unlocked?: boolean | null;
+      };
+    }>,
+    globalOpts.connectId
+  );
+
+  if (!device) {
+    throw new Error(`未找到指定的 BLE 设备: ${globalOpts.connectId}`);
+  }
+
+  const selectedDevice = device as {
     connectId?: string;
     deviceId?: string;
     features?: {
@@ -956,7 +1096,7 @@ async function prepareSession(
       unlocked?: boolean | null;
     };
   };
-  const connectId = device.connectId || globalOpts.connectId || '';
+  const connectId = selectedDevice.connectId || globalOpts.connectId || '';
   if (!globalOpts.connectId && connectId) {
     globalOpts.connectId = connectId;
   }
@@ -964,10 +1104,10 @@ async function prepareSession(
   // ── Step 2: Get features if searchDevices didn't populate them ──
   // getFeatures failures here are non-fatal — we fall through to Step 3
   // which will fail with a clearer error if the device is truly unreachable.
-  let deviceId = device.features?.deviceId || device.deviceId || '';
-  let deviceType = getDeviceType(device.features as Features | undefined);
-  let unlocked = device.features?.unlocked;
-  let passphraseProtection = device.features?.passphraseProtection;
+  let deviceId = selectedDevice.features?.deviceId || selectedDevice.deviceId || '';
+  let deviceType = getDeviceType(selectedDevice.features as Features | undefined);
+  let unlocked = selectedDevice.features?.unlocked;
+  let passphraseProtection = selectedDevice.features?.passphraseProtection;
 
   if (!deviceId || unlocked == null || passphraseProtection == null) {
     try {
@@ -1162,6 +1302,42 @@ function readBinaryParam(path: string): ArrayBuffer {
   return new Uint8Array(buffer).buffer;
 }
 
+async function resolveLegacyFirmwareConnectId(
+  sdk: AnySdk,
+  explicitConnectId?: string,
+  deviceName?: string
+): Promise<string> {
+  if (explicitConnectId && !deviceName) return explicitConnectId;
+
+  const searchResult = await sdk.searchDevices();
+  if (!searchResult?.success || !Array.isArray(searchResult.payload)) {
+    throw new Error('Unable to scan BLE devices');
+  }
+
+  const devices = searchResult.payload as EnrichedSearchDevice[];
+  const normalizedName = deviceName?.trim().toLowerCase();
+  const matches = normalizedName
+    ? devices.filter(device => device.name?.trim().toLowerCase() === normalizedName)
+    : devices.filter(device => device.deviceType?.toLowerCase() === 'classic');
+
+  if (matches.length === 0) {
+    throw new Error(
+      normalizedName ? `BLE device not found by name: ${deviceName}` : 'No Classic/Pure BLE device found'
+    );
+  }
+  if (matches.length > 1) {
+    throw new Error(
+      normalizedName
+        ? `Multiple BLE devices found by name: ${deviceName}`
+        : 'Multiple Classic/Pure BLE devices found; specify --device-name'
+    );
+  }
+
+  const connectId = matches[0].connectId;
+  if (!connectId) throw new Error(`BLE device has no connect ID: ${matches[0].name}`);
+  return connectId;
+}
+
 function parseResourceBundleParam(spec: string): { binary: ArrayBuffer; devicePath: string } {
   const sep = spec.indexOf(':');
   if (sep <= 0 || sep === spec.length - 1) {
@@ -1234,6 +1410,32 @@ function formatFirmwareBytes(bytes: number) {
   return `${(bytes / 1024).toFixed(1)} KiB`;
 }
 
+export function buildWallpaperUploadMetrics({
+  totalBytes,
+  transferredBytes,
+  startedAt,
+  endedAt,
+  lastProgress,
+}: {
+  totalBytes: number;
+  transferredBytes: number;
+  startedAt: number;
+  endedAt: number;
+  lastProgress: number;
+}) {
+  const elapsedMs = Math.max(endedAt - startedAt, 0);
+  return {
+    totalBytes,
+    transferredBytes,
+    totalSeconds: Number((elapsedMs / 1000).toFixed(2)),
+    transferKiBPerSecond:
+      elapsedMs > 0
+        ? Number((transferredBytes / 1024 / (elapsedMs / 1000)).toFixed(2))
+        : null,
+    lastProgress,
+  };
+}
+
 function maybePrintFirmwareProgress({
   progressType,
   progress,

package/src/deviceSelection.ts

@@ -0,0 +1,13 @@
+export function selectSearchDevice<T extends { connectId?: string }>(
+  devices: T[],
+  preferredConnectId?: string
+): T | undefined {
+  if (preferredConnectId) {
+    return (
+      devices.find(device => device.connectId === preferredConnectId) ??
+      ({ connectId: preferredConnectId } as T)
+    );
+  }
+
+  return devices[0];
+}

package/src/transports/nobleBlePlugin.ts

@@ -453,7 +453,7 @@ export function createNobleBlePlugin(): LowlevelTransportSharedPlugin {
       await disconnectDevice(uuid);
     },
 
-    async send(uuid: string, data: string) {
+    async send(uuid: string, data: string, options?: { withoutResponse?: boolean }) {
       const characteristics = deviceCharacteristics.get(uuid);
       if (!characteristics) {
         throw ERRORS.TypedError(
@@ -463,9 +463,10 @@ export function createNobleBlePlugin(): LowlevelTransportSharedPlugin {
       }
 
       const buffer = Buffer.from(data, 'hex');
+      const withoutResponse = options?.withoutResponse ?? true;
       for (let offset = 0; offset < buffer.length; offset += BLE_PACKET_SIZE) {
         const chunk = buffer.subarray(offset, Math.min(offset + BLE_PACKET_SIZE, buffer.length));
-        await writeCharacteristic(characteristics.write, chunk, true);
+        await writeCharacteristic(characteristics.write, chunk, withoutResponse);
       }
     },