@depz/sensor-sdk 0.1.3 → 0.2.0

package/dist/sensors/vl53l4/uld.d.ts

@@ -0,0 +1,214 @@
+/**
+ * VL53L4CD ULD driver (ST STSW-IMG026 2.2.3) over the register bridge.
+ *
+ * Port of `VL53L4CD_api.c` + `VL53L4CD_calibration.c` — a 1:1 async mirror of
+ * the Python reference `depz_sensor_sdk.vl53l4.uld` (itself absorbed from the
+ * firmware repo's hardware-proven port). The MCU owns nothing but the I2C
+ * bus, XSHUT, INT and one streaming FSM — every register sequence below goes
+ * over VL53_READ_REG / VL53_WRITE_REG (contracts/10_SENSOR_VL53L4.md §1).
+ *
+ * Register sequences are a faithful port of the C code, integer widths and
+ * 32-bit truncations included; do not "simplify" them. Pure codec/math pieces
+ * (`parseResultBlock`, `rangeTimingRegisters`, `decodeRangeTiming`,
+ * `configBlock`, the tuning codecs) are module functions so the golden
+ * vectors can hold them to byte-exact parity with the other SDKs.
+ */
+export declare const ULD_VERSION: readonly [number, number, number, number];
+export declare const SOFT_RESET = 0;
+export declare const I2C_SLAVE__DEVICE_ADDRESS = 1;
+/** Unnamed in the C driver. */
+export declare const OSC_FREQUENCY = 6;
+export declare const VHV_CONFIG__TIMEOUT_MACROP_LOOP_BOUND = 8;
+export declare const XTALK_PLANE_OFFSET_KCPS = 22;
+export declare const XTALK_X_PLANE_GRADIENT_KCPS = 24;
+export declare const XTALK_Y_PLANE_GRADIENT_KCPS = 26;
+export declare const RANGE_OFFSET_MM = 30;
+export declare const INNER_OFFSET_MM = 32;
+export declare const OUTER_OFFSET_MM = 34;
+export declare const GPIO_HV_MUX__CTRL = 48;
+export declare const GPIO__TIO_HV_STATUS = 49;
+export declare const SYSTEM__INTERRUPT = 70;
+export declare const RANGE_CONFIG_A = 94;
+export declare const RANGE_CONFIG_B = 97;
+export declare const RANGE_CONFIG__SIGMA_THRESH = 100;
+export declare const MIN_COUNT_RATE_RTN_LIMIT_MCPS = 102;
+export declare const INTERMEASUREMENT_MS = 108;
+export declare const THRESH_HIGH = 114;
+export declare const THRESH_LOW = 116;
+export declare const SYSTEM__INTERRUPT_CLEAR = 134;
+export declare const SYSTEM_START = 135;
+export declare const RESULT__RANGE_STATUS = 137;
+export declare const RESULT__SPAD_NB = 140;
+export declare const RESULT__SIGNAL_RATE = 142;
+export declare const RESULT__AMBIENT_RATE = 144;
+export declare const RESULT__SIGMA = 146;
+export declare const RESULT__DISTANCE = 150;
+export declare const RESULT__OSC_CALIBRATE_VAL = 222;
+export declare const FIRMWARE__SYSTEM_STATUS = 229;
+export declare const IDENTIFICATION__MODEL_ID = 271;
+export declare const MODEL_ID_VL53L4CD = 60330;
+export declare const WINDOW_BELOW = 0;
+export declare const WINDOW_ABOVE = 1;
+export declare const WINDOW_OUT = 2;
+export declare const WINDOW_IN = 3;
+export declare const CONFIG_ADDR = 45;
+export declare const CONFIG_END = 135;
+/**
+ * VL53L4CD_DEFAULT_CONFIGURATION[] — 91 bytes, registers 0x2D..0x87.
+ * `configBlock()` always overrides byte 0 (register 0x2D) with
+ * CONFIG_FMP_BYTE (0x12) to put the sensor's I2C pad in Fast Mode Plus —
+ * exactly what VL53L4CD_I2C_FAST_MODE_PLUS does in the C ULD. FM+ pads work
+ * at every bus step down to 100 kHz, so it is set unconditionally and never
+ * cleared (clearing it mid-block NACKs and truncates the write).
+ */
+export declare const DEFAULT_CONFIGURATION: Uint8Array;
+export declare const CONFIG_FMP_BYTE = 18;
+export declare const RESULT_BLOCK_ADDR = 137;
+export declare const RESULT_BLOCK_LEN = 17;
+export declare const I2C_KHZ_BOOT = 400;
+export declare const I2C_KHZ_DEFAULT = 1000;
+/** GetResult() raw status → ULD status (status_rtn[24] in VL53L4CD_api.c). */
+export declare const STATUS_RTN: readonly number[];
+/** UM2931, "Range status description". */
+export declare const RANGE_STATUS_NAMES: Readonly<Record<number, string>>;
+export declare class Vl53l4cdError extends Error {
+    constructor(message?: string);
+}
+/** What the ULD needs from the register bridge. */
+export interface Vl53l4Platform {
+    rdMulti(addr: number, size: number): Promise<Uint8Array>;
+    wrMulti(addr: number, data: Uint8Array): Promise<void>;
+    setI2cSpeed(khz: number): Promise<void>;
+    sleepMs(ms: number): Promise<void>;
+}
+/** VL53L4CD_ResultsData_t plus the sensor's own frame counter. */
+export interface Vl53l4Results {
+    /** 0 = valid (RANGE_STATUS_NAMES). */
+    rangeStatus: number;
+    distanceMm: number;
+    ambientRateKcps: number;
+    ambientPerSpadKcps: number;
+    signalRateKcps: number;
+    signalPerSpadKcps: number;
+    numberOfSpad: number;
+    sigmaMm: number;
+    /**
+     * 0x008B RESULT__STREAM_COUNT: wraps at 255. The C ULD ignores it; it is
+     * what tells a frame the host never received from one the sensor never
+     * produced.
+     */
+    streamCount: number;
+}
+/** Human-readable text for a decoded range status. */
+export declare function rangeStatusText(rangeStatus: number): string;
+/**
+ * Decode the streamed 0x0089..0x0099 block exactly as VL53L4CD_GetResult()
+ * decodes the same registers read one by one. Register contents are
+ * big-endian words (the bridge passes them through untouched).
+ */
+export declare function parseResultBlock(raw: Uint8Array): Vl53l4Results;
+/**
+ * The 91-byte block sensorInit() writes at CONFIG_ADDR: the ST default
+ * configuration with byte 0 forced to CONFIG_FMP_BYTE (Fast Mode Plus).
+ */
+export declare function configBlock(): Uint8Array;
+/** SetRangeTiming register words. */
+export interface RangeTimingRegisters {
+    rangeConfigA: number;
+    rangeConfigB: number;
+    /** INTERMEASUREMENT_MS raw dword. */
+    intermeasurementRaw: number;
+}
+/**
+ * SetRangeTiming register math → RANGE_CONFIG_A, RANGE_CONFIG_B and the
+ * INTERMEASUREMENT_MS raw dword.
+ *
+ * `oscFrequency` is the word read from 0x0006; `clockPll` is the word read
+ * from RESULT__OSC_CALIBRATE_VAL (used only in autonomous mode, i.e. when
+ * `interMeasurementMs > 0`).
+ */
+export declare function rangeTimingRegisters(timingBudgetMs: number, interMeasurementMs: number, oscFrequency: number, clockPll?: number): RangeTimingRegisters;
+/** GetRangeTiming decode result. */
+export interface RangeTiming {
+    timingBudgetMs: number;
+    interMeasurementMs: number;
+}
+/**
+ * GetRangeTiming register math → timing budget and inter-measurement period.
+ *
+ * Inputs are the raw register reads: INTERMEASUREMENT_MS dword, the
+ * RESULT__OSC_CALIBRATE_VAL word, the 0x0006 word and the RANGE_CONFIG_A
+ * word.
+ */
+export declare function decodeRangeTiming(intermeasurementRaw: number, clockPll: number, oscFrequency: number, rangeConfigA: number): RangeTiming;
+/** RANGE_OFFSET_MM word for setOffset (INNER/OUTER are zeroed alongside). */
+export declare function offsetRaw(offsetMm: number): number;
+/** getOffset: RANGE_OFFSET_MM word → signed millimetres. */
+export declare function decodeOffset(rawWord: number): number;
+/** XTALK_PLANE_OFFSET_KCPS word for setXtalk. */
+export declare function xtalkRaw(xtalkKcps: number): number;
+/** getXtalk: XTALK_PLANE_OFFSET_KCPS word → kcps. */
+export declare function decodeXtalk(rawWord: number): number;
+export declare function signalThresholdRaw(signalKcps: number): number;
+export declare function decodeSignalThreshold(rawWord: number): number;
+export declare function sigmaThresholdRaw(sigmaMm: number): number;
+export declare function decodeSigmaThreshold(rawWord: number): number;
+/** Port of VL53L4CD_api.c + VL53L4CD_calibration.c (ULD 2.2.3). */
+export declare class VL53L4CD {
+    readonly p: Vl53l4Platform;
+    constructor(p: Vl53l4Platform);
+    rdByte(addr: number): Promise<number>;
+    rdWord(addr: number): Promise<number>;
+    rdDword(addr: number): Promise<number>;
+    wrByte(addr: number, value: number): Promise<void>;
+    wrWord(addr: number, value: number): Promise<void>;
+    wrDword(addr: number, value: number): Promise<void>;
+    getSensorId(): Promise<number>;
+    isAlive(): Promise<boolean>;
+    waitBoot(timeoutMs?: number): Promise<void>;
+    /**
+     * Initialise the sensor and leave the bus at `busKhz`.
+     *
+     * The configuration block is written at I2C_KHZ_BOOT (400 kHz) because that
+     * is the only speed an unconfigured sensor is specified for; the bridge is
+     * re-timed to `busKhz` after it. A sensor reset just re-runs this whole
+     * sequence.
+     */
+    sensorInit(busKhz?: number): Promise<void>;
+    clearInterrupt(): Promise<void>;
+    startRanging(): Promise<void>;
+    stopRanging(): Promise<void>;
+    checkForDataReady(): Promise<boolean>;
+    waitDataReady(timeoutMs?: number): Promise<void>;
+    /**
+     * One block read instead of the C driver's six register reads — the sensor
+     * auto-increments and the decoding is identical.
+     */
+    getResult(): Promise<Vl53l4Results>;
+    setRangeTiming(timingBudgetMs: number, interMeasurementMs: number): Promise<void>;
+    getRangeTiming(): Promise<RangeTiming>;
+    setOffset(offsetMm: number): Promise<void>;
+    getOffset(): Promise<number>;
+    setXtalk(xtalkKcps: number): Promise<void>;
+    getXtalk(): Promise<number>;
+    setDetectionThresholds(distanceLowMm: number, distanceHighMm: number, window: number): Promise<void>;
+    getDetectionThresholds(): Promise<{
+        distanceLowMm: number;
+        distanceHighMm: number;
+        window: number;
+    }>;
+    setSignalThreshold(signalKcps: number): Promise<void>;
+    getSignalThreshold(): Promise<number>;
+    setSigmaThreshold(sigmaMm: number): Promise<void>;
+    getSigmaThreshold(): Promise<number>;
+    /** Recommended after a >8 °C ambient change (ST Example_3). */
+    startTemperatureUpdate(): Promise<void>;
+    /**
+     * The ranging loop both calibrations share: data-ready, getResult,
+     * clearInterrupt, `nbSamples` times.
+     */
+    private collect;
+    calibrateOffset(targetDistMm: number, nbSamples?: number): Promise<number>;
+    calibrateXtalk(targetDistMm: number, nbSamples?: number): Promise<number>;
+}
+//# sourceMappingURL=uld.d.ts.map

package/dist/sensors/vl53l4/uld.d.ts.map

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