@ukeyfe/hardware-core 1.1.13

package/src/api/FirmwareUpdateV3.ts

@@ -0,0 +1,437 @@
+import { Deferred, ERRORS, HardwareErrorCode, EDeviceType, wait } from '@ukeyfe/hardware-shared';
+import semver from 'semver';
+import JSZip from 'jszip';
+import { UI_REQUEST, FirmwareUpdateTipMessage } from '../events/ui-request';
+import { validateParams } from './helpers/paramsValidator';
+
+import {
+  getDeviceType,
+  getDeviceBootloaderVersion,
+  getDeviceBLEFirmwareVersion,
+  getDeviceFirmwareVersion,
+  LoggerNames,
+  getLogger,
+} from '../utils';
+import { getBinary, getSysResourceBinary } from './firmware/getBinary';
+import { DataManager } from '../data-manager';
+import { FirmwareUpdateV3Params } from '../types/api/firmwareUpdate';
+import { FirmwareUpdateBaseMethod } from './firmware/FirmwareUpdateBaseMethod';
+import { DevicePool } from '../device/DevicePool';
+import { TypedResponseMessage } from '../device/DeviceCommands';
+
+const Log = getLogger(LoggerNames.Method);
+
+export const MIN_UPDATE_V3_BOOTLOADER_VERSION = '2.8.0';
+
+/**
+ * FirmwareUpdateV3 flow
+   1. StartDownloadFirmware
+   2. FinishDownloadFirmware
+   3. AutoRebootToBootloader
+   4. GoToBootloaderSuccess
+   5. StartTransferData
+   6. ConfirmOnDevice
+   7. FirmwareUpdating
+   8. FirmwareUpdateCompleted
+ */
+export default class FirmwareUpdateV3 extends FirmwareUpdateBaseMethod<FirmwareUpdateV3Params> {
+  checkPromise: Deferred<any> | null = null;
+
+  init() {
+    this.allowDeviceMode = [UI_REQUEST.BOOTLOADER, UI_REQUEST.NOT_INITIALIZE];
+    this.requireDeviceMode = [];
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+
+    const { payload } = this;
+
+    validateParams(payload, [
+      { name: 'bleVersion', type: 'array' },
+      { name: 'bleBinary', type: 'buffer' },
+      { name: 'firmwareVersion', type: 'array' },
+      { name: 'firmwareBinary', type: 'buffer' },
+      { name: 'resourceBinary', type: 'buffer' },
+      { name: 'forcedUpdateRes', type: 'boolean' },
+      { name: 'bootloaderVersion', type: 'array' },
+      { name: 'bootloaderBinary', type: 'buffer' },
+      { name: 'platform', type: 'string' },
+    ]);
+
+    this.params = {
+      bleBinary: payload.bleBinary,
+      firmwareBinary: payload.firmwareBinary,
+      forcedUpdateRes: payload.forcedUpdateRes,
+      bleVersion: payload.bleVersion,
+      bootloaderVersion: payload.bootloaderVersion,
+      bootloaderBinary: payload.bootloaderBinary,
+      firmwareVersion: payload.firmwareVersion,
+      resourceBinary: payload.resourceBinary,
+      platform: payload.platform,
+    };
+  }
+
+  async run() {
+    const { device } = this;
+    const { features } = device;
+
+    const deviceType = getDeviceType(features);
+    const bootloaderCurrVersion = getDeviceBootloaderVersion(features).join('.');
+
+    this.validateDeviceAndVersion(deviceType, bootloaderCurrVersion);
+
+    if (!features) {
+      throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Device features not available');
+    }
+
+    let resourceBinary: ArrayBuffer | null = null;
+    let fwBinaryMap: { fileName: string; binary: ArrayBuffer }[] = [];
+    let bootloaderBinary: ArrayBuffer | null = null;
+    try {
+      this.postTipMessage(FirmwareUpdateTipMessage.StartDownloadFirmware);
+      resourceBinary = await this.prepareResourceBinary();
+      fwBinaryMap = await this.prepareFirmwareAndBleBinary();
+      bootloaderBinary = await this.prepareBootloaderBinary();
+      this.postTipMessage(FirmwareUpdateTipMessage.FinishDownloadFirmware);
+    } catch (err) {
+      throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateDownloadFailed, err.message ?? err);
+    }
+
+    if (!bootloaderBinary && fwBinaryMap.length === 0) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.FirmwareUpdateDownloadFailed,
+        'No firmware to update'
+      );
+    }
+
+    await this.enterBootloaderMode();
+
+    const updateResult = await this.executeUpdate({
+      resourceBinary,
+      fwBinaryMap,
+      bootloaderBinary,
+    });
+    return updateResult;
+  }
+
+  private validateDeviceAndVersion(deviceType: EDeviceType, bootloaderVersion: string) {
+    if (deviceType === EDeviceType.Unknown) {
+      throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'unknown device type');
+    }
+
+    if (deviceType !== EDeviceType.Pro) {
+      throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'only pro device is supported');
+    }
+
+    if (semver.lt(bootloaderVersion, MIN_UPDATE_V3_BOOTLOADER_VERSION)) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        'bootloader version needs to be updated'
+      );
+    }
+  }
+
+  private async prepareResourceBinary() {
+    if (this.params.resourceBinary) {
+      return this.params.resourceBinary;
+    }
+    const { features } = this.device;
+    if (!features) return null;
+    const resourceUrl = DataManager.getSysResourcesLatestRelease(
+      features,
+      this.params.forcedUpdateRes
+    );
+
+    if (resourceUrl) {
+      const resource = (await getSysResourceBinary(resourceUrl)).binary;
+      return resource;
+    }
+    Log.warn('No resource url found');
+    return null;
+  }
+
+  private async prepareBootloaderBinary(): Promise<ArrayBuffer | null> {
+    if (this.params.bootloaderBinary) {
+      return this.params.bootloaderBinary;
+    }
+    const { features } = this.device;
+    if (!features) return null;
+
+    if (this.params.bootloaderVersion) {
+      const bootResourceUrl = DataManager.getBootloaderResource(features);
+      if (bootResourceUrl) {
+        const bootBinary = (await getSysResourceBinary(bootResourceUrl)).binary;
+        return bootBinary;
+      }
+    }
+    return null;
+  }
+
+  private async prepareFirmwareAndBleBinary() {
+    const fwBinaryMap: { fileName: string; binary: ArrayBuffer }[] = [];
+    if (this.params.firmwareBinary) {
+      fwBinaryMap.push({
+        fileName: 'firmware.bin',
+        binary: this.params.firmwareBinary,
+      });
+    } else if (this.params.firmwareVersion) {
+      const { features } = this.device;
+      if (features) {
+        const firmwareBinary = (
+          await getBinary({
+            features,
+            version: this.params.firmwareVersion,
+            updateType: 'firmware',
+            isUpdateBootloader: false,
+          })
+        ).binary;
+        fwBinaryMap.push({
+          fileName: 'firmware.bin',
+          binary: firmwareBinary,
+        });
+      }
+    }
+
+    if (this.params.bleBinary) {
+      fwBinaryMap.push({
+        fileName: 'ble-firmware.bin',
+        binary: this.params.bleBinary,
+      });
+    } else if (this.params.bleVersion) {
+      const { features } = this.device;
+      if (features) {
+        const bleBinary = await getBinary({
+          features,
+          version: this.params.bleVersion,
+          updateType: 'ble',
+        });
+        fwBinaryMap.push({
+          fileName: 'ble-firmware.bin',
+          binary: bleBinary.binary,
+        });
+      }
+    }
+    return fwBinaryMap;
+  }
+
+  private async executeUpdate({
+    resourceBinary,
+    fwBinaryMap,
+    bootloaderBinary,
+  }: {
+    resourceBinary: ArrayBuffer | null;
+    fwBinaryMap: { fileName: string; binary: ArrayBuffer }[];
+    bootloaderBinary: ArrayBuffer | null;
+  }) {
+    let totalSize = 0;
+    let processedSize = 0;
+
+    if (resourceBinary) {
+      totalSize += resourceBinary.byteLength;
+    }
+    for (const fwbinary of fwBinaryMap) {
+      totalSize += fwbinary.binary.byteLength;
+    }
+    if (bootloaderBinary) {
+      totalSize += bootloaderBinary.byteLength;
+    }
+
+    this.postTipMessage(FirmwareUpdateTipMessage.StartTransferData);
+    // 处理资源文件
+    if (resourceBinary) {
+      const file = await JSZip.loadAsync(resourceBinary);
+      const files = Object.entries(file.files);
+      for (const [fileName, file] of files) {
+        const name = fileName.split('/').pop();
+        if (!file.dir && fileName.indexOf('__MACOSX') === -1 && name) {
+          const data = await file.async('arraybuffer');
+          processedSize = await this.emmcCommonUpdateProcess({
+            payload: data,
+            filePath: `0:res/${name}`,
+            processedSize,
+            totalSize,
+          });
+        }
+      }
+    }
+
+    if (bootloaderBinary) {
+      processedSize = await this.emmcCommonUpdateProcess({
+        payload: bootloaderBinary,
+        filePath: `0:boot/bootloader.bin`,
+        processedSize,
+        totalSize,
+      });
+    }
+
+    await this.createUpdatesFolderIfNotExists(`0:updates/`);
+
+    for (const fwbinary of fwBinaryMap) {
+      if (fwbinary) {
+        processedSize = await this.emmcCommonUpdateProcess({
+          payload: fwbinary.binary,
+          filePath: `0:updates/${fwbinary.fileName}`,
+          processedSize,
+          totalSize,
+        });
+      }
+    }
+
+    // trigger firmware update, support folder updates
+    try {
+      this.postTipMessage(FirmwareUpdateTipMessage.ConfirmOnDevice);
+      await this.startEmmcFirmwareUpdate({
+        path: '0:updates',
+      });
+    } catch (error) {
+      Log.error('triggerFirmwareUpdateEmmc error: ', error);
+      // Re-throw errors with specific error codes that should not be ignored
+      if (error?.errorCode) {
+        const unexpectedError = [
+          HardwareErrorCode.ActionCancelled,
+          HardwareErrorCode.FirmwareVerificationFailed,
+          // BLE connection errors
+          HardwareErrorCode.BleDeviceNotBonded,
+          HardwareErrorCode.BleServiceNotFound,
+          HardwareErrorCode.BlePoweredOff,
+          HardwareErrorCode.BleUnsupported,
+          HardwareErrorCode.BlePermissionError,
+          HardwareErrorCode.BleLocationError,
+          HardwareErrorCode.BleDeviceBondError,
+          HardwareErrorCode.BleCharacteristicNotifyError,
+          HardwareErrorCode.BleTimeoutError,
+          HardwareErrorCode.BleWriteCharacteristicError,
+          // Web device errors
+          HardwareErrorCode.WebDeviceNotFoundOrNeedsPermission,
+        ];
+
+        if (unexpectedError.includes(error.errorCode)) {
+          throw error;
+        }
+      }
+
+      // Wrap and re-throw all other errors
+      throw ERRORS.TypedError(
+        HardwareErrorCode.FirmwareError,
+        error?.message || 'Firmware update failed'
+      );
+    }
+
+    // wait for 1.5s to ensure the device is in update mode
+    await wait(1500);
+    this.postProcessingMessage('firmware');
+    this.postProgressMessage(0, 'installingFirmware');
+    // Add timeout of 5 minutes
+    const installStartTime = Date.now();
+    const maxWaitTimeForInstallingFirmware = 5 * 60 * 1000; // 5 minutes in milliseconds
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      // Check if timeout exceeded
+      if (Date.now() - installStartTime > maxWaitTimeForInstallingFirmware) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          'Firmware update process timeout after 5 minutes'
+        );
+      }
+
+      try {
+        const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
+        const featuresRes = await Promise.race<TypedResponseMessage<'Features'>>([
+          typedCall('GetFeatures', 'Features', {}),
+          new Promise<never>((_, reject) => {
+            setTimeout(() => reject(new Error('GetFeatures timeout after 3 seconds')), 3000);
+          }),
+        ]);
+        const features = featuresRes.message;
+        const bootloaderVersion = getDeviceBootloaderVersion(features).join('.');
+        const bleVersion = getDeviceBLEFirmwareVersion(features).join('.');
+        const firmwareVersion = getDeviceFirmwareVersion(features).join('.');
+        this.postTipMessage(FirmwareUpdateTipMessage.FirmwareUpdateCompleted);
+        DevicePool.resetState();
+        return {
+          bootloaderVersion,
+          bleVersion,
+          firmwareVersion,
+        };
+      } catch (error) {
+        if (error.message && error.message.includes('Update mode')) {
+          const updateParts = error.message.split('Update mode ');
+          const progressValue = updateParts[1] ?? '0';
+          const progress = parseInt(progressValue, 10) || 0;
+          this.postProgressMessage(progress, 'installingFirmware');
+          await wait(1000);
+        } else {
+          await wait(1000);
+          /**
+           * Needs second reconnect case:
+           * 1. While including 'Ble firmwware' in ble connect type
+           * 2. While including bootloader upgrade
+           */
+          const reconnectTimeout =
+            this.isBleReconnect() && (this.params.bleBinary || this.params.bleVersion)
+              ? 3 * 60 * 1000 // 3 minutes for BLE reconnect
+              : 60 * 1000; // 1 minute for normal reconnect
+
+          await this.waitForDeviceReconnect(reconnectTimeout);
+        }
+      }
+    }
+  }
+
+  /**
+   * @description Reconnect device - While update with bootloader, it will reconnect device
+   * @param {number} timeout - The timeout for the reconnection
+   */
+  async waitForDeviceReconnect(timeout: number) {
+    const startTime = Date.now();
+    const isBleReconnect = this.isBleReconnect();
+    while (Date.now() - startTime < timeout) {
+      try {
+        if (isBleReconnect) {
+          try {
+            await this.device.deviceConnector?.acquire(
+              this.device.originalDescriptor.id,
+              null,
+              true
+            );
+            const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
+            await Promise.race([
+              typedCall('Initialize', 'Features', {}),
+              new Promise((_, reject) => {
+                setTimeout(() => {
+                  reject(ERRORS.TypedError(HardwareErrorCode.DeviceInitializeFailed));
+                }, 3000);
+              }),
+            ]);
+            return;
+          } catch (e) {
+            // ignore error because of device is not connected
+            Log.log('catch Bluetooth error when device is restarting: ', e);
+          }
+        } else {
+          const deviceDiff = await this.device.deviceConnector?.enumerate();
+          const devicesDescriptor = deviceDiff?.descriptors ?? [];
+          const { deviceList } = await DevicePool.getDevices(devicesDescriptor, this.connectId);
+
+          if (deviceList.length === 1) {
+            this.device.updateFromCache(deviceList[0]);
+            await this.device.acquire();
+            this.device.commands.disposed = false;
+            this.device.getCommands().mainId = this.device.mainId ?? '';
+            return;
+          }
+        }
+        await wait(1000);
+      } catch (error) {
+        console.error('Device reconnect failed: ', error);
+        Log.error('Device reconnect failed:', error);
+        await wait(1000);
+      }
+    }
+
+    throw ERRORS.TypedError(
+      HardwareErrorCode.DeviceNotFound,
+      `Device not reconnected within ${timeout / 1000}s`
+    );
+  }
+}

package/src/api/GetFeatures.ts

@@ -0,0 +1,22 @@
+import { ERRORS, HardwareErrorCode } from '@ukeyfe/hardware-shared';
+import { UI_REQUEST } from '../constants/ui-request';
+import { BaseMethod } from './BaseMethod';
+
+export default class GetFeatures extends BaseMethod {
+  init() {
+    this.allowDeviceMode = [
+      ...this.allowDeviceMode,
+      UI_REQUEST.NOT_INITIALIZE,
+      UI_REQUEST.BOOTLOADER,
+    ];
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+  }
+
+  run() {
+    if (this.payload?.detectBootloaderDevice && this.device.features?.bootloader_mode) {
+      return Promise.reject(ERRORS.TypedError(HardwareErrorCode.DeviceDetectInBootloaderMode));
+    }
+    return Promise.resolve(this.device.features);
+  }
+}

package/src/api/GetLogs.ts

@@ -0,0 +1,40 @@
+import { BaseMethod } from './BaseMethod';
+import { getLog } from '../utils';
+
+export default class GetLogs extends BaseMethod {
+  init() {
+    this.useDevice = false;
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+  }
+
+  serializeLog({
+    level,
+    prefix,
+    message,
+    timestamp,
+  }: {
+    level: string;
+    prefix: string;
+    message: any[];
+    timestamp: number;
+  }) {
+    const date = new Date(timestamp).toISOString();
+
+    const messageString = message
+      .map(item => {
+        if (typeof item === 'object') {
+          return JSON.stringify(item);
+        }
+        return String(item);
+      })
+      .join(' ');
+
+    return `[${date}] ${level.toUpperCase()} ${prefix}: ${messageString}`;
+  }
+
+  async run() {
+    const logs = getLog().map(log => this.serializeLog(log));
+    return Promise.resolve(logs);
+  }
+}

package/src/api/GetPassphraseState.ts

@@ -0,0 +1,27 @@
+import { ERRORS, HardwareErrorCode } from '@ukeyfe/hardware-shared';
+import { UI_REQUEST } from '../constants/ui-request';
+import { getPassphraseStateWithRefreshDeviceInfo } from '../utils/deviceFeaturesUtils';
+import { BaseMethod } from './BaseMethod';
+
+export default class GetPassphraseState extends BaseMethod {
+  init() {
+    this.allowDeviceMode = [...this.allowDeviceMode, UI_REQUEST.NOT_INITIALIZE];
+    this.useDevicePassphraseState = false;
+  }
+
+  async run() {
+    if (!this.device.features)
+      return Promise.reject(ERRORS.TypedError(HardwareErrorCode.DeviceInitializeFailed));
+
+    const { passphraseState } = await getPassphraseStateWithRefreshDeviceInfo(this.device);
+
+    const { features } = this.device;
+
+    // refresh device info
+    if (features && features.passphrase_protection === true) {
+      return Promise.resolve(passphraseState);
+    }
+
+    return Promise.resolve(undefined);
+  }
+}

package/src/api/GetUkeyFeatures.ts

@@ -0,0 +1,24 @@
+import semver from 'semver';
+import { UI_REQUEST } from '../constants/ui-request';
+import { fixVersion } from '../utils/deviceFeaturesUtils';
+import { BaseMethod } from './BaseMethod';
+
+export default class GetUkeyFeatures extends BaseMethod {
+  init() {
+    this.allowDeviceMode = [
+      ...this.allowDeviceMode,
+      UI_REQUEST.NOT_INITIALIZE,
+      UI_REQUEST.BOOTLOADER,
+    ];
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+  }
+
+  async run() {
+    const { message } = await this.device.commands.typedCall('UkeyGetFeatures', 'UkeyFeatures');
+    if (!!message.ukey_firmware_version && !semver.valid(message.ukey_firmware_version)) {
+      message.ukey_firmware_version = fixVersion(message.ukey_firmware_version);
+    }
+    return Promise.resolve(message);
+  }
+}

package/src/api/PromptWebDeviceAccess.ts

@@ -0,0 +1,75 @@
+import { ERRORS, HardwareErrorCode } from '@ukeyfe/hardware-shared';
+import { UKeyDeviceInfo } from '@ukeyfe/hardware-transport';
+import { BaseMethod } from './BaseMethod';
+import TransportManager from '../data-manager/TransportManager';
+import { DataManager } from '../data-manager';
+import { DevicePool } from '../device/DevicePool';
+import { getLogger, LoggerNames } from '../utils';
+
+const Log = getLogger(LoggerNames.Method);
+
+export default class PromptWebDeviceAccess extends BaseMethod {
+  init() {
+    this.useDevice = false;
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+  }
+
+  async run() {
+    const { deviceSerialNumberFromUI } = this.payload;
+    await TransportManager.configure();
+    const isWebUsbEnv = DataManager.getSettings('env') === 'webusb';
+    if (!isWebUsbEnv) {
+      return Promise.reject(
+        ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Not webusb environment')
+      );
+    }
+
+    try {
+      let device;
+      let devicesDescriptor;
+
+      // If serial number is provided, skip prompting user
+      if (deviceSerialNumberFromUI) {
+        // Manually construct device descriptor using provided serial number
+        devicesDescriptor = [
+          {
+            path: deviceSerialNumberFromUI,
+            device: { serialNumber: deviceSerialNumberFromUI },
+            debug: true,
+          },
+        ];
+      } else {
+        // Otherwise prompt user to select a device
+        device = await this.connector?.promptDeviceAccess();
+        if (!device) {
+          return await Promise.reject(
+            ERRORS.TypedError(HardwareErrorCode.WebDevicePromptAccessError)
+          );
+        }
+
+        if (isWebUsbEnv) {
+          devicesDescriptor = [
+            {
+              path: (device as USBDevice).serialNumber ?? '',
+              device,
+              debug: true,
+            },
+          ];
+        }
+      }
+      const { deviceList } = await DevicePool.getDevices(
+        devicesDescriptor as unknown as UKeyDeviceInfo[]
+      );
+      if (deviceList.length > 0) {
+        return { device: deviceList[0].toMessageObject() };
+      }
+      return { device: null };
+    } catch (error) {
+      Log.debug(error);
+      return Promise.reject(
+        ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Please select the device to connect')
+      );
+    }
+  }
+}

package/src/api/SearchDevices.ts

@@ -0,0 +1,49 @@
+import { BaseMethod } from './BaseMethod';
+import DeviceConnector from '../device/DeviceConnector';
+import TransportManager from '../data-manager/TransportManager';
+import { DataManager } from '../data-manager';
+import { getDeviceTypeByBleName } from '../utils';
+import { DevicePool } from '../device/DevicePool';
+
+export default class SearchDevices extends BaseMethod {
+  connector?: DeviceConnector;
+
+  init() {
+    this.useDevice = false;
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+  }
+
+  async run() {
+    await TransportManager.configure();
+    const deviceDiff = await this.connector?.enumerate();
+    const devicesDescriptor = deviceDiff?.descriptors ?? [];
+
+    const env = DataManager.getSettings('env');
+
+    /**
+     * No need to call features during Bluetooth scaning
+     * to avoid device pairing
+     */
+    if (DataManager.isBleConnect(env)) {
+      const devices = [];
+      const seenIds = new Set<string>();
+
+      for (const device of devicesDescriptor) {
+        const lowerId = device.id?.toLowerCase();
+        if (!seenIds.has(lowerId)) {
+          seenIds.add(lowerId);
+          devices.push({
+            ...device,
+            connectId: device.id,
+            deviceType: getDeviceTypeByBleName(device.name ?? ''),
+          });
+        }
+      }
+      return devices;
+    }
+
+    const { deviceList } = await DevicePool.getDevices(devicesDescriptor);
+    return deviceList.map(device => device.toMessageObject());
+  }
+}