Add microbitBoardId type and update DeviceVersion enum.

Author: microbit-carlos

docs/quick-guide.md

@@ -61,19 +61,19 @@ Using multiple MicroPython Intel Hex files to generate a Universal Hex:
 ```js
 // Create a new FileSystem instance passing the MicroPython Intel Hex string
 var micropythonFs = new microbitFs.MicropythonFsHex([
-  { hex: uPy1HexFile, boardId: 0x9900 },
-  { hex: uPy2HexFile, boardId: 0x9903 },
+  { hex: uPy1HexFile, boardId: microbitFs.microbitBoardId.V1 },
+  { hex: uPy2HexFile, boardId: microbitFs.microbitBoardId.V2 },
 ]);;
 
 // Import files from a different MicroPython Intel hex file with filesystem
 var addedFilenames = micropythonFs.importFilesFromIntelHex(UploadedHexWithUserFiles);
 addedFilenames = micropythonFs.importFilesFromIntelHex(UploadedHexWithUserFiles, {overwrite: false, formatFirst: false});
 
 // Generate a new Intel hex string or Uint8Array with MicroPython and the files
-var uPy1IntelHexStrWithFs = micropythonFs.getIntelHex(0x9900);
-var uPy1IntelHexBytesWithFs = micropythonFs.getIntelHexBytes(0x9900);
-var uPy2IntelHexStrWithFs = micropythonFs.getIntelHex(0x9903);
-var uPy2IntelHexBytesWithFs = micropythonFs.getIntelHexBytes(0x9903);
+var uPy1IntelHexStrWithFs = micropythonFs.getIntelHex(microbitFs.microbitBoardId.V1);
+var uPy1IntelHexBytesWithFs = micropythonFs.getIntelHexBytes(microbitFs.microbitBoardId.V1);
+var uPy2IntelHexStrWithFs = micropythonFs.getIntelHex(microbitFs.microbitBoardId.V2);
+var uPy2IntelHexBytesWithFs = micropythonFs.getIntelHexBytes(microbitFs.microbitBoardId.V2);
 
 // Generate a new Universal hex string with all MicroPython+files data
 var universalHexStrWithFs = micropythonFs.getUniversalHex();

src/__tests__/flash-regions.spec.ts

@@ -38,6 +38,6 @@ describe('Read MicroPython UICR data.', () => {
     expect(result.fsStartAddress).toEqual(expectedFsStartAddress);
     expect(result.fsEndAddress).toEqual(expectedFsEndAddress);
     expect(result.uPyVersion).toEqual(expectedUpyVersion);
-    expect(result.deviceVersion).toEqual(2);
+    expect(result.deviceVersion).toEqual('V2');
   });
 });

src/__tests__/micropython-fs-hex.spec.ts

@@ -8,7 +8,7 @@ import MemoryMap from 'nrf-intel-hex';
 import * as microbitUh from '@microbit/microbit-universal-hex';
 
 import * as fsBuilder from '../micropython-fs-builder';
-import { MicropythonFsHex } from '../micropython-fs-hex';
+import { MicropythonFsHex, microbitBoardId } from '../micropython-fs-hex';
 
 // MicroPython hex file for testing
 const uPy1HexFile = fs.readFileSync('./src/__tests__/upy-v1.0.1.hex', 'utf8');
@@ -36,7 +36,7 @@ describe('Test the class constructor', () => {
       const microbitFs = new MicropythonFsHex([
         {
           hex: uPy1HexFile,
-          boardId: 0x9903,
+          boardId: microbitBoardId.V2,
         },
         {
           hex: '',
@@ -64,7 +64,7 @@ describe('Test the class constructor', () => {
       const microbitFs = new MicropythonFsHex([
         {
           hex: uPy1HexFile,
-          boardId: 0x9903,
+          boardId: microbitBoardId.V2,
         },
         {
           hex: 'notahex',
@@ -128,8 +128,8 @@ describe('Test general read write operations', () => {
     testInstance(new MicropythonFsHex(uPy1HexFile));
     testInstance(
       new MicropythonFsHex([
-        { hex: uPy1HexFile, boardId: 0x9900 },
-        { hex: uPy2HexFile, boardId: 0x9903 },
+        { hex: uPy1HexFile, boardId: microbitBoardId.V1 },
+        { hex: uPy2HexFile, boardId: microbitBoardId.V2 },
       ])
     );
   });

src/__tests__/uicr.spec.ts

@@ -32,7 +32,7 @@ describe('Read MicroPython UICR data.', () => {
     const expectedUPyVersion =
       'micro:bit v1.0.1+b0bf4a9 on 2018-12-13; ' +
       'MicroPython v1.9.2-34-gd64154c73 on 2017-09-01';
-    const expectedDeviceVersion = 1;
+    const expectedDeviceVersion = 'V1';
 
     const result = getIntelHexUicrData(uPy1HexFile);
 
@@ -72,7 +72,7 @@ describe('Read MicroPython UICR data.', () => {
     const expectedUPyVersion =
       'micro:bit v2.0.99+3e09245 on 2020-11-02; ' +
       'MicroPython 3e09245 on 2020-11-02';
-    const expectedDeviceVersion = 2;
+    const expectedDeviceVersion = 'V2';
 
     const result = getIntelHexUicrData(uPy2HexFile);
 

src/device-mem-info.ts

@@ -1,17 +1,37 @@
+/**
+ * This interface represents the data about the device target contained within a
+ * MicroPython hex file.
+ *
+ * This data is stored in different formats depending on the MicroPython port,
+ * V1 uses the UICR location, and V2 uses a table stored in flash.
+ */
 export interface DeviceMemInfo {
+  /** Size of a single flash page, in bytes. */
   flashPageSize: number;
+  /** Full flash size in bytes. */
   flashSize: number;
+  /** Start address for the flash memory. */
   flashStartAddress: number;
+  /** End address for the flash memory. */
   flashEndAddress: number;
+  /** Start address in flash where the MicroPython runtime starts. */
   runtimeStartAddress: number;
+  /** End address in flash where the MicroPython runtime starts. */
   runtimeEndAddress: number;
+  /** Start address in flash where the MicroPython filesystem starts. */
   fsStartAddress: number;
+  /** End address in flash where the MicroPython filesystem starts. */
   fsEndAddress: number;
+  /** MicroPython version string. */
   uPyVersion: string;
-  deviceVersion: number;
+  /** Device targeted by this hex file. */
+  deviceVersion: DeviceVersion;
 }
 
+/**
+ * Represents the micro:bit Version the hex file targets.
+ */
 export const enum DeviceVersion {
-  one = 1,
-  two = 2,
+  V1 = 'V1',
+  V2 = 'V2',
 }

src/flash-regions.ts

@@ -329,7 +329,7 @@ function getHexMapFlashRegionsData(iHexMap: MemoryMap): DeviceMemInfo {
     fsStartAddress,
     fsEndAddress,
     uPyVersion,
-    deviceVersion: DeviceVersion.two,
+    deviceVersion: DeviceVersion.V2,
   };
 }
 

src/micropython-fs-builder.ts

@@ -173,7 +173,7 @@ function getEndAddress(intelHexMap: MemoryMap): number {
   let endAddress = deviceMem.fsEndAddress;
   // TODO: Maybe we should move this inside the UICR module to calculate
   // the real fs area in that step
-  if (deviceMem.deviceVersion === DeviceVersion.one) {
+  if (deviceMem.deviceVersion === DeviceVersion.V1) {
     if (isAppendedScriptPresent(intelHexMap)) {
       endAddress = AppendedBlock.StartAdd;
     }

src/micropython-fs-hex.ts

@@ -18,12 +18,21 @@ import {
 import { SimpleFile } from './simple-file';
 import { areUint8ArraysEqual } from './common';
 
+/**
+ * The Board ID is used to identify the different targets from a Universal Hex.
+ * In this case the target represents a micro:bit version.
+ * For micro:bit V1 (v1.3, v1.3B and v1.5) the `boardId` is `0x9900`, and for
+ * V2 `0x9903`.
+ * This is being re-exported from the @microbit/microbit-universal-hex package.
+ */
+export import microbitBoardId = microbitUh.microbitBoardId;
+
 /**
  * Extends the interface from microbit-fs-building to include the board ID that
  * corresponds to each of the cached objects.
  */
 interface MpFsBuilderCacheWithId extends MpFsBuilderCache {
-  boardId: number;
+  boardId: number | microbitBoardId;
 }
 
 /**
@@ -33,7 +42,7 @@ export interface IntelHexWithId {
   /** Intel Hex string */
   hex: string;
   /** Board ID to identify the Intel Hex and encode inside the Universal Hex */
-  boardId: number;
+  boardId: number | microbitBoardId;
 }
 
 /**
@@ -456,7 +465,7 @@ export class MicropythonFsHex implements FsInterface {
    *
    * @returns A new string with MicroPython and the filesystem included.
    */
-  getIntelHex(boardId?: number): string {
+  getIntelHex(boardId?: number | microbitBoardId): string {
     if (this.getStorageRemaining() < 0) {
       throw new Error('There is no storage space left.');
     }
@@ -499,7 +508,7 @@ export class MicropythonFsHex implements FsInterface {
    *
    * @returns A Uint8Array with MicroPython and the filesystem included.
    */
-  getIntelHexBytes(boardId?: number): Uint8Array {
+  getIntelHexBytes(boardId?: number | microbitBoardId): Uint8Array {
     if (this.getStorageRemaining() < 0) {
       throw new Error('There is no storage space left.');
     }

src/uicr.ts

@@ -15,13 +15,13 @@ import { DeviceVersion } from './hex-mem-info';
 
 const DEVICE_INFO = [
   {
-    deviceVersion: DeviceVersion.one,
+    deviceVersion: DeviceVersion.V1,
     magicHeader: 0x17eeb07c,
     flashSize: 256 * 1024,
     fsEnd: 256 * 1024,
   },
   {
-    deviceVersion: DeviceVersion.two,
+    deviceVersion: DeviceVersion.V2,
     magicHeader: 0x47eeb07c,
     flashSize: 512 * 1024,
     fsEnd: 0x73000,
@@ -99,7 +99,7 @@ function getMagicValue(intelHexMap: MemoryMap): number {
  * @param intelHexMap - Memory map of the Intel Hex data.
  * @returns The micro:bit board version.
  */
-function getDeviceVersion(intelHexMap: MemoryMap): number {
+function getDeviceVersion(intelHexMap: MemoryMap): DeviceVersion {
   const readMagicHeader = getMagicValue(intelHexMap);
   for (const device of DEVICE_INFO) {
     if (device.magicHeader === readMagicHeader) {
@@ -214,7 +214,7 @@ function getHexMapUicrData(intelHexMap: MemoryMap): MicropythonUicrData {
   const runtimeEndAddress: number = pagesUsed * flashPageSize;
   const versionAddress: number = getVersionLocation(uicrMap);
   const uPyVersion: string = hexMapUtil.getString(intelHexMap, versionAddress);
-  const deviceVersion: number = getDeviceVersion(uicrMap);
+  const deviceVersion: DeviceVersion = getDeviceVersion(uicrMap);
   const fsEndAddress: number = getFsEndAddress(uicrMap);
 
   return {