raspimcu

raspimcu is a Node.js library and CLI for working with Raspberry Pi microcontroller boards such as the Pico. It helps you discover devices, move files to and from mounted UF2 volumes, switch boards into filesystem (BOOTSEL) mode, and manage firmware images.

Features

• List connected Raspberry Pi MCUs and report whether they are in serial or filesystem mode.
• Copy files and directories to and from mounted UF2 storage volumes.
• Upload, download, or execute commands on Raspberry Pi boards running MicroPython via mpremote.
• Reboot a device into filesystem mode via picotool.
• Upload or download UF2 firmware images from a mounted board.
• Works as both a Node.js module and an npx-friendly CLI.

Installation

npm install raspimcu

or run the CLI via npx without installing globally:

npx raspimcu devices

Requirements

• Node.js 18 or newer.
• picotool in your PATH for rebooting boards into filesystem mode.
• mpremote in your PATH for interacting with MicroPython firmware.
• Access to mounted UF2 volumes created by Raspberry Pi MCUs (e.g. /Volumes/RPI-RP2, /media/<user>/RPI-RP2).

CLI Usage

List detected boards:

raspimcu devices

Reboot a specific board into filesystem mode using picotool:

raspimcu put-fs --serial E6606603B7313128

Copy a file onto the mounted UF2 drive:

raspimcu push firmware.uf2 /Volumes/RPI-RP2

Copy files from the device back to your machine:

raspimcu pull /Volumes/RPI-RP2 logs.txt ./logs.txt

Upload firmware with a custom filename:

raspimcu firmware upload firmware.uf2 /Volumes/RPI-RP2 --name pico.uf2

Download firmware from the device (auto-detects the first UF2 file if you do not specify --name):

raspimcu firmware download /Volumes/RPI-RP2 ./downloaded.uf2

Inspect the INFO_UF2.TXT metadata from a mounted board:

raspimcu firmware info /Volumes/RPI-RP2

Upload a file to a MicroPython-enabled board over serial:

raspimcu micropython upload /dev/ttyACM0 ./main.py main.py

Download a file (or directory with --recursive) from the board:

raspimcu micropython download /dev/ttyACM0 main.py ./backups/main.py

Run a one-off REPL command (omit --exec for an interactive session):

raspimcu micropython repl /dev/ttyACM0 --exec "import os; print(os.listdir())"

Use raspimcu devices --json to integrate the discovery output into other tooling.

Library Usage

import {
  listDevices,
  copyToDevice,
  copyFromDevice,
  putDeviceInFsMode,
  uploadFirmware,
  downloadFirmware,
  readInfoFile,
  uploadToMicropython,
  downloadFromMicropython
} from 'raspimcu';

async function flashFirmware() {
  const { devices } = await listDevices();
  console.log(devices);

  // Reboot the first serial device into filesystem mode.
  if (devices.length && devices[0].type === 'serial') {
    await putDeviceInFsMode({ serialNumber: devices[0].serialNumber });
  }

  // Copy a UF2 once the device exposes a mount point.
  await uploadFirmware('./firmware.uf2', '/Volumes/RPI-RP2');
}

async function syncScripts(serialPath) {
  await uploadToMicropython(serialPath, './src', 'lib');
  await downloadFromMicropython(serialPath, 'main.py', './backups/main.py');
}

Each helper throws descriptive errors when paths are missing or commands fail, making it straightforward to compose your own workflows.

Automated Tests

This project uses Vitest for unit testing. Run the full suite with:

npm test

The tests cover key file-transfer helpers and firmware upload/download flows using temporary directories, so you can run them without attaching physical hardware.

Manual Firmware Test Scripts

The manual-tests folder contains small scripts that exercise the firmware helpers directly against a mounted UF2 volume. They are useful sanity checks when working with real hardware:

• node manual-tests/upload-firmware.js <firmware.uf2> <mount-point> [target-name.uf2]
• node manual-tests/download-firmware.js <mount-point> <destination.uf2> [filename.uf2]

Both scripts print progress information and propagate any validation errors raised by the library.

License

Licensed under the MIT License.