mirror of
https://github.com/alexandrebobkov/ESP-Nodes.git
synced 2025-08-08 03:42:24 +00:00
84 lines
3.3 KiB
Markdown
84 lines
3.3 KiB
Markdown
# Javascript implementation of esptool
|
|
|
|
This repository contains a Javascript implementation of [esptool](https://github.com/espressif/esptool), a serial flasher utility for Espressif chips. `esptool-js` is based on [Web Serial API](https://wicg.github.io/serial/) and works in Google Chrome and Microsoft Edge [version 89 or later](https://developer.mozilla.org/en-US/docs/Web/API/Serial#browser_compatibility) browsers and Google Chrome on Android [version 61 or later](https://developer.mozilla.org/en-US/docs/Web/API/USB#browser_compatibility) via the [web-serial-polyfill](https://github.com/google/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](https://github.com/espressif/esptool/wiki/espefuse) and [espsecure.py](https://github.com/espressif/esptool/wiki/espsecure).
|
|
|
|
## 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](https://github.com/espressif/esptool-js/tree/main/examples/typescript).
|
|
|
|
**Nightly builds** for <a href="https://nightly.link/espressif/esptool-js/workflows/ci/main">ESPTOOL-JS</a>
|
|
|
|
## Define port filters for device using WebSerial
|
|
|
|
```js
|
|
const portFilters: { usbVendorId?: number | undefined, usbProductId?: number | undefined }[] = [];
|
|
const device = await navigator.serial.requestPort({ filters: portFilters });
|
|
```
|
|
|
|
## Inject a Terminal to use with esptool-js
|
|
|
|
```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](./examples/).
|
|
|
|
## Live demo
|
|
|
|
Visit https://espressif.github.io/esptool-js/ to see this tool in action.
|
|
|
|
## Testing it locally
|
|
|
|
```sh
|
|
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](#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
|
|
|
|
```json
|
|
"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](https://github.com/espressif/esptool-js/blob/main/LICENSE) file.
|