@emdzej/j2534-webserial 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michał Jaskólski
+
+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,40 @@
+# @emdzej/j2534-webserial
+
+Browser **Web Serial** transport for
+[`@emdzej/j2534-driver`](https://www.npmjs.com/package/@emdzej/j2534-driver).
+Talks to the Tactrix OpenPort 2.0 directly from Chrome / Edge — no
+native dependencies. Works in any modern Chromium-based browser
+that exposes [`navigator.serial`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API).
+
+## Install
+
+```bash
+npm install @emdzej/j2534-driver @emdzej/j2534-webserial
+```
+
+## Use
+
+```ts
+import { J2534Device } from '@emdzej/j2534-driver';
+import { createWebSerialTransport } from '@emdzej/j2534-webserial';
+
+// must be called from a user-gesture handler (button click etc.)
+const transport = await createWebSerialTransport();
+
+const dev = new J2534Device(transport);
+await dev.open();
+// … see @emdzej/j2534-driver
+```
+
+The browser shows its standard port-picker dialog; the user grants
+access per-origin / per-device.
+
+## See also
+
+- [Root README](https://github.com/emdzej/j2534#readme)
+- [`@emdzej/j2534-webusb`](https://www.npmjs.com/package/@emdzej/j2534-webusb) —
+  WebUSB alternative when Web Serial isn't available
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { type Transport, type DeviceInfo } from "@emdzej/j2534-types";
+/**
+ * Browser Web Serial transport for J2534 devices.
+ *
+ * The Tactrix OpenPort 2.0 presents as a CDC ACM device (virtual COM port),
+ * which Chrome's WebUSB blocks but Web Serial handles natively.
+ */
+export declare class WebSerialTransport implements Transport {
+    private vendorId;
+    private productId;
+    private port;
+    private reader;
+    private writer;
+    private _isConnected;
+    private rxBuffer;
+    constructor(vendorId?: number, productId?: number);
+    get isConnected(): boolean;
+    /**
+     * Request a serial port and open it. Must be called from a user gesture.
+     *
+     * The OpenPort 2.0 CDC device doesn't use standard baud rate negotiation —
+     * the baud rate parameter is ignored by the firmware. We set a high value
+     * to avoid any artificial throttling by the OS serial driver.
+     */
+    open(): Promise<void>;
+    /**
+     * Background read loop that accumulates incoming data.
+     * The J2534 device sends asynchronous responses (ack, messages, etc.)
+     * that we need to buffer for the driver's polling read calls.
+     */
+    private readLoop;
+    close(): Promise<void>;
+    write(data: Uint8Array): Promise<number>;
+    read(timeout?: number): Promise<Uint8Array>;
+}
+/**
+ * List already-granted serial ports matching the OpenPort VID/PID.
+ * No user gesture required.
+ */
+export declare function listDevices(vid?: number, pid?: number): Promise<DeviceInfo[]>;
+export default WebSerialTransport;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EAGhB,MAAM,qBAAqB,CAAC;AAE7B;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,SAAS;IAQhD,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IARnB,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,MAAM,CAAwD;IACtE,OAAO,CAAC,MAAM,CAAwD;IACtE,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAoB;gBAG1B,QAAQ,SAAe,EACvB,SAAS,SAAe;IAGlC,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC3B;;;;OAIG;YACW,QAAQ;IAehB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBtB,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAQxC,IAAI,CAAC,OAAO,SAAO,GAAG,OAAO,CAAC,UAAU,CAAC;CA2BhD;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,GAAG,SAAe,EAClB,GAAG,SAAe,GACjB,OAAO,CAAC,UAAU,EAAE,CAAC,CAevB;AAED,eAAe,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,158 @@
+import { OPENPORT_VID, OPENPORT_PID, } from "@emdzej/j2534-types";
+/**
+ * Browser Web Serial transport for J2534 devices.
+ *
+ * The Tactrix OpenPort 2.0 presents as a CDC ACM device (virtual COM port),
+ * which Chrome's WebUSB blocks but Web Serial handles natively.
+ */
+export class WebSerialTransport {
+    vendorId;
+    productId;
+    port = null;
+    reader = null;
+    writer = null;
+    _isConnected = false;
+    rxBuffer = [];
+    constructor(vendorId = OPENPORT_VID, productId = OPENPORT_PID) {
+        this.vendorId = vendorId;
+        this.productId = productId;
+    }
+    get isConnected() {
+        return this._isConnected;
+    }
+    /**
+     * Request a serial port and open it. Must be called from a user gesture.
+     *
+     * The OpenPort 2.0 CDC device doesn't use standard baud rate negotiation —
+     * the baud rate parameter is ignored by the firmware. We set a high value
+     * to avoid any artificial throttling by the OS serial driver.
+     */
+    async open() {
+        if (!("serial" in navigator)) {
+            throw new Error("Web Serial API is not supported in this browser");
+        }
+        // Try to find an already-granted port first
+        const ports = await navigator.serial.getPorts();
+        this.port =
+            ports.find((p) => {
+                const info = p.getInfo();
+                return (info.usbVendorId === this.vendorId &&
+                    info.usbProductId === this.productId);
+            }) ?? null;
+        // If not found, prompt user
+        if (!this.port) {
+            this.port = await navigator.serial.requestPort({
+                filters: [{ usbVendorId: this.vendorId, usbProductId: this.productId }],
+            });
+        }
+        await this.port.open({
+            baudRate: 500000, // ignored by OpenPort firmware, but required by API
+            bufferSize: 4096,
+        });
+        if (this.port.readable && this.port.writable) {
+            this.reader = this.port.readable.getReader();
+            this.writer = this.port.writable.getWriter();
+        }
+        else {
+            throw new Error("Failed to obtain readable/writable streams from serial port");
+        }
+        this._isConnected = true;
+        // Start background reading into buffer
+        this.readLoop();
+    }
+    /**
+     * Background read loop that accumulates incoming data.
+     * The J2534 device sends asynchronous responses (ack, messages, etc.)
+     * that we need to buffer for the driver's polling read calls.
+     */
+    async readLoop() {
+        if (!this.reader)
+            return;
+        try {
+            while (this._isConnected) {
+                const { value, done } = await this.reader.read();
+                if (done)
+                    break;
+                if (value && value.length > 0) {
+                    this.rxBuffer.push(value);
+                }
+            }
+        }
+        catch {
+            // Port closed or error — expected during disconnect
+        }
+    }
+    async close() {
+        this._isConnected = false;
+        try {
+            this.reader?.releaseLock();
+        }
+        catch { }
+        try {
+            this.writer?.releaseLock();
+        }
+        catch { }
+        this.reader = null;
+        this.writer = null;
+        try {
+            await this.port?.close();
+        }
+        catch { }
+        this.port = null;
+        this.rxBuffer = [];
+    }
+    async write(data) {
+        if (!this.writer) {
+            throw new Error("Transport not connected");
+        }
+        await this.writer.write(data);
+        return data.length;
+    }
+    async read(timeout = 1000) {
+        const deadline = Date.now() + timeout;
+        // Wait for data to appear in the rx buffer
+        while (this.rxBuffer.length === 0) {
+            if (Date.now() >= deadline) {
+                throw new Error("Read timeout");
+            }
+            await new Promise((r) => setTimeout(r, 5));
+        }
+        // Drain all buffered chunks into a single response
+        // (matches the bulk transfer behavior of USB transport)
+        if (this.rxBuffer.length === 1) {
+            return this.rxBuffer.shift();
+        }
+        const total = this.rxBuffer.reduce((sum, chunk) => sum + chunk.length, 0);
+        const result = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of this.rxBuffer) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+        this.rxBuffer = [];
+        return result;
+    }
+}
+/**
+ * List already-granted serial ports matching the OpenPort VID/PID.
+ * No user gesture required.
+ */
+export async function listDevices(vid = OPENPORT_VID, pid = OPENPORT_PID) {
+    if (!("serial" in navigator))
+        return [];
+    const ports = await navigator.serial.getPorts();
+    return ports
+        .filter((p) => {
+        const info = p.getInfo();
+        return info.usbVendorId === vid && info.usbProductId === pid;
+    })
+        .map((p) => {
+        const info = p.getInfo();
+        return {
+            vendorId: info.usbVendorId,
+            productId: info.usbProductId,
+        };
+    });
+}
+export default WebSerialTransport;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@emdzej/j2534-webserial",
+  "version": "0.1.0",
+  "description": "Browser Web Serial API transport for @emdzej/j2534-driver. Talks to the Tactrix OpenPort 2.0 directly from Chrome/Edge — no native dependencies, runs in any modern Chromium-based browser.",
+  "keywords": [
+    "j2534",
+    "passthru",
+    "tactrix",
+    "openport",
+    "diagnostics",
+    "web-serial",
+    "browser",
+    "transport",
+    "typescript"
+  ],
+  "homepage": "https://github.com/emdzej/j2534#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emdzej/j2534.git",
+    "directory": "packages/webserial"
+  },
+  "bugs": {
+    "url": "https://github.com/emdzej/j2534/issues"
+  },
+  "license": "MIT",
+  "author": "Michał Jaskólski",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@emdzej/j2534-types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/w3c-web-serial": "^1.0.7",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  }
+}