upy-fs-builder: Add optional parameter to add files and return Uint8Array. (#15)

Author: microbit-carlos

docs/quick-guide.md

@@ -38,8 +38,9 @@ var fsSize = micropythonFs.getStorageSize();
 var fsAvailableSize = micropythonFs.getStorageUsed();
 var fsUsedSize = micropythonFs.getStorageRemaining();
 
-// Generate a new hex string with MicroPython and the files
-var intelHexWithFs = micropythonFs.getIntelHex();
+// Generate a new hex string or Uint8Array with MicroPython and the files
+var intelHexStrWithFs = micropythonFs.getIntelHex();
+var intelHexBytesWithFs = micropythonFs.getIntelHexBytes();
 ```
 
 Public interface can be found in the `src/fs-interface.ts` file.

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

@@ -165,7 +165,7 @@ describe('Writing files to the filesystem.', () => {
     },
   ];
 
-  it('Add files to hex.', () => {
+  it('Add files to hex, return a string.', () => {
     const fwWithFsOther = addIntelHexFiles(uPyHexFile, {
       [files[0].fileName]: strToBytes(files[0].fileStr),
       [files[1].fileName]: strToBytes(files[1].fileStr),
@@ -183,6 +183,28 @@ describe('Writing files to the filesystem.', () => {
     expect(file1data).toEqual(files[1].bytes());
   });
 
+  it('Add files to hex, return a byte array', () => {
+    const fwWithFsBytes = addIntelHexFiles(
+      uPyHexFile,
+      {
+        [files[0].fileName]: strToBytes(files[0].fileStr),
+        [files[1].fileName]: strToBytes(files[1].fileStr),
+      },
+      true
+    );
+
+    // Address calculated starting at the top of the MicroPython v1.0.1 fs
+    const startFs = 0x38c00;
+    const file0data = fwWithFsBytes.slice(startFs, startFs + files[0].fsSize);
+    const file1start = startFs + files[0].fsSize;
+    const file1data = fwWithFsBytes.slice(
+      file1start,
+      file1start + files[1].fsSize
+    );
+    expect(file0data).toEqual(files[0].bytes());
+    expect(file1data).toEqual(files[1].bytes());
+  });
+
   // A chunk using up the last byte will also use the next and leave it empty
   const fullChunkPlus = {
     fileName: 'one_chunk_plus.py',

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

@@ -368,6 +368,18 @@ describe('Test hex generation.', () => {
 
     expect(addIntelHexFilesSpy.mock.calls.length).toEqual(1);
     expect(addIntelHexFilesSpy.mock.calls[0][0]).toBe(uPyHexFile);
+    expect(addIntelHexFilesSpy.mock.calls[0][2]).toBeFalsy();
+  });
+
+  it('getIntelHexBytes called with constructor hex string.', () => {
+    const microbitFs = new MicropythonFsHex(uPyHexFile);
+    microbitFs.write('a.txt', 'content');
+
+    const returnedIntelHex = microbitFs.getIntelHexBytes();
+
+    expect(addIntelHexFilesSpy.mock.calls.length).toEqual(1);
+    expect(addIntelHexFilesSpy.mock.calls[0][0]).toBe(uPyHexFile);
+    expect(addIntelHexFilesSpy.mock.calls[0][2]).toBeTruthy();
   });
 
   it('getIntelHex called with argument hex string.', () => {

src/micropython-fs-builder.ts

@@ -387,14 +387,17 @@ function addIntelHexFile(
  */
 function addIntelHexFiles(
   intelHex: string,
-  files: { [filename: string]: Uint8Array }
-): string {
+  files: { [filename: string]: Uint8Array },
+  returnBytes: boolean = false
+): string | Uint8Array {
   const intelHexClean = cleanseOldHexFormat(intelHex);
   let intelHexMap: MemoryMap = MemoryMap.fromHex(intelHexClean);
   Object.keys(files).forEach((filename) => {
     intelHexMap = addMemMapFile(intelHexMap, filename, files[filename]);
   });
-  return intelHexMap.asHexString() + '\n';
+  return returnBytes
+    ? intelHexMap.slicePad(0, FLASH_END)
+    : intelHexMap.asHexString() + '\n';
 }
 
 /**

src/micropython-fs-hex.ts

@@ -260,6 +260,26 @@ export class MicropythonFsHex implements FsInterface {
     Object.values(this._files).forEach((file) => {
       files[file.filename] = file.getBytes();
     });
-    return addIntelHexFiles(finalHex, files);
+    return addIntelHexFiles(finalHex, files) as string;
+  }
+
+  /**
+   * Generate a byte array of the MicroPython and filesystem data.
+   *
+   * @throws {Error} When a file doesn't have any data.
+   * @throws {Error} When there are issues calculating file system boundaries.
+   * @throws {Error} When there is no space left for a file.
+   *
+   * @param intelHex - Optionally provide a different Intel Hex to include the
+   *    filesystem into.
+   * @returns A Uint8Array with MicroPython and the filesystem included.
+   */
+  getIntelHexBytes(intelHex?: string): Uint8Array {
+    const finalHex = intelHex || this._intelHex;
+    const files: { [filename: string]: Uint8Array } = {};
+    Object.values(this._files).forEach((file) => {
+      files[file.filename] = file.getBytes();
+    });
+    return addIntelHexFiles(finalHex, files, true) as Uint8Array;
   }
 }