本页目录

固件升级

按协议族选升级 API，不要只看产品名。Hardware SDK 1.2.0 仍是同一套 JavaScript 接口，设备协议决定哪一个方法合法。

当前机型	协议	方法	升级内容
Classic、Mini、Touch	V1	`firmwareUpdateV2`	主固件和/或 BLE
OneKey Pro	V1	`firmwareUpdateV3`	一次流程里 Bootloader + 主固件 + BLE + 资源
OneKey Pro 2、Neo	V2	`firmwareUpdateV4`	Bootloader、应用分区、协处理器、资源 ZIP

用设备对象上的 connectProtocol，或 getDeviceState 确认实时协议。不要用 USB PID 或蓝牙名分支。见设备和 Protocol V1 与 V2。

只有用户选择目标设备并批准操作后，才开始升级。使用该机型的官方发布元数据和已验证文件，不能让文档中的示例版本决定实际安装目标。

1. 先检查要不要升级


const release = await HardwareSDK.checkFirmwareRelease(connectId);
if (!release.success) throw new Error(release.payload.error);
 
// payload.status: 'valid' | 'outdated' | 'required' | 'unknown' | 'none'
const updateAvailable = release.payload !== null &&
  (release.payload.status === 'outdated' || release.payload.status === 'required');
// Offer an update only when updateAvailable is true and release metadata exists.

BLE 协处理器用 checkBLEFirmwareRelease。如果想连上以后再提示，订阅 FIRMWARE_EVENT（RELEASE_INFO / BLE_RELEASE_INFO）。

2. 调用升级前先订进度


import { UI_EVENT, UI_REQUEST } from '@onekeyfe/hd-core';
 
HardwareSDK.on(UI_EVENT, (msg) => {
  if (
    msg.type === UI_REQUEST.FIRMWARE_PROGRESS ||
    msg.type === UI_REQUEST.FIRMWARE_TIP ||
    msg.type === UI_REQUEST.FIRMWARE_PROCESSING
  ) {
    renderFirmwareProgress(msg.payload);
  }
  // firmwareUpdateV4 可能发出 REQUEST_BUTTON，reason 为 'firmware-update'。
  // 展示「请在设备确认」。不要对这个提示调用 uiResponse()。
});

3. 调用对应方法

Classic / Mini / Touch：从所连接机型的已验证发布元数据中选择目标版本。


declare const targetFirmwareVersion: number[];
const result = await HardwareSDK.firmwareUpdateV2(connectId, {
  platform: 'web',
  updateType: 'firmware',
  version: targetFirmwareVersion,
});
if (!result.success) throw new Error(result.payload.error);

Pro：


declare const targetFirmwareVersion: number[];
const result = await HardwareSDK.firmwareUpdateV3(connectId, {
  platform: 'desktop',
  firmwareVersion: targetFirmwareVersion,
});
if (!result.success) throw new Error(result.payload.error);

Pro 2 / Neo —— 传入你已经校验过的二进制：


const result = await HardwareSDK.firmwareUpdateV4(connectId, {
  platform: 'desktop',
  bootloaderBinary,
  applicationP1Binary,
  applicationP2Binary,
  coprocessorBinary,
  resourceArchiveBinary,
});
if (!result.success) throw new Error(result.payload.error);

三个方法都要传 platform：'native' | 'desktop' | 'ext' | 'web' | 'web-embed'。

4. 调用之后

设备可能重启。等 DEVICE.CONNECT（或重新 search）。普通重连会保持已确认的协议。见断线与重连。
相信新版本之前，重新读 getDeviceState（需要版本时用 scope: 'firmware'）。
如果是安装请求发出之后的传输超时，不要重放同一次升级。先重连、读状态，再决定。

不要做的事

在 Pro 2 / Neo 上调 firmwareUpdateV3，或在 Classic / Pro 上调 firmwareUpdateV4。
断开或超时后自动重试升级。
把 BLE 的 retryCount 助手铺到升级调用上。
用 firmwareUpdateV4 安装 romloader。