@depz/sensor-sdk 0.1.0

package/dist/device/device.js

@@ -0,0 +1,421 @@
+/**
+ * DepzDevice: request correlation, events, common commands
+ * (contracts/02_COMMON_COMMANDS.md, 07_SDK_FACADE.md).
+ *
+ * Behavioral rules per contract 07 §3: correlation by echoed request opcode
+ * (never seq), one in-flight request per opcode, 200 ms default timeout,
+ * bounded drop-oldest stream queues, callbacks run on the read-pump context.
+ *
+ * Mirrors the Python reference `depz_sensor_sdk.device.DeviceBase`. The read
+ * pump only starts in `open()`, after the (sub)class constructor finished —
+ * subclass stream state always exists before the first dispatch.
+ */
+import { BusyError, DepzError, DepzTimeoutError, DeviceLostError, LinkClosedError, StatusError, } from "../errors.js";
+import { Cmd, Rpt, Status, UNSOLICITED, packSyncPinConfig, packSyncTime, syncTimeOffsetRtt, unpackSequenceError, unpackStatus, unpackSyncPinConfig, unpackSyncTime, unpackTemperature, unpackText, } from "../protocol/common.js";
+import { parseSoftwareName } from "../protocol/identity.js";
+import { CrcType } from "../protocol/framing.js";
+import { DepzLink } from "./link.js";
+export const DEFAULT_TIMEOUT_MS = 200;
+/** Monotonic host clock in µs — the host side of all time-sync math. */
+export function hostNowUs() {
+    return BigInt(Math.round(performance.now() * 1000));
+}
+// ── request correlation ──────────────────────────────────────────────────────
+/** Returned by a matcher to decline a packet. */
+export const NO_MATCH = Symbol("depz.NO_MATCH");
+// ── stream queues ────────────────────────────────────────────────────────────
+/**
+ * Bounded drop-oldest async stream (contract 07 §3). Doubles as the async
+ * iterator returned by e.g. `Sr04.measurements()`; `droppedCount` is the
+ * monotonic count of items evicted while the consumer lagged.
+ */
+export class StreamQueue {
+    droppedCount = 0;
+    maxsize;
+    onDone;
+    buf = [];
+    waiters = [];
+    closed = false;
+    constructor(maxsize, onDone) {
+        this.maxsize = Math.max(1, maxsize);
+        this.onDone = onDone;
+    }
+    /** Producer side: enqueue, evicting the oldest item when full. */
+    push(item) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter({ value: item, done: false });
+            return;
+        }
+        if (this.buf.length >= this.maxsize) {
+            this.buf.shift();
+            this.droppedCount += 1;
+        }
+        this.buf.push(item);
+    }
+    /** End the stream; buffered items are still drained by the consumer. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
+    }
+    next() {
+        const item = this.buf.shift();
+        if (item !== undefined)
+            return Promise.resolve({ value: item, done: false });
+        if (this.closed)
+            return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    return() {
+        this.close();
+        this.onDone?.();
+        return Promise.resolve({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+/**
+ * Connection to one DEPZ device in application mode. Construct over any
+ * `SerialTransport`, then `await open()` before use.
+ */
+export class DepzDevice {
+    timeoutMs;
+    link;
+    transport;
+    pending = new Map();
+    eventCbs = [];
+    streams = [];
+    timeSyncState = null;
+    closing = false;
+    torndown = false;
+    constructor(transport, opts) {
+        this.transport = transport;
+        this.timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.link = new DepzLink(transport, { txCrcType: opts?.txCrcType ?? CrcType.None });
+        this.link.onParserEvent((ev) => this.handleParserEvent(ev));
+        this.link.onClose(() => this.handleLinkClosed());
+    }
+    // ── lifecycle ──────────────────────────────────────────────────────────────
+    /** Open the transport and start the read pump. */
+    async open() {
+        await this.transport.open();
+        this.link.start();
+    }
+    async close() {
+        this.closing = true;
+        await this.link.close();
+    }
+    get stats() {
+        return this.link.stats;
+    }
+    handleLinkClosed() {
+        if (this.torndown)
+            return;
+        this.torndown = true;
+        if (this.closing) {
+            this.failAllPending(new LinkClosedError("device closed"));
+        }
+        else {
+            this.failAllPending(new DeviceLostError("transport closed"));
+            this.emitEvent({ type: "disconnected", reason: "transport closed" });
+        }
+        for (const s of [...this.streams])
+            s.close();
+    }
+    failAllPending(error) {
+        const all = [...this.pending.values()];
+        this.pending.clear();
+        for (const p of all) {
+            clearTimeout(p.timer);
+            p.reject(error);
+        }
+    }
+    // ── dispatch (read-pump context) ───────────────────────────────────────────
+    handleParserEvent(ev) {
+        if (ev.type === "packet") {
+            this.dispatch(ev);
+        }
+        else if (ev.type === "crcError") {
+            this.emitEvent({ type: "linkCrcError", cmd: ev.cmd, seq: ev.seq });
+        }
+        else {
+            this.emitEvent({ type: "trash", data: ev.data });
+        }
+    }
+    dispatch(pkt) {
+        if (pkt.cmd === Rpt.Status && pkt.payload.length >= 2) {
+            const rep = unpackStatus(pkt.payload);
+            if (rep.cmd !== UNSOLICITED) {
+                const pending = this.pending.get(rep.cmd);
+                if (pending !== undefined) {
+                    if (rep.status === Status.ErrBusy) {
+                        this.settle(pending, { error: new BusyError(rep.cmd) });
+                    }
+                    else if (rep.status !== Status.Ok) {
+                        this.settle(pending, { error: new StatusError(rep.cmd, rep.status) });
+                    }
+                    else if (pending.okCompletes) {
+                        this.settle(pending, { value: undefined });
+                    }
+                    // else: OK ack while waiting for the data report — leave the
+                    // pending request in flight untouched.
+                    return;
+                }
+            }
+            this.emitEvent({ type: "unsolicitedStatus", status: rep.status });
+            return;
+        }
+        // Give pending matchers first shot at any non-status packet.
+        for (const p of [...this.pending.values()]) {
+            if (p.matcher === null)
+                continue;
+            const result = p.matcher(pkt);
+            if (result !== NO_MATCH) {
+                this.settle(p, { value: result });
+                return;
+            }
+        }
+        if (pkt.cmd === Rpt.SequenceError && pkt.payload.length === 2) {
+            const rep = unpackSequenceError(pkt.payload);
+            this.emitEvent({
+                type: "sequenceError",
+                expectedSeq: rep.expectedSeq,
+                receivedSeq: rep.receivedSeq,
+                reportedByDevice: true,
+            });
+            return;
+        }
+        if (pkt.cmd === Rpt.Text && pkt.payload.length > 0) {
+            const rep = unpackText(pkt.payload);
+            this.emitEvent({ type: "text", cmd: rep.cmd, text: rep.text });
+            return;
+        }
+        if (pkt.cmd === Rpt.Temperature && pkt.payload.length === 10) {
+            const rep = unpackTemperature(pkt.payload);
+            this.emitEvent({
+                type: "temperature",
+                timestampUs: rep.timestampUs,
+                celsius: rep.rawDecidegrees / 10,
+            });
+            return;
+        }
+        if (this.handleReport(pkt))
+            return;
+        // Unknown/unrouted report: keep it visible so new firmware is debuggable.
+        this.emitEvent({ type: "text", cmd: pkt.cmd, text: toHex(pkt.payload) });
+    }
+    settle(p, outcome) {
+        clearTimeout(p.timer);
+        this.pending.delete(p.cmd);
+        if (outcome.error !== undefined)
+            p.reject(outcome.error);
+        else
+            p.resolve(outcome.value);
+    }
+    /**
+     * Hook for sensor subclasses: route streaming reports here. Return true
+     * when the packet was consumed. Runs after status/matcher/common-report
+     * routing, on the read-pump context.
+     */
+    handleReport(pkt) {
+        void pkt;
+        return false;
+    }
+    /** Register a stream to be closed on device teardown. */
+    registerStream(stream) {
+        this.streams.push(stream);
+        return () => {
+            this.streams = this.streams.filter((s) => s !== stream);
+        };
+    }
+    // ── events ─────────────────────────────────────────────────────────────────
+    /**
+     * Subscribe to unsolicited/diagnostic events (read-pump context; do not
+     * block). Returns an unsubscribe function.
+     */
+    onEvent(cb) {
+        this.eventCbs.push(cb);
+        return () => {
+            this.eventCbs = this.eventCbs.filter((c) => c !== cb);
+        };
+    }
+    emitEvent(event) {
+        for (const cb of [...this.eventCbs])
+            cb(event);
+    }
+    // ── TX / requests ──────────────────────────────────────────────────────────
+    /**
+     * Send `cmd` and wait for its correlated completion (contract 02 §1).
+     *
+     * Exactly one of the completion paths must be configured:
+     * - `okCompletes` — RPT_STATUS(cmd, OK) resolves with undefined;
+     * - `matcher` — first packet for which the matcher returns non-`NO_MATCH`
+     *   resolves with the matcher's return value.
+     * Non-OK RPT_STATUS echoing `cmd` always rejects (BusyError for ERR_BUSY,
+     * StatusError otherwise). One in-flight request per opcode.
+     */
+    async request(cmd, payload = new Uint8Array(0), opts = {}) {
+        const { matcher, okCompletes = false } = opts;
+        if (matcher === undefined && !okCompletes) {
+            throw new DepzError("configure matcher or okCompletes");
+        }
+        if (this.pending.has(cmd))
+            throw new BusyError(cmd);
+        const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
+        const result = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(cmd);
+                reject(new DepzTimeoutError(cmd, timeoutMs));
+            }, timeoutMs);
+            this.pending.set(cmd, {
+                cmd,
+                matcher: matcher ?? null,
+                okCompletes,
+                resolve: resolve,
+                reject,
+                timer,
+            });
+        });
+        // Mark handled so an early rejection (timeout/disconnect racing the
+        // write) never surfaces as an unhandled rejection; the caller still
+        // receives it through the returned promise.
+        void result.catch(() => undefined);
+        try {
+            await this.link.send(cmd, payload);
+        }
+        catch (err) {
+            const p = this.pending.get(cmd);
+            if (p !== undefined) {
+                clearTimeout(p.timer);
+                this.pending.delete(cmd);
+            }
+            throw err;
+        }
+        return result;
+    }
+    /** Matcher for a typed report identified by its report ID alone. */
+    static expectReport(reportId, unpack) {
+        return (pkt) => (pkt.cmd === reportId ? unpack(pkt.payload) : NO_MATCH);
+    }
+    /** Matcher for RPT_TEXT echoing `requestCmd`. */
+    static expectText(requestCmd) {
+        return (pkt) => {
+            if (pkt.cmd !== Rpt.Text || pkt.payload.length === 0 || pkt.payload[0] !== requestCmd) {
+                return NO_MATCH;
+            }
+            return unpackText(pkt.payload).text;
+        };
+    }
+    // ── common commands (contract 02) ──────────────────────────────────────────
+    getDeviceName() {
+        return this.request(Cmd.GetDeviceName, undefined, {
+            matcher: DepzDevice.expectText(Cmd.GetDeviceName),
+        });
+    }
+    getSoftwareName() {
+        return this.request(Cmd.GetNameActiveSoftware, undefined, {
+            matcher: DepzDevice.expectText(Cmd.GetNameActiveSoftware),
+        });
+    }
+    getSerialNumber() {
+        return this.request(Cmd.GetSerial, undefined, {
+            matcher: DepzDevice.expectText(Cmd.GetSerial),
+        });
+    }
+    /** Classify the running firmware (contract 02 §4). */
+    async identify() {
+        return parseSoftwareName(await this.getSoftwareName());
+    }
+    /** Last cached MCU temperature in °C (device refreshes ~2 Hz). */
+    async readMcuTemperature() {
+        const rep = await this.request(Cmd.GetMcuTemperature, undefined, {
+            matcher: DepzDevice.expectReport(Rpt.Temperature, unpackTemperature),
+        });
+        return rep.rawDecidegrees / 10;
+    }
+    /** NTP-style sync; keeps the lowest-RTT sample (contract 02 §5). */
+    async syncTime(samples = 5) {
+        let best = null;
+        for (let i = 0; i < Math.max(1, samples); i++) {
+            const t1 = hostNowUs();
+            const rep = await this.request(Cmd.SyncTime, packSyncTime(t1), {
+                matcher: DepzDevice.expectReport(Rpt.SyncTime, unpackSyncTime),
+            });
+            const t4 = hostNowUs();
+            const { offsetUs, rttUs } = syncTimeOffsetRtt(t1, rep.mcuRxUs, rep.mcuTxUs, t4);
+            if (best === null || rttUs < best.rttUs) {
+                best = { offsetUs, rttUs, syncedAtHostUs: t4 };
+            }
+        }
+        this.timeSyncState = best;
+        return best;
+    }
+    get timeSync() {
+        return this.timeSyncState;
+    }
+    /** Device µs → host monotonic µs (requires a prior `syncTime`). */
+    toHostTimeUs(deviceTsUs) {
+        if (this.timeSyncState === null)
+            throw new DepzError("call syncTime() first");
+        return deviceTsUs - this.timeSyncState.offsetUs;
+    }
+    async getReportPayloadCrc() {
+        return this.request(Cmd.GetPayloadCrcType, undefined, {
+            matcher: DepzDevice.expectReport(Rpt.PayloadCrcType, (p) => p[0]),
+        });
+    }
+    /** Set the device→host payload CRC mode (host→device is per-packet). */
+    async setReportPayloadCrc(crcType) {
+        await this.request(Cmd.SetPayloadCrcType, Uint8Array.of(crcType), { okCompletes: true });
+    }
+    getSyncPin(pin) {
+        return this.request(Cmd.GetSyncPinConfig, Uint8Array.of(pin), {
+            matcher: DepzDevice.expectReport(Rpt.SyncPinConfig, unpackSyncPinConfig),
+        });
+    }
+    async setSyncPin(config) {
+        await this.request(Cmd.SetSyncPinConfig, packSyncPinConfig(config), { okCompletes: true });
+    }
+    /** DEVICE_RESET: device ACKs then reboots; the link will drop. */
+    async reset() {
+        await this.request(Cmd.DeviceReset, undefined, { okCompletes: true });
+    }
+    /**
+     * Ask the device to reboot into the resident bootloader and close this
+     * connection. Re-discovery/flash flow lives in the bootloader module
+     * (contract 06).
+     */
+    async enterBootloaderMode() {
+        await this.request(Cmd.Bootloader, undefined, { okCompletes: true });
+        await this.close();
+    }
+}
+/**
+ * Software-sync several devices to the common host monotonic clock.
+ *
+ * Runs `syncTime()` on each device so that every device's `toHostTimeUs()`
+ * maps its own timestamps onto ONE shared host timeline — the basis for
+ * correlating reports from multiple sensors live. Returns a Map
+ * {device → TimeSync}. Mirrors the Python reference `sync_time_all`.
+ */
+export async function syncTimeAll(devices, samples = 5) {
+    const out = new Map();
+    for (const dev of devices) {
+        out.set(dev, await dev.syncTime(samples));
+    }
+    return out;
+}
+function toHex(data) {
+    let s = "";
+    for (const b of data)
+        s += b.toString(16).padStart(2, "0");
+    return s;
+}
+//# sourceMappingURL=device.js.map

package/dist/device/device.js.map

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

package/dist/device/link.d.ts

@@ -0,0 +1,62 @@
+/**
+ * DepzLink: packet-level pump over a byte transport
+ * (contracts/07_SDK_FACADE.md §1 layer 1→2 boundary).
+ *
+ * Owns the read pump (`transport.readable()` → `PacketParser`), the
+ * auto-incrementing TX sequence counter, and the link statistics. Packet
+ * routing/correlation lives one layer up in `DepzDevice`.
+ */
+import { CrcType, type PacketEvent, type ParserEvent } from "../protocol/framing.js";
+import type { SerialTransport } from "../transport/types.js";
+/** Link statistics (contract 07 §2 `stats`). */
+export interface LinkStats {
+    rxPackets: number;
+    txPackets: number;
+    rxBytes: number;
+    txBytes: number;
+    crcErrors: number;
+    headerErrors: number;
+    trashBytes: number;
+    /** Host-observed gaps in the device→host seq counter (mod 256). */
+    seqGaps: number;
+}
+export declare class DepzLink {
+    readonly stats: LinkStats;
+    private readonly transport;
+    private readonly txCrcType;
+    private readonly parser;
+    private txSeq;
+    private lastRxSeq;
+    private started;
+    private closeFired;
+    private packetCbs;
+    private parserCbs;
+    private closeCbs;
+    private unsubDisconnect;
+    constructor(transport: SerialTransport, opts?: {
+        txCrcType?: CrcType;
+    });
+    /**
+     * Begin the read pump. Must be called exactly once, after the transport
+     * is open. Ends (and fires `onClose`) when the transport's readable
+     * iterator finishes or the transport reports a disconnect.
+     */
+    start(): void;
+    private pump;
+    private handleParserEvent;
+    private trackSeq;
+    /** Frame and write one packet with the next TX seq (wraps at 0xFF). */
+    send(cmd: number, payload?: Uint8Array): Promise<void>;
+    /** Subscribe to decoded packets. Returns an unsubscribe function. */
+    onPacket(cb: (pkt: PacketEvent) => void): () => void;
+    /**
+     * Subscribe to all parser events, including CRC errors and trash
+     * (diagnostics; the device layer maps these to `DeviceEvent`s).
+     */
+    onParserEvent(cb: (ev: ParserEvent) => void): () => void;
+    /** Subscribe to link teardown (fires once). Returns an unsubscribe. */
+    onClose(cb: () => void): () => void;
+    private fireClose;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=link.d.ts.map

package/dist/device/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/device/link.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,OAAO,EAEP,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,QAAQ;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,CASvB;IAEF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,SAAS,CAAwC;IACzD,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,eAAe,CAA6B;gBAExC,SAAS,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;IAKtE;;;;OAIG;IACH,KAAK,IAAI,IAAI;YAOC,IAAI;IAYlB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,QAAQ;IAOhB,uEAAuE;IACjE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,UAA8B,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/E,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;IAOpD;;;OAGG;IACH,aAAa,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;IAOxD,uEAAuE;IACvE,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAOnC,OAAO,CAAC,SAAS;IAOX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/device/link.js

@@ -0,0 +1,130 @@
+/**
+ * DepzLink: packet-level pump over a byte transport
+ * (contracts/07_SDK_FACADE.md §1 layer 1→2 boundary).
+ *
+ * Owns the read pump (`transport.readable()` → `PacketParser`), the
+ * auto-incrementing TX sequence counter, and the link statistics. Packet
+ * routing/correlation lives one layer up in `DepzDevice`.
+ */
+import { buildPacket, CrcType, PacketParser, } from "../protocol/framing.js";
+export class DepzLink {
+    stats = {
+        rxPackets: 0,
+        txPackets: 0,
+        rxBytes: 0,
+        txBytes: 0,
+        crcErrors: 0,
+        headerErrors: 0,
+        trashBytes: 0,
+        seqGaps: 0,
+    };
+    transport;
+    txCrcType;
+    parser = new PacketParser();
+    txSeq = 0;
+    lastRxSeq = null;
+    started = false;
+    closeFired = false;
+    packetCbs = [];
+    parserCbs = [];
+    closeCbs = [];
+    unsubDisconnect = null;
+    constructor(transport, opts) {
+        this.transport = transport;
+        this.txCrcType = opts?.txCrcType ?? CrcType.None;
+    }
+    /**
+     * Begin the read pump. Must be called exactly once, after the transport
+     * is open. Ends (and fires `onClose`) when the transport's readable
+     * iterator finishes or the transport reports a disconnect.
+     */
+    start() {
+        if (this.started)
+            throw new Error("DepzLink already started");
+        this.started = true;
+        this.unsubDisconnect = this.transport.onDisconnect(() => this.fireClose());
+        void this.pump();
+    }
+    async pump() {
+        try {
+            for await (const chunk of this.transport.readable()) {
+                this.stats.rxBytes += chunk.length;
+                for (const ev of this.parser.feed(chunk))
+                    this.handleParserEvent(ev);
+                this.stats.headerErrors = this.parser.headerErrors;
+            }
+        }
+        finally {
+            this.fireClose();
+        }
+    }
+    handleParserEvent(ev) {
+        if (ev.type === "packet") {
+            this.stats.rxPackets += 1;
+            this.trackSeq(ev.seq);
+        }
+        else if (ev.type === "crcError") {
+            this.stats.crcErrors += 1;
+        }
+        else {
+            this.stats.trashBytes += ev.data.length;
+        }
+        for (const cb of [...this.parserCbs])
+            cb(ev);
+        if (ev.type === "packet") {
+            for (const cb of [...this.packetCbs])
+                cb(ev);
+        }
+    }
+    trackSeq(seq) {
+        if (this.lastRxSeq !== null && seq !== ((this.lastRxSeq + 1) & 0xff)) {
+            this.stats.seqGaps += 1;
+        }
+        this.lastRxSeq = seq;
+    }
+    /** Frame and write one packet with the next TX seq (wraps at 0xFF). */
+    async send(cmd, payload = new Uint8Array(0)) {
+        const frame = buildPacket(cmd, payload, this.txSeq, this.txCrcType);
+        this.txSeq = (this.txSeq + 1) & 0xff;
+        await this.transport.write(frame);
+        this.stats.txPackets += 1;
+        this.stats.txBytes += frame.length;
+    }
+    /** Subscribe to decoded packets. Returns an unsubscribe function. */
+    onPacket(cb) {
+        this.packetCbs.push(cb);
+        return () => {
+            this.packetCbs = this.packetCbs.filter((c) => c !== cb);
+        };
+    }
+    /**
+     * Subscribe to all parser events, including CRC errors and trash
+     * (diagnostics; the device layer maps these to `DeviceEvent`s).
+     */
+    onParserEvent(cb) {
+        this.parserCbs.push(cb);
+        return () => {
+            this.parserCbs = this.parserCbs.filter((c) => c !== cb);
+        };
+    }
+    /** Subscribe to link teardown (fires once). Returns an unsubscribe. */
+    onClose(cb) {
+        this.closeCbs.push(cb);
+        return () => {
+            this.closeCbs = this.closeCbs.filter((c) => c !== cb);
+        };
+    }
+    fireClose() {
+        if (this.closeFired)
+            return;
+        this.closeFired = true;
+        this.unsubDisconnect?.();
+        for (const cb of [...this.closeCbs])
+            cb();
+    }
+    async close() {
+        await this.transport.close();
+        this.fireClose();
+    }
+}
+//# sourceMappingURL=link.js.map

package/dist/device/link.js.map

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