Upstream Watchdog Fixes

.github/workflows/pages.yml

@@ -36,13 +36,15 @@ jobs:
       - name: Build project
         run: |
           npm run build
+          cd examples/typescript
+          npm install
+          npm run build
       - name: Setup Pages
         uses: actions/configure-pages@v2
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1
         with:
-          # Upload entire repository
-          path: '.'
+          path: 'examples/typescript/dist'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v1

.gitignore

@@ -3,3 +3,4 @@ lib
 bundle.js
 esptool-js-*.tgz
 .vscode/settings.json
+.parcel-cache

.vscode/tasks.json

@@ -1,41 +1,30 @@
 {
-	"version": "2.0.0",
-	"tasks": [
-		{
-			"type": "npm",
-			"script": "build",
-			"group": {
-				"kind": "build",
-				"isDefault": true
-			},
-			"problemMatcher": [],
-			"label": "npm: build",
-			"detail": "npm run clean && tsc && rollup --config"
-		},
-		{
-			"type": "npm",
-			"script": "install",
-			"label": "NPM install",
-			"runOptions": {
-				"runOn": "folderOpen"
-			}
-		},
-		{
-			"type": "npm",
-			"script": "lint",
-			"problemMatcher": [
-				"$eslint-stylish"
-			],
-			"label": "npm: lint"
-		},
-		{
-			"type": "shell",
-			"label": "HTTP server",
-			"command": "http-server -p 5001",
-			"isBackground": true,
-			"runOptions": {
-				"runOn": "folderOpen"
-			}
-		}
-	]
-}
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "npm",
+      "script": "build",
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "problemMatcher": [],
+      "label": "npm: build",
+      "detail": "npm run clean && tsc && rollup --config"
+    },
+    {
+      "type": "npm",
+      "script": "install",
+      "label": "NPM install",
+      "runOptions": {
+        "runOn": "folderOpen"
+      }
+    },
+    {
+      "type": "npm",
+      "script": "lint",
+      "problemMatcher": ["$eslint-stylish"],
+      "label": "npm: lint"
+    }
+  ]
+}

README.md

@@ -1,23 +1,67 @@
 # Javascript implementation of esptool
 
-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).
+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.
 
-`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).
+**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?module`
+
+**NPM**
+
+`npm install --save esptool-js`
+
+**Yarn**
+
+`yarn add --save esptool-js`
+
+Check an example project [here](./examples/typescript).
+
+## 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
-python3 -m http.server 8008
+cd examples/typescript
+npm install
+npm run dev # Run local sever with example code
 ```
 
-Then open http://localhost:8008 in Chrome or Edge. The `npm run build` step builds the `bundle.js` used in the example `index.html`.
+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.
 
 ## License
 
-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.
+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

@@ -0,0 +1,4 @@
+node/modules
+.parcel-cache
+dist
+package-lock.json

examples/typescript/README.md

@@ -0,0 +1,12 @@
+# Using Esptool-JS in a Typescript environment
+
+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.
+
+## Testing it locally
+
+```
+npm install
+npm run dev
+```
+
+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`.

examples/typescript/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "typescript",
+  "version": "1.0.0",
+  "description": "This an example of using esptool-js with parcel and typescript",
+  "source": "src/index.html",
+  "scripts": {
+    "dev": "parcel src/index.html",
+    "build": "npm run clean && parcel build src/index.html --no-optimize --public-url ./",
+    "clean": "rimraf dist .parcel-cache",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "parcel": "^2.8.3",
+    "rimraf": "^4.1.2",
+    "typescript": "^4.9.4"
+  }
+}

index.html → examples/typescript/src/index.html

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