@depz/sensor-sdk 0.2.2 → 0.4.0

package/dist/sensors/vl53lx/vl53lx.js

@@ -0,0 +1,694 @@
+/**
+ * VL53L 1D ToF family — VL53L0X, VL53L1CX, VL53L1CB, VL53L3CX, VL53L4CD,
+ * VL53L4CX — over the `APP_VL53L0_4` register bridge (contracts/12).
+ *
+ * The MCU is a thin I2C bridge that knows no sensor; every ULD runs here on
+ * the host (`uld/`). Two axes pick how a board is driven (`uld/registry.ts`):
+ * the **product** (whose parameter set to load — normally the part the
+ * board's device name carries; naming a neighbour borrows its driver) and the
+ * **driver kind** (`uld`, `ulp` or `histogram`). Every product answers with
+ * the same `Vl53lxMeasurement`; what differs is `supports(group)`.
+ *
+ * Mirrors the Python reference `depz_sensor_sdk.vl53lx`. TS-only difference:
+ * the product-level description is `identifyProduct()`, because
+ * `DepzDevice.identify()` already classifies the firmware.
+ */
+import { DepzDevice, StreamQueue } from "../../device/device.js";
+import { DepzError, DepzTimeoutError, StatusError } from "../../errors.js";
+import { Status } from "../../protocol/common.js";
+import { XFER_MAX, XSHUT_OFF, XSHUT_ON, XSHUT_RESET, packReadReg, packSetI2cSpeed, packWriteReg, packXshut, unpackRegData, unpackStream, } from "../../protocol/vl53l4.js";
+import { Vl53lxCmd, Vl53lxRpt, packVl53lxSetAddrWidth, packVl53lxStartStream, unpackVl53lxInfo, } from "../../protocol/vl53lx.js";
+import { chunkedRead, chunkedWrite } from "../reg-bridge.js";
+import { BridgePlatform } from "./uld/base.js";
+import { ProtocolError, Vl53Error } from "./uld/link.js";
+import * as registry from "./uld/registry.js";
+export { XSHUT_OFF, XSHUT_ON, XSHUT_RESET };
+/**
+ * Statuses that mean "this distance is real". A histogram product reports 6
+ * on the first frame of a stream and 11 on a merged pulse: use this, not
+ * `status === 0`, as the validity test on histogram products.
+ */
+export const PLOTTABLE_STATUSES = [0, 6, 11];
+function toVl53lxMeasurement(timestampUs, m, bins = null) {
+    return {
+        timestampUs,
+        distanceMm: m.distanceMm,
+        status: m.status,
+        statusText: m.statusText,
+        signalKcps: m.signalKcps,
+        ambientKcps: m.ambientKcps,
+        sigmaMm: m.sigmaMm,
+        spads: m.spads,
+        targets: [...m.targets],
+        extra: { ...m.extra },
+        bins,
+        valid: m.status === 0,
+        plottable: PLOTTABLE_STATUSES.includes(m.status),
+    };
+}
+/**
+ * The distances a chart should draw for one measurement: the plottable
+ * targets in driver order, or the single distance on a light driver.
+ */
+export function plotDistances(m) {
+    if (m.targets.length > 0) {
+        return m.targets.filter((t) => PLOTTABLE_STATUSES.includes(t.status)).map((t) => t.distanceMm);
+    }
+    return PLOTTABLE_STATUSES.includes(m.status) ? [m.distanceMm] : [];
+}
+/** The first plottable target, or null when the frame produced nothing usable. */
+export function primaryTarget(m) {
+    for (const t of m.targets)
+        if (PLOTTABLE_STATUSES.includes(t.status))
+            return t;
+    return null;
+}
+function isThenable(x) {
+    return typeof x === "object" && x !== null && typeof x.then === "function";
+}
+/**
+ * A board of the VL53L 1D family (firmware `APP_VL53L0_4`).
+ *
+ * `init()` binds the (product, driver kind) pair and runs the ULD's
+ * sensorInit; `configure()` re-initialises and applies the ranging
+ * configuration — call it before every run. Then `startRanging()` arms the MCU
+ * stream and measurements arrive via `onMeasurement` / `measurements()` /
+ * `getMeasurement()`. Configuration must not change while ranging.
+ *
+ * This generic class serves any product (read from the board's device name,
+ * or `product` at init); the per-product subclasses (`Vl53l0x`...) fix it.
+ */
+export class Vl53lx extends DepzDevice {
+    /** The product this class drives; null = read it from the device name. */
+    static PRODUCT = null;
+    driverInst = null;
+    productName = null;
+    driverKindName = null;
+    caveat = null;
+    boardNameCache = null;
+    measureCbs = [];
+    measureQueues = [];
+    rangingFlag = false;
+    streamParseErrorCount = 0;
+    /** Keeps asynchronous histogram decodes in frame order. */
+    decodeChain = Promise.resolve();
+    /** MCU timestamp of the latest register read (poll-mode measurements). */
+    lastRegTimestampUs = 0n;
+    sleepImpl;
+    platform;
+    /**
+     * The `BridgeDevice` the ULD ports talk to: register transfers split at the
+     * bridge's 253-byte limit; a non-OK status or a missing answer surfaces as
+     * `ProtocolError`, exactly what the ports catch.
+     */
+    bridge = {
+        readReg: async (addr, length) => {
+            try {
+                return await chunkedRead(addr, length, {
+                    chunkSize: XFER_MAX,
+                    readChunk: async (a, n) => {
+                        const rep = await this.request(Vl53lxCmd.ReadReg, packReadReg(a, n), {
+                            matcher: DepzDevice.expectReport(Vl53lxRpt.RegData, unpackRegData),
+                            timeoutMs: 2000,
+                        });
+                        return { data: rep.data, timestampUs: rep.timestampUs };
+                    },
+                    onTimestamp: (ts) => {
+                        this.lastRegTimestampUs = ts;
+                    },
+                });
+            }
+            catch (err) {
+                throw Vl53lx.asProtocolError(err, true);
+            }
+        },
+        writeReg: async (addr, data) => {
+            try {
+                await chunkedWrite(addr, data, {
+                    chunkSize: XFER_MAX,
+                    writeChunk: (a, chunk) => this.request(Vl53lxCmd.WriteReg, packWriteReg(a, chunk), {
+                        okCompletes: true,
+                        timeoutMs: 2000,
+                    }),
+                });
+            }
+            catch (err) {
+                throw Vl53lx.asProtocolError(err);
+            }
+        },
+        setI2cSpeed: async (khz) => {
+            try {
+                await this.request(Vl53lxCmd.SetI2cSpeed, packSetI2cSpeed(khz), { okCompletes: true });
+            }
+            catch (err) {
+                throw Vl53lx.asProtocolError(err);
+            }
+        },
+        setAddrWidth: async (width) => {
+            try {
+                await this.request(Vl53lxCmd.SetAddrWidth, packVl53lxSetAddrWidth(width), {
+                    okCompletes: true,
+                });
+            }
+            catch (err) {
+                throw Vl53lx.asProtocolError(err);
+            }
+        },
+        clearI2cErrors: async () => {
+            // A resetting die NACKs its own address for a moment; only the driver
+            // knows those NACKs were expected, so the host zeroes the counter once
+            // its init is through. A v2.00 bridge does not know the command.
+            try {
+                await this.request(Vl53lxCmd.ClearI2cErrors, new Uint8Array(0), { okCompletes: true });
+            }
+            catch (err) {
+                if (err instanceof StatusError && err.status === Status.ErrInvalidCmd) {
+                    throw new DepzError("the board's firmware predates APP_VL53L0_4_v0.24 (protocol v2.01) " +
+                        "and cannot clear its I2C error counter — reflash it");
+                }
+                throw Vl53lx.asProtocolError(err);
+            }
+        },
+        xshut: async (action) => {
+            try {
+                await this.request(Vl53lxCmd.Xshut, packXshut(action), {
+                    okCompletes: true,
+                    timeoutMs: 1000,
+                });
+            }
+            catch (err) {
+                throw Vl53lx.asProtocolError(err);
+            }
+        },
+    };
+    /**
+     * A reset makes the die NACK for a moment (the VL53L0X soft reset does it);
+     * the driver waits those out, and they are no bus fault.
+     */
+    async sensorInit(drv) {
+        await drv.sensorInit();
+        await this.bridge.clearI2cErrors();
+    }
+    /** StatusError / DepzTimeoutError (and a short register read) → ProtocolError. */
+    static asProtocolError(err, shortReadToo = false) {
+        if (err instanceof StatusError || err instanceof DepzTimeoutError) {
+            return new ProtocolError(err.message);
+        }
+        // chunkedRead reports a short reply as a plain DepzError.
+        if (shortReadToo && err instanceof DepzError && err.constructor === DepzError) {
+            return new ProtocolError(err.message);
+        }
+        return err;
+    }
+    constructor(transport, opts) {
+        super(transport, opts);
+        this.sleepImpl = opts?.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.platform = new BridgePlatform(this.bridge, (ms) => this.sleepImpl(ms));
+    }
+    get classProduct() {
+        return this.constructor.PRODUCT;
+    }
+    // ── identity ─────────────────────────────────────────────────────────────
+    /**
+     * The board's device name (bootloader metablock), e.g.
+     * `DEPZ ToF Sensor VL53L4CX USB v2.1 TOVJALN523`. Read once, then cached.
+     */
+    async boardName() {
+        if (this.boardNameCache === null)
+            this.boardNameCache = await this.getDeviceName();
+        return this.boardNameCache;
+    }
+    /** The product the device name carries, or null on an unstamped board. */
+    async detected() {
+        return registry.productFromBoardName(await this.boardName());
+    }
+    /** The product init() bound (null before init). */
+    get product() {
+        return this.productName;
+    }
+    get driverKind() {
+        return this.driverKindName;
+    }
+    /** The ULD port in use — escape hatch for product-specific calls. */
+    get driver() {
+        if (this.driverInst === null)
+            throw new DepzError("call init() first");
+        return this.driverInst;
+    }
+    get initialized() {
+        return this.driverInst !== null;
+    }
+    /** The driver kinds a product has (default: this board's). */
+    async driverKinds(product) {
+        const name = product || this.classProduct || (await this.detected());
+        return name ? registry.driverKinds(name) : [];
+    }
+    // ── lifecycle ────────────────────────────────────────────────────────────
+    /**
+     * Bind the (product, driver kind) pair and initialise the sensor.
+     *
+     * `product` defaults to this class's product, else the board's device name;
+     * `driver` defaults to the product's first kind (`uld`, else `ulp`, else
+     * `histogram`). A pair the table has no row for throws
+     * `NotImplementedError` naming what the product has.
+     */
+    async init(driver, opts = {}) {
+        this.requireNotRanging();
+        const name = opts.product || this.classProduct || (await this.detected());
+        if (!name) {
+            throw new DepzError(`board '${await this.boardName()}' carries no product number — pass product explicitly`);
+        }
+        const kind = driver || registry.driverKinds(name)[0];
+        if (kind === undefined) {
+            throw new registry.NotImplementedError(`${name} has no driver in this build`);
+        }
+        const [DriverCls, caveat] = registry.driverFor(name, kind);
+        // Sticky on the bridge and 2 after a reset: set before the first register
+        // access, model id included.
+        await this.bridge.setAddrWidth(DriverCls.ADDR_WIDTH);
+        const drv = new DriverCls(this.platform, name);
+        await this.sensorInit(drv);
+        this.driverInst = drv;
+        this.productName = name;
+        this.driverKindName = kind;
+        this.caveat = caveat;
+    }
+    /** Everything about what is connected (needs init()). */
+    async identifyProduct() {
+        const drv = this.driver;
+        const modelId = await drv.modelId();
+        const detected = await this.detected();
+        return {
+            board: await this.boardName(),
+            detected,
+            product: this.productName,
+            driver: this.driverKindName,
+            driverClass: drv.constructor.name,
+            kinds: registry.driverKinds(this.productName),
+            modelId,
+            modelIdOk: registry.modelIdOk(this.productName, modelId),
+            supports: new Set(drv.SUPPORTS),
+            modes: [...drv.MODES],
+            reachMm: registry.reachMm(detected || this.productName),
+            driverReachMm: await drv.reachMm(),
+            budgetMs: drv.BUDGET_MS,
+            budgetChoices: this.budgetChoices(),
+            histogram: drv.HISTOGRAM,
+            maxKhz: drv.MAX_KHZ,
+            caveat: this.caveat,
+        };
+    }
+    /**
+     * The lines a UI should show about the chosen pair: product named by hand,
+     * a borrowed driver, a pair that reaches less than the board is rated for,
+     * the driver's caveat.
+     */
+    async notes() {
+        const drv = this.driver;
+        const detected = await this.detected();
+        const out = [];
+        if (detected === null) {
+            out.push(`${this.productName}: board name carries no product number, named by hand`);
+        }
+        else if (detected !== this.productName) {
+            out.push(`${this.productName}: borrowing this driver - the board says it is a ${detected}`);
+        }
+        const rated = registry.reachMm(detected || this.productName);
+        const reach = await drv.reachMm();
+        if (rated && reach && reach < rated) {
+            out.push(`${this.productName}/${this.driverKindName}: this pair reaches ${reach} mm, the board ` +
+                `is rated ${rated} mm - past ${reach} mm the phase is out of the valid window and ` +
+                "frames come back with status 4");
+        }
+        if (this.caveat)
+            out.push(`${this.productName}/${this.driverKindName}: ${this.caveat}`);
+        return out;
+    }
+    /**
+     * Whether this product/driver serves an optional capability group: mode,
+     * timing, offset, calib_offset, xtalk, calib_xtalk, thresholds,
+     * signal_thresh, sigma_thresh, roi, temp_update, refspad.
+     */
+    supports(group) {
+        return this.driver.SUPPORTS.has(group);
+    }
+    /** Named ranging modes, first = what init leaves; [] if none. */
+    get modes() {
+        return [...this.driver.MODES];
+    }
+    // ── sensor power (XSHUT) and bridge diagnostics ─────────────────────────
+    /**
+     * Drive XSHUT: XSHUT_OFF / XSHUT_ON / XSHUT_RESET (1 ms pulse + 5 ms wait;
+     * the host confirms the boot). OFF and RESET stop the stream; the sensor
+     * then holds none of the configuration — init() again.
+     */
+    async xshut(action) {
+        await this.request(Vl53lxCmd.Xshut, packXshut(action), { okCompletes: true, timeoutMs: 1000 });
+        this.rangingFlag = false;
+        this.driverInst = null;
+    }
+    /** RPT_VL53_INFO — the bridge's own counters; safe while streaming. */
+    bridgeInfo() {
+        return this.request(Vl53lxCmd.GetInfo, undefined, {
+            matcher: DepzDevice.expectReport(Vl53lxRpt.Info, unpackVl53lxInfo),
+        });
+    }
+    // ── configuration (init() first; not while ranging) ─────────────────────
+    /**
+     * Re-initialise the sensor and apply a ranging configuration. The re-init
+     * is deliberate (the only way to know what the configuration registers
+     * hold). `mode` goes on before the budget; `offsetMm` / `xtalkKcps`
+     * re-apply a stored calibration; `signalKcps` goes on last. An unsupported
+     * group is refused before the re-init.
+     */
+    async configure(opts = {}) {
+        this.requireNotRanging();
+        const drv = this.driver;
+        const offset = opts.offsetMm != null ? this.need("offset") : null;
+        const xtalk = opts.xtalkKcps != null ? this.need("xtalk") : null;
+        const signal = opts.signalKcps != null ? this.need("signal_thresh") : null;
+        await this.sensorInit(drv);
+        if (opts.mode != null)
+            await drv.setMode(opts.mode);
+        await drv.setRangeTiming(opts.budgetMs ?? 50, opts.interMs ?? 0);
+        if (offset)
+            await offset.setOffset(opts.offsetMm);
+        if (xtalk)
+            await xtalk.setXtalk(opts.xtalkKcps);
+        if (signal)
+            await signal.setSignalThreshold(opts.signalKcps);
+    }
+    /** → [timingBudgetMs, interMeasurementMs]; 0 for the period = continuous. */
+    getRangeTiming() {
+        return this.driver.getRangeTiming();
+    }
+    /** The ranging mode in use, or null on a product without modes. */
+    async getMode() {
+        return this.supports("mode") ? this.driver.getMode() : null;
+    }
+    /** The only budgets accepted right now (ascending), or [] for any in range. */
+    budgetChoices() {
+        return [...this.driver.budgetChoices()];
+    }
+    /** The nearest budget this product will actually accept. */
+    snapBudget(budgetMs) {
+        const choices = this.budgetChoices();
+        if (choices.length > 0) {
+            let best = choices[0];
+            for (const c of choices)
+                if (Math.abs(c - budgetMs) < Math.abs(best - budgetMs))
+                    best = c;
+            return best;
+        }
+        const [low, high] = this.driver.BUDGET_MS;
+        return Math.max(low, Math.min(high, budgetMs));
+    }
+    // Capability-gated passthroughs. Each throws DepzError on a product/driver
+    // that does not serve the group (see supports()).
+    getOffsetMm() {
+        return this.need("offset").getOffset();
+    }
+    async setOffsetMm(offsetMm) {
+        this.requireNotRanging();
+        await this.need("offset").setOffset(offsetMm);
+    }
+    getXtalkKcps() {
+        return this.need("xtalk").getXtalk();
+    }
+    async setXtalkKcps(xtalkKcps) {
+        this.requireNotRanging();
+        await this.need("xtalk").setXtalk(xtalkKcps);
+    }
+    /**
+     * Offset calibration against a flat target at `targetDistMm`; returns the
+     * offset now programmed. Store it on the host (sensor RAM, lost on reset).
+     */
+    async calibrateOffset(targetDistMm, nbSamples) {
+        this.requireNotRanging();
+        return this.need("calib_offset").calibrateOffset(targetDistMm, nbSamples);
+    }
+    /** Crosstalk calibration; returns the xtalk now programmed (kcps). */
+    async calibrateXtalk(targetDistMm, nbSamples) {
+        this.requireNotRanging();
+        return this.need("calib_xtalk").calibrateXtalk(targetDistMm, nbSamples);
+    }
+    /** → [distanceLowMm, distanceHighMm, window]. */
+    getDetectionThresholds() {
+        return this.need("thresholds").getDetectionThresholds();
+    }
+    /** Arm the distance-window interrupt; stays armed until the next init/configure. */
+    async setDetectionThresholds(distanceLowMm, distanceHighMm, window) {
+        this.requireNotRanging();
+        await this.need("thresholds").setDetectionThresholds(distanceLowMm, distanceHighMm, window);
+    }
+    getSignalThresholdKcps() {
+        return this.need("signal_thresh").getSignalThreshold();
+    }
+    async setSignalThresholdKcps(signalKcps) {
+        this.requireNotRanging();
+        await this.need("signal_thresh").setSignalThreshold(signalKcps);
+    }
+    getSigmaThresholdMm() {
+        return this.need("sigma_thresh").getSigmaThreshold();
+    }
+    async setSigmaThresholdMm(sigmaMm) {
+        this.requireNotRanging();
+        await this.need("sigma_thresh").setSigmaThreshold(sigmaMm);
+    }
+    /** → [x, y] SPAD window size. */
+    getRoi() {
+        return this.need("roi").getRoi();
+    }
+    async setRoi(x, y) {
+        this.requireNotRanging();
+        await this.need("roi").setRoi(x, y);
+    }
+    getRoiCenter() {
+        return this.need("roi").getRoiCenter();
+    }
+    async setRoiCenter(centerSpad) {
+        this.requireNotRanging();
+        await this.need("roi").setRoiCenter(centerSpad);
+    }
+    /** Re-run VHV after an ambient change over 8 °C. */
+    async startTemperatureUpdate() {
+        this.requireNotRanging();
+        await this.need("temp_update").startTemperatureUpdate();
+    }
+    /** VL53L0X: re-measure the reference SPADs → [count, isAperture]. */
+    async performRefSpadManagement() {
+        this.requireNotRanging();
+        return this.need("refspad").performRefSpadManagement();
+    }
+    // ── ranging ──────────────────────────────────────────────────────────────
+    /**
+     * Start the sensor's ranging loop and arm the MCU stream: one
+     * RPT_VL53_STREAM per INT edge, followed on the MCU by the driver's
+     * interrupt-release writes.
+     */
+    async startRanging() {
+        this.requireNotRanging();
+        const drv = this.driver;
+        await drv.startRanging();
+        const [addr, length] = drv.streamBlock();
+        await this.request(Vl53lxCmd.StartStream, packVl53lxStartStream(addr, length, drv.CLEAR_STEPS), { okCompletes: true });
+        this.rangingFlag = true;
+    }
+    async stopRanging() {
+        if (!this.rangingFlag)
+            return;
+        // Clear host state and stop the sensor even if the STOP_STREAM ack fails.
+        try {
+            await this.request(Vl53lxCmd.StopStream, undefined, { okCompletes: true });
+        }
+        finally {
+            this.rangingFlag = false;
+            await this.driver.stopRanging();
+        }
+    }
+    get ranging() {
+        return this.rangingFlag;
+    }
+    /**
+     * Single poll-mode measurement: start ranging, wait for data-ready, read,
+     * release the interrupt, stop. Rejects while the stream runs.
+     */
+    async measureOnce(timeoutMs = 1000) {
+        this.requireNotRanging();
+        const drv = this.driver;
+        await drv.startRanging();
+        let m;
+        let bins = null;
+        try {
+            await drv.waitDataReady(timeoutMs / 1000);
+            if (drv.HISTOGRAM) {
+                const [addr, length] = drv.streamBlock();
+                const h = drv;
+                bins = await h.binData(await this.platform.rdMulti(addr, length));
+                m = h.toMeasurement(bins);
+            }
+            else {
+                m = await drv.readMeasurement();
+            }
+            await drv.clearInterrupt();
+        }
+        finally {
+            await drv.stopRanging();
+        }
+        return toVl53lxMeasurement(this.lastRegTimestampUs, m, bins);
+    }
+    /** Subscribe to streamed measurements. 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). */
+    measurements(maxsize = 64) {
+        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;
+    }
+    /** Wait for the next streamed measurement. */
+    async getMeasurement(timeoutMs = 2000) {
+        const queue = new StreamQueue(1);
+        this.measureQueues.push(queue);
+        const deregister = this.registerStream(queue);
+        let timer;
+        try {
+            const result = await Promise.race([
+                queue.next(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new DepzTimeoutError(Vl53lxRpt.Stream, timeoutMs)), timeoutMs);
+                }),
+            ]);
+            if (result.done === true)
+                throw new DepzError("device closed");
+            return result.value;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            this.measureQueues = this.measureQueues.filter((q) => q !== queue);
+            deregister();
+        }
+    }
+    /** Stream reports dropped because the driver failed to decode them. */
+    get streamParseErrors() {
+        return this.streamParseErrorCount;
+    }
+    /** Drop counters of all live measurement queues (diagnostics). */
+    get streamDroppedCounts() {
+        return this.measureQueues.map((q) => q.droppedCount);
+    }
+    // ── internal ─────────────────────────────────────────────────────────────
+    need(group) {
+        const drv = this.driver;
+        if (!drv.SUPPORTS.has(group)) {
+            throw new DepzError(`${this.productName}/${this.driverKindName} does not support '${group}'` +
+                (this.caveat ? ` (${this.caveat})` : ""));
+        }
+        return drv;
+    }
+    requireNotRanging() {
+        if (this.rangingFlag)
+            throw new DepzError("stopRanging() first — the stream owns the bus");
+    }
+    emit(out) {
+        for (const cb of [...this.measureCbs])
+            cb(out);
+        for (const q of [...this.measureQueues])
+            q.push(out);
+    }
+    handleReport(pkt) {
+        if (pkt.cmd !== Vl53lxRpt.Stream || pkt.payload.length < 12)
+            return false;
+        const drv = this.driverInst;
+        if (drv === null)
+            return true;
+        const sample = unpackStream(pkt.payload);
+        // Decoded exactly once per sample: the histogram driver steps its own
+        // frame-pair state on every frame it sees.
+        try {
+            if (!drv.HISTOGRAM) {
+                this.emit(toVl53lxMeasurement(sample.timestampUs, drv.decode(sample.data)));
+                return true;
+            }
+            const h = drv;
+            const bins = h.binData(sample.data);
+            if (!isThenable(bins)) {
+                this.emit(toVl53lxMeasurement(sample.timestampUs, h.toMeasurement(bins), bins));
+                return true;
+            }
+            // An async binData: keep frames in order through one chain.
+            this.decodeChain = this.decodeChain.then(async () => {
+                try {
+                    const b = await bins;
+                    this.emit(toVl53lxMeasurement(sample.timestampUs, h.toMeasurement(b), b));
+                }
+                catch {
+                    this.streamParseErrorCount += 1;
+                }
+            });
+        }
+        catch {
+            // A bad sample must not kill the read pump.
+            this.streamParseErrorCount += 1;
+        }
+        return true;
+    }
+}
+/**
+ * VL53L0X (2 m, 1-byte register addresses, 400 kHz): ULD API 1.0.4 with
+ * ranging profiles, offset and crosstalk calibration, ref-SPAD management.
+ */
+export class Vl53l0x extends Vl53lx {
+    static PRODUCT = "VL53L0X";
+}
+/** VL53L1CX (4 m): VL53L1X ULD (short / long) or the histogram driver. */
+export class Vl53l1cx extends Vl53lx {
+    static PRODUCT = "VL53L1CX";
+}
+/** VL53L1CB (8 m, cover-glass module): same die and drivers as VL53L1CX. */
+export class Vl53l1cb extends Vl53lx {
+    static PRODUCT = "VL53L1CB";
+}
+/** VL53L3CX (3 m): ST's ULP driver (single target) or the histogram driver. */
+export class Vl53l3cx extends Vl53lx {
+    static PRODUCT = "VL53L3CX";
+}
+/**
+ * VL53L4CX (6 m): the histogram driver only — to run it light, borrow a
+ * sibling's with `init(undefined, { product: "VL53L4CD" })`.
+ */
+export class Vl53l4cx extends Vl53lx {
+    static PRODUCT = "VL53L4CX";
+}
+/** Class per product (VL53L4CD on this firmware uses the generic class). */
+export const VL53LX_CLASS_BY_PRODUCT = {
+    VL53L0X: Vl53l0x,
+    VL53L1CX: Vl53l1cx,
+    VL53L1CB: Vl53l1cb,
+    VL53L3CX: Vl53l3cx,
+    VL53L4CX: Vl53l4cx,
+};
+/**
+ * Pick the 1D-family class (contract 12 §1): the production PID model, then
+ * the product the device name carries, then the generic class.
+ */
+export function resolveVl53lxClass(usbModel, deviceName) {
+    let product = (usbModel ?? "").toUpperCase() || null;
+    if (product === null || !registry.PRODUCTS.includes(product)) {
+        product = registry.productFromBoardName(deviceName ?? "");
+    }
+    return VL53LX_CLASS_BY_PRODUCT[product ?? ""] ?? Vl53lx;
+}
+export const VL53LX_PRODUCTS = registry.PRODUCTS;
+export const VL53LX_DRIVER_KINDS = registry.DRIVER_KINDS;
+export { ProtocolError, Vl53Error };
+//# sourceMappingURL=vl53lx.js.map