@onekeyfe/hardware-cli 1.2.0-alpha.0 → 1.2.0-alpha.10

package/src/cli.ts

@@ -1,11 +1,8 @@
+import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
+import { UI_EVENT, UI_REQUEST, getDeviceType } from '@onekeyfe/hd-core';
+import { EDeviceType } from '@onekeyfe/hd-shared';
 
-import { createSDK, disposeSDK } from './sdk';
-import {
-  clearSessionFromKeychain,
-  preloadSessionFromKeychain,
-  saveSessionToKeychain,
-} from './session';
 import {
   resolveBatchGetAddress,
   resolveGetAddress,
@@ -13,9 +10,13 @@ import {
   resolveSignMessage,
   resolveSignTransaction,
 } from './chains';
+import { createSDK, disposeSDK } from './sdk';
+import {
+  clearSessionFromKeychain,
+  preloadSessionFromKeychain,
+  saveSessionToKeychain,
+} from './session';
 
-import { EDeviceType } from '@onekeyfe/hd-shared';
-import { getDeviceType } from '@onekeyfe/hd-core';
 import type {
   EthereumSignTypedDataMessage,
   EthereumSignTypedDataTypes,
@@ -78,8 +79,10 @@ program.option(
   '--device-id <id>',
   'Persistent device ID from getFeatures (changes when seed changes)'
 );
+program.option('--transport <transport>', 'Transport to use: usb or ble', 'usb');
 program.option('--passphrase-state <state>', 'Passphrase state for hidden wallet access');
 program.option('--use-empty-passphrase', 'Use standard wallet (skip passphrase prompt)');
+program.option('--debug', 'Enable SDK debug logs');
 
 // ============================================================
 // Device Commands
@@ -92,16 +95,16 @@ program
     runCommand({}, async ({ sdk, globalOpts }) => {
       const result = await sdk.searchDevices();
 
-      // Auto-fetch features for each discovered device (doesn't require PIN)
-      if (result?.success && Array.isArray(result.payload)) {
+      // USB 下自动读取 features 成本低；BLE 搜索阶段只做枚举，避免批量连接导致超时。
+      if (globalOpts.transport !== 'ble' && result?.success && Array.isArray(result.payload)) {
         for (const device of result.payload as EnrichedSearchDevice[]) {
           if (device.connectId) {
             try {
               const features = await sdk.getFeatures(device.connectId);
               if (features?.success && features.payload) {
                 device.features = features.payload;
-                device.name = features.payload.label || features.payload.ble_name || device.name;
-                const devType = features.payload.onekey_device_type?.toLowerCase();
+                device.name = features.payload.label || features.payload.bleName || device.name;
+                const devType = features.payload.deviceType?.toLowerCase();
                 if (devType) {
                   device.deviceType = devType as IDeviceType;
                 }
@@ -540,18 +543,50 @@ program
 
 program
   .command('firmware-update-ble')
-  .description('BLE firmware update is not supported via CLI')
+  .description('Run Protocol V2 firmware update over BLE')
   .action(() =>
     respondAndExit({
       success: false,
       payload: {
         error:
-          'BLE firmware update via CLI is not supported. Please use the OneKey App or https://firmware.onekey.so/ to update firmware.',
-        code: 'FIRMWARE_UPDATE_NOT_SUPPORTED',
+          'Use `onekey-hw --transport ble firmware-update-v4` for BLE Protocol V2 firmware updates.',
+        code: 'USE_FIRMWARE_UPDATE_V4',
       },
     })
   );
 
+program
+  .command('firmware-update-v4')
+  .description('Run Protocol V2 firmware update through sdk.firmwareUpdateV4')
+  .option('--chunk-size <bytes>', 'Transfer chunk size in bytes')
+  .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')
+  .option('--application-p2 <path>', 'FW_MGMT_TARGET_APPLICATION_P2 binary path')
+  .option('--coprocessor <path>', 'FW_MGMT_TARGET_COPROCESSOR binary path')
+  .option('--se01 <path>', 'FW_MGMT_TARGET_SE01 binary path')
+  .option('--se02 <path>', 'FW_MGMT_TARGET_SE02 binary path')
+  .option('--se03 <path>', 'FW_MGMT_TARGET_SE03 binary path')
+  .option('--se04 <path>', 'FW_MGMT_TARGET_SE04 binary path')
+  .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 = buildFirmwareUpdateV4Params(opts);
+      const result = await runFirmwareUpdateV4WithRetry({
+        sdk,
+        globalOpts,
+        params,
+        retries: opts.retries ? safeParseInt(opts.retries, '--retries') : undefined,
+      });
+      outputResult(globalOpts, result);
+    })
+  );
+
 program
   .command('bootloader-check')
   .description('Check bootloader version and status')
@@ -757,8 +792,8 @@ sessionCmd
         skipPassphraseCheck: true,
       });
       const featPayload = featResult?.success ? featResult.payload : undefined;
-      const deviceId = featPayload?.device_id || device.deviceId || '';
-      const sessionId = passphraseSessionId || featPayload?.session_id || '';
+      const deviceId = featPayload?.deviceId || device.deviceId || '';
+      const sessionId = passphraseSessionId || featPayload?.sessionId || '';
 
       // 6. Save to keychain
       if (passphraseState && deviceId && sessionId) {
@@ -914,10 +949,10 @@ async function prepareSession(
     connectId?: string;
     deviceId?: string;
     features?: {
-      device_id?: string;
-      onekey_device_type?: string;
-      session_id?: string;
-      passphrase_protection?: boolean | null;
+      deviceId?: string | null;
+      deviceType?: string;
+      sessionId?: string | null;
+      passphraseProtection?: boolean | null;
       unlocked?: boolean | null;
     };
   };
@@ -929,19 +964,19 @@ 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?.device_id || device.deviceId || '';
+  let deviceId = device.features?.deviceId || device.deviceId || '';
   let deviceType = getDeviceType(device.features as Features | undefined);
   let unlocked = device.features?.unlocked;
-  let passphraseProtection = device.features?.passphrase_protection;
+  let passphraseProtection = device.features?.passphraseProtection;
 
   if (!deviceId || unlocked == null || passphraseProtection == null) {
     try {
       const featResult = await sdk.getFeatures(connectId);
       if (featResult?.success && featResult.payload) {
-        deviceId = featResult.payload.device_id || deviceId;
+        deviceId = featResult.payload.deviceId || deviceId;
         deviceType = getDeviceType(featResult.payload) || deviceType;
         unlocked = featResult.payload.unlocked;
-        passphraseProtection = featResult.payload.passphrase_protection;
+        passphraseProtection = featResult.payload.passphraseProtection;
       }
     } catch {
       /* non-fatal — Step 3 will surface a clear error if device is gone */
@@ -957,9 +992,9 @@ async function prepareSession(
   if (wasLocked) {
     process.stderr.write('[onekey-hw] Device is locked. Unlocking (PIN required)...\n');
     const { payload: feat } = await unlockWithRetry(sdk, connectId);
-    deviceId = feat.device_id || deviceId;
+    deviceId = feat.deviceId || deviceId;
     unlocked = feat.unlocked;
-    passphraseProtection = feat.passphrase_protection;
+    passphraseProtection = feat.passphraseProtection;
   }
 
   if (!globalOpts.deviceId && deviceId) {
@@ -1009,7 +1044,7 @@ async function prepareSession(
         skipPassphraseCheck: true,
       });
       const sessionId =
-        passphraseSessionId || (featAfter?.success ? featAfter.payload?.session_id : undefined);
+        passphraseSessionId || (featAfter?.success ? featAfter.payload?.sessionId : undefined);
       if (sessionId) {
         await saveSessionToKeychain(deviceId, passphraseState, sessionId);
         await preloadSessionFromKeychain(deviceId);
@@ -1071,6 +1106,9 @@ async function runCommand(
 ): Promise<void> {
   const globalOpts = program.opts();
   try {
+    if (globalOpts.transport !== 'usb' && globalOpts.transport !== 'ble') {
+      throw new Error(`Unsupported transport: ${globalOpts.transport}. Use "usb" or "ble".`);
+    }
     const sdk = await createSDK(globalOpts);
     if (options.needsSession) {
       await prepareSession(sdk, globalOpts);
@@ -1119,6 +1157,389 @@ function safeJsonParse(input: string, label: string): unknown {
   }
 }
 
+function readBinaryParam(path: string): ArrayBuffer {
+  const buffer = readFileSync(path);
+  return new Uint8Array(buffer).buffer;
+}
+
+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.resourceBundleFiles?.map(item => item.binary) ?? []),
+    params.bootloaderBinary,
+    params.applicationP1Binary,
+    params.applicationP2Binary,
+    params.coprocessorBinary,
+    params.se01Binary,
+    params.se02Binary,
+    params.se03Binary,
+    params.se04Binary,
+  ].reduce((total, binary) => total + (binary?.byteLength ?? 0), 0);
+}
+
+function getFirmwareUpdateV4ErrorText(result: unknown) {
+  if (!result || typeof result !== 'object') return '';
+  const { payload } = result as { payload?: unknown };
+  if (!payload || typeof payload !== 'object') return '';
+  const { error } = payload as { error?: unknown };
+  return typeof error === 'string' ? error : '';
+}
+
+function isProtocolV2UsbProbeTransientResult(result: unknown) {
+  const error = getFirmwareUpdateV4ErrorText(result);
+  return (
+    error.includes('Device protocol mismatch') &&
+    error.includes('expected V2') &&
+    error.includes('did not respond to expected protocol')
+  );
+}
+
+function isSuccessResult(result: unknown) {
+  return (
+    !!result && typeof result === 'object' && (result as { success?: boolean }).success === true
+  );
+}
+
+function getFirmwareUpdatePayload(message: unknown) {
+  if (!message || typeof message !== 'object') return undefined;
+  return (message as { payload?: Record<string, unknown> }).payload;
+}
+
+function formatFirmwareProgress(progress: number) {
+  if (!Number.isFinite(progress)) return '0%';
+  return `${Math.min(Math.max(Math.round(progress), 0), 100)}%`;
+}
+
+function formatFirmwareBytes(bytes: number) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '';
+  return `${(bytes / 1024).toFixed(1)} KiB`;
+}
+
+function maybePrintFirmwareProgress({
+  progressType,
+  progress,
+  payload,
+  lastPrintedProgress,
+}: {
+  progressType: string;
+  progress: number;
+  payload: Record<string, unknown>;
+  lastPrintedProgress: number;
+}) {
+  const printableProgress = Math.floor(progress / 10) * 10;
+  if (printableProgress <= lastPrintedProgress && progress < 100) {
+    return lastPrintedProgress;
+  }
+
+  const transferredBytes = Number(payload.transferredBytes);
+  const totalBytes = Number(payload.totalBytes);
+  const rateBytesPerSecond = Number(payload.rateBytesPerSecond);
+  const sizeText =
+    Number.isFinite(transferredBytes) && Number.isFinite(totalBytes) && totalBytes > 0
+      ? ` ${formatFirmwareBytes(transferredBytes)}/${formatFirmwareBytes(totalBytes)}`
+      : '';
+  const speedText =
+    Number.isFinite(rateBytesPerSecond) && rateBytesPerSecond > 0
+      ? ` ${(rateBytesPerSecond / 1024).toFixed(2)} KiB/s`
+      : '';
+
+  process.stderr.write(
+    `[onekey-hw] Firmware ${progressType}: ${formatFirmwareProgress(
+      progress
+    )}${sizeText}${speedText}\n`
+  );
+  return progress >= 100 ? 100 : printableProgress;
+}
+
+function buildFirmwareUpdateV4Metrics({
+  attempt,
+  maxAttempts,
+  totalBytes,
+  totalStartedAt,
+  transferStartedAt,
+  transferEndedAt,
+  installStartedAt,
+  installEndedAt,
+  progressEvents,
+  lastProgress,
+  installProgressEvents,
+  lastInstallProgress,
+  retried,
+}: {
+  attempt: number;
+  maxAttempts: number;
+  totalBytes: number;
+  totalStartedAt: number;
+  transferStartedAt?: number;
+  transferEndedAt?: number;
+  installStartedAt?: number;
+  installEndedAt?: number;
+  progressEvents: number;
+  lastProgress: number;
+  installProgressEvents: number;
+  lastInstallProgress: number;
+  retried: boolean;
+}) {
+  const totalElapsedMs = Date.now() - totalStartedAt;
+  const transferElapsedMs =
+    transferStartedAt !== undefined && transferEndedAt !== undefined
+      ? transferEndedAt - transferStartedAt
+      : undefined;
+  const installElapsedMs =
+    installStartedAt !== undefined && installEndedAt !== undefined
+      ? installEndedAt - installStartedAt
+      : undefined;
+
+  return {
+    attempt,
+    maxAttempts,
+    retried,
+    totalBytes,
+    progressEvents,
+    lastProgress,
+    installProgressEvents,
+    lastInstallProgress,
+    transferSeconds:
+      transferElapsedMs !== undefined ? Number((transferElapsedMs / 1000).toFixed(2)) : null,
+    transferKiBPerSecond:
+      transferElapsedMs !== undefined && transferElapsedMs > 0
+        ? Number((totalBytes / 1024 / (transferElapsedMs / 1000)).toFixed(2))
+        : null,
+    installSeconds:
+      installElapsedMs !== undefined ? Number((installElapsedMs / 1000).toFixed(2)) : null,
+    totalSeconds: Number((totalElapsedMs / 1000).toFixed(2)),
+  };
+}
+
+async function runFirmwareUpdateV4WithRetry({
+  sdk,
+  globalOpts,
+  params,
+  retries,
+}: {
+  sdk: AnySdk;
+  globalOpts: Record<string, any>;
+  params: ReturnType<typeof buildFirmwareUpdateV4Params>;
+  retries?: number;
+}) {
+  const totalBytes = getFirmwareUpdateV4TotalBytes(params);
+  const maxAttempts = Math.max((retries ?? 2) + 1, 1);
+  let currentSdk = sdk;
+  let lastResult: unknown;
+  let retried = false;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    let progressEvents = 0;
+    let lastProgress = -1;
+    let transferStartedAt: number | undefined;
+    let transferEndedAt: number | undefined;
+    let installProgressEvents = 0;
+    let lastInstallProgress = -1;
+    let installStartedAt: number | undefined;
+    let installEndedAt: number | undefined;
+    let lastPrintedTransferProgress = -10;
+    let lastPrintedInstallProgress = -10;
+    const totalStartedAt = Date.now();
+    const connectId =
+      retried && globalOpts.transport === 'usb' && globalOpts.connectId
+        ? undefined
+        : globalOpts.connectId;
+
+    const onUiEvent = (message: unknown) => {
+      if (!message || typeof message !== 'object') return;
+      const messageType = (message as { type?: string }).type;
+      const payload = getFirmwareUpdatePayload(message);
+
+      if (messageType === UI_REQUEST.FIRMWARE_TIP) {
+        const tipMessage = (payload?.data as { message?: unknown } | undefined)?.message;
+        if (typeof tipMessage === 'string') {
+          process.stderr.write(`[onekey-hw] Firmware: ${tipMessage}\n`);
+        }
+        return;
+      }
+
+      if (messageType === UI_REQUEST.REQUEST_BUTTON) {
+        const code = typeof payload?.code === 'string' ? ` (${payload.code})` : '';
+        process.stderr.write(
+          `[onekey-hw] Please confirm the firmware update on your device${code}.\n`
+        );
+        return;
+      }
+
+      if (messageType !== UI_REQUEST.FIRMWARE_PROGRESS || !payload) return;
+      const progress = Number(payload.progress);
+      if (!Number.isFinite(progress)) return;
+
+      if (payload.progressType === 'transferData') {
+        progressEvents += 1;
+        lastProgress = Math.max(lastProgress, progress);
+        transferStartedAt ??= Date.now();
+        lastPrintedTransferProgress = maybePrintFirmwareProgress({
+          progressType: 'transfer',
+          progress,
+          payload,
+          lastPrintedProgress: lastPrintedTransferProgress,
+        });
+        if (progress >= 100) {
+          transferEndedAt ??= Date.now();
+        }
+        return;
+      }
+
+      if (payload.progressType === 'installingFirmware') {
+        installProgressEvents += 1;
+        lastInstallProgress = Math.max(lastInstallProgress, progress);
+        installStartedAt ??= Date.now();
+        lastPrintedInstallProgress = maybePrintFirmwareProgress({
+          progressType: 'install',
+          progress,
+          payload,
+          lastPrintedProgress: lastPrintedInstallProgress,
+        });
+        if (progress >= 100) {
+          installEndedAt ??= Date.now();
+        }
+      }
+    };
+
+    currentSdk.on(UI_EVENT, onUiEvent);
+    try {
+      lastResult = await currentSdk.firmwareUpdateV4(connectId, params);
+    } finally {
+      currentSdk.off?.(UI_EVENT, onUiEvent);
+    }
+    if (installStartedAt !== undefined && installEndedAt === undefined) {
+      installEndedAt = Date.now();
+    }
+
+    const metrics = buildFirmwareUpdateV4Metrics({
+      attempt,
+      maxAttempts,
+      totalBytes,
+      totalStartedAt,
+      transferStartedAt,
+      transferEndedAt,
+      installStartedAt,
+      installEndedAt,
+      progressEvents,
+      lastProgress,
+      installProgressEvents,
+      lastInstallProgress,
+      retried,
+    });
+
+    if (lastResult && typeof lastResult === 'object') {
+      const payload = ((lastResult as { payload?: unknown }).payload ?? {}) as Record<
+        string,
+        unknown
+      >;
+      lastResult = {
+        ...(lastResult as Record<string, unknown>),
+        payload: {
+          ...payload,
+          metrics,
+        },
+      };
+    }
+
+    if (isSuccessResult(lastResult)) {
+      return lastResult;
+    }
+
+    if (
+      attempt >= maxAttempts ||
+      globalOpts.transport !== 'usb' ||
+      !isProtocolV2UsbProbeTransientResult(lastResult)
+    ) {
+      return lastResult;
+    }
+
+    retried = true;
+    process.stderr.write(
+      `[onekey-hw] Protocol V2 USB probe was transient; retrying firmwareUpdateV4 (${attempt}/${maxAttempts})...\n`
+    );
+    await disposeSDK();
+    await new Promise(resolve => {
+      setTimeout(resolve, 3000);
+    });
+    currentSdk = await createSDK(globalOpts);
+  }
+
+  return lastResult;
+}
+
+function buildFirmwareUpdateV4Params(opts: {
+  chunkSize?: string;
+  resourceBundle?: string[];
+  romloader?: string;
+  bootloader?: string;
+  applicationP1?: string;
+  applicationP2?: string;
+  coprocessor?: string;
+  se01?: string;
+  se02?: string;
+  se03?: string;
+  se04?: string;
+  forcedUpdateRes?: boolean;
+}) {
+  const params = {
+    platform: 'desktop' as const,
+    connectProtocol: 'V2' as const,
+    chunkSize: opts.chunkSize ? safeParseInt(opts.chunkSize, '--chunk-size') : undefined,
+    forcedUpdateRes: opts.forcedUpdateRes,
+    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,
+    applicationP2Binary: opts.applicationP2 ? readBinaryParam(opts.applicationP2) : undefined,
+    coprocessorBinary: opts.coprocessor ? readBinaryParam(opts.coprocessor) : undefined,
+    se01Binary: opts.se01 ? readBinaryParam(opts.se01) : undefined,
+    se02Binary: opts.se02 ? readBinaryParam(opts.se02) : undefined,
+    se03Binary: opts.se03 ? readBinaryParam(opts.se03) : undefined,
+    se04Binary: opts.se04 ? readBinaryParam(opts.se04) : undefined,
+  };
+
+  const hasPayload = [
+    params.resourceBundleFiles,
+    params.romloaderBinary,
+    params.bootloaderBinary,
+    params.applicationP1Binary,
+    params.applicationP2Binary,
+    params.coprocessorBinary,
+    params.se01Binary,
+    params.se02Binary,
+    params.se03Binary,
+    params.se04Binary,
+  ].some(Boolean);
+
+  if (!hasPayload) {
+    const err = new Error('firmware-update-v4 requires at least one binary path');
+    (err as Error & { code?: string }).code = 'MISSING_FIRMWARE_BINARY';
+    throw err;
+  }
+
+  return params;
+}
+
 /**
  * #9 FIX: Safe parseInt with NaN check
  */
@@ -1130,4 +1551,8 @@ function safeParseInt(input: string, label: string): number {
   return num;
 }
 
-program.parse();
+export { program };
+
+if (require.main === module) {
+  program.parse();
+}

package/src/sdk.ts

@@ -14,6 +14,7 @@ import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 import { DEVICE, UI_EVENT, UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hd-core';
 
 import { promptPassphraseViaPinentry } from './pinentry';
+import { createNobleBlePlugin } from './transports/nobleBlePlugin';
 
 import type { ConnectSettings } from '@onekeyfe/hd-core';
 import type { PinentryResult } from './pinentry';
@@ -22,6 +23,8 @@ export interface SDKOptions {
   connectId?: string;
   passphraseState?: string;
   useEmptyPassphrase?: boolean;
+  debug?: boolean;
+  transport?: 'usb' | 'ble';
 }
 
 /**
@@ -182,12 +185,17 @@ function registerEventHandlers(sdk: typeof HardwareSDK): void {
 // ---------------------------------------------------------------------------
 
 async function initSDK(): Promise<typeof HardwareSDK> {
+  const transport = currentOpts.transport ?? 'usb';
   const settings: Partial<ConnectSettings> = {
-    debug: false,
+    debug: currentOpts.debug ?? false,
     fetchConfig: true,
-    env: 'node-usb',
+    env: transport === 'ble' ? 'lowlevel' : 'node-usb',
   };
-  await HardwareSDK.init(settings);
+  await HardwareSDK.init(
+    settings,
+    undefined,
+    transport === 'ble' ? createNobleBlePlugin() : undefined
+  );
 
   // Defensive: strip any stale listeners (e.g. left over from a previous
   // dispose/init cycle in a long-running process) before wiring ours.