feat: kboot native firmware upgrade

Author: ert78gb

packages/mcumgr/src/util/crc16.ts

@@ -1,3 +1,4 @@
+// TODO: eliminate the duplication of the uhk-usb-module
 const CRC16TABLE = new Uint16Array([
     0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50a5, 0x60c6, 0x70e7,
     0x8108, 0x9129, 0xa14a, 0xb16b, 0xc18c, 0xd1ad, 0xe1ce, 0xf1ef,

packages/uhk-usb/src/constants.ts

@@ -36,6 +36,10 @@ export enum UsbCommand {
     EraseBleSettings         = 0x1d,
     ExecShellCommand         = 0x1e,
     ReadOled                 = 0x1f,
+    WriteModuleFirmware      = 0x20,
+    FlashModule              = 0x21,
+    GetModuleFlashState      = 0x22,
+    ValidateBufferCrc        = 0x23,
 }
 
 export enum EepromOperation {
@@ -46,7 +50,8 @@ export enum EepromOperation {
 export enum ConfigBufferId {
     hardwareConfig = 0,
     stagingUserConfig = 1,
-    validatedUserConfig = 2
+    validatedUserConfig = 2,
+    moduleFirmware = 3,
 }
 
 export enum DevicePropertyIds {

packages/uhk-usb/src/models/device-state.ts

@@ -1,6 +1,7 @@
 export interface DeviceState {
     isEepromBusy: boolean;
     isMacroStatusDirty: boolean;
+    isModuleFlashBusy: boolean;
     isZephyrLogAvailable: boolean;
     areHalvesMerged: boolean;
     isLeftHalfConnected: boolean;

packages/uhk-usb/src/models/index.ts

@@ -4,6 +4,7 @@ export * from './duration.js';
 export * from './i2c-baud-rate.js';
 export * from './i2c-error-buffer.js';
 export * from './load-configurations-result.js';
+export * from './module-flash-state.js';
 export * from './pairing-info.js';
 export * from './reenumerate-option.js';
 export * from './reenumerate-result.js';

packages/uhk-usb/src/models/module-flash-state.ts

@@ -0,0 +1,15 @@
+export const MODULE_FLASH_STATE = Object.freeze({
+    Idle: 0,
+    Erasing: 1,
+    Writing: 2,
+    Done: 3,
+    Error: 4,
+})
+
+export type MODULE_FLASH_STATE_KEY_TYPE = keyof typeof MODULE_FLASH_STATE;
+export type MODULE_FLASH_STATE_TYPE = typeof MODULE_FLASH_STATE[MODULE_FLASH_STATE_KEY_TYPE];
+
+export interface ModuleFlashResponse {
+    state: MODULE_FLASH_STATE_TYPE;
+    errorCode?: number;
+}

packages/uhk-usb/src/uhk-hid-device.ts

@@ -619,8 +619,9 @@ export class UhkHidDevice {
         const activeLayerNumber = buffer[6] & 0x7f;
 
         return {
-            isEepromBusy: buffer[1] !== 0,
+            isEepromBusy: isBitSet(buffer[1], 0),
             isMacroStatusDirty: buffer[7] !== 0,
+            isModuleFlashBusy: isBitSet(buffer[1], 1),
             areHalvesMerged: isBitSet(buffer[2], 0),
             isLeftHalfConnected: buffer[3] !== 0,
             activeLayerNumber,

packages/uhk-usb/src/uhk-operations.ts

@@ -1,5 +1,6 @@
 import { McuManager, SerialPeripheral } from '@uhk/mcumgr';
 import * as fs from 'fs';
+import { readFile } from 'node:fs/promises';
 import { DataOption, KBoot, Properties, UsbPeripheral } from 'kboot';
 import {
     ALL_UHK_DEVICES,
@@ -45,6 +46,11 @@ import {
     UsbCommand,
     UsbVariables
 } from './constants.js';
+import {
+    MODULE_FLASH_STATE,
+    MODULE_FLASH_STATE_TYPE,
+    ModuleFlashResponse,
+} from './models/module-flash-state.js';
 import {
     DebugInfo,
     Duration,
@@ -60,6 +66,7 @@ import {
     readBootloaderFirmwareFromHexFileAsync,
     waitForDevice
 } from './util.js';
+import crc16 from './utils/crc16.js';
 import { generateDeviceSerialNumber } from './utils/generate-device-serial-number.js';
 import { convertMsToDuration, convertSlaveI2cErrorBuffer, snooze, waitUntil} from './utils/index.js';
 import { normalizeStatusBuffer } from './utils/normalize-status-buffer.js';
@@ -197,7 +204,7 @@ export class UhkOperations {
         const peripheral = new SerialPeripheral(reenumerateResult.serialPath);
         const mcuManager = new McuManager(peripheral);
         this.logService.misc(`[UhkOperations] Read ${device.logName} firmware from file`);
-        const configData = fs.readFileSync(firmwarePath);
+        const configData = await readFile(firmwarePath);
         this.logService.misc('[UhkOperations] Write memory with mcumgr');
         await mcuManager.imageUpload(configData);
         this.logService.misc('[UhkOperations] Reset mcu bootloader');
@@ -275,7 +282,7 @@ export class UhkOperations {
         await kboot.flashEraseAllUnsecure();
 
         this.logService.misc(`[UhkOperations] Read "${module.name}" firmware from file`);
-        const configData = fs.readFileSync(firmwarePath);
+        const configData = await readFile(firmwarePath);
 
         this.logService.misc('[UhkOperations] Write memory');
         await kboot.configureI2c(module.i2cAddress);
@@ -304,6 +311,51 @@ export class UhkOperations {
         this.logService.misc(`[UhkOperations] "${module.name}" firmware successfully flashed`);
     }
 
+    public async updateModuleWithKbootNative(
+        firmwarePath: string,
+        device: UhkDeviceProduct,
+        module: UhkModule
+    ): Promise<void> {
+        this.logService.misc(`[UhkOperations][kboot-native] Start flashing "${module.name}" module firmware`);
+        await this.device.reenumerate({
+            device,
+            enumerationMode: EnumerationModes.NormalKeyboard,
+        });
+        await this.device.close();
+        await snooze(1000);
+
+        const configData = await readFile(firmwarePath) as any;
+        this.logService.misc('[UhkOperations][kboot-native] sending firmware to the keyboard');
+        await this.sendConfigToKeyboard(configData, UsbCommand.WriteModuleFirmware);
+
+        this.logService.misc('[UhkOperations][kboot-native] validating module firmware');
+        const crc = crc16(configData);
+        this.logService.misc(`[UhkOperations][kboot-native] module firmware crc: ${crc}`);
+        const isValid = await this.isBufferValid(ConfigBufferId.moduleFirmware, configData.length, crc);
+
+        if (!isValid) {
+            this.logService.error('[UhkOperations][kboot-native] module firmware crc validation failed');
+            throw new Error('Module firmware crc validation failed');
+        }
+
+        this.logService.misc('[UhkOperations][kboot-native] flashing module');
+        await this.flashModule(module);
+
+        this.logService.misc('[UhkOperations][kboot-native] wait until flashing finished');
+        const response = await this.waitUntilModuleFlashFinished();
+
+        if (response.state === MODULE_FLASH_STATE.Error) {
+            this.logService.error(`[UhkOperations][kboot-native] error occurred in the module flashing process. Error code: ${response.errorCode}`);
+
+            throw new Error(`Error occurred in the module flashing process. Error code: ${response.errorCode}`);
+        }
+
+        this.logService.misc('[UhkOperations][kboot-native] wait until flashing finished');
+        await this.waitUntilModuleFlashFinished();
+
+        this.logService.misc(`[UhkOperations][kboot-native] "${module.name}" firmware successfully flashed`);
+    }
+
     /**
      * Return with the actual UserConfiguration from UHK Device
      * @returns {Promise<Buffer>}
@@ -463,9 +515,15 @@ export class UhkOperations {
             const transferPercentRange = 0.83;
 
             reportProgress(preTransferPercent);
-            await this.sendConfigToKeyboard(configBuffer, true, (percent) => {
-                reportProgress(preTransferPercent + Math.round(percent * transferPercentRange));
-            });
+
+            await this.sendConfigToKeyboard(
+                resultBuffer.getBufferContent(),
+                UsbCommand.WriteStagingUserConfig,
+                (percent) => {
+                    reportProgress(preTransferPercent + Math.round(percent * transferPercentRange));
+                },
+            );
+
             reportProgress(86);
             await this.applyConfiguration();
             reportProgress(90);
@@ -501,7 +559,7 @@ export class UhkOperations {
         hardwareConfig.toBinary(hardwareBuffer);
         const buffer = hardwareBuffer.getBufferContent();
 
-        await this.sendConfigToKeyboard(buffer, false);
+        await this.sendConfigToKeyboard(buffer, UsbCommand.WriteHardwareConfig);
         await this.writeConfigToEeprom(ConfigBufferId.hardwareConfig);
         await this.waitUntilKeyboardBusy();
     }
@@ -529,6 +587,25 @@ export class UhkOperations {
         }
     }
 
+    public async waitUntilModuleFlashFinished(): Promise<ModuleFlashResponse> {
+        while (true) {
+            const response = await this.getModuleFlashState();
+            if (response.state === MODULE_FLASH_STATE.Erasing) {
+                this.logService.misc('[DeviceOperation] Module flash erasing, wait...');
+                await snooze(200);
+                continue;
+            }
+
+            if (response.state === MODULE_FLASH_STATE.Writing) {
+                this.logService.misc('[DeviceOperation] Module flash writing, wait...');
+                await snooze(200);
+                continue;
+            }
+
+            return response;
+        }
+    }
+
     public async waitForKbootIdle(moduleName: string): Promise<boolean> {
         while (true) {
             const buffer = await this.device.write(Buffer.from([UsbCommand.GetProperty, DevicePropertyIds.CurrentKbootCommand]));
@@ -544,6 +621,15 @@ export class UhkOperations {
         }
     }
 
+    public async getModuleFlashState(): Promise<ModuleFlashResponse> {
+        const buffer = await this.device.write(Buffer.from([UsbCommand.GetModuleFlashState]));
+
+        return {
+            state: buffer[0] as MODULE_FLASH_STATE_TYPE,
+            errorCode: buffer[1]
+        }
+    }
+
     public async getModuleProperty({ module, property } : GetModulePropertyArguments): Promise<UhkBuffer> {
         const moduleSlotName = getSlotIdName(module);
 
@@ -697,17 +783,24 @@ export class UhkOperations {
     public async eraseHardwareConfig(): Promise<void> {
         this.logService.usbOps('[DeviceOperation] USB[T]: Erase hardware configuration');
         const buffer = Buffer.from(Array(64).fill(0xff));
-        await this.sendConfigToKeyboard(buffer, false);
+        await this.sendConfigToKeyboard(buffer, UsbCommand.WriteHardwareConfig);
         await this.writeConfigToEeprom(ConfigBufferId.hardwareConfig);
     }
 
     public async eraseUserConfig(): Promise<void> {
         this.logService.usbOps('[DeviceOperation] USB[T]: Erase user configuration');
         const buffer = Buffer.from(Array(2 ** 15 - 64).fill(0xff));
-        await this.sendConfigToKeyboard(buffer, true);
+        await this.sendConfigToKeyboard(buffer, UsbCommand.WriteStagingUserConfig);
         await this.writeConfigToEeprom(ConfigBufferId.stagingUserConfig);
     }
 
+    public async flashModule(module: UhkModule): Promise<void> {
+        this.logService.usbOps('[DeviceOperation] USB[T]: Flash module');
+        const buffer = Buffer.from([UsbCommand.FlashModule, module.slotId]);
+
+        await this.device.write(buffer);
+    }
+
     public async switchKeymap(keymapAbbreviation: string): Promise<void> {
         this.logService.usbOps('[DeviceOperation] USB[T]: Switch keymap');
         const keymapAbbreviationAscii = keymapAbbreviation.split('').map(char => char.charCodeAt(0));
@@ -958,19 +1051,15 @@ export class UhkOperations {
     /**
      * IpcMain handler. Send the UserConfiguration to the UHK Device and send a response with the result.
      * @param {Buffer} buffer - UserConfiguration buffer
-     * @param {Boolean} isUserConfiguration - User or Hardware configuration
+     * @param {UsbCommand} command - Represent which configuration area write to the device
      * @returns {Promise<void>}
      * @private
      */
     private async sendConfigToKeyboard(
         buffer: Buffer,
-        isUserConfiguration,
+        command: UsbCommand,
         onProgress?: (percent: number) => void
     ): Promise<void> {
-        const command = isUserConfiguration
-            ? UsbCommand.WriteStagingUserConfig
-            : UsbCommand.WriteHardwareConfig;
-
         const fragments = getTransferBuffers(command, buffer);
         for (let i = 0; i < fragments.length; i++) {
             await this.device.write(fragments[i]);
@@ -1005,4 +1094,17 @@ export class UhkOperations {
 
         await this.device.write(buffer);
     }
+
+    public async isBufferValid(bufferId: ConfigBufferId, expectedSize: number, expectedCrc: number): Promise<boolean> {
+        this.logService.usbOps('[DeviceOperation] USB[T]: Validate Buffer CRC');
+        const buffer = Buffer.alloc(6);
+        buffer.writeUInt8(UsbCommand.ValidateBufferCrc, 0);
+        buffer.writeUInt8(bufferId, 1);
+        buffer.writeUInt16LE(expectedSize, 2);
+        buffer.writeUInt16LE(expectedCrc, 4);
+
+        const response = await this.device.write(buffer);
+
+        return response[1] === 0;
+    }
 }

packages/uhk-usb/src/utils/crc16.ts

@@ -0,0 +1,46 @@
+// TODO: eliminate the duplication of the uhk-usb-module
+const CRC16TABLE = new Uint16Array([
+    0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50a5, 0x60c6, 0x70e7,
+    0x8108, 0x9129, 0xa14a, 0xb16b, 0xc18c, 0xd1ad, 0xe1ce, 0xf1ef,
+    0x1231, 0x0210, 0x3273, 0x2252, 0x52b5, 0x4294, 0x72f7, 0x62d6,
+    0x9339, 0x8318, 0xb37b, 0xa35a, 0xd3bd, 0xc39c, 0xf3ff, 0xe3de,
+    0x2462, 0x3443, 0x0420, 0x1401, 0x64e6, 0x74c7, 0x44a4, 0x5485,
+    0xa56a, 0xb54b, 0x8528, 0x9509, 0xe5ee, 0xf5cf, 0xc5ac, 0xd58d,
+    0x3653, 0x2672, 0x1611, 0x0630, 0x76d7, 0x66f6, 0x5695, 0x46b4,
+    0xb75b, 0xa77a, 0x9719, 0x8738, 0xf7df, 0xe7fe, 0xd79d, 0xc7bc,
+    0x48c4, 0x58e5, 0x6886, 0x78a7, 0x0840, 0x1861, 0x2802, 0x3823,
+    0xc9cc, 0xd9ed, 0xe98e, 0xf9af, 0x8948, 0x9969, 0xa90a, 0xb92b,
+    0x5af5, 0x4ad4, 0x7ab7, 0x6a96, 0x1a71, 0x0a50, 0x3a33, 0x2a12,
+    0xdbfd, 0xcbdc, 0xfbbf, 0xeb9e, 0x9b79, 0x8b58, 0xbb3b, 0xab1a,
+    0x6ca6, 0x7c87, 0x4ce4, 0x5cc5, 0x2c22, 0x3c03, 0x0c60, 0x1c41,
+    0xedae, 0xfd8f, 0xcdec, 0xddcd, 0xad2a, 0xbd0b, 0x8d68, 0x9d49,
+    0x7e97, 0x6eb6, 0x5ed5, 0x4ef4, 0x3e13, 0x2e32, 0x1e51, 0x0e70,
+    0xff9f, 0xefbe, 0xdfdd, 0xcffc, 0xbf1b, 0xaf3a, 0x9f59, 0x8f78,
+    0x9188, 0x81a9, 0xb1ca, 0xa1eb, 0xd10c, 0xc12d, 0xf14e, 0xe16f,
+    0x1080, 0x00a1, 0x30c2, 0x20e3, 0x5004, 0x4025, 0x7046, 0x6067,
+    0x83b9, 0x9398, 0xa3fb, 0xb3da, 0xc33d, 0xd31c, 0xe37f, 0xf35e,
+    0x02b1, 0x1290, 0x22f3, 0x32d2, 0x4235, 0x5214, 0x6277, 0x7256,
+    0xb5ea, 0xa5cb, 0x95a8, 0x8589, 0xf56e, 0xe54f, 0xd52c, 0xc50d,
+    0x34e2, 0x24c3, 0x14a0, 0x0481, 0x7466, 0x6447, 0x5424, 0x4405,
+    0xa7db, 0xb7fa, 0x8799, 0x97b8, 0xe75f, 0xf77e, 0xc71d, 0xd73c,
+    0x26d3, 0x36f2, 0x0691, 0x16b0, 0x6657, 0x7676, 0x4615, 0x5634,
+    0xd94c, 0xc96d, 0xf90e, 0xe92f, 0x99c8, 0x89e9, 0xb98a, 0xa9ab,
+    0x5844, 0x4865, 0x7806, 0x6827, 0x18c0, 0x08e1, 0x3882, 0x28a3,
+    0xcb7d, 0xdb5c, 0xeb3f, 0xfb1e, 0x8bf9, 0x9bd8, 0xabbb, 0xbb9a,
+    0x4a75, 0x5a54, 0x6a37, 0x7a16, 0x0af1, 0x1ad0, 0x2ab3, 0x3a92,
+    0xfd2e, 0xed0f, 0xdd6c, 0xcd4d, 0xbdaa, 0xad8b, 0x9de8, 0x8dc9,
+    0x7c26, 0x6c07, 0x5c64, 0x4c45, 0x3ca2, 0x2c83, 0x1ce0, 0x0cc1,
+    0xef1f, 0xff3e, 0xcf5d, 0xdf7c, 0xaf9b, 0xbfba, 0x8fd9, 0x9ff8,
+    0x6e17, 0x7e36, 0x4e55, 0x5e74, 0x2e93, 0x3eb2, 0x0ed1, 0x1ef0
+]);
+
+export default function crc16(data: ArrayLike<any>): number {
+    let crc = 0;
+    const l = data.length;
+    for (let i = 0; i < l; i++) {
+        crc = ((crc << 8) & 0xff00) ^ CRC16TABLE[((crc >> 8) & 0xff) ^ data[i]];
+    }
+
+    return crc;
+}
+

packages/usb/get-device-state.ts

@@ -14,6 +14,7 @@ setInterval(async function () {
         console.log(
             `isEepromBusy: ${state.isEepromBusy ? 'yes' : 'no'} | \
 isMacroStatusDirty: ${state.isMacroStatusDirty ? 'yes' : 'no'} | \
+isModuleFlashBusy: ${state.isModuleFlashBusy ? 'yes' : 'no'} | \
 isZephyrLogAvailable: ${state.isZephyrLogAvailable ? 'yes' : 'no'} | \
 areHalvesMerged: ${state.areHalvesMerged ? 'yes' : 'no'} | \
 newPairedDevice: ${state.newPairedDevice ? 'yes' : 'no'} | \

packages/usb/kboot-native-firmware-upgrade.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning
+
+import fs from 'fs';
+import * as path from 'path';
+import { LEFT_HALF_MODULE } from 'uhk-common';
+import { getCurrentUhkDeviceProduct, getDeviceFirmwarePath, getFirmwarePackageJson } from 'uhk-usb';
+
+import Uhk, { errorHandler, yargs } from './src/index.js';
+
+(async function () {
+    try {
+        const argv = yargs
+            .usage('Usage: $0 <firmware directory>')
+            .argv;
+
+        const firmwarePath = argv._[0];
+
+        if (!fs.existsSync(firmwarePath)) {
+            console.log('Firmware directory does not exists.');
+            process.exit(1);
+        }
+
+        const uhkDeviceProduct = await getCurrentUhkDeviceProduct(argv);
+
+        const { operations } = Uhk(argv);
+
+        const packageJsonPath = path.join(firmwarePath, 'package.json');
+        const packageJson = await getFirmwarePackageJson({
+            packageJsonPath,
+            tmpDirectory: firmwarePath
+        });
+        const rightFirmwarePath = getDeviceFirmwarePath(uhkDeviceProduct, packageJson);
+
+        await operations.updateRightFirmwareWithKboot(rightFirmwarePath, uhkDeviceProduct);
+        const leftFirmwarePath = path.join(firmwarePath, 'modules/uhk60-left.bin');
+        await operations.updateModuleWithKbootNative(leftFirmwarePath, uhkDeviceProduct, LEFT_HALF_MODULE);
+    } catch (error) {
+        await errorHandler(error);
+    }
+})();