@depz/sensor-sdk 0.1.0

package/dist/transport/webserial.js

@@ -0,0 +1,196 @@
+/**
+ * WebSerial transport (Chrome/Edge, secure context). The `SerialPort` must be
+ * obtained by the app inside a user gesture (`navigator.serial.requestPort()`)
+ * and passed here — the SDK never triggers the permission picker itself.
+ */
+import { isDeviceInfo, listDepzDevicesFrom, openDeviceByDeviceSerial, openDeviceFrom, orderDevicesBySerial, } from "../discovery.js";
+function navigatorSerial() {
+    const nav = globalThis.navigator;
+    return nav?.serial ?? null;
+}
+/** Feature-detect Web Serial support in the current environment. */
+export function isWebSerialSupported() {
+    return navigatorSerial() !== null;
+}
+/** Previously-granted ports (survive page reloads per origin+device). */
+export async function getGrantedPorts() {
+    const serial = navigatorSerial();
+    return serial ? serial.getPorts() : [];
+}
+/**
+ * Watch physical connect events; used by the firmware-update flow to
+ * re-acquire a device after it reboots. Returns an unsubscribe function.
+ */
+export function watchConnect(cb) {
+    const serial = navigatorSerial();
+    if (!serial)
+        return () => { };
+    const handler = (ev) => {
+        const port = ev.target;
+        if (port)
+            cb(port);
+    };
+    serial.addEventListener("connect", handler);
+    return () => serial.removeEventListener("connect", handler);
+}
+export class WebSerialTransport {
+    port;
+    info;
+    reader = null;
+    writer = null;
+    disconnectCbs = [];
+    disconnectHandler = null;
+    constructor(port) {
+        this.port = port;
+        const info = port.getInfo();
+        this.info = { usbVendorId: info.usbVendorId, usbProductId: info.usbProductId };
+    }
+    async open(opts) {
+        await this.port.open({ baudRate: opts?.baudRate ?? 115200 });
+        if (this.disconnectHandler === null && this.port.addEventListener) {
+            this.disconnectHandler = () => this.fireDisconnect();
+            this.port.addEventListener("disconnect", this.disconnectHandler);
+        }
+    }
+    async write(data) {
+        if (!this.port.writable)
+            throw new Error("port not writable (closed?)");
+        this.writer ??= this.port.writable.getWriter();
+        await this.writer.write(data);
+    }
+    async *readable() {
+        if (!this.port.readable)
+            throw new Error("port not readable (closed?)");
+        this.reader = this.port.readable.getReader();
+        try {
+            for (;;) {
+                const { value, done } = await this.reader.read();
+                if (done)
+                    return;
+                if (value && value.length > 0)
+                    yield value;
+            }
+        }
+        catch {
+            // Read failure = cable yank / device reboot.
+            this.fireDisconnect();
+            return;
+        }
+        finally {
+            this.reader.releaseLock();
+            this.reader = null;
+        }
+    }
+    async close() {
+        try {
+            await this.reader?.cancel();
+        }
+        catch {
+            /* already gone */
+        }
+        if (this.writer) {
+            try {
+                this.writer.releaseLock();
+            }
+            catch {
+                /* already gone */
+            }
+            this.writer = null;
+        }
+        if (this.disconnectHandler !== null) {
+            this.port.removeEventListener?.("disconnect", this.disconnectHandler);
+            this.disconnectHandler = null;
+        }
+        await this.port.close();
+    }
+    onDisconnect(cb) {
+        this.disconnectCbs.push(cb);
+        return () => {
+            this.disconnectCbs = this.disconnectCbs.filter((c) => c !== cb);
+        };
+    }
+    fireDisconnect() {
+        const cbs = this.disconnectCbs;
+        this.disconnectCbs = [];
+        cbs.forEach((cb) => cb());
+    }
+}
+// ── discovery (WebSerial) ─────────────────────────────────────────────────────
+//
+// WebSerial CANNOT enumerate the system's ports or read a port's USB iSerial:
+// `navigator.serial.getPorts()` returns only ports the user has already
+// granted (per origin+device), and `port.getInfo()` exposes just vid/pid.
+//
+// BUT the device serial is still reachable — over the PROTOCOL: probing a port
+// (open → GET_SERIAL → close) yields `DeviceInfo.serialNumber`. So selection
+// and ordering by serial ARE supported in the browser, at the cost of opening
+// each granted port once. Selection is by DEVICE serial (not granted-port
+// order), which matches Node — for programmed units USB iSerial == device
+// serial. Explicit targets (a `WebSerialPortLike`, a granted-port path, or a
+// `DeviceInfo`) open that exact port without a selection scan.
+//
+// The app must first obtain ports in a user gesture via
+// `navigator.serial.requestPort()`; the SDK never opens the picker itself.
+function grantedPortInfos(ports) {
+    const infos = [];
+    const byPath = new Map();
+    ports.forEach((port, i) => {
+        const path = `webserial:${i}`;
+        const usb = port.getInfo();
+        infos.push({ path, usbVid: usb.usbVendorId, usbPid: usb.usbProductId });
+        byPath.set(path, port);
+    });
+    return { infos, byPath };
+}
+/**
+ * Probe the already-granted WebSerial ports and return the DEPZ devices among
+ * them, ordered by DEVICE serial (GET_SERIAL) — the USB iSerial is unavailable
+ * in the browser, so the serial is read over the protocol. By default every
+ * granted port is probed (`matchUsb: false`) since a granted port is
+ * user-curated; pass `matchUsb: true` to probe only known-DEPZ vid/pids.
+ */
+export async function listDepzDevices(opts = {}) {
+    const { infos, byPath } = grantedPortInfos(await getGrantedPorts());
+    const factory = (p) => new WebSerialTransport(byPath.get(p.path));
+    const found = await listDepzDevicesFrom(infos, factory, {
+        matchUsb: opts.matchUsb ?? false,
+        timeoutMs: opts.timeoutMs,
+    });
+    return orderDevicesBySerial(found);
+}
+/**
+ * Open the right sensor class for a granted WebSerial port.
+ *
+ * `target` is a `WebSerialPortLike` (typically fresh from
+ * `navigator.serial.requestPort()`), a granted-port path string / `DeviceInfo`
+ * from `listDepzDevices()`, a candidate index (number, ordered by device
+ * serial), or omitted for the smallest-serial DEPZ candidate. `opts.serial`
+ * selects the candidate whose device serial matches exactly. Selection probes
+ * the granted ports; explicit targets open directly. Throws
+ * `NoDepzDeviceError` when nothing matches.
+ */
+export async function openDevice(target, opts = {}) {
+    // A raw WebSerial port handed in directly (the usual requestPort() flow).
+    if (isWebSerialPort(target)) {
+        const port = target;
+        const usb = port.getInfo();
+        const info = { path: "webserial:direct", usbVid: usb.usbVendorId, usbPid: usb.usbProductId };
+        const factory = () => new WebSerialTransport(port);
+        return openDeviceFrom([info], factory, "webserial:direct", opts);
+    }
+    const { infos, byPath } = grantedPortInfos(await getGrantedPorts());
+    const factory = (p) => new WebSerialTransport(byPath.get(p.path));
+    // Explicit granted port (path string or DeviceInfo): open exactly it.
+    if (typeof target === "string" || isDeviceInfo(target)) {
+        return openDeviceFrom(infos, factory, target, opts);
+    }
+    // Default / index / serial: select by DEVICE serial (probes granted ports).
+    return openDeviceByDeviceSerial(infos, factory, target ?? null, opts);
+}
+function isWebSerialPort(t) {
+    return (typeof t === "object" &&
+        t !== null &&
+        typeof t.getInfo === "function" &&
+        typeof t.open === "function");
+}
+//# sourceMappingURL=webserial.js.map

package/dist/transport/webserial.js.map

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

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@depz/sensor-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the DEPZ USB sensor line (SR04, VL53L8, BNO086) — WebSerial + Node",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "keywords": [
+    "depz",
+    "sensor",
+    "usb",
+    "webserial",
+    "serialport",
+    "vl53l8",
+    "bno086",
+    "hc-sr04",
+    "tof",
+    "imu"
+  ],
+  "homepage": "https://github.com/depz-ai/depz-sensor-sdk-and-viewer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/depz-ai/depz-sensor-sdk-and-viewer.git",
+    "directory": "packages/depz-sensor-sdk-ts"
+  },
+  "bugs": {
+    "url": "https://github.com/depz-ai/depz-sensor-sdk-and-viewer/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./web": {
+      "types": "./dist/transport/webserial.d.ts",
+      "import": "./dist/transport/webserial.js"
+    },
+    "./node": {
+      "types": "./dist/transport/node.d.ts",
+      "import": "./dist/transport/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "docs": "typedoc --out docs/.api-md && node scripts/merge-api-md.mjs docs/.api-md docs/api.md",
+    "docs:json": "typedoc --json docs/api.json --out docs/.api-json && node -e \"require('node:fs').rmSync('docs/.api-json',{recursive:true,force:true})\""
+  },
+  "peerDependencies": {
+    "serialport": ""
+  },
+  "peerDependenciesMeta": {
+    "serialport": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "serialport": "^12.0.0",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.12.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}