node-rasbberrypi-usbboot

Transforms Raspberry Pi Compute Modules and Zeros to mass storage devices.

Usage

For usage, see the example.

On most GNU/Linux distributions, you'll need to run this as root.

Import UsbbootScanner, instanciate it, then on the instance attach the following event listeners:

• attach: a device was connected and we started transforming it to a mass storage device;
• detach: a device was detached, note that this could mean that it was physically detached or that it was successfully transformed into a mass storage device;
• error: an error occured.

The attach and detach event listeners will get a UsbbootDevice as parameter. This object will emit progress events which parameter is the percentage of completion. The progress will be 100 when the device reattaches itself as a mass storage device. This will be followed by a detach event from the UsbbootScanner (because the device will no longer be a usbboot device).

Details

This is heavily based on Raspberry Pi USB booting code.

It should support Raspberry Pi Compute Modules and Raspberry Pi Zeros.

This module will upload a slightly more complex kernel to the pis than the original code above, it allows the devices to reach higher write speeds at the cost of a longer preparation phase.

Troubleshooting

If you have any trouble using this module, please check if it works with the original usb boot link above.

You can enable debug output by setting the DEBUG env var to node-raspberrypi-usbboot.

Change Log

All notable changes to this project will be documented in this file automatically by Versionist. DO NOT EDIT THIS FILE MANUALLY! This project adheres to Semantic Versioning.

v1.1.3

(2025-04-07)

• Lock file maintenance [balena-renovate[bot]]

v1.1.2

(2025-04-02)

• Update dependency rimraf to v6 [balena-renovate[bot]]

v1.1.1

(2025-03-19)

• Update dependency @balena/lint to v8.2.8 [balena-renovate[bot]]

v1.1.0

(2024-06-07)

• minor: allow passing custom assets to start SB protected CM4 [Edwin Joassart]
• patch: fix linter, formatting and old errors [Edwin Joassart]

v1.0.8

(2024-04-12)

• patch: bump all dependencies to latest [Edwin Joassart]

v1.0.7

(2023-05-31)

• Update flowzone.yml [Kyle Harding]

v1.0.6

(2023-01-16)

• patch: updated start4.elf pieeprom-2021-07-06 [Peter Makra]

v1.0.5

(2023-01-11)

• patch: removed device filtering from iSerial check [Peter Makra]
• patch: WIP force second stage [Peter Makra]

v1.0.4

(2022-10-21)

• switch from concourse to flowzone [Zane Hitchcox]

v1.0.3

(2022-04-20)

• update usb [Zane Hitchcox]

v1.0.2

(2021-12-06)

• blobs/raspberrypi: Update start_cd.elf to latest patched revision [Alexandru Costache]

v1.0.1

(2021-09-30)

• patch: Add node14 tests [Lorenzo Alberto Maria Ambrosi]

v1.0.0

(2021-09-30)

• major: Switch to tessel/node-usb [Lorenzo Alberto Maria Ambrosi]

v0.3.1

(2021-03-29)

• Fix progress calculation for cm4 [Alexis Svinartchouk]

v0.3.0

(2021-03-26)

• Add support for compute module 4 [Alexis Svinartchouk]
• Fix size endianness of boot_message_t message [Alexis Svinartchouk]

v0.2.11

(2021-02-10)

• Update @balena.io/usb from 1.3.12 to 1.3.14 [Alexis Svinartchouk]

v0.2.10

(2020-11-30)

• Update typescript to v4.1.2 [Alexis Svinartchouk]
• Add versionbot changelog [Alexis Svinartchouk]

v0.2.9

(2020-07-27)

• Remove bluebird dependency [Alexis Svinartchouk]

v0.2.8

(2020-06-11)

• Add .resinci.yml file [Alexis Svinartchouk]
• Update dependencies, target es2018 [Alexis Svinartchouk]
• Update resin-lint to @balena/lint [Alexis Svinartchouk]
• Fix fin not detaching after receiving files on some computers [Alexis Svinartchouk]

0.2.7 - 2019-10-15

• Import @balena.io/usb instead of usb [Alexis Svinartchouk]

0.2.6 - 2019-10-15

• Get @balena.io/usb from npm [Alexis Svinartchouk]

0.2.5 - 2019-08-19

• Use balena-io org for node-usb [Alexis Svinartchouk]

0.2.4 - 2019-05-22

• Dependencies: bump node-usb to v1.3.10 to enable Node 12 builds [Gergely Imreh]

0.2.3 - 2019-03-20

• Don't crash on initialization [Juan Cruz Viotti]

0.2.2 - 2019-03-20

• Node-usb: Upgrade to v1.3.6 [Juan Cruz Viotti]

0.2.1 - 2019-03-19

• Add noUnusedLocals and noUnusedParameters to tsconfig.json [Alexis Svinartchouk]
• Poll usb.getDeviceList() every 2 seconds. [Juan Cruz Viotti]
• Improve USB boot stability [Juan Cruz Viotti]

0.2.0 - 2019-03-18

• Export isUsbBootCapableUSBDevice [Alexis Svinartchouk]
• Update resin-lint to ^3.0.1 [Alexis Svinartchouk]
• Use @types/usb instead of our own typings [Alexis Svinartchouk]

0.1.0 - 2019-02-07

• Update usbboot firmware to support the CM3+ [curcuz]

v0.0.13 - 2018-10-21

• Update resin-lint, run prettier on all ts files [Alexis Svinartchouk]

v0.0.12 - 2018-10-19

• Claim usb interface before running usbboot [Juan Cruz Viotti]

v0.0.11 - 2018-10-19

• Remove mutex in epWrite [Alexis Svinartchouk]

v0.0.10 - 2018-10-18

• Add a mutex around epWrite. [Alexis Svinartchouk]
• Add the usb port id to each debug message [Alexis Svinartchouk]

v0.0.9 - 2018-10-10

• Build before publishing [Alexis Svinartchouk]

v0.0.8 - 2018-10-10

• Use fork of node-usb to disable libudev [Alexis Svinartchouk]

v0.0.7 - 2018-07-06

• Update node-usb to 1.3.2 #11 [Alexis Svinartchouk]

v0.0.6 - 2018-07-03

• When an error happens during a usb transfer, don't emit an error. #10 [Alexis Svinartchouk]

v0.0.5 - 2018-06-11

• Target es6 #9 [Alexis Svinartchouk]

v0.0.4 - 2018-05-15

• Emit a 'ready' event. #7 [Alexis Svinartchouk]

v0.0.3 - 2018-05-10

• UsbbootScanner.step is private #5 [Alexis Svinartchouk]

v0.0.2 - 2018-05-09

• Add types to package.json #3 [Alexis Svinartchouk]

v0.0.1 - 2018-05-08

• Initial release [Alexis Svinartchouk]