From e5550533a21e5d0f8944fc1712569f67385e21cf Mon Sep 17 00:00:00 2001 From: Matt Hillsdon Date: Tue, 28 Jan 2025 17:28:03 +0000 Subject: [PATCH] Modernise docs + link to API --- docs/quick-guide.md | 78 ++++++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 33 deletions(-) diff --git a/docs/quick-guide.md b/docs/quick-guide.md index 7daf499..c6f076a 100644 --- a/docs/quick-guide.md +++ b/docs/quick-guide.md @@ -16,19 +16,21 @@ $ npm add @microbit/microbit-fs ### Initialise -Initialise a File System instance with a MicroPython Intel Hex string using {@link MicropythonFsHex | MicropythonFsHex class}. +Initialise a filesystem with a MicroPython Intel Hex string using {@link MicropythonFsHex | MicropythonFsHex class}. ```js +import { MicropythonFsHex } from "@microbit/microbit-fs"; + // Create a new FileSystem instance passing the MicroPython Intel Hex string -var micropythonFs = new microbitFs.MicropythonFsHex(IntelHexStr); +const micropythonFs = new MicropythonFsHex(IntelHexStr); // There are some options available in the constructor -micropythonFs = new microbitFs.MicropythonFsHex(IntelHexStr, { maxFsSize: 20 * 1024}); +micropythonFs = new MicropythonFsHex(IntelHexStr, { maxFsSize: 20 * 1024}); ``` -### Import files +### Import files Import files from a different MicroPython hex file with filesystem using {@link MicropythonFsHex.importFilesFromIntelHex | importFilesFromIntelHex}. ``` -var addedFilenames = micropythonFs.importFilesFromIntelHex(UploadedHexWithUserFiles); +const addedFilenames = micropythonFs.importFilesFromIntelHex(UploadedHexWithUserFiles); addedFilenames = micropythonFs.importFilesFromIntelHex(UploadedHexWithUserFiles, {overwrite: false, formatFirst: false}); ``` @@ -41,69 +43,79 @@ micropythonFs.create('filename.txt', 'Error thrown if file already exists.'); micropythonFs.write('filename.txt', 'Create or overwrite a file.'); // Append not yet implemented micropythonFs.append('filename.txt', 'Add additional content.'); -var fileContent = micropythonFs.read('filename.txt'); -var fileContentByteArray = micropythonFs.readBytes('filename.txt'); +const fileContent = micropythonFs.read('filename.txt'); +const fileContentByteArray = micropythonFs.readBytes('filename.txt'); if (micropythonFs.exists('filename.txt')) { micropythonFs.remove('filename.txt'); } -var fileSizeInBytes = micropythonFs.size('filename.txt'); -var fileList = micropythonFs.ls(); +const fileSizeInBytes = micropythonFs.size('filename.txt'); +const fileList = micropythonFs.ls(); ``` ### Filesystem size -To get file size information use {@link MicropythonFsHex.getStorageSize | getStorageSize}, +{@link MicropythonFsHex} can query storage usage: + ``` // Filesystem size information -var fsSize = micropythonFs.getStorageSize(); -var fsAvailableSize = micropythonFs.getStorageUsed(); -var fsUsedSize = micropythonFs.getStorageRemaining(); +const fsSize = micropythonFs.getStorageSize(); +const fsAvailableSize = micropythonFs.getStorageUsed(); +const fsUsedSize = micropythonFs.getStorageRemaining(); // You can also provide an artificial storage size micropythonFs.setStorageSize(20 * 1024); // Generate a new hex string or Uint8Array with MicroPython and the files -var intelHexStrWithFs = micropythonFs.getIntelHex(); -var intelHexBytesWithFs = micropythonFs.getIntelHexBytes(); +const intelHexStrWithFs = micropythonFs.getIntelHex(); +const intelHexBytesWithFs = micropythonFs.getIntelHexBytes(); ``` -Using multiple MicroPython Intel Hex files to generate a Universal Hex: +## Supporting V1 and V2 micro:bit versions with a Universal Hex + +You can create a Universal Hex by passing a hex for each board version to the {@link MicropythonFsHex} constructor: ```js +import { MicropythonFsHex, microbitBoardId } from "@microbit/microbit-fs"; + // Create a new FileSystem instance passing the MicroPython Intel Hex string -var micropythonFs = new microbitFs.MicropythonFsHex([ - { hex: uPy1HexFile, boardId: microbitFs.microbitBoardId.V1 }, - { hex: uPy2HexFile, boardId: microbitFs.microbitBoardId.V2 }, +const micropythonFs = new MicropythonFsHex([ + { hex: uPy1HexFile, boardId: microbitBoardId.V1 }, + { hex: uPy2HexFile, boardId: 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}); +const 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(microbitFs.microbitBoardId.V1); -var uPy1IntelHexBytesWithFs = micropythonFs.getIntelHexBytes(microbitFs.microbitBoardId.V1); -var uPy2IntelHexStrWithFs = micropythonFs.getIntelHex(microbitFs.microbitBoardId.V2); -var uPy2IntelHexBytesWithFs = micropythonFs.getIntelHexBytes(microbitFs.microbitBoardId.V2); +const uPy1IntelHexStrWithFs = micropythonFs.getIntelHex(microbitBoardId.V1); +const uPy1IntelHexBytesWithFs = micropythonFs.getIntelHexBytes(microbitBoardId.V1); +const uPy2IntelHexStrWithFs = micropythonFs.getIntelHex(microbitBoardId.V2); +const uPy2IntelHexBytesWithFs = micropythonFs.getIntelHexBytes(microbitBoardId.V2); // Generate a new Universal hex string with all MicroPython+files data -var universalHexStrWithFs = micropythonFs.getUniversalHex(); +const universalHexStrWithFs = micropythonFs.getUniversalHex(); ``` ## Append and extract Python code from known flash location -To add and remove the Python code using the old format: + +To add and remove the Python code use {@link addIntelHexAppendedScript}: ```js -var finalHexStr = microbitFs.addIntelHexAppendedScript(originalIntelHexStr, 'print("hello world!")'); -if (microbitFs.isAppendedScriptPresent(finalHexStr)) { - var pythonCode = microbitFs.getIntelHexAppendedScript(finalHexStr); +import { isAppendedScriptPresent, getIntelHexAppendedScript } from "@microbit/microbit-fs"; + +const finalHexStr = addIntelHexAppendedScript(originalIntelHexStr, 'print("hello world!")'); +if (isAppendedScriptPresent(finalHexStr)) { + const pythonCode = getIntelHexAppendedScript(finalHexStr); } ``` -## Read device memory info data +## Read device memory information + +To read device memory information use {@link getIntelHexDeviceMemInfo}: ```js -var deviceMemInfoData = getIntelHexDeviceMemInfo(IntelHexStr); +const deviceMemInfoData = getIntelHexDeviceMemInfo(IntelHexStr); console.log('Flash Page Size:' + deviceMemInfoData.flashPageSize); console.log('Flash Size:' + deviceMemInfoData.flashSize); console.log('Flash Start Address:' + deviceMemInfoData.flashStartAddress); @@ -114,4 +126,4 @@ console.log('Filesystem Start Address:' + deviceMemInfoData.fsStartAddress); console.log('Filesystem End Address:' + deviceMemInfoData.fsEndAddress); console.log('MicroPython Version:' + deviceMemInfoData.uPyVersion); console.log('Device Version: ' + deviceMemInfoData.deviceVersion); -``` \ No newline at end of file +```