libsuperbird

WebUSB library for flashing the Spotify Car Thing (Superbird). Runs entirely in the browser.

[!NOTE] This doesn't work on Firefox or Safari based browsers due to the lack of WebUSB. Use a good browser.

npm install libsuperbird

Usage

import { Superbird } from 'libsuperbird';

const thing = await Superbird.connect({
  bl2: await fetch('/superbird.bl2.encrypted.bin').then(r => r.blob()),
  bootloader: await fetch('/superbird.bootloader.img').then(r => r.blob()),
  onStatus: status => console.log(status),
});

await thing.restorePartition('boot_a', bootImageBlob, {
  onProgress: p => console.log(`${p.percent.toFixed(1)}%`),
});

• Calling connect() must be in a secure context and must be done via a click handler.

Sparse flashing

Filesystem images are mostly zeros, and normally every zero byte crosses USB and gets written. Passing sparse: true to writeUserArea erases the complete 4 MiB eMMC erase groups covered by the image and skips 8 MiB staging chunks that contain only zeros and lie entirely inside a successfully erased range. If U-Boot refuses to erase part of the range (for example because it overlaps the protected key area), the erase is split around the rejected erase groups; chunks over unerased groups are always written in full, as are unaligned edges and nonzero chunks.

await thing.writeUserArea(0, image, { sparse: true });

restorePartition always writes the complete image.

Browser support

WebUSB needs a Chromium browser on a secure context (https or localhost). On Linux you also need a udev rule:

SUBSYSTEM=="usb", ATTRS{idVendor}=="1b8e", ATTRS{idProduct}=="c003", MODE="0666"