@depz/sensor-sdk 0.1.0

package/dist/sensors/bno086/shtp.js

@@ -0,0 +1,205 @@
+/**
+ * SHTP framing layer for the BNO086 (contracts/05_SENSOR_BNO086.md §3).
+ *
+ * Pure codec — no I/O. A frame is a 4-byte header plus a cargo fragment:
+ *
+ *     length u16 LE  — bits 14:0 cargo length *including* the 4-byte header;
+ *                      bit 15 set marks a continuation fragment
+ *     channel u8     — see ShtpChannel
+ *     seq u8         — per-channel, per-direction free-running counter
+ *
+ * For a cargo that spans several bridge frames, the first fragment's length
+ * field carries the TOTAL cargo length (header included) even though the
+ * frame itself holds fewer bytes; each continuation fragment carries the
+ * remaining length (its own header included) with bit 15 set. The receiver
+ * trusts the first fragment's total and the actual frame sizes; continuation
+ * length fields are informative only.
+ *
+ * Mirrors the Python reference `depz_sensor_sdk.bno086.shtp`.
+ */
+export var ShtpChannel;
+(function (ShtpChannel) {
+    /** SHTP command channel (advertisements). */
+    ShtpChannel[ShtpChannel["Command"] = 0] = "Command";
+    /** Device executable: reset/on/sleep; RX 0x01 = reset done. */
+    ShtpChannel[ShtpChannel["Executable"] = 1] = "Executable";
+    /** SH-2 control: feature/FRS/command reports. */
+    ShtpChannel[ShtpChannel["Control"] = 2] = "Control";
+    /** Non-wake input reports (0xFB timebase + sensors). */
+    ShtpChannel[ShtpChannel["InputNormal"] = 3] = "InputNormal";
+    /** Wake input reports (same cargo format as channel 3). */
+    ShtpChannel[ShtpChannel["InputWake"] = 4] = "InputWake";
+    /** Gyro-integrated rotation vector, dense format. */
+    ShtpChannel[ShtpChannel["GyroRv"] = 5] = "GyroRv";
+})(ShtpChannel || (ShtpChannel = {}));
+export const SHTP_HEADER_SIZE = 4;
+export const LENGTH_MASK = 0x7fff;
+export const CONTINUATION_BIT = 0x8000;
+export const NUM_CHANNELS = 6;
+/** Host->sensor frames must fit one MCU transmit slot (ERRATA E2: 2 x 64 B). */
+export const MAX_TX_FRAME = 64;
+export function packShtpHeader(hdr) {
+    const word = (hdr.length & LENGTH_MASK) | (hdr.continuation ? CONTINUATION_BIT : 0);
+    const out = new Uint8Array(SHTP_HEADER_SIZE);
+    const v = new DataView(out.buffer);
+    v.setUint16(0, word, true);
+    v.setUint8(2, hdr.channel);
+    v.setUint8(3, hdr.seq);
+    return out;
+}
+export function unpackShtpHeader(data) {
+    const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const word = v.getUint16(0, true);
+    return {
+        length: word & LENGTH_MASK,
+        channel: v.getUint8(2),
+        seq: v.getUint8(3),
+        continuation: (word & CONTINUATION_BIT) !== 0,
+    };
+}
+/** Single-fragment frame: length = header + payload. */
+export function buildFrame(channel, payload, seq) {
+    const hdr = packShtpHeader({
+        length: SHTP_HEADER_SIZE + payload.length,
+        channel,
+        seq: seq & 0xff,
+        continuation: false,
+    });
+    const out = new Uint8Array(hdr.length + payload.length);
+    out.set(hdr, 0);
+    out.set(payload, hdr.length);
+    return out;
+}
+/**
+ * Split a cargo into wire frames of at most `maxFrame` bytes.
+ *
+ * First fragment advertises the TOTAL cargo length; continuations carry the
+ * remaining length with the continuation bit set. seq increments per frame.
+ */
+export function fragmentCargo(channel, payload, seqStart, maxFrame = MAX_TX_FRAME) {
+    if (maxFrame <= SHTP_HEADER_SIZE) {
+        throw new Error("maxFrame must exceed the 4-byte SHTP header");
+    }
+    const room = maxFrame - SHTP_HEADER_SIZE;
+    const frames = [];
+    let off = 0;
+    let seq = seqStart & 0xff;
+    const total = SHTP_HEADER_SIZE + payload.length;
+    for (;;) {
+        const chunk = payload.subarray(off, off + room);
+        const remaining = total - off; // includes one header
+        const hdr = packShtpHeader({ length: remaining, channel, seq, continuation: off > 0 });
+        const frame = new Uint8Array(hdr.length + chunk.length);
+        frame.set(hdr, 0);
+        frame.set(chunk, hdr.length);
+        frames.push(frame);
+        off += chunk.length;
+        seq = (seq + 1) & 0xff;
+        if (off >= payload.length)
+            return frames;
+    }
+}
+function emptyRx() {
+    return { chunks: [], received: 0, expected: 0, seq: 0 };
+}
+function concatChunks(chunks, total) {
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}
+/**
+ * Per-channel TX sequence counters + RX cargo reassembly.
+ *
+ * Feed every inbound frame (the RPT_DATA payload after cmd/timestamp) to
+ * `feed()`; it returns a completed ShtpCargo or null. Build outbound frames
+ * with `nextFrame()` which consumes the channel's TX seq. The device layer
+ * serializes access.
+ */
+export class ShtpLayer {
+    /** Incomplete cargos thrown away. */
+    discarded = 0;
+    txSeqs = new Array(NUM_CHANNELS).fill(0);
+    rx = Array.from({ length: NUM_CHANNELS }, emptyRx);
+    // ── TX ─────────────────────────────────────────────────────────────────────
+    /**
+     * Build a single-fragment frame, consuming the channel's TX seq.
+     *
+     * Host-side cargos always fit one MCU slot (control payloads are <= 21
+     * bytes); larger payloads are a caller bug.
+     */
+    nextFrame(channel, payload) {
+        if (SHTP_HEADER_SIZE + payload.length > MAX_TX_FRAME) {
+            throw new Error(`TX cargo ${payload.length}B exceeds the ${MAX_TX_FRAME}B MCU slot`);
+        }
+        const seq = this.txSeqs[channel];
+        this.txSeqs[channel] = (seq + 1) & 0xff;
+        return buildFrame(channel, payload, seq);
+    }
+    txSeq(channel) {
+        return this.txSeqs[channel];
+    }
+    // ── RX ─────────────────────────────────────────────────────────────────────
+    /**
+     * Consume one inbound frame; return the cargo when complete.
+     *
+     * Rules (contract 05 §3): a non-continuation fragment starts a new cargo
+     * (discarding any partial one on that channel); a continuation without a
+     * cargo in progress is dropped; the cargo completes when the accumulated
+     * bytes reach the first fragment's advertised total.
+     */
+    feed(frame) {
+        if (frame.length < SHTP_HEADER_SIZE)
+            return null;
+        const hdr = unpackShtpHeader(frame);
+        if (hdr.channel >= NUM_CHANNELS || hdr.length < SHTP_HEADER_SIZE) {
+            return null; // empty/padding header ("no data" read) or junk
+        }
+        const chunk = frame.subarray(SHTP_HEADER_SIZE);
+        const rx = this.rx[hdr.channel];
+        if (!hdr.continuation) {
+            if (rx.expected !== 0 && rx.received !== 0)
+                this.discarded += 1;
+            rx.chunks = [chunk.slice()];
+            rx.received = chunk.length;
+            rx.expected = hdr.length - SHTP_HEADER_SIZE;
+            rx.seq = hdr.seq;
+        }
+        else {
+            if (rx.expected === 0) {
+                this.discarded += 1;
+                return null;
+            }
+            rx.chunks.push(chunk.slice());
+            rx.received += chunk.length;
+        }
+        if (rx.received < rx.expected)
+            return null;
+        if (rx.received > rx.expected) {
+            // Overrun — junk framing.
+            this.discarded += 1;
+            rx.chunks = [];
+            rx.received = 0;
+            rx.expected = 0;
+            return null;
+        }
+        const cargo = {
+            channel: hdr.channel,
+            seq: rx.seq,
+            payload: concatChunks(rx.chunks, rx.received),
+        };
+        rx.chunks = [];
+        rx.received = 0;
+        rx.expected = 0;
+        return cargo;
+    }
+    /** Forget all TX seq counters and partial cargos (sensor reset). */
+    reset() {
+        this.txSeqs = new Array(NUM_CHANNELS).fill(0);
+        this.rx = Array.from({ length: NUM_CHANNELS }, emptyRx);
+    }
+}
+//# sourceMappingURL=shtp.js.map

package/dist/sensors/bno086/shtp.js.map

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

package/dist/sensors/sr04.d.ts

@@ -0,0 +1,65 @@
+/**
+ * SR04 ultrasonic sensor (contracts/03_SENSOR_SR04.md).
+ * Mirrors the Python reference `depz_sensor_sdk.sr04.Sr04`.
+ */
+import { DepzDevice, StreamQueue } from "../device/device.js";
+import type { PacketEvent } from "../protocol/framing.js";
+/** One ranging result. `valid` is false for the no-echo timeout sentinel. */
+export interface Sr04Measurement {
+    timestampUs: bigint;
+    echoTimeUs: number;
+    /** "once": host command or SYNC_IN edge; "loop": measurement loop sample. */
+    source: "once" | "loop";
+    valid: boolean;
+    /** Distance at 343 m/s, or null when no echo was received. */
+    distanceMm: number | null;
+}
+/**
+ * HC-SR04 ultrasonic ranging device.
+ *
+ * Measurements stream via callbacks (`onMeasurement`) and/or the pull
+ * iterator (`measurements()`); both receive loop samples *and* unsolicited
+ * single shots triggered by an AUX SYNC_IN edge (RPT_DATA source cmd 0x36).
+ */
+export declare class Sr04 extends DepzDevice {
+    private measureCbs;
+    private measureQueues;
+    /** Minimum interval between measurement starts (default 50000). */
+    getSamplePeriodUs(): Promise<number>;
+    /**
+     * The effective rate is auto-throttled by the echo window (contract 03
+     * §3) — reading back returns the stored value, not the effective one.
+     */
+    setSamplePeriodUs(periodUs: number): Promise<void>;
+    getEchoDecayUs(): Promise<number>;
+    /**
+     * Set the settle pause; the device clamps to 4000–65000 µs silently, so
+     * this re-reads and returns the value actually in effect.
+     */
+    setEchoDecayUs(decayUs: number): Promise<number>;
+    /**
+     * Single shot. Rejects with BusyError while the loop is running. The
+     * reply arrives only when the echo completes (or times out at ~65.5 ms),
+     * so the default timeout is generous.
+     */
+    measureOnce(timeoutMs?: number): Promise<Sr04Measurement>;
+    /** Start the measurement loop (idempotent). */
+    start(): Promise<void>;
+    /** Stop the measurement loop (idempotent). */
+    stop(): Promise<void>;
+    /**
+     * Subscribe to measurements (read-pump context; don't block). Returns an
+     * unsubscribe function.
+     */
+    onMeasurement(cb: (m: Sr04Measurement) => void): () => void;
+    /**
+     * Async iterator over measurements — bounded, drop-oldest (contract 07
+     * §3). The returned queue exposes `droppedCount`; it ends when the device
+     * closes or the consumer breaks out of iteration.
+     */
+    measurements(maxsize?: number): StreamQueue<Sr04Measurement>;
+    /** Drop counters of all live measurement queues (diagnostics). */
+    get streamDroppedCounts(): number[];
+    protected handleReport(pkt: PacketEvent): boolean;
+}
+//# sourceMappingURL=sr04.d.ts.map

package/dist/sensors/sr04.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sr04.d.ts","sourceRoot":"","sources":["../../src/sensors/sr04.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAY,WAAW,EAAgB,MAAM,qBAAqB,CAAC;AACtF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAc1D,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,8DAA8D;IAC9D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAYD;;;;;;GAMG;AACH,qBAAa,IAAK,SAAQ,UAAU;IAClC,OAAO,CAAC,UAAU,CAA2C;IAC7D,OAAO,CAAC,aAAa,CAAsC;IAI3D,mEAAmE;IACnE,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAMpC;;;OAGG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxD,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAMjC;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOtD;;;;OAIG;IACH,WAAW,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,eAAe,CAAC;IAUvD,+CAA+C;IACzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,8CAA8C;IACxC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACH,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAO3D;;;;OAIG;IACH,YAAY,CAAC,OAAO,SAAM,GAAG,WAAW,CAAC,eAAe,CAAC;IAUzD,kEAAkE;IAClE,IAAI,mBAAmB,IAAI,MAAM,EAAE,CAElC;cAIkB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO;CAS3D"}

package/dist/sensors/sr04.js

@@ -0,0 +1,121 @@
+/**
+ * SR04 ultrasonic sensor (contracts/03_SENSOR_SR04.md).
+ * Mirrors the Python reference `depz_sensor_sdk.sr04.Sr04`.
+ */
+import { DepzDevice, NO_MATCH, StreamQueue } from "../device/device.js";
+import { ECHO_TIMEOUT, Sr04Cmd, Sr04Rpt, distanceMmFromEcho, packEchoDecay, packSamplePeriod, unpackEchoDecay, unpackSamplePeriod, unpackSr04Data, } from "../protocol/sr04.js";
+function measurementFromData(data) {
+    return {
+        timestampUs: data.timestampUs,
+        echoTimeUs: data.echoTimeUs,
+        source: data.sourceCmd === Sr04Cmd.StartMeasurementLoop ? "loop" : "once",
+        valid: data.echoTimeUs !== ECHO_TIMEOUT,
+        distanceMm: distanceMmFromEcho(data.echoTimeUs),
+    };
+}
+/**
+ * HC-SR04 ultrasonic ranging device.
+ *
+ * Measurements stream via callbacks (`onMeasurement`) and/or the pull
+ * iterator (`measurements()`); both receive loop samples *and* unsolicited
+ * single shots triggered by an AUX SYNC_IN edge (RPT_DATA source cmd 0x36).
+ */
+export class Sr04 extends DepzDevice {
+    measureCbs = [];
+    measureQueues = [];
+    // ── configuration ──────────────────────────────────────────────────────────
+    /** Minimum interval between measurement starts (default 50000). */
+    getSamplePeriodUs() {
+        return this.request(Sr04Cmd.GetSamplePeriod, undefined, {
+            matcher: DepzDevice.expectReport(Sr04Rpt.SamplePeriod, unpackSamplePeriod),
+        });
+    }
+    /**
+     * The effective rate is auto-throttled by the echo window (contract 03
+     * §3) — reading back returns the stored value, not the effective one.
+     */
+    async setSamplePeriodUs(periodUs) {
+        await this.request(Sr04Cmd.SetSamplePeriod, packSamplePeriod(periodUs), {
+            okCompletes: true,
+        });
+    }
+    getEchoDecayUs() {
+        return this.request(Sr04Cmd.GetEchoDecay, undefined, {
+            matcher: DepzDevice.expectReport(Sr04Rpt.EchoDecay, unpackEchoDecay),
+        });
+    }
+    /**
+     * Set the settle pause; the device clamps to 4000–65000 µs silently, so
+     * this re-reads and returns the value actually in effect.
+     */
+    async setEchoDecayUs(decayUs) {
+        await this.request(Sr04Cmd.SetEchoDecay, packEchoDecay(decayUs), { okCompletes: true });
+        return this.getEchoDecayUs();
+    }
+    // ── measuring ──────────────────────────────────────────────────────────────
+    /**
+     * Single shot. Rejects with BusyError while the loop is running. The
+     * reply arrives only when the echo completes (or times out at ~65.5 ms),
+     * so the default timeout is generous.
+     */
+    measureOnce(timeoutMs = 1000) {
+        const matcher = (pkt) => {
+            if (pkt.cmd !== Sr04Rpt.Data || pkt.payload.length !== 11)
+                return NO_MATCH;
+            const data = unpackSr04Data(pkt.payload);
+            if (data.sourceCmd !== Sr04Cmd.MeasureOnce)
+                return NO_MATCH;
+            return measurementFromData(data);
+        };
+        return this.request(Sr04Cmd.MeasureOnce, undefined, { matcher, timeoutMs });
+    }
+    /** Start the measurement loop (idempotent). */
+    async start() {
+        await this.request(Sr04Cmd.StartMeasurementLoop, undefined, { okCompletes: true });
+    }
+    /** Stop the measurement loop (idempotent). */
+    async stop() {
+        await this.request(Sr04Cmd.StopMeasurementLoop, undefined, { okCompletes: true });
+    }
+    /**
+     * Subscribe to measurements (read-pump context; don't block). Returns an
+     * unsubscribe function.
+     */
+    onMeasurement(cb) {
+        this.measureCbs.push(cb);
+        return () => {
+            this.measureCbs = this.measureCbs.filter((c) => c !== cb);
+        };
+    }
+    /**
+     * Async iterator over measurements — bounded, drop-oldest (contract 07
+     * §3). The returned queue exposes `droppedCount`; it ends when the device
+     * closes or the consumer breaks out of iteration.
+     */
+    measurements(maxsize = 256) {
+        const queue = new StreamQueue(maxsize, () => {
+            this.measureQueues = this.measureQueues.filter((q) => q !== queue);
+            deregister();
+        });
+        this.measureQueues.push(queue);
+        const deregister = this.registerStream(queue);
+        return queue;
+    }
+    /** Drop counters of all live measurement queues (diagnostics). */
+    get streamDroppedCounts() {
+        return this.measureQueues.map((q) => q.droppedCount);
+    }
+    // ── internal ───────────────────────────────────────────────────────────────
+    handleReport(pkt) {
+        if (pkt.cmd === Sr04Rpt.Data && pkt.payload.length === 11) {
+            const m = measurementFromData(unpackSr04Data(pkt.payload));
+            for (const cb of [...this.measureCbs])
+                cb(m);
+            for (const q of [...this.measureQueues])
+                q.push(m);
+            return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=sr04.js.map

package/dist/sensors/sr04.js.map

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