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

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -1,12 +1,14 @@
 #!/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");
+const hd_shared_1 = require("@onekeyfe/hd-shared");
+const chains_1 = require("./chains");
 const sdk_1 = require("./sdk");
 const session_1 = require("./session");
-const chains_1 = require("./chains");
-const hd_shared_1 = require("@onekeyfe/hd-shared");
-const hd_core_1 = require("@onekeyfe/hd-core");
 function extractPassphraseSession(payload) {
     if (typeof payload === 'string') {
         return { passphraseState: payload };
@@ -32,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')
@@ -41,8 +44,10 @@ program
 // ============================================================
 program.option('--connect-id <id>', 'Device connection ID (USB: serial, iOS: uuid, Android: MAC)');
 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
 // ============================================================
@@ -51,16 +56,16 @@ program
     .description('Search for connected OneKey hardware wallet devices')
     .action(() => 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) {
             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;
                         }
@@ -411,14 +416,40 @@ 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',
+        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')
+    .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')
@@ -592,8 +623,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) {
         await (0, session_1.saveSessionToKeychain)(deviceId, passphraseState, sessionId);
@@ -723,18 +754,18 @@ globalOpts) {
     // ── 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 = (0, hd_core_1.getDeviceType)(device.features);
     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 = (0, hd_core_1.getDeviceType)(featResult.payload) || deviceType;
                 unlocked = featResult.payload.unlocked;
-                passphraseProtection = featResult.payload.passphrase_protection;
+                passphraseProtection = featResult.payload.passphraseProtection;
             }
         }
         catch {
@@ -750,9 +781,9 @@ globalOpts) {
     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) {
         globalOpts.deviceId = deviceId;
@@ -793,7 +824,7 @@ globalOpts) {
                 passphraseState,
                 skipPassphraseCheck: true,
             });
-            const sessionId = passphraseSessionId || (featAfter?.success ? featAfter.payload?.session_id : undefined);
+            const sessionId = passphraseSessionId || (featAfter?.success ? featAfter.payload?.sessionId : undefined);
             if (sessionId) {
                 await (0, session_1.saveSessionToKeychain)(deviceId, passphraseState, sessionId);
                 await (0, session_1.preloadSessionFromKeychain)(deviceId);
@@ -818,6 +849,9 @@ function outputResult(_globalOpts, result) {
 async function runCommand(options, handler) {
     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 (0, sdk_1.createSDK)(globalOpts);
         if (options.needsSession) {
             await prepareSession(sdk, globalOpts);
@@ -866,6 +900,275 @@ function safeJsonParse(input, label) {
         throw err;
     }
 }
+function readBinaryParam(path) {
+    const buffer = (0, node_fs_1.readFileSync)(path);
+    return new Uint8Array(buffer).buffer;
+}
+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.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) {
+    if (!result || typeof result !== 'object')
+        return '';
+    const { payload } = result;
+    if (!payload || typeof payload !== 'object')
+        return '';
+    const { error } = payload;
+    return typeof error === 'string' ? error : '';
+}
+function isProtocolV2UsbProbeTransientResult(result) {
+    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) {
+    return (!!result && typeof result === 'object' && result.success === true);
+}
+function getFirmwareUpdatePayload(message) {
+    if (!message || typeof message !== 'object')
+        return undefined;
+    return message.payload;
+}
+function formatFirmwareProgress(progress) {
+    if (!Number.isFinite(progress))
+        return '0%';
+    return `${Math.min(Math.max(Math.round(progress), 0), 100)}%`;
+}
+function formatFirmwareBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return '';
+    return `${(bytes / 1024).toFixed(1)} KiB`;
+}
+function maybePrintFirmwareProgress({ progressType, progress, payload, lastPrintedProgress, }) {
+    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, }) {
+    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, }) {
+    const totalBytes = getFirmwareUpdateV4TotalBytes(params);
+    const maxAttempts = Math.max((retries ?? 2) + 1, 1);
+    let currentSdk = sdk;
+    let lastResult;
+    let retried = false;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        let progressEvents = 0;
+        let lastProgress = -1;
+        let transferStartedAt;
+        let transferEndedAt;
+        let installProgressEvents = 0;
+        let lastInstallProgress = -1;
+        let installStartedAt;
+        let installEndedAt;
+        let lastPrintedTransferProgress = -10;
+        let lastPrintedInstallProgress = -10;
+        const totalStartedAt = Date.now();
+        const connectId = retried && globalOpts.transport === 'usb' && globalOpts.connectId
+            ? undefined
+            : globalOpts.connectId;
+        const onUiEvent = (message) => {
+            if (!message || typeof message !== 'object')
+                return;
+            const messageType = message.type;
+            const payload = getFirmwareUpdatePayload(message);
+            if (messageType === hd_core_1.UI_REQUEST.FIRMWARE_TIP) {
+                const tipMessage = payload?.data?.message;
+                if (typeof tipMessage === 'string') {
+                    process.stderr.write(`[onekey-hw] Firmware: ${tipMessage}\n`);
+                }
+                return;
+            }
+            if (messageType === hd_core_1.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 !== hd_core_1.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 ?? (transferStartedAt = Date.now());
+                lastPrintedTransferProgress = maybePrintFirmwareProgress({
+                    progressType: 'transfer',
+                    progress,
+                    payload,
+                    lastPrintedProgress: lastPrintedTransferProgress,
+                });
+                if (progress >= 100) {
+                    transferEndedAt ?? (transferEndedAt = Date.now());
+                }
+                return;
+            }
+            if (payload.progressType === 'installingFirmware') {
+                installProgressEvents += 1;
+                lastInstallProgress = Math.max(lastInstallProgress, progress);
+                installStartedAt ?? (installStartedAt = Date.now());
+                lastPrintedInstallProgress = maybePrintFirmwareProgress({
+                    progressType: 'install',
+                    progress,
+                    payload,
+                    lastPrintedProgress: lastPrintedInstallProgress,
+                });
+                if (progress >= 100) {
+                    installEndedAt ?? (installEndedAt = Date.now());
+                }
+            }
+        };
+        currentSdk.on(hd_core_1.UI_EVENT, onUiEvent);
+        try {
+            lastResult = await currentSdk.firmwareUpdateV4(connectId, params);
+        }
+        finally {
+            currentSdk.off?.(hd_core_1.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.payload ?? {});
+            lastResult = {
+                ...lastResult,
+                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 (0, sdk_1.disposeSDK)();
+        await new Promise(resolve => {
+            setTimeout(resolve, 3000);
+        });
+        currentSdk = await (0, sdk_1.createSDK)(globalOpts);
+    }
+    return lastResult;
+}
+function buildFirmwareUpdateV4Params(opts) {
+    const params = {
+        platform: 'desktop',
+        connectProtocol: 'V2',
+        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.code = 'MISSING_FIRMWARE_BINARY';
+        throw err;
+    }
+    return params;
+}
 /**
  * #9 FIX: Safe parseInt with NaN check
  */
@@ -876,4 +1179,6 @@ function safeParseInt(input, label) {
     }
     return num;
 }
-program.parse();
+if (require.main === module) {
+    program.parse();
+}

package/dist/sdk.d.ts

@@ -13,6 +13,8 @@ export interface SDKOptions {
     connectId?: string;
     passphraseState?: string;
     useEmptyPassphrase?: boolean;
+    debug?: boolean;
+    transport?: 'usb' | 'ble';
 }
 export declare function createSDK(opts: SDKOptions): Promise<typeof HardwareSDK>;
 /**

package/dist/sdk.js

@@ -41,6 +41,7 @@ const readline = __importStar(require("node:readline"));
 const hd_common_connect_sdk_1 = __importDefault(require("@onekeyfe/hd-common-connect-sdk"));
 const hd_core_1 = require("@onekeyfe/hd-core");
 const pinentry_1 = require("./pinentry");
+const nobleBlePlugin_1 = require("./transports/nobleBlePlugin");
 /**
  * Current per-invocation CLI options. Event handlers read from this object
  * so that invoking createSDK() with different opts never results in stale
@@ -182,12 +183,13 @@ function registerEventHandlers(sdk) {
 // SDK Factory
 // ---------------------------------------------------------------------------
 async function initSDK() {
+    const transport = currentOpts.transport ?? 'usb';
     const settings = {
-        debug: false,
+        debug: currentOpts.debug ?? false,
         fetchConfig: true,
-        env: 'node-usb',
+        env: transport === 'ble' ? 'lowlevel' : 'node-usb',
     };
-    await hd_common_connect_sdk_1.default.init(settings);
+    await hd_common_connect_sdk_1.default.init(settings, undefined, transport === 'ble' ? (0, nobleBlePlugin_1.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.
     // Mirrors app-monorepo's cleanupHardwareSDKInstance() which removes

package/dist/transports/nobleBlePlugin.d.ts

@@ -0,0 +1,2 @@
+import type { LowlevelTransportSharedPlugin } from '@onekeyfe/hd-transport';
+export declare function createNobleBlePlugin(): LowlevelTransportSharedPlugin;