@depz/sensor-sdk 0.5.0 → 0.6.0

package/dist/sensors/tmf8829/frames.js

@@ -0,0 +1,190 @@
+/**
+ * TMF8829 frame layout and pixel decoding (contracts/14_SENSOR_TMF8829.md §3).
+ * Mirrors the Python reference `depz_sensor_sdk.tmf8829.frames`.
+ */
+import { DepzError } from "../../errors.js";
+export const TMF8829_PRE_HEADER_SIZE = 5;
+export const TMF8829_HEADER_SIZE = 16;
+export const TMF8829_FOOTER_SIZE = 12;
+/** The 21 bytes the bridge reads at 0xFA. */
+export const TMF8829_FRAME_HEAD = TMF8829_PRE_HEADER_SIZE + TMF8829_HEADER_SIZE;
+export const TMF8829_FRAME_EOF = 0xe0f7;
+export const TMF8829_FID_MASK = 0xf0;
+export const TMF8829_FID_RESULTS = 0x10;
+export const TMF8829_FID_HISTOGRAMS = 0x20;
+export const TMF8829_FID_REF_SPAD = 0x30;
+export const TMF8829_LAYOUT_PEAKS = 0x07;
+export const TMF8829_LAYOUT_SIGNAL = 0x08;
+export const TMF8829_LAYOUT_NOISE = 0x10;
+export const TMF8829_LAYOUT_XTALK = 0x20;
+/** 32x32/48x32: set on the second (odd-row) half-frame. */
+export const TMF8829_LAYOUT_SUBFRAME = 0x40;
+const FRAME_VALID = 0x01;
+const FRAME_ABORTED = 0xc0;
+const FRAME_WARNINGS = [
+    [0x08, "HV_CP_OVERLOAD"],
+    [0x10, "VCDRV_OVERLOAD"],
+    [0x20, "VCDRV_BURST_EXCEEDED"],
+];
+const FOOTER_DIST_IN_MM = 0x01;
+const FIFO_TX_UNDERRUN = 0x10;
+const FIFO_RX_OVERRUN = 0x20;
+/** fp_mode → [rows, cols] of the full focal plane. */
+export const TMF8829_FP_GRID = {
+    0: [8, 8],
+    1: [8, 8],
+    2: [16, 16],
+    3: [32, 32],
+    4: [32, 32],
+    5: [32, 48],
+};
+export const TMF8829_FP_NAMES = {
+    0: "8x8A",
+    1: "8x8B",
+    2: "16x16",
+    3: "32x32",
+    4: "32x32s",
+    5: "48x32",
+};
+/** Full frame size (pre-header included) from its first 21 bytes. */
+export function tmf8829FrameSize(head) {
+    return TMF8829_PRE_HEADER_SIZE + 4 + (head[7] | (head[8] << 8));
+}
+export function parseTmf8829Frame(raw) {
+    if (raw.length < TMF8829_FRAME_HEAD + TMF8829_FOOTER_SIZE) {
+        throw new DepzError(`frame of ${raw.length} B is shorter than header + footer`);
+    }
+    const v = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    const h = TMF8829_PRE_HEADER_SIZE;
+    const f = raw.length - TMF8829_FOOTER_SIZE;
+    const id = raw[h];
+    const layout = raw[h + 1];
+    const reserved = raw[f + 9];
+    return {
+        fifoStatus: raw[0],
+        systick: v.getUint32(1, true),
+        id,
+        kind: id & TMF8829_FID_MASK,
+        fpMode: id & 0x0f,
+        layout,
+        payload: v.getUint16(h + 2, true),
+        fNumber: v.getUint32(h + 4, true),
+        temperature: [v.getInt8(h + 8), v.getInt8(h + 9), v.getInt8(h + 10)],
+        bdv: raw[h + 11],
+        refPos: [v.getUint16(h + 12, true), v.getUint16(h + 14, true)],
+        t0Integration: v.getUint32(f, true),
+        t1Integration: v.getUint32(f + 4, true),
+        frameStatus: raw[f + 8],
+        reserved,
+        eof: v.getUint16(f + 10, true),
+        size: raw.length,
+        isSecondHalf: (layout & TMF8829_LAYOUT_SUBFRAME) !== 0,
+        distanceInMm: (reserved & FOOTER_DIST_IN_MM) !== 0,
+    };
+}
+/** What is wrong with a frame, human-readable; empty when fine. */
+export function tmf8829FrameProblems(f) {
+    const out = [];
+    if (f.eof !== TMF8829_FRAME_EOF)
+        out.push(`EOF 0x${f.eof.toString(16).toUpperCase().padStart(4, "0")}`);
+    if (!(f.frameStatus & FRAME_VALID)) {
+        out.push(`status 0x${f.frameStatus.toString(16).toUpperCase().padStart(2, "0")} not valid`);
+    }
+    if (f.frameStatus & FRAME_ABORTED)
+        out.push("aborted");
+    for (const [bit, name] of FRAME_WARNINGS)
+        if (f.frameStatus & bit)
+            out.push(name);
+    if (f.fifoStatus & FIFO_TX_UNDERRUN)
+        out.push("txfifo_underrun");
+    if (f.fifoStatus & FIFO_RX_OVERRUN)
+        out.push("rxfifo_overrun");
+    return out;
+}
+/** [rows, cols] one results frame carries: half the rows for 32x32/48x32. */
+export function tmf8829FrameRows(fpMode) {
+    const g = TMF8829_FP_GRID[fpMode];
+    if (!g)
+        throw new DepzError(`unknown fp_mode ${fpMode}`);
+    return g[0] === 32 ? [g[0] / 2, g[1]] : [g[0], g[1]];
+}
+/** Pixel results of one results frame. */
+export function parseTmf8829Results(raw, info) {
+    const f = info ?? parseTmf8829Frame(raw);
+    if (f.kind !== TMF8829_FID_RESULTS) {
+        throw new DepzError(`frame id 0x${f.id.toString(16)} is not a results frame`);
+    }
+    const [rows, cols] = tmf8829FrameRows(f.fpMode);
+    const peaks = f.layout & TMF8829_LAYOUT_PEAKS;
+    const noise = (f.layout & TMF8829_LAYOUT_NOISE) !== 0;
+    const xtalk = (f.layout & TMF8829_LAYOUT_XTALK) !== 0;
+    const signal = (f.layout & TMF8829_LAYOUT_SIGNAL) !== 0;
+    const peakSize = 3 + (signal ? 2 : 0);
+    const pxSize = (noise ? 2 : 0) + (xtalk ? 2 : 0) + peaks * peakSize;
+    const n = rows * cols;
+    const dataSize = f.size - TMF8829_FRAME_HEAD - TMF8829_FOOTER_SIZE;
+    if (pxSize * n !== dataSize) {
+        throw new DepzError(`result data ${dataSize} B, expected ${n} px × ${pxSize} B (layout 0x${f.layout.toString(16)})`);
+    }
+    const out = {
+        peaks,
+        rows,
+        cols,
+        distance: peaks ? new Uint16Array(peaks * n) : null,
+        snr: peaks ? new Uint8Array(peaks * n) : null,
+        signal: peaks && signal ? new Uint16Array(peaks * n) : null,
+        noise: noise ? new Uint16Array(n) : null,
+        xtalk: xtalk ? new Uint16Array(n) : null,
+    };
+    let o = TMF8829_FRAME_HEAD;
+    const u16 = (at) => raw[at] | (raw[at + 1] << 8);
+    for (let i = 0; i < n; i++) {
+        if (out.noise) {
+            out.noise[i] = u16(o);
+            o += 2;
+        }
+        if (out.xtalk) {
+            out.xtalk[i] = u16(o);
+            o += 2;
+        }
+        for (let p = 0; p < peaks; p++) {
+            out.distance[p * n + i] = u16(o);
+            out.snr[p * n + i] = raw[o + 2];
+            o += 3;
+            if (out.signal) {
+                out.signal[p * n + i] = u16(o);
+                o += 2;
+            }
+        }
+    }
+    return out;
+}
+/** 32x32/48x32: the first half-frame holds the even rows, the second the odd ones. */
+export function mergeTmf8829Halves(first, second) {
+    const rows = first.rows * 2;
+    const cols = first.cols;
+    function merge(a, b, layers) {
+        if (a === null || b === null)
+            return null;
+        const m = new a.constructor(layers * rows * cols);
+        for (let l = 0; l < layers; l++) {
+            for (let r = 0; r < first.rows; r++) {
+                const src = (l * first.rows + r) * cols;
+                m.set(a.subarray(src, src + cols), (l * rows + 2 * r) * cols);
+                m.set(b.subarray(src, src + cols), (l * rows + 2 * r + 1) * cols);
+            }
+        }
+        return m;
+    }
+    return {
+        peaks: first.peaks,
+        rows,
+        cols,
+        distance: merge(first.distance, second.distance, first.peaks),
+        snr: merge(first.snr, second.snr, first.peaks),
+        signal: merge(first.signal, second.signal, first.peaks),
+        noise: merge(first.noise, second.noise, 1),
+        xtalk: merge(first.xtalk, second.xtalk, 1),
+    };
+}
+//# sourceMappingURL=frames.js.map

package/dist/sensors/tmf8829/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../../src/sensors/tmf8829/frames.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AACtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AACtC,6CAA6C;AAC7C,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,GAAG,mBAAmB,CAAC;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAExC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AACrC,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACxC,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAC3C,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AACzC,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AACzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AACzC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C,MAAM,WAAW,GAAG,IAAI,CAAC;AACzB,MAAM,aAAa,GAAG,IAAI,CAAC;AAC3B,MAAM,cAAc,GAA4B;IAC9C,CAAC,IAAI,EAAE,gBAAgB,CAAC;IACxB,CAAC,IAAI,EAAE,gBAAgB,CAAC;IACxB,CAAC,IAAI,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AACF,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAC/B,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAC9B,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B,sDAAsD;AACtD,MAAM,CAAC,MAAM,eAAe,GAAwD;IAClF,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACT,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACT,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACX,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACX,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACX,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;CACZ,CAAC;AACF,MAAM,CAAC,MAAM,gBAAgB,GAAqC;IAChE,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,OAAO;IACV,CAAC,EAAE,OAAO;IACV,CAAC,EAAE,QAAQ;IACX,CAAC,EAAE,OAAO;CACX,CAAC;AA0BF,qEAAqE;AACrE,MAAM,UAAU,gBAAgB,CAAC,IAAgB;IAC/C,OAAO,uBAAuB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAe;IAC/C,IAAI,GAAG,CAAC,MAAM,GAAG,kBAAkB,GAAG,mBAAmB,EAAE,CAAC;QAC1D,MAAM,IAAI,SAAS,CAAC,YAAY,GAAG,CAAC,MAAM,oCAAoC,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,CAAC,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACnE,MAAM,CAAC,GAAG,uBAAuB,CAAC;IAClC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,mBAAmB,CAAC;IAC3C,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC;IACnB,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;IAC7B,OAAO;QACL,UAAU,EAAE,GAAG,CAAC,CAAC,CAAE;QACnB,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC;QAC7B,EAAE;QACF,IAAI,EAAE,EAAE,GAAG,gBAAgB;QAC3B,MAAM,EAAE,EAAE,GAAG,IAAI;QACjB,MAAM;QACN,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;QACjC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;QACjC,WAAW,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QACpE,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,CAAE;QACjB,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9D,aAAa,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC;QACnC,aAAa,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;QACvC,WAAW,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE;QACxB,QAAQ;QACR,GAAG,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC;QAC9B,IAAI,EAAE,GAAG,CAAC,MAAM;QAChB,YAAY,EAAE,CAAC,MAAM,GAAG,uBAAuB,CAAC,KAAK,CAAC;QACtD,YAAY,EAAE,CAAC,QAAQ,GAAG,iBAAiB,CAAC,KAAK,CAAC;KACnD,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,oBAAoB,CAAC,CAAmB;IACtD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,CAAC,CAAC,GAAG,KAAK,iBAAiB;QAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IACxG,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC;QACnC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,CAAC,WAAW,GAAG,aAAa;QAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACvD,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,cAAc;QAAE,IAAI,CAAC,CAAC,WAAW,GAAG,GAAG;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClF,IAAI,CAAC,CAAC,UAAU,GAAG,gBAAgB;QAAE,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACjE,IAAI,CAAC,CAAC,UAAU,GAAG,eAAe;QAAE,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC/D,OAAO,GAAG,CAAC;AACb,CAAC;AAmBD,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;IACzD,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,mBAAmB,CAAC,GAAe,EAAE,IAAuB;IAC1E,MAAM,CAAC,GAAG,IAAI,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,yBAAyB,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,GAAG,oBAAoB,CAAC;IAC9C,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,QAAQ,CAAC;IACpE,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IACtB,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;IACnE,IAAI,MAAM,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,SAAS,CACjB,eAAe,QAAQ,gBAAgB,CAAC,SAAS,MAAM,gBAAgB,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,CAChG,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAwB;QAC/B,KAAK;QACL,IAAI;QACJ,IAAI;QACJ,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QACnD,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QAC7C,MAAM,EAAE,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QAC3D,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QACxC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;KACzC,CAAC;IACF,IAAI,CAAC,GAAG,kBAAkB,CAAC;IAC3B,MAAM,GAAG,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,GAAG,CAAC,EAAE,CAAE,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAE,IAAI,CAAC,CAAC,CAAC;IACnE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACd,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YACtB,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;QACD,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACd,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YACtB,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,GAAG,CAAC,QAAS,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YAClC,GAAG,CAAC,GAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;YAClC,CAAC,IAAI,CAAC,CAAC;YACP,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;gBACf,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;gBAC/B,CAAC,IAAI,CAAC,CAAC;YACT,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CAChC,KAA0B,EAC1B,MAA2B;IAE3B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,SAAS,KAAK,CAAqC,CAAW,EAAE,CAAW,EAAE,MAAc;QACzF,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,CAAC,GAAG,IAAK,CAAC,CAAC,WAAoC,CAAC,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;QAC5E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBACpC,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;gBACxC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;gBAC9D,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI;QACJ,IAAI;QACJ,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC;QAC7D,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC;QAC9C,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC;QACvD,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QAC1C,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/dist/sensors/tmf8829/tmf8829.d.ts

@@ -0,0 +1,144 @@
+/**
+ * TMF8829 multizone dToF sensor over the SPI register bridge
+ * (contracts/14_SENSOR_TMF8829.md).
+ *
+ * The board is a thin bridge: this class runs the sensor — soft reset,
+ * sensor firmware download through the sensor bootloader, presets and the
+ * config page, start/stop — and turns the bridge's chunked frame stream into
+ * measurements (half-frame merge, histograms, ref-SPAD frames, clock model,
+ * capture time). Mirrors the Python reference `depz_sensor_sdk.tmf8829.Tmf8829`.
+ */
+import { DepzDevice, StreamQueue, type DeviceOptions } from "../../device/device.js";
+import { DepzError } from "../../errors.js";
+import type { PacketEvent } from "../../protocol/framing.js";
+import { type Tmf8829Event, type Tmf8829Info } from "../../protocol/tmf8829.js";
+import type { SerialTransport } from "../../transport/types.js";
+import { type Tmf8829Measurement } from "./builder.js";
+import { type Tmf8829CfgField, type Tmf8829Preset } from "./config.js";
+/** ams tmf8829_application.hex load address (application 2.200.0). */
+export declare const TMF8829_FIRMWARE_LOAD_ADDR = 65536;
+/** The sensor firmware image `init()` downloads (14 444 B, MIT). Lazily decoded. */
+export declare function tmf8829FirmwareImage(): Promise<Uint8Array>;
+/** The sensor refused or did not answer (bootloader / application status). */
+export declare class Tmf8829Error extends DepzError {
+}
+export interface Tmf8829ConfigureOptions {
+    periodMs?: number;
+    /** Defaults to the preset's own value. */
+    kiloIterations?: number;
+    nrPeaks?: number;
+    signalStrength?: boolean;
+    noiseStrength?: boolean;
+    xtalk?: boolean;
+    histograms?: boolean;
+    refFrame?: boolean;
+    /** Any other config-page field by name. */
+    fields?: Partial<Record<Tmf8829CfgField, number>>;
+}
+/** The config written by `configure()`, as read back from the sensor. */
+export interface Tmf8829Config {
+    preset: Tmf8829Preset;
+    /** The 190-byte page 0x22..0xDF. */
+    page: Uint8Array;
+    histograms: boolean;
+    refFrame: boolean;
+    fields: Record<Tmf8829CfgField, number>;
+    /** [rows, cols] of a measurement. */
+    grid: readonly [number, number];
+}
+export interface Tmf8829Options extends DeviceOptions {
+    /** Injectable sleep (tests). */
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+/**
+ * TMF8829 ToF device (8×8 … 48×32 zones, up to 4 peaks per zone, histograms).
+ * `init()` downloads the 14.4 KB sensor firmware (~0.15 s), `configure(preset,
+ * …)` writes the config page, `start()` streams measurements to
+ * `onMeasurement` / `measurements()`, `stop()` ends it. The sensor's EN pin is
+ * wired high: there is no sleep, recovery from any state is `init()`.
+ */
+export declare class Tmf8829 extends DepzDevice {
+    appVersion: string | null;
+    sensorSerial: number | null;
+    private readonly sleepImpl;
+    private chain;
+    private readonly reassembler;
+    private readonly builder;
+    private measCbs;
+    private measQueues;
+    private interruptCbs;
+    private streamingFlag;
+    private stopping;
+    private cfg;
+    constructor(transport: SerialTransport, opts?: Tmf8829Options);
+    /**
+     * Read `length` bytes from `addr` in ≤1024-byte requests; reads that reach the
+     * FIFO port 0xFF stay there (the sensor does not auto-increment it).
+     */
+    readRegisters(addr: number, length: number): Promise<Uint8Array>;
+    /** Write `data` from `addr` in ≤1023-byte requests (writes to 0xFF stay at 0xFF). */
+    writeRegisters(addr: number, data: Uint8Array): Promise<void>;
+    /** Raw host-interface registers, for diagnostics. */
+    sensorState(): Promise<Record<string, number>>;
+    /** Bridge counters (never touches the sensor, safe mid-stream). */
+    getBridgeInfo(): Promise<Tmf8829Info>;
+    /**
+     * Bring the sensor from any state to its running RAM application: soft
+     * reset, bootloader, firmware download, start. Resolves [application
+     * version, sensor serial]. Stops a running stream first. `progress(done,
+     * total)` tracks the image download.
+     */
+    init(progress?: (done: number, total: number) => void): Promise<[string, number]>;
+    /** LOAD_CONFIG_PAGE → the 190-byte page 0x22..0xDF now in the sensor. */
+    configPage(): Promise<Uint8Array>;
+    /**
+     * Load `preset` and write the config page. Every field a preset does not
+     * reset is written (contract 14 §4), so the result never depends on an
+     * earlier config. Rejects with `Tmf8829Error` when the sensor refuses the
+     * page (e.g. ERR_CONFIG_RESULT_SIZE) or a written field does not read back.
+     */
+    configure(preset?: Tmf8829Preset, opts?: Tmf8829ConfigureOptions): Promise<Tmf8829Config>;
+    /** The last `configure()` result (null after `init()`). */
+    get config(): Tmf8829Config | null;
+    get streaming(): boolean;
+    /** MEASURE with the bridge stream armed; configures the 8x8 preset first if needed. */
+    start(): Promise<void>;
+    /**
+     * Sensor STOP, then the bridge stream (frames already queued drain). The
+     * bad-header event a STOP raises mid histogram dump is expected and
+     * swallowed.
+     */
+    stop(): Promise<void>;
+    close(): Promise<void>;
+    /** Subscribe to measurements (read-pump context; don't block). */
+    onMeasurement(cb: (m: Tmf8829Measurement) => void): () => void;
+    /** Async iterator over measurements — bounded, drop-oldest. */
+    measurements(maxsize?: number): StreamQueue<Tmf8829Measurement>;
+    /** Wait for the next measurement. */
+    getMeasurement(timeoutMs?: number): Promise<Tmf8829Measurement>;
+    /**
+     * RPT_TMF_EVENT that is not an expected stop artefact: a MOTION/PROXIMITY
+     * interrupt (code 0) or a refused frame header (code 1 — the sensor is lost,
+     * run `init()` again).
+     */
+    onInterrupt(cb: (e: Tmf8829Event) => void): () => void;
+    /** Frames the bridge dropped (frame_seq gaps) in this stream. */
+    get framesDropped(): number;
+    /** Frames lost to reassembly (incomplete, out-of-order chunks) in this stream. */
+    get framesDiscarded(): number;
+    get frameParseErrors(): number;
+    /** Current clock ratio (Q16), for diagnostics. */
+    get clockRatioQ16(): number;
+    /** Run `fn` after every previously queued sequence (non-reentrant). */
+    private locked;
+    private rd;
+    private rd8;
+    private wr;
+    private wr8;
+    private poll;
+    private blCmd;
+    private appCmd;
+    private loadConfig;
+    protected handleReport(pkt: PacketEvent): boolean;
+}
+//# sourceMappingURL=tmf8829.d.ts.map

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

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