uf2flash

A Node.js package to detect UF2 bootloader drives and flash firmware files onto them.

Description

This package provides utilities for interacting with devices that expose a UF2 bootloader as a mass storage device. It can automatically detect connected UF2 drives and copy firmware (.uf2) files to them, effectively flashing the device.

It is built using TypeScript and relies on native Node.js modules (fs, path) and the node-disk-info package to list available drives.

Installation

Install the package using npm or yarn:

npm install @rm-netsu/uf2flash
# or
yarn add @rm-netsu/uf2flash

Usage

Finding UF2 Drives

You can find all currently connected drives that appear to be UF2 bootloaders:

import { findUf2Drives } from '@rm-netsu/uf2flash';

async function listUf2Drives() {
    try {
        const uf2Drives = await findUf2Drives();

        if(uf2Drives.length > 0) {
            console.log('Found UF2 drives:', uf2Drives);
        }
        else {
            console.log('No UF2 drives found.');
        }
    }
    catch(error) {
        console.error('Error finding UF2 drives:', error);
    }
}

listUf2Drives();

The findUf2Drives function returns an array of drive paths (e.g., /Volumes/RPI-RP2 on macOS, E:\ on Windows, /media/user/RPI-RP2 on Linux).

Flashing Firmware

To flash a .uf2 firmware file to a detected UF2 drive:

import { flashFirmware } from '@rm-netsu/uf2flash';
import * as path from 'path';

async function performFlash(firmwareFilePath: string) {
    const absoluteFirmwarePath = path.resolve(firmwareFilePath); // Ensure absolute path

    try {
        console.log(`Attempting to flash ${absoluteFirmwarePath}...`);
        const destinationPath = await flashFirmware(absoluteFirmwarePath);
        console.log(`Firmware flashed successfully to: ${destinationPath}`);
        // The device might automatically disconnect/reconnect after flashing
    }
    catch(error: any) {
        console.error(`Failed to flash firmware: ${error.message}`);
        // Handle specific errors, e.g., "UF2 drive not found"
        if(error.message === 'UF2 drive not found') {
            console.error('Please ensure your device is connected and in UF2 bootloader mode.');
        }
    }
}

// Example usage: flash a firmware file named 'my_firmware.uf2'
performFlash('./my_firmware.uf2');

Important: The flashFirmware function currently flashes to the first UF2 drive found by findUf2Drives. If multiple UF2 devices are connected, it will only flash to the first one listed.

Checking a Specific Drive

You can check if a specific path appears to be a UF2 drive:

import { isUf2Drive } from '@rm-netsu/uf2flash';

async function checkDrive(drivePath: string) {
    try {
        const isUf2 = await isUf2Drive(drivePath);
        if(isUf2) {
            console.log(`${drivePath} is likely a UF2 drive.`);
        }
        else {
            console.log(`${drivePath} does not appear to be a UF2 drive.`);
        }
    }
    catch(error) {
        onsole.error(`Error checking drive ${drivePath}:`, error);
    }
}

// Example: check a potential drive path
checkDrive('/Volumes/MY_DEVICE');

API Reference

findUf2Drives(): Promise<string[]>

Asynchronously finds and returns an array of paths for drives that match the UF2 bootloader signature (INDEX.HTM and INFO_UF2.TXT files in the root).

flashFirmware(firmwarePath: string): Promise<string>

Asynchronously copies the firmware file located at firmwarePath to the first detected UF2 drive.

• firmwarePath: The path to the .uf2 firmware file to flash.
• Returns: A Promise that resolves with the destination path on the UF2 drive if successful.
• Throws:
  • Error('UF2 drive not found'): If no UF2 drive is detected.
  • Other errors related to file system operations (e.g., permissions, file not found) from fs.copyFile.

isUf2Drive(drivePath: string): Promise<boolean>

Asynchronously checks if the directory at drivePath contains the necessary files (INDEX.HTM, INFO_UF2.TXT) to be considered a UF2 bootloader drive.

• drivePath: The path to the potential drive root.
• Returns: A Promise that resolves to true if the drive is likely a UF2 drive, false otherwise.

REQUIRED_FILES: string[]

An array constant listing the filenames (['INDEX.HTM', 'INFO_UF2.TXT']) used to identify a UF2 bootloader drive.

Limitations

• Currently, flashFirmware only flashes to the first UF2 drive found. It does not provide an option to select a specific drive if multiple are present.
• Error handling in the provided code is basic (logging and re-throwing). More sophisticated error handling might be needed depending on the application.
• Relies on node-disk-info which works across Windows, macOS, and Linux, but behavior can sometimes vary slightly between operating systems.

Contributing

Feel free to open issues or submit pull requests if you find bugs or want to add features.