webserial-flasher 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Sebastian Barrenechea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# webserial-flasher
+
+A modern, ESM-compatible, TypeScript implementation of the STK500v1 protocol for programming Arduino boards directly from Node.js or the browser.
+
+## Features
+
+- Full JavaScript/TypeScript implementation of the STK500v1 programmer
+- ESM (ECMAScript Modules) compatible
+- Can be used in Node.js or browser environments
+- No dependency on avrdude or the Arduino IDE
+- TypeScript support for improved developer experience
+- **Built-in Intel HEX parsing** (no need for external parsing libraries)
+
+## Installation
+
+```bash
+npm install webserial-flasher
+```
+
+## Usage
+
+Here's a basic example of how to use webserial-flasher to program an Arduino:
+
+```typescript
+import { SerialPort } from "serialport";
+import fs from "fs/promises";
+import STK500, { type Board } from "webserial-flasher";
+
+const board: Board = {
+  name: "Arduino Uno",
+  baudRate: 115200,
+  signature: new Uint8Array([0x1e, 0x95, 0x0f]),
+  pageSize: 128,
+  timeout: 400,
+};
+
+async function upload(path: string) {
+  let serialPort;
+  try {
+    const hexData = await fs.readFile("path/to/your/sketch.hex");
+    serialPort = new SerialPort({ path, baudRate: board.baudRate });
+    const stk = new STK500(serialPort, board);
+    await stk.bootload(hexData);
+    console.log("Programming successful!");
+  } catch (error) {
+    console.error("Programming failed:", error);
+  } finally {
+    if (serialPort) {
+      await serialPort.close();
+    }
+  }
+}
+
+upload("/dev/ttyACM0"); // Replace with your Arduino's serial port
+```
+
+## Examples
+
+For more detailed examples, please check the `examples` folder in the repository. It contains several TypeScript files demonstrating how to use webserial-flasher with different Arduino boards:
+
+- `avr4809.ts`: Example for AVR4809 based boards
+- `diecimila-duemilanove168.ts`: Example for Arduino Diecimila and Duemilanove (ATmega168)
+- `duemilanove328.ts`: Example for Arduino Duemilanove (ATmega328)
+- `lg8f328.ts`: Example for LGT8F328 boards
+- `nano.ts`: Example for Arduino Nano
+- `uno.ts`: Example for Arduino Uno
+
+These examples show how to set up the board configuration, read hex files, and upload them to the respective Arduino boards.
+
+To run an example, use:
+
+```bash
+npx tsx examples/uno.ts /dev/ttyACM0
+```
+
+Replace `uno.ts` with the appropriate example file and `/dev/ttyACM0` with your Arduino's serial port.
+
+## API
+
+The main class `STK500` provides the following methods:
+
+- `constructor(stream: Duplex, board: Board, opts?: STK500Options)`
+- `bootload(hexData: string | Uint8Array, progressCallback?: BootloadProgressCallback): Promise<void>`
+- `sync(attempts: number): Promise<Uint8Array>`
+- `verifySignature(): Promise<Uint8Array>`
+- `upload(hexData: string | Uint8Array, progressCallback?: (percentage: number) => void): Promise<void>`
+- `verify(hexData: string | Uint8Array, progressCallback?: (percentage: number) => void): Promise<void>`
+
+For more detailed API information, please refer to the TypeScript definitions or the source code.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/dist/autoDetect.d.ts

@@ -0,0 +1,24 @@
+import type { Board } from './core/types.js';
+import type { ISTKTransport } from './transport/ITransport.js';
+/** Result from a successful auto-detect probe */
+export interface AutoDetectResult {
+    /** Detected bootloader protocol */
+    protocol: 'stk500v1' | 'stk500v2' | 'avr109';
+    /** Raw 3-byte device signature */
+    signature: Uint8Array;
+    /** Matched board, or undefined if the signature is unknown */
+    board: Board | undefined;
+}
+export interface AutoDetectOptions {
+    /**
+     * Timeout (ms) for each individual protocol probe attempt.
+     * Shorter = faster detection but may miss slow bootloaders.
+     * Default: 300
+     */
+    probeTimeoutMs?: number;
+    /** Suppress all log output during probing (default: true) */
+    quiet?: boolean;
+}
+/** Probe board for a given transport — detect protocol and signature. */
+export declare function autoDetect(transport: ISTKTransport, opts?: AutoDetectOptions): Promise<AutoDetectResult | null>;
+//# sourceMappingURL=autoDetect.d.ts.map

package/dist/autoDetect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoDetect.d.ts","sourceRoot":"","sources":["../src/autoDetect.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,QAAQ,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC7C,kCAAkC;IAClC,SAAS,EAAE,UAAU,CAAC;IACtB,8DAA8D;IAC9D,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,yEAAyE;AACzE,wBAAsB,UAAU,CAC9B,SAAS,EAAE,aAAa,EACxB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA8ClC"}

package/dist/autoDetect.js

@@ -0,0 +1,66 @@
+// Auto-detection: probe an unknown target and determine its protocol + board.
+//
+// Tries each protocol in order with a short timeout:
+//   1. STK500v1 — GET_SYNC (most common: Uno, Nano, Pro Mini)
+//   2. STK500v2 — SIGN_ON  (Mega 2560, Mega 1280)
+//   3. AVR109   — get software ID (Leonardo, Micro, Pro Micro)
+//
+// UPDI devices require a BREAK condition first and cannot be auto-detected
+// in this manner — callers must select UPDI explicitly.
+//
+// Usage:
+//   const result = await autoDetect(transport, { probeTimeoutMs: 300 });
+//   if (result) {
+//     console.log(result.protocol, result.board?.name, result.signature);
+//   }
+import { STK500 } from './stk500.js';
+import { STK500v2 } from './protocol/stk500v2/programmer.js';
+import { AVR109 } from './protocol/avr109/programmer.js';
+import { BOARDS, detectBoardBySignature, } from './boards/database.js';
+/** Probe board for a given transport — detect protocol and signature. */
+export async function autoDetect(transport, opts = {}) {
+    const timeout = opts.probeTimeoutMs ?? 300;
+    const quiet = opts.quiet !== false; // default quiet=true
+    // Minimal probe board — only timeout matters for probing
+    const probeBoard = {
+        ...BOARDS['arduino-uno'],
+        timeout,
+    };
+    // ── 1. STK500v1 ────────────────────────────────────────────────────────────
+    try {
+        const stk = new STK500(transport, probeBoard, {
+            quiet,
+            retry: { syncAttempts: 1, retryDelayMs: 0 },
+        });
+        await stk.sync(1);
+        const sig = await stk.getSignature();
+        const board = detectBoardBySignature(sig) ?? undefined;
+        return { protocol: 'stk500v1', signature: sig, board };
+    }
+    catch { /* not STK500v1 */ }
+    // ── 2. STK500v2 ────────────────────────────────────────────────────────────
+    try {
+        const probeV2Board = { ...BOARDS['arduino-mega2560'], timeout };
+        const stk2 = new STK500v2(transport, probeV2Board, {
+            quiet,
+            retry: { syncAttempts: 1, retryDelayMs: 0 },
+        });
+        await stk2.sync(1);
+        const sig = await stk2.readSignature();
+        const board = detectBoardBySignature(sig) ?? undefined;
+        return { protocol: 'stk500v2', signature: sig, board };
+    }
+    catch { /* not STK500v2 */ }
+    // ── 3. AVR109 ──────────────────────────────────────────────────────────────
+    try {
+        const probeAvrBoard = { ...BOARDS['arduino-leonardo'], timeout };
+        const avr = new AVR109(transport, probeAvrBoard, { quiet });
+        await avr.sync(1);
+        const sig = await avr.getSignature();
+        const board = detectBoardBySignature(sig) ?? undefined;
+        return { protocol: 'avr109', signature: sig, board };
+    }
+    catch { /* not AVR109 */ }
+    return null;
+}
+//# sourceMappingURL=autoDetect.js.map

package/dist/autoDetect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoDetect.js","sourceRoot":"","sources":["../src/autoDetect.ts"],"names":[],"mappings":"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"}

package/dist/boards/database.d.ts

@@ -0,0 +1,17 @@
+import type { Board } from '../core/types.js';
+export declare const BOARDS: Readonly<Record<string, Board>>;
+/**
+ * Find a board by its 3-byte device signature.
+ * Returns the first match, or null if no board matches.
+ * Note: multiple boards share the same signature (e.g. all ATmega328P variants).
+ */
+export declare function detectBoardBySignature(signature: Uint8Array): Board | null;
+/**
+ * Get a board config from an arduino-cli FQBN string.
+ * Returns null if the FQBN is not recognised.
+ * @example boardFromFqbn('arduino:avr:mega') → BOARDS['arduino-mega2560']
+ */
+export declare function boardFromFqbn(fqbn: string): Board | null;
+/** USB Vendor IDs for board auto-detection in WebSerial requestPort() */
+export declare const ARDUINO_USB_VENDOR_IDS: readonly number[];
+//# sourceMappingURL=database.d.ts.map

package/dist/boards/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/boards/database.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,eAAO,MAAM,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CA+6BlD,CAAC;AAIF;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,UAAU,GAAG,KAAK,GAAG,IAAI,CAa1E;AA8CD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAGxD;AAED,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAQnD,CAAC"}