npm/firmware: add v1.1 metadata support

- Add new metadata fields.
- Add new `encodeHubName()` function.
- Auto-format code with Prettier.

Author: dlech

.github/workflows/npm-firmware.yml

@@ -21,7 +21,7 @@ jobs:
     - run: python -m pip install PyGithub
     - uses: actions/setup-node@v1
       with:
-        node-version: '10.x'
+        node-version: '16.x'
         registry-url: 'https://registry.npmjs.org'
     - run: yarn install
     - run: yarn build

npm/firmware/CHANGELOG.md

@@ -1,4 +1,8 @@
 
+### Added
+- Added support for v1.1.0 metadata.
+- Added `encodeHubName()` function.
+
 ## 4.13.0-beta.1 - 2021-09-21
 ### Changed
 - Updated dependencies.

npm/firmware/index.test.ts

@@ -1,10 +1,22 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2020 The Pybricks Authors
+// Copyright (c) 2020-2021 The Pybricks Authors
 
 import * as fs from 'fs';
 import * as path from 'path';
 import * as util from 'util';
-import { firmwareVersion, FirmwareReader, FirmwareReaderErrorCode } from '.';
+import {
+    firmwareVersion,
+    FirmwareReader,
+    FirmwareReaderErrorCode,
+    encodeHubName,
+    FirmwareMetadata,
+} from './index';
+
+let TextEncoder;
+
+beforeAll(() => {
+    TextEncoder = util.TextEncoder;
+});
 
 const readFile = util.promisify(fs.readFile);
 
@@ -84,3 +96,45 @@ test('reading data works', async () => {
     expect(await reader.readMainPy()).toMatchSnapshot();
     expect(await reader.readReadMeOss()).toMatchSnapshot();
 });
+
+describe('firmware name encoder', () => {
+    const metadata = { 'max-hub-name-size': 16 } as FirmwareMetadata;
+
+    test('default works', () => {
+        expect(encodeHubName('', metadata)).toEqual(
+            new Uint8Array([
+                80, 121, 98, 114, 105, 99, 107, 115, 32, 72, 117, 98, 0, 0, 0,
+                0,
+            ])
+        );
+    });
+
+    test('max length works', () => {
+        expect(encodeHubName('123456789012345', metadata)).toEqual(
+            new Uint8Array([
+                49, 50, 51, 52, 53, 54, 55, 56, 57, 48, 49, 50, 51, 52, 53, 0,
+            ])
+        );
+    });
+
+    test('exceeding max length truncates and preserves zero termination', () => {
+        expect(encodeHubName('1234567890123456', metadata)).toEqual(
+            new Uint8Array([
+                49, 50, 51, 52, 53, 54, 55, 56, 57, 48, 49, 50, 51, 52, 53, 0,
+            ])
+        );
+    });
+
+    test('truncating on multi-byte characters results in valid UTF-8', () => {
+        expect(encodeHubName('Pybricks Hub 😀', metadata)).toEqual(
+            new Uint8Array([
+                80, 121, 98, 114, 105, 99, 107, 115, 32, 72, 117, 98, 32, 0, 0,
+                0,
+            ])
+        );
+    });
+
+    test('old firmware throws', () => {
+        expect(() => encodeHubName('', {} as FirmwareMetadata)).toThrowError();
+    });
+});

npm/firmware/index.ts

@@ -2,12 +2,16 @@
 // Copyright (c) 2020-2021 The Pybricks Authors
 
 import JSZip, { JSZipObject } from 'jszip';
-import {PACKAGE_VERSION} from './version';
+import { PACKAGE_VERSION } from './version';
+
+const encoder = new TextEncoder();
 
 /**
  * String containing the firmware version.
  */
-export const firmwareVersion = PACKAGE_VERSION.substring(PACKAGE_VERSION.lastIndexOf('v') + 1);
+export const firmwareVersion = PACKAGE_VERSION.substring(
+    PACKAGE_VERSION.lastIndexOf('v') + 1
+);
 
 /**
  * LEGO Powered Up Hub IDs
@@ -58,6 +62,12 @@ export interface FirmwareMetadata {
     'user-mpy-offset': number;
     /** The maximum firmware size allowed on the hub. */
     'max-firmware-size': number;
+    /** The offset to where the hub name is stored in the firmware. (since  v1.1.0) */
+    'hub-name-offset': number | undefined;
+    /** The maximum size of the firmware name in bytes, including the zero-termination. (since  v1.1.0) */
+    'max-hub-name-size': number | undefined;
+    /** The SHA256 hash of the firmware. (since  v1.1.0) */
+    'firmware-sha256': string | undefined;
 }
 
 /** Types of errors that can be raised by FirmwareReader. */
@@ -75,22 +85,20 @@ export enum FirmwareReaderErrorCode {
 }
 
 /** Maps error codes to error messages. */
-const firmwareReaderErrorMessage: ReadonlyMap<
-    FirmwareReaderErrorCode,
-    string
-> = new Map([
-    [FirmwareReaderErrorCode.ZipError, 'bad zip data'],
-    [
-        FirmwareReaderErrorCode.MissingFirmwareBaseBin,
-        'missing firmware-base.bin',
-    ],
-    [
-        FirmwareReaderErrorCode.MissingMetadataJson,
-        'missing firmware.metadata.json',
-    ],
-    [FirmwareReaderErrorCode.MissingMainPy, 'missing main.py'],
-    [FirmwareReaderErrorCode.MissingReadmeOssTxt, 'ReadMe_OSS.txt'],
-]);
+const firmwareReaderErrorMessage: ReadonlyMap<FirmwareReaderErrorCode, string> =
+    new Map([
+        [FirmwareReaderErrorCode.ZipError, 'bad zip data'],
+        [
+            FirmwareReaderErrorCode.MissingFirmwareBaseBin,
+            'missing firmware-base.bin',
+        ],
+        [
+            FirmwareReaderErrorCode.MissingMetadataJson,
+            'missing firmware.metadata.json',
+        ],
+        [FirmwareReaderErrorCode.MissingMainPy, 'missing main.py'],
+        [FirmwareReaderErrorCode.MissingReadmeOssTxt, 'ReadMe_OSS.txt'],
+    ]);
 
 /** Errors throw by FirmwareReader */
 export class FirmwareReaderError extends Error {
@@ -159,7 +167,9 @@ export class FirmwareReader {
      * Loads data from a firmware.zip file and does a few sanity checks.
      * @param zipData The firmware.zip file binary data.
      */
-    public static async load(zipData: Uint8Array | ArrayBuffer | Blob): Promise<FirmwareReader> {
+    public static async load(
+        zipData: Uint8Array | ArrayBuffer | Blob
+    ): Promise<FirmwareReader> {
         const reader = new FirmwareReader();
         const zip = await wrapError(
             () => JSZip.loadAsync(zipData),
@@ -217,3 +227,34 @@ export class FirmwareReader {
         return this.readMeOss!.async('text');
     }
 }
+
+/**
+ * Encodes a firmware name as UTF-8 bytes with zero-termination.
+ *
+ * If the name is too long to fit in the size specified by the metadata, the
+ * name will be truncated. The resulting value can be written to the firmware
+ * image at 'hub-name-offset'.
+ *
+ * @param name The hub name.
+ * @param metadata The firmware metadata.
+ */
+export function encodeHubName(
+    name: string,
+    metadata: FirmwareMetadata
+): Uint8Array {
+    if (metadata['max-hub-name-size'] === undefined) {
+        throw new Error('firmware image does not support firmware name');
+    }
+
+    // fall back to default on empty name
+    if (!name) {
+        name = 'Pybricks Hub';
+    }
+
+    const bytes = new Uint8Array(metadata['max-hub-name-size']);
+
+    // subarray ensures zero termination if encoded length is >= 'max-hub-name-size'.
+    encoder.encodeInto(name, bytes.subarray(0, bytes.length - 1));
+
+    return bytes;
+}

npm/firmware/jest.config.js

@@ -1,4 +1,5 @@
 module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-};
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testPathIgnorePatterns: ['<rootDir>/build/', '<rootDir>/node_modules/'],
+};

npm/firmware/tsconfig.json

@@ -63,5 +63,5 @@
     /* Advanced Options */
     "forceConsistentCasingInFileNames": true  /* Disallow inconsistently-cased references to the same file. */
   },
-  "files": ["index.ts"]
+  "files": ["index.ts", "index.test.ts"]
 }