kdrag0n / fastboot.js

WebUSB implementation of the Android fastboot protocol

fastboot.js

fastboot.js is an implementation of the Android fastboot protocol in JavaScript. It runs in web browsers by using the WebUSB API, which is currently supported by Chrome.

If you're looking for a ready-to-use installer for custom ROMs, see android-webinstall.

Why?

Many users, particularly those with less technical experience, have trouble flashing custom operating systems on Android devices. This is not necessarily their fault; there are many steps in the process that can go wrong. Broken or outdated Android platform tools, missed commands or steps, and many other factors can cause problems during flashing.

WebUSB makes it possible to move most of the complexity into the browser, where the environment is much more controlled and most of the steps can be automated. This makes it easier for users to flash ROMs onto their devices and is more likely to result in success.

Google's Android Flash Tool for AOSP CI images and Pixel factory images is already taking advantage of this, but unfortunately, it is proprietary and closed-source. Furthermore, it only supports flashing the aforementioned images from Google, so flashing custom ROMs with it is not possible. This is where fastboot.js comes in: it is an open-source library that can be used to create web installers for flashing anything.

Features

The following fastboot features are supported:

• Running commands (erase, lock, unlock, getvar, reboot, etc.)
• Flashing raw, bootloader, sparse, and custom AVB key images
• Flashing AOSP factory image zips (update.zip), including firmware, logical partitions, and verified boot keys
• Flashing images larger than the bootloader's maximum download size (by splitting sparse images)
• Flashing logical partitions

Detailed progress callbacks are also provided for many flashing steps.

Installation

This library is available as a package on npm, so you can easily add it to your project:

# Using npm
npm install --save android-fastboot

# Using yarn
yarn add android-fastboot

Examples

A basic demo of fastboot.js can be found here. The source code is included in this repository.

There is also a user-friendly ROM installer available, with a live ProtonAOSP instance that can be used to flash devices officially supported by ProtonAOSP.

Documentation

Documentation generated from JSDoc comments can be found here.

fastboot.js's Issues

Reduce memory usage

Android 13 has greatly increased the required memory for successful flashing. Users have been reporting lots of issues flashing 6th and 7th generation Pixels due to the site process running out of memory. Upgrading zip.js was previously blocked due to a major memory usage increase but there have been substantial changes and it's quite possible that it's now leaner on memory instead of much worse. It's worth trying to see if this problem can be resolved that way.

If upgrading zip.js doesn't resolve this, it would be nice to find another way to reduce memory usage because the portability has suffered a lot due to the memory requirement increase. We're now seeing this as one of the main issues people encounter during flashing. I'm not sure why exactly Android 13 made this so much worse. I wonder if zip.js or the dependencies it has are leaking memory and having additional images / overall more data to flash ended up causing this.

It appears that some API breakage needs to be resolved to update zip.js. I might try this myself soon but I'm unfamiliar with the zip.js API and most of the fastboot.js code.

DOMException: The requested file could not be read, typically due to permission problems that have occurred after a reference to a file was acquired

When I flash a zip file, if read smaill file, it will be ok. but if read big file just like product.img(522MB) it will throw: "
ui.js:107 Uncaught (in promise) DOMException: The requested file could not be read, typically due to permission problems that have occurred after a reference to a file was acquired.
flashSelectedFactoryZip @ ui.js:107
async function (async)
flashSelectedFactoryZip @ ui.js:105"

I think it's not permission related issues.

getvar timeout could be more generous

I used the web installer for GrapheneOS at https://grapheneos.org/install/web and was getting Timeout of 10000 ms exceeded at a particular step. I think it was the Unpacking system step or something.

The browser on my XPS laptop was getting overwhelmed at this step and couldn't complete it in the deadline. I located the timeout in the minified JS file and bumped the timeout from 1e4 to 1e5. After that the installation completed without a hitch.

fastboot.js/src/fastboot.ts

Line 19 in 87b2101

const GETVAR_TIMEOUT = 10000; // ms

Thanks for this project by the way! It's really cool and makes the process a breeze for someone like me not very familiar with Android systems.

How to get not paired devices list？

I used
navigator.usb.getDevices();
to get already paired devices.
But please tell me without using "requestDevice()" how to get not paired devices list.

DOMException: A transfer error has occurred.

I use function "_sendRawPayload" to send buffer and set BULK_TRANSFER_SIZE=50mb

the error: DOMException: A transfer error has occurred.

Is have any transfer limit size ?

Unable to install "android-fastboot" in React Project.

Add more command support

Add command support for "erase", "help", and some others

boot image error

Uncaught (in promise) TypeError: device.bootBlob is not a function
at HTMLFormElement.bootFormFile (ui.js:45:18)

the image works on fastoot ran from any OS..
not from this.

also: fastboot commands are separated by a colon.
so the string in command input should have a replace of " " with ":"

Is any possible can connect multiple devices at a time?

unable to install the .zip into device using flashFactoryZip function

Can you help me in this @kdrag0n

Uncaught (in promise) DOMException: Failed to execute 'open' on 'USBDevice': An operation that changes the device state is in progress.
at FastbootDevice._validateAndConnectDevice

Touble with install firmware for Pixel 7 pro

Hello. I have trouble with installing firmware for Pixel 7 pro using your project. My error is related to the system_dlkm partition, my phone needs to update this partition when i install firmware. Work with partition is not added to version 1.1.3 (this last version), I see your commit in master branch. Tell me when to expect a new version of the project or how you can help me please.

Motorola sparsechunks report wrong progress

Motorola sparsechunk reports number of blocks from full file, sparsechunk is a part of it, sparsechunks can be different size too.

Issue with uploading image due to size

Hello 👋 . I want to flash a device running a custom Android 9 but I am having an issue with one of my image files that is bigger than the max-download-size of the device.

• max-download-size: 536870912 bytes
• size of system.img: 1.8 GB

I have used the ::flashEntryBlob function to flash the image, and it attempts to split the sparse image and upload splits individually. It does so correctly until it reaches a chunk that is bigger than the max-download-size: 537522176 bytes, and the uploading fails with the following error: FastbootError: Bootloader replied with FAIL: Requested download size is more than max allowed. From looking at the source code it seems like the scenario where a chunk would not fit in the upload limit is not covered.

I should also mention that using the Fastboot CLI works just fine, so I am assuming it splits the chunk even further. This it the output from fastboot:

Sending sparse 'system_b' 1/4 (524284 KB)          OKAY [ 16.603s]
Writing 'system_b'                                 OKAY [  0.001s]
Sending sparse 'system_b' 2/4 (524284 KB)          OKAY [ 16.749s]
Writing 'system_b'                                 OKAY [  0.001s]
Sending sparse 'system_b' 3/4 (524284 KB)          OKAY [ 16.449s]
Writing 'system_b'                                 OKAY [  0.001s]
Sending sparse 'system_b' 4/4 (158996 KB)          OKAY [  5.239s]
Writing 'system_b'                                 OKAY [  0.001s]
Finished. Total time: 55.060s

I am willing to open a PR on this but I am unsure how to implement this fix. If you could provide some guidance it would be greatly appreciated.

How to start the demo? I click contact device no effect.

NPM Package does not get the latest changes

Hello.

I have been trying to update my project which uses the android-fastboot npm package to flash the Pixel 7 and 7 Pro devices.
I have been seen the fastboot.js repo that there are updates specifically for these devices but they were done after the 1.1.1 version update. And I can also see that the latest version available for android-fastboot is 1.1.1 on both npm and on yarn.

Is this correct or do the packages need to be updated or am I doing something wrong?
Can anyone please advise?

Thanks