feat(demo): CircuitPython demo (#121)

* Add CircuitPython filesystem functionality
* Consolidate MicroPython and CircuitPython demo files
* Update README with CircuitPython instructions

Author: tekktrik

README.md

@@ -37,7 +37,7 @@ npm install
 npm run start:micropython
 ```
 
-and enjoy the MicroPython REPL! Quit the REPL with Ctrl+X. A different UF2 image can be loaded by supplying the `--image` option:
+and enjoy the MicroPython REPL! Quit the REPL with Ctrl+X. A different MicroPython UF2 image can be loaded by supplying the `--image` option:
 
 ```
 npm run start:micropython -- --image=my_image.uf2
@@ -53,7 +53,7 @@ For using the MicroPython demo code in tests, the `--expect-text` can come handy
 
 #### Filesystem support
 
-With MicroPython – and probably also CircuitPython – you can use the filesystem on the Pico. This becomes useful as more than one script file is used in your code. Just put a [LittleFS](https://github.com/littlefs-project/littlefs) formatted filesystem image called `littlefs.img` into the rp2040js root directory, and your `main.py` will be automatically started from there.
+With MicroPython, you can use the filesystem on the Pico. This becomes useful as more than one script file is used in your code. Just put a [LittleFS](https://github.com/littlefs-project/littlefs) formatted filesystem image called `littlefs.img` into the rp2040js root directory, and your `main.py` will be automatically started from there.
 
 A simple way to create a suitable LittleFS image containing your script files is outlined in [create_littlefs_image.py](https://github.com/tomods/GrinderController/blob/358ad3e0f795d8cc0bdf4f21bb35f806871d433f/tools/create_littlefs_image.py).
 So, using [littlefs-python](https://pypi.org/project/littlefs-python/), you can do the following:
@@ -74,6 +74,39 @@ Other ways of creating LittleFS images can be found [here](https://github.com/wo
 
 Currently, the filesystem is not writeable, as the SSI peripheral required for flash writing is not implemented yet. If you're interested in hacking, see the discussion in https://github.com/wokwi/rp2040js/issues/88 for a workaround.
 
+### CircuitPython code
+
+To run the CircuitPython demo, you can follow the directions above for MicroPython, except download [adafruit-circuitpython-raspberry_pi_pico-en_US-8.0.2.uf2](https://adafruit-circuit-python.s3.amazonaws.com/bin/raspberry_pi_pico/en_US/adafruit-circuitpython-raspberry_pi_pico-en_US-8.0.2.uf2) instead of the MicroPython UF2 file. Place it in the rp2040js root directory, then run:
+
+```
+npm install
+npm run start:circuitpython
+```
+
+and start the CircuitPython REPL! The rest of the experience is the same as the MicroPython demo (Ctrl+X to exit, using the `--image` and
+`--gdb` options, etc).
+
+#### Filesystem support
+
+For CircuitPython, you can create a FAT12 filesystem in Linux using the `truncate` and `mkfs.vfat` utilities:
+
+```shell
+truncate fat12.img -s 1M  # make the image file
+mkfs.vfat -F12 -S512 fat12.img  # create the FAT12 filesystem
+```
+
+You can then mount the filesystem image and add files to it:
+
+```shell
+mkdir fat12  # create the mounting folder if needed
+sudo mount -o loop fat12.img fat12/  # mount the filesystem to the folder
+sudo cp code.py fat12/  # copy code.py to the filesystem
+sudo umount fat12/  # unmount the filesystem
+```
+
+While CircuitPython does not typically use a writeable filesystem, note that this functionality is unavailable (see MicroPython filesystem
+support section for more details).
+
 ## Learn more
 
 - [Live-coding stream playlist](https://www.youtube.com/playlist?list=PLLomdjsHtJTxT-vdJHwa3z62dFXZnzYBm)

demo/load-flash.ts

@@ -7,17 +7,29 @@ const MICROPYTHON_FS_FLASH_START = 0xa0000;
 const MICROPYTHON_FS_BLOCKSIZE = 4096;
 const MICROPYTHON_FS_BLOCKCOUNT = 352;
 
-export function loadMicropythonFlashImage(filename: string, rp2040: RP2040) {
+const CIRCUITPYTHON_FS_FLASH_START = 0x100000;
+const CIRCUITPYTHON_FS_BLOCKSIZE = 4096;
+const CIRCUITPYTHON_FS_BLOCKCOUNT = 512;
+
+function loadFlashImage(filename: string, rp2040: RP2040, flashStart: number, blockSize: number) {
   const file = openSync(filename, 'r');
-  const buffer = new Uint8Array(MICROPYTHON_FS_BLOCKSIZE);
-  let flashAddress = MICROPYTHON_FS_FLASH_START;
+  const buffer = new Uint8Array(blockSize);
+  let flashAddress = flashStart;
   while (readSync(file, buffer) === buffer.length) {
     rp2040.flash.set(buffer, flashAddress);
     flashAddress += buffer.length;
   }
   closeSync(file);
 }
 
+export function loadMicropythonFlashImage(filename: string, rp2040: RP2040) {
+  loadFlashImage(filename, rp2040, MICROPYTHON_FS_FLASH_START, MICROPYTHON_FS_BLOCKSIZE);
+}
+
+export function loadCircuitpythonFlashImage(filename: string, rp2040: RP2040) {
+  loadFlashImage(filename, rp2040, CIRCUITPYTHON_FS_FLASH_START, CIRCUITPYTHON_FS_BLOCKSIZE);
+}
+
 export function loadUF2(filename: string, rp2040: RP2040) {
   const file = openSync(filename, 'r');
   const buffer = new Uint8Array(512);

demo/micropython-run.ts

@@ -3,7 +3,7 @@ import { GDBTCPServer } from '../src/gdb/gdb-tcp-server';
 import { USBCDC } from '../src/usb/cdc';
 import { ConsoleLogger, LogLevel } from '../src/utils/logging';
 import { bootromB1 } from './bootrom';
-import { loadUF2, loadMicropythonFlashImage } from './load-flash';
+import { loadUF2, loadMicropythonFlashImage, loadCircuitpythonFlashImage } from './load-flash';
 import fs from 'fs';
 import minimist from 'minimist';
 
@@ -12,20 +12,30 @@ const args = minimist(process.argv.slice(2), {
     'image', // UF2 image to load; defaults to "rp2-pico-20210902-v1.17.uf2"
     'expect-text', // Text to expect on the serial console, process will exit with code 0 if found
   ],
-  boolean: 'gdb', // start GDB server on 3333
+  boolean: [
+    'gdb', // start GDB server on 3333
+    'circuitpython', // use CircuitPython instead of MicroPython
+  ],
 });
 const expectText = args['expect-text'];
 
 const mcu = new RP2040();
 mcu.loadBootrom(bootromB1);
 mcu.logger = new ConsoleLogger(LogLevel.Error);
 
-const imageName = args.image ?? 'rp2-pico-20210902-v1.17.uf2';
+let imageName: string;
+if (!args.circuitpython) {
+  imageName = args.image ?? 'rp2-pico-20210902-v1.17.uf2';
+} else {
+  imageName = args.image ?? 'adafruit-circuitpython-raspberry_pi_pico-en_US-8.0.2.uf2';
+}
 console.log(`Loading uf2 image ${imageName}`);
 loadUF2(imageName, mcu);
 
-if (fs.existsSync('littlefs.img')) {
+if (fs.existsSync('littlefs.img') && !args.circuitpython) {
   loadMicropythonFlashImage('littlefs.img', mcu);
+} else if (fs.existsSync('fat12.img') && args.circuitpython) {
+  loadCircuitpythonFlashImage('fat12.img', mcu);
   // Instead of reading from file, it would also be possible to generate the LittleFS image on-the-fly here, e.g. using
   // https://github.com/wokwi/littlefs-wasm or https://github.com/littlefs-project/littlefs-js
 }
@@ -37,9 +47,13 @@ if (args.gdb) {
 
 const cdc = new USBCDC(mcu.usbCtrl);
 cdc.onDeviceConnected = () => {
-  // We send a newline so the user sees the MicroPython prompt
-  cdc.sendSerialByte('\r'.charCodeAt(0));
-  cdc.sendSerialByte('\n'.charCodeAt(0));
+  if (!args.circuitpython) {
+    // We send a newline so the user sees the MicroPython prompt
+    cdc.sendSerialByte('\r'.charCodeAt(0));
+    cdc.sendSerialByte('\n'.charCodeAt(0));
+  } else {
+    cdc.sendSerialByte(3);
+  }
 };
 
 let currentLine = '';

package.json

@@ -34,6 +34,7 @@
     "lint": "eslint . --ext .ts",
     "start": "ts-node demo/emulator-run.ts",
     "start:micropython": "ts-node demo/micropython-run.ts",
+    "start:circuitpython": "ts-node demo/micropython-run.ts --circuitpython",
     "start:gdbdiff": "ts-node debug/gdbdiff.ts",
     "test": "jest"
   },