Skip to content

Commit c34c8c7

Browse files
brianignacio5brianignacio5
authored
adding examples and usage in readme (#85)
update example fix lint fix github pages update flash and loader options update readme fix lint update copyright year
1 parent a5abf5d commit c34c8c7

File tree

14 files changed

+198
-112
lines changed

14 files changed

+198
-112
lines changed

‎.github/workflows/pages.yml

+4-2
Original file line numberDiff line numberDiff line change
@@ -36,13 +36,15 @@ jobs:
3636
- name: Build project
3737
run: |
3838
npm run build
39+
cd examples/typescript
40+
npm install
41+
npm run build
3942
- name: Setup Pages
4043
uses: actions/configure-pages@v2
4144
- name: Upload artifact
4245
uses: actions/upload-pages-artifact@v1
4346
with:
44-
# Upload entire repository
45-
path: '.'
47+
path: 'examples/typescript/dist'
4648
- name: Deploy to GitHub Pages
4749
id: deployment
4850
uses: actions/deploy-pages@v1

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@ lib
33
bundle.js
44
esptool-js-*.tgz
55
.vscode/settings.json
6+
.parcel-cache

‎.vscode/tasks.json

+29-40
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,30 @@
11
{
2-
"version": "2.0.0",
3-
"tasks": [
4-
{
5-
"type": "npm",
6-
"script": "build",
7-
"group": {
8-
"kind": "build",
9-
"isDefault": true
10-
},
11-
"problemMatcher": [],
12-
"label": "npm: build",
13-
"detail": "npm run clean && tsc && rollup --config"
14-
},
15-
{
16-
"type": "npm",
17-
"script": "install",
18-
"label": "NPM install",
19-
"runOptions": {
20-
"runOn": "folderOpen"
21-
}
22-
},
23-
{
24-
"type": "npm",
25-
"script": "lint",
26-
"problemMatcher": [
27-
"$eslint-stylish"
28-
],
29-
"label": "npm: lint"
30-
},
31-
{
32-
"type": "shell",
33-
"label": "HTTP server",
34-
"command": "http-server -p 5001",
35-
"isBackground": true,
36-
"runOptions": {
37-
"runOn": "folderOpen"
38-
}
39-
}
40-
]
41-
}
2+
"version": "2.0.0",
3+
"tasks": [
4+
{
5+
"type": "npm",
6+
"script": "build",
7+
"group": {
8+
"kind": "build",
9+
"isDefault": true
10+
},
11+
"problemMatcher": [],
12+
"label": "npm: build",
13+
"detail": "npm run clean && tsc && rollup --config"
14+
},
15+
{
16+
"type": "npm",
17+
"script": "install",
18+
"label": "NPM install",
19+
"runOptions": {
20+
"runOn": "folderOpen"
21+
}
22+
},
23+
{
24+
"type": "npm",
25+
"script": "lint",
26+
"problemMatcher": ["$eslint-stylish"],
27+
"label": "npm: lint"
28+
}
29+
]
30+
}

‎README.md

+50-6
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,67 @@
11
# Javascript implementation of esptool
22

3-
This repository contains a Javascript implementation of [esptool](https://github.com/espressif/esptool), a serial flasher utility for Espressif chips. 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).
3+
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.
44

5-
`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).
5+
**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).
6+
7+
## Usage
8+
9+
**CDN**
10+
11+
`https://unpkg.com/esptool-js/lib/index.js?module`
12+
13+
**NPM**
14+
15+
`npm install --save esptool-js`
16+
17+
**Yarn**
18+
19+
`yarn add --save esptool-js`
20+
21+
Check an example project [here](./examples/typescript).
22+
23+
## Define port filters for device using WebSerial
24+
25+
```js
26+
const portFilters: { usbVendorId?: number | undefined, usbProductId?: number | undefined }[] = [];
27+
const device = await navigator.serial.requestPort({ filters: portFilters });
28+
```
29+
30+
## Inject a Terminal to use with esptool-js
31+
32+
```js
33+
// You can use any JavaScript compatible terminal by wrapping it in a helper object like this:
34+
let espLoaderTerminal = {
35+
clean() {
36+
// Implement the clean function call for your terminal here.
37+
},
38+
writeLine(data) {
39+
// Implement the writeLine function call for your terminal here.
40+
},
41+
write(data) {
42+
// Implement the write function call for your terminal here.
43+
},
44+
};
45+
```
46+
47+
You can pass this terminal object to `ESPLoader` constructor as shown in the [examples projects](./examples/).
648

749
## Live demo
850

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

1153
## Testing it locally
1254

13-
```
55+
```sh
1456
npm install
1557
npm run build
16-
python3 -m http.server 8008
58+
cd examples/typescript
59+
npm install
60+
npm run dev # Run local sever with example code
1761
```
1862

19-
Then open http://localhost:8008 in Chrome or Edge. The `npm run build` step builds the `bundle.js` used in the example `index.html`.
63+
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.
2064

2165
## License
2266

23-
The code in this repository is Copyright (c) 2021 Espressif Systems (Shanghai) Co. Ltd. It is licensed under Apache 2.0 license, as described in [LICENSE](LICENSE) file.
67+
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](LICENSE) file.

‎examples/typescript/.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node/modules
2+
.parcel-cache
3+
dist
4+
package-lock.json

‎examples/typescript/README.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Using Esptool-JS in a Typescript environment
2+
3+
This example has example code in `src/index.ts` which is called in the `index.html`. We are using Parcel to do bundle mechanism for the resulting JavaScript for simplicity here.
4+
5+
## Testing it locally
6+
7+
```
8+
npm install
9+
npm run dev
10+
```
11+
12+
Then open http://localhost:1234 in Chrome or Edge. The `npm run dev` step will call Parcel which start a local http server serving `index.html` with compiled `index.ts`.

‎assets/esp-logo.png ‎examples/typescript/assets/esp-logo.png

File renamed without changes.

‎favicon.ico ‎examples/typescript/assets/favicon.ico

File renamed without changes.

‎examples/typescript/package.json

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"name": "typescript",
3+
"version": "1.0.0",
4+
"description": "This an example of using esptool-js with parcel and typescript",
5+
"source": "src/index.html",
6+
"scripts": {
7+
"dev": "parcel src/index.html",
8+
"build": "npm run clean && parcel build src/index.html --no-optimize --public-url ./",
9+
"clean": "rimraf dist .parcel-cache",
10+
"test": "echo \"Error: no test specified\" && exit 1"
11+
},
12+
"author": "",
13+
"license": "ISC",
14+
"devDependencies": {
15+
"parcel": "^2.8.3",
16+
"rimraf": "^4.1.2",
17+
"typescript": "^4.9.4"
18+
}
19+
}

‎index.html ‎examples/typescript/src/index.html

+3-3
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,14 @@
99
href="https://fonts.googleapis.com/css?family=Orbitron"
1010
rel="stylesheet"
1111
/>
12-
<link rel="icon" href="favicon.ico" />
12+
<link rel="icon" href="../assets/favicon.ico" />
1313
<script src="https://cdn.jsdelivr.net/npm/[email protected]/lib/xterm.min.js"></script>
1414
<script src="https://cdn.jsdelivr.net/npm/[email protected]/crypto-js.js"></script>
1515
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
1616
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/js/bootstrap.min.js"></script>
1717
</head>
1818
<body>
19-
<h1 align="center"><p><img src="./assets/esp-logo.png" width="42" height="42" style="vertical-align:middle"></img> ESP Tool</p></h1>
19+
<h1 align="center"><p><img src="../assets/esp-logo.png" width="42" height="42" style="vertical-align:middle" crossorigin></img> ESP Tool</p></h1>
2020
<h4 align="center">A Serial Flasher utility for Espressif chips</h4>
2121
<div id="safariErr" style="display:none"><p align="center" style="color:red">This tool is not supported on Safari browser!</p>
2222
</div>
@@ -72,7 +72,7 @@ <h3>Console </h3>
7272
</div>
7373
<div id="terminal"></div>
7474
</div>
75-
<script src="index.js" type="module"></script>
75+
<script src="index.ts" type="module"></script>
7676
<script>
7777
// Safari 3.0+ "[object HTMLElementConstructor]"
7878
var isSafari = /constructor/i.test(window.HTMLElement) || (function (p) { return p.toString() === "[object SafariRemoteNotification]"; })(!window['safari'] || (typeof safari !== 'undefined' && window['safari'].pushNotification));

0 commit comments

Comments
 (0)