Firmware Update

Pick the update API from the protocol family, not from the marketing name alone. Hardware SDK 1.2.0 keeps one JavaScript surface; the device protocol decides which method is valid.

Confirm the live protocol with connectProtocol on the device object or via getDeviceState. Do not branch on USB PID or BLE name. See Devices and Protocol V1 and V2.

Only start an update after the user has selected the target device and approved the operation. Use official release metadata and verified artifacts for that model; an example version must never determine the firmware to install.

1. Check whether an update is needed

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 coprocessor: checkBLEFirmwareRelease. Subscribe to FIRMWARE_EVENT (RELEASE_INFO / BLE_RELEASE_INFO) if you want to prompt later instead of blocking the first connection.

2. Subscribe to progress before you call update

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 may emit REQUEST_BUTTON with reason 'firmware-update'.
  // Show "confirm on device". Do not uiResponse() that hint.
});

3. Call the matching method

Classic / Mini / Touch. Select the target from verified release metadata for the connected model:

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 — pass binaries you already verified:

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

platform is required on all three methods: 'native' | 'desktop' | 'ext' | 'web' | 'web-embed'.

4. After the call

1. The device may reboot. Wait for DEVICE.CONNECT (or search again). Ordinary reconnect keeps the confirmed protocol. See Disconnects and reconnection.
2. Re-read getDeviceState (scope: 'firmware' if you need versions) before trusting the new build.
3. If the call failed with a transport timeout after the install request was sent, do not replay the same update. Reconnect, read status, then decide.

Do not

• Call firmwareUpdateV3 on Pro 2 / Neo, or firmwareUpdateV4 on Classic / Pro.
• Automatically retry an update after disconnect or timeout.
• Spread BLE retryCount helpers onto update calls.
• Install romloader through firmwareUpdateV4.

Next

• firmwareUpdateV2
• firmwareUpdateV3
• firmwareUpdateV4
• Core API Guide → events