Registry / devops / node-raspberrypi-usbboot

node-raspberrypi-usbboot

library1.1.9jsnpmunverified

A Node.js library that transforms Raspberry Pi Compute Modules and Zeros into mass storage devices via USB boot. Current stable version is 1.1.9. It is based on Raspberry Pi's official usbboot code but uses a more complex kernel for higher write speeds during the preparation phase. The library is TypeScript-native with bundled type definitions and uses an event-driven API (UsbbootScanner with attach/detach/error events). It requires root/sudo on most Linux distributions and only supports Linux. Alternative implementations include the official Raspberry Pi USB boot tool (C-based) and other platform-specific tools.

devops

npm install node-raspberrypi-usbboot

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-RASPBERRYPI-U

node-raspberrypi-usbboot

devopsjavascriptv1.1.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UsbbootScanner

✓ import { UsbbootScanner } from 'node-raspberrypi-usbboot'

✗ const UsbbootScanner = require('node-raspberrypi-usbboot')

Library is ESM-only; CommonJS require will fail. Named import only, no default export.

UsbbootDevice

✓ import { UsbbootDevice } from 'node-raspberrypi-usbboot'

✗ import UsbbootDevice from 'node-raspberrypi-usbboot'

TypeScript type/class for the device object emitted by events. Use named import.

UsbbootScanner (type)

✓ import type { UsbbootScanner } from 'node-raspberrypi-usbboot'

For TypeScript type-only imports when you only need the type.

default

✓

✗ import UsbbootScanner from 'node-raspberrypi-usbboot'

There is no default export; attempting default import will result in undefined.

Shows event-driven setup of UsbbootScanner: attach, progress, detach, and error events. Must be run as root on Linux.

import { UsbbootScanner } from 'node-raspberrypi-usbboot'; const scanner = new UsbbootScanner(); scanner.on('attach', (device) => { console.log('Device attached, converting to mass storage...'); device.on('progress', (percentage) => { console.log(`Progress: ${percentage}%`); if (percentage === 100) { console.log('Device ready as mass storage.'); } }); }); scanner.on('detach', (device) => { console.log('Device detached.'); }); scanner.on('error', (err) => { console.error('Error:', err.message); }); scanner.start(); setTimeout(() => { scanner.stop(); }, 30000);

Debug

Known issues

breakingLibrary requires root/sudo on most Linux distributions. Running without elevated permissions will fail to access USB devices.

fix

Run your Node.js script with sudo: sudo node yourscript.js

affects: >=0.0.0

gotchaLibrary is ESM-only. Using CommonJS require() will throw an error.

fix

Use import syntax or set type: module in package.json

affects: >=1.0.0

gotchaThe detach event fires both when the device is physically removed and when the conversion to mass storage is complete. Do not assume the device is lost.

fix

Check device's progress or use additional logic to differentiate disconnection from conversion completion.

affects: >=0.0.0

deprecatedThe package previously had a callback-based API; event-based API is the only supported pattern now.

fix

Migrate to event listeners (attach, detach, error) as shown in quickstart.

affects: <1.0.0

gotchaWorks only on Linux. Windows and macOS are not supported and will not enumerate USB devices correctly.

fix

Use a Linux environment (physical, VM, or WSL2 with USB passthrough).

affects: >=0.0.0

Errors

Common errors & fixes

Error: LIBUSB_ERROR_ACCESS

The process does not have permission to access USB devices (not running as root).

fix

Run the script with sudo: sudo node yourscript.js

ERR_MODULE_NOT_FOUND

Trying to require('node-raspberrypi-usbboot') with CommonJS; this package is ESM-only.

fix

Use dynamic import: await import('node-raspberrypi-usbboot'); or set type: module in package.json and use static import.

TypeError: scanner.on is not a function

UsbbootScanner was not instantiated with new; e.g., const scanner = UsbbootScanner() instead of new UsbbootScanner().

fix

Instantiate with new: const scanner = new UsbbootScanner();

Error: No such device

No Raspberry Pi in usbboot mode was detected on the USB bus.

fix

Ensure the device is connected and in BOOT mode (hold BOOTSEL button while connecting), and that you run as root.

Upgrade

Version history

1.1.9latest on npm

Audit

Dependencies

usbrequiredProvides USB device enumeration and communication via libusb.

debugoptionalUsed for optional debug logging controlled by DEBUG environment variable.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/balena-io-modules/node-raspberrypi-usbboot ↗

packagenode-raspberrypi-usbboot ↗

homepagehttps://github.com/balena-io-modules/node-raspberrypi-usbboot#readme ↗