README.md

Fork

NOTE: this is a fork of https://github.com/espressif/esptool-js We have adapted it so it can also work on NodejS instead of web based only

Javascript implementation of esptool

This repository contains a Javascript implementation of esptool, a serial flasher utility for Espressif chips. esptool-js is based on Web Serial API and works in Google Chrome and Microsoft Edge version 89 or later browsers and Google Chrome on Android version 61 or later via the web-serial-polyfill compatibility layer.

NOTE: Unlike the Python-based esptool, esptool-js doesn't implement generation of binary images out of ELF files, and doesn't include companion tools similar to espefuse.py and espsecure.py.

Usage

CDN

https://unpkg.com/esptool-js/lib/index.js or https://unpkg.com/esptool-js/bundle.js to use the single bundle JavaScript file.

NPM

npm install --save esptool-js

Yarn

yarn add --save esptool-js

Check an example project here.

Nightly builds for ESPTOOL-JS

Define port filters for device using WebSerial

const portFilters: { usbVendorId?: number | undefined, usbProductId?: number | undefined }[] = [];
const device = await navigator.serial.requestPort({ filters: portFilters });

Inject a Terminal to use with esptool-js

// You can use any JavaScript compatible terminal by wrapping it in a helper object like this:
let espLoaderTerminal = {
  clean() {
    // Implement the clean function call for your terminal here.
  },
  writeLine(data) {
    // Implement the writeLine function call for your terminal here.
  },
  write(data) {
    // Implement the write function call for your terminal here.
  },
};

You can pass this terminal object to ESPLoader constructor as shown in the examples projects.

Live demo

Visit https://espressif.github.io/esptool-js/ to see this tool in action.

Testing it locally

npm install
npm run build
cd examples/typescript
npm install
npm run dev # Run local sever with example code

Then open http://localhost:1234 in a Chrome browser. The npm run build step builds the lib used in the example examples/typescript/index.html. Update this reference as described in Usage section.

Test from Pull Request artifact

If you are testing the main branch or any Pull Request (PR) artifact you can follow these steps:

1. Get the esptool-js-<version>.tgz where <version> is the current version and download it.
2. Add the following line to your project's package.json dependencies

"dependencies": {
  "esptool-js": "file:../path/to/esptool-js-<version>.tgz"
}

3. Use the package like import "esptool-js/lib/index.js" when added in package.json as shown before.

License

The code in this repository is Copyright (c) 2023 Espressif Systems (Shanghai) Co. Ltd. It is licensed under Apache 2.0 license, as described in LICENSE file.