@robotical/webapp-types 3.25.10 → 3.25.12

package/dist-types/package.json

@@ -1,6 +1,6 @@
 {
     "name": "marty-web-app",
-    "version": "3.25.10",
+    "version": "3.25.12",
     "private": true,
     "engines": {
         "node": ">=20"

package/dist-types/src/application/RAFTs/Marty/PublishedDataAnalyser.d.ts

@@ -1,12 +1,12 @@
 /// <reference types="node" />
 import EventEmitter from "events";
-import { ColourSignalProfile } from "../../../utils/colour-classifier";
+import { classifyColour, ColourSignalProfile } from "../../../utils/colour-classifier";
 import RAFT from "../RAFT";
 import type { RICStateInfo } from "@robotical/roboticaljs";
 import { type ColourSensorValues } from "./published-data-helpers";
 interface MartyState {
     colourSensed: "blue" | "green" | "red" | "yellow" | "purple" | "unclear" | "air";
-    /** Rule strength (0–100), not probability; null when no scored reading is available. */
+    /** Rule strength of the confirmed/held colour (0–100); null without a reading. */
     colourConfidence: number | null;
     lightSense: "none" | "high" | "mid" | "low";
     objectSense: "none" | "near";
@@ -16,6 +16,11 @@ declare class PublishedDataAnalyser extends EventEmitter {
     private marty;
     martyState: MartyState;
     private pubSub;
+    lastColourReading: ReturnType<typeof classifyColour> | null;
+    private colourFilter;
+    private colourContext;
+    private colourExpiry;
+    private connectionObserver;
     lightSenseDetection: LightSenseDetection;
     colourSensedDetection: ColourSensedDetection;
     objectSenseDetection: ObjectSenseDetection;
@@ -37,12 +42,15 @@ declare class PublishedDataAnalyser extends EventEmitter {
     unsubscribeFromPublishedData(): void;
     analyse(data: RICStateInfo): void;
     setColourSensed(colour: MartyState["colourSensed"], confidence?: number | null): void;
+    private resetColourDetection;
+    recordColourReading(reading: ReturnType<typeof classifyColour>, receivedAtMs: number): void;
+    private scheduleColourExpiry;
     setLightSense(lightSense: MartyState["lightSense"]): void;
     setObjectSense(objectSense: MartyState["objectSense"]): void;
     setNoiseSense(noiseSense: MartyState["noiseSense"]): void;
 }
 declare class ColourSensedDetection {
-    detectColourSensed({ r, g, b, clear, air }: ColourSensorValues, analyser: PublishedDataAnalyser, profile?: ColourSignalProfile): void;
+    detectColourSensed({ r, g, b, clear, air }: ColourSensorValues, analyser: PublishedDataAnalyser, profile?: ColourSignalProfile, receivedAtMs?: number): void;
 }
 declare class LightSenseDetection {
     private lowLightThreshold;

package/dist-types/src/application/RAFTs/Marty/PublishedDataAnalyser.js

@@ -14,15 +14,29 @@ var __extends = (this && this.__extends) || (function () {
     };
 })();
 import EventEmitter from "events";
-import { classifyColour } from "../../../utils/colour-classifier";
+import { RaftConnEvent } from "@robdobsn/raftjs";
+import { classifyColour, colourChannelsFromValues } from "../../../utils/colour-classifier";
+import { ColourEventFilter } from "../../../utils/colour-event-filter";
 import { getAddonColourSensorProfile } from "../../../utils/colour-sensor-profile";
 import { createRaftPubSubscriptionHelper } from "../raft-subscription-helpers";
-import { getColourSensor, getLightSensor, getObjectSensor, getNoiseSensor, getRGBFromColourSensorVals, getLightSenseValues, getObjectIsTouchingFromVals, getNoiseSenseValue, } from "./published-data-helpers";
+import { getColourSensor, getLightSensor, getObjectSensor, getNoiseSensor, getLightSenseValues, getObjectIsTouchingFromVals, getNoiseSenseValue, } from "./published-data-helpers";
 var PublishedDataAnalyser = /** @class */ (function (_super) {
     __extends(PublishedDataAnalyser, _super);
     function PublishedDataAnalyser(marty) {
         var _this = _super.call(this) || this;
         _this.marty = marty;
+        _this.lastColourReading = null;
+        _this.colourFilter = new ColourEventFilter();
+        _this.colourContext = "";
+        _this.colourExpiry = null;
+        _this.connectionObserver = {
+            notify: function (eventType, eventEnum) {
+                if (eventType === "conn" && [RaftConnEvent.CONN_DISCONNECTED, RaftConnEvent.CONN_REJECTED,
+                    RaftConnEvent.CONN_VERIFYING_CORRECT, RaftConnEvent.CONN_VERIFIED_CORRECT].includes(eventEnum)) {
+                    _this.resetColourDetection();
+                }
+            },
+        };
         _this.lightSenseDetection = new LightSenseDetection();
         _this.colourSensedDetection = new ColourSensedDetection();
         _this.objectSenseDetection = new ObjectSenseDetection();
@@ -72,6 +86,9 @@ var PublishedDataAnalyser = /** @class */ (function (_super) {
     }
     PublishedDataAnalyser.prototype.subscribeToPublishedData = function () {
         var _this = this;
+        var _a;
+        (_a = this.pubSub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        this.marty.subscribe(this.connectionObserver, ["conn"]);
         this.pubSub = createRaftPubSubscriptionHelper(this.marty, this.marty.id);
         this.pubSub.subscribe(function (data) {
             _this.analyse(data.stateInfo);
@@ -80,6 +97,9 @@ var PublishedDataAnalyser = /** @class */ (function (_super) {
     PublishedDataAnalyser.prototype.unsubscribeFromPublishedData = function () {
         var _a;
         (_a = this.pubSub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        this.pubSub = null;
+        this.marty.unsubscribe(this.connectionObserver);
+        this.resetColourDetection();
     };
     PublishedDataAnalyser.prototype.analyse = function (data) {
         var _a;
@@ -89,8 +109,24 @@ var PublishedDataAnalyser = /** @class */ (function (_super) {
         var lightSensor = getLightSensor(data);
         var objectSensor = getObjectSensor(data);
         var noiseSensor = getNoiseSensor(data);
-        colourSensor &&
-            this.colourSensedDetection.detectColourSensed(getRGBFromColourSensorVals(colourSensor), this, (_a = getAddonColourSensorProfile(this.marty, colourSensor)) === null || _a === void 0 ? void 0 : _a.signal);
+        var powerAge = Date.now() - data.powerValidMs;
+        if (!colourSensor || this.marty.isVerified === false || document.hidden ||
+            (colourSensor.status !== undefined && !(colourSensor.status & 0x80)) ||
+            (data.powerValidMs > 0 && powerAge >= 0 && powerAge < 3000 && ((_a = data.power) === null || _a === void 0 ? void 0 : _a.powerStatus.power5VIsOn) === false)) {
+            this.resetColourDetection();
+        }
+        else {
+            var profile = getAddonColourSensorProfile(this.marty, colourSensor);
+            var profileSignal = profile === null || profile === void 0 ? void 0 : profile.signal;
+            var context = JSON.stringify([colourSensor.id, colourSensor.name, profile === null || profile === void 0 ? void 0 : profile.serialNumber, profile === null || profile === void 0 ? void 0 : profile.offsetsHex, profile === null || profile === void 0 ? void 0 : profile.whiteCalibrationHex, profile === null || profile === void 0 ? void 0 : profile.capturedAtMs, profileSignal === null || profileSignal === void 0 ? void 0 : profileSignal.airMax.red, profileSignal === null || profileSignal === void 0 ? void 0 : profileSignal.airMax.green, profileSignal === null || profileSignal === void 0 ? void 0 : profileSignal.airMax.blue, profileSignal === null || profileSignal === void 0 ? void 0 : profileSignal.margin.red, profileSignal === null || profileSignal === void 0 ? void 0 : profileSignal.margin.green, profileSignal === null || profileSignal === void 0 ? void 0 : profileSignal.margin.blue]);
+            if (context !== this.colourContext) {
+                this.resetColourDetection();
+                this.colourContext = context;
+            }
+            var values = colourChannelsFromValues(colourSensor.vals);
+            this.colourSensedDetection.detectColourSensed({ r: values.red, g: values.green, b: values.blue,
+                clear: values.clear, air: values.air }, this, profile === null || profile === void 0 ? void 0 : profile.signal, data.addOnInfoValidMs);
+        }
         (objectSensor || colourSensor) &&
             this.objectSenseDetection.detectObjectSense(getObjectIsTouchingFromVals(objectSensor, colourSensor), this);
         lightSensor &&
@@ -104,9 +140,42 @@ var PublishedDataAnalyser = /** @class */ (function (_super) {
     };
     PublishedDataAnalyser.prototype.setColourSensed = function (colour, confidence) {
         if (confidence === void 0) { confidence = null; }
+        var changed = colour !== this.martyState.colourSensed;
         this.martyState.colourSensed = colour;
         this.martyState.colourConfidence = confidence;
-        this.emit(this.eventsMap.colourSensed[colour]);
+        if (changed)
+            this.emit(this.eventsMap.colourSensed[colour]);
+    };
+    PublishedDataAnalyser.prototype.resetColourDetection = function () {
+        if (this.colourExpiry !== null)
+            clearTimeout(this.colourExpiry);
+        this.colourExpiry = null;
+        this.colourContext = "";
+        this.colourFilter.reset();
+        this.lastColourReading = null;
+        this.setColourSensed("unclear", null);
+    };
+    PublishedDataAnalyser.prototype.recordColourReading = function (reading, receivedAtMs) {
+        this.lastColourReading = reading;
+        var value = this.colourFilter.update(reading, receivedAtMs, Date.now());
+        this.setColourSensed(value.colour, value.confidence);
+        this.scheduleColourExpiry();
+    };
+    PublishedDataAnalyser.prototype.scheduleColourExpiry = function () {
+        var _this = this;
+        if (this.colourExpiry !== null)
+            clearTimeout(this.colourExpiry);
+        var expiresAt = this.colourFilter.nextExpiryAtMs;
+        this.colourExpiry = expiresAt === null ? null : setTimeout(function () {
+            _this.colourExpiry = null;
+            if (_this.marty.isVerified === false || document.hidden) {
+                _this.resetColourDetection();
+                return;
+            }
+            var value = _this.colourFilter.current(Date.now());
+            _this.setColourSensed(value.colour, value.confidence);
+            _this.scheduleColourExpiry();
+        }, Math.max(0, expiresAt - Date.now()));
     };
     PublishedDataAnalyser.prototype.setLightSense = function (lightSense) {
         this.martyState.lightSense = lightSense;
@@ -125,10 +194,11 @@ var PublishedDataAnalyser = /** @class */ (function (_super) {
 var ColourSensedDetection = /** @class */ (function () {
     function ColourSensedDetection() {
     }
-    ColourSensedDetection.prototype.detectColourSensed = function (_a, analyser, profile) {
+    ColourSensedDetection.prototype.detectColourSensed = function (_a, analyser, profile, receivedAtMs) {
         var r = _a.r, g = _a.g, b = _a.b, clear = _a.clear, air = _a.air;
+        if (receivedAtMs === void 0) { receivedAtMs = Date.now(); }
         var reading = classifyColour({ red: r, green: g, blue: b, clear: clear, air: air }, profile);
-        return analyser.setColourSensed(reading.classifiedColour, reading.confidence);
+        return analyser.recordColourReading(reading, receivedAtMs);
     };
     return ColourSensedDetection;
 }());

package/dist-types/src/screens/configuration/marty/Diagnostics/ColourSensorDiagnostics/messages.d.ts

@@ -22,6 +22,19 @@ declare const colourDiagnosticsEnglish: {
     confidenceHelp: string;
     withoutAir: string;
     firmwareAir: string;
+    profileSource: string;
+    eepromStatus: string;
+    eeprom: string;
+    local: string;
+    firebase: string;
+    defaultRules: string;
+    verified: string;
+    empty: string;
+    invalid: string;
+    readFailed: string;
+    writeFailed: string;
+    firmwareNotAudited: string;
+    notChecked: string;
     waiting: string;
     capture: string;
     captureAir: string;

package/dist-types/src/screens/configuration/marty/Diagnostics/ColourSensorDiagnostics/messages.js

@@ -17,6 +17,12 @@ var colourDiagnosticsEnglish = {
     confidenceHelp: "Rule strength, not probability. Higher scores mean more room before a colour or air cutoff. Air needs a saved calibration to score.",
     withoutAir: "Firmware reports air; the RGB signal matches {{result}}.",
     firmwareAir: "Firmware Air",
+    profileSource: "Profile: {{source}}",
+    eepromStatus: "EEPROM: {{status}}",
+    eeprom: "sensor memory", local: "local backup", firebase: "database backup", defaultRules: "default rules",
+    verified: "verified", empty: "no profile saved", invalid: "invalid or outdated profile",
+    readFailed: "read failed", writeFailed: "save failed", firmwareNotAudited: "not enabled for this firmware",
+    notChecked: "not checked yet",
     waiting: "Select a sensor and wait for fresh readings.",
     capture: "Take {{colour}} snapshot",
     captureAir: "Take air snapshot",

package/dist-types/src/utils/colour-classifier.d.ts

@@ -4,7 +4,7 @@ export type RGB = {
     blue: number;
 };
 export type ColourSignalProfile = {
-    airMin: RGB;
+    airMin?: RGB;
     airMax: RGB;
     margin: RGB;
 };
@@ -33,7 +33,7 @@ export declare const classifyColour: (values: RGB & {
     signalSource: string;
     classificationReason: string;
 };
-export declare const colourChannelsFromValues: (vals: Record<string, number | boolean>) => {
+export declare const colourChannelsFromValues: (vals: Record<string, unknown>) => {
     red: number;
     green: number;
     blue: number;

package/dist-types/src/utils/colour-classifier.js

@@ -86,5 +86,5 @@ export var colourChannelsFromValues = function (vals) {
                 values[channel.toLowerCase()] = vals[key];
         }
     return { red: values.red, green: values.green, blue: values.blue,
-        clear: values.clear, air: [true, false, 0, 1].includes(values.air) ? Boolean(values.air) : undefined };
+        clear: values.clear, air: [true, false, 0, 1].some(function (value) { return value === values.air; }) ? Boolean(values.air) : undefined };
 };

package/dist-types/src/utils/colour-event-filter.d.ts

@@ -0,0 +1,24 @@
+import type { classifyColour, ColourName } from "./colour-classifier";
+export declare const COLOUR_EVENT_TIMING: {
+    readonly minimumReadings: 3;
+    readonly confirmationMs: 200;
+    readonly signalGapMs: 250;
+    readonly staleMs: 500;
+};
+type Reading = Pick<ReturnType<typeof classifyColour>, "classifiedColour" | "confidence" | "classificationReason">;
+type Value = {
+    colour: ColourName;
+    confidence: number | null;
+};
+/** Per-sensor event confirmation. Instantaneous classification remains independent. */
+export declare class ColourEventFilter {
+    private lastPacketAtMs;
+    private latest;
+    private confirmed;
+    private candidate;
+    reset(): void;
+    current(now: number): Value;
+    update(reading: Reading, receivedAtMs: number, now: number): Value;
+    get nextExpiryAtMs(): number | null;
+}
+export {};

package/dist-types/src/utils/colour-event-filter.js

@@ -0,0 +1,88 @@
+export var COLOUR_EVENT_TIMING = {
+    minimumReadings: 3,
+    confirmationMs: 200,
+    signalGapMs: 250,
+    staleMs: 500,
+};
+var isCard = function (colour) { return colour !== "air" && colour !== "unclear"; };
+/** Per-sensor event confirmation. Instantaneous classification remains independent. */
+var ColourEventFilter = /** @class */ (function () {
+    function ColourEventFilter() {
+        this.lastPacketAtMs = null;
+        this.latest = null;
+        this.confirmed = null;
+        this.candidate = null;
+    }
+    ColourEventFilter.prototype.reset = function () {
+        this.lastPacketAtMs = null;
+        this.latest = this.confirmed = this.candidate = null;
+    };
+    ColourEventFilter.prototype.current = function (now) {
+        var _a, _b;
+        if (this.lastPacketAtMs !== null && now - this.lastPacketAtMs >= COLOUR_EVENT_TIMING.staleMs) {
+            // Retain the packet watermark: repeated cached packets are still duplicates.
+            this.latest = this.confirmed = this.candidate = null;
+        }
+        if (this.confirmed && now - this.confirmed.lastAtMs >= COLOUR_EVENT_TIMING.signalGapMs)
+            this.confirmed = null;
+        if (this.candidate && now - this.candidate.lastAtMs >= COLOUR_EVENT_TIMING.signalGapMs)
+            this.candidate = null;
+        return ((_a = this.confirmed) === null || _a === void 0 ? void 0 : _a.value) || (((_b = this.latest) === null || _b === void 0 ? void 0 : _b.colour) === "air" ? this.latest :
+            { colour: "unclear", confidence: this.latest ? 0 : null });
+    };
+    ColourEventFilter.prototype.update = function (reading, receivedAtMs, now) {
+        var _a, _b;
+        this.current(now);
+        if (!Number.isFinite(receivedAtMs) || receivedAtMs <= 0 || receivedAtMs > now ||
+            now - receivedAtMs >= COLOUR_EVENT_TIMING.staleMs) {
+            this.reset();
+            return this.current(now);
+        }
+        // A STATE_INFO event can reuse the same add-on packet when other telemetry changes.
+        if (this.lastPacketAtMs !== null && receivedAtMs <= this.lastPacketAtMs)
+            return this.current(now);
+        this.lastPacketAtMs = receivedAtMs;
+        var value = { colour: reading.classifiedColour, confidence: reading.confidence };
+        this.latest = value;
+        if (reading.classificationReason === "invalid") {
+            this.confirmed = this.candidate = null;
+        }
+        else if (isCard(value.colour)) {
+            if (((_a = this.confirmed) === null || _a === void 0 ? void 0 : _a.value.colour) === value.colour) {
+                this.confirmed.value = value;
+                this.confirmed.lastAtMs = receivedAtMs;
+                this.candidate = null;
+            }
+            else {
+                if (((_b = this.candidate) === null || _b === void 0 ? void 0 : _b.value.colour) === value.colour) {
+                    this.candidate.count++;
+                    this.candidate.lastAtMs = receivedAtMs;
+                    this.candidate.value = value;
+                }
+                else {
+                    this.candidate = { value: value, firstAtMs: receivedAtMs, lastAtMs: receivedAtMs, count: 1 };
+                }
+                if (this.candidate.count >= COLOUR_EVENT_TIMING.minimumReadings &&
+                    receivedAtMs - this.candidate.firstAtMs >= COLOUR_EVENT_TIMING.confirmationMs) {
+                    this.confirmed = this.candidate;
+                    this.candidate = null;
+                }
+            }
+        }
+        return this.current(now);
+    };
+    Object.defineProperty(ColourEventFilter.prototype, "nextExpiryAtMs", {
+        get: function () {
+            var deadlines = [
+                this.confirmed && this.confirmed.lastAtMs + COLOUR_EVENT_TIMING.signalGapMs,
+                this.candidate && this.candidate.lastAtMs + COLOUR_EVENT_TIMING.signalGapMs,
+                this.latest && this.lastPacketAtMs + COLOUR_EVENT_TIMING.staleMs,
+            ].filter(function (value) { return value !== null; });
+            return deadlines.length ? Math.min.apply(Math, deadlines) : null;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return ColourEventFilter;
+}());
+export { ColourEventFilter };

package/dist-types/src/utils/colour-profile-eeprom.d.ts

@@ -0,0 +1,36 @@
+import type { ColourSignalProfile } from "./colour-classifier";
+export declare const COLOUR_PROFILE_EEPROM_ADDRESS: "401c";
+export declare const COLOUR_PROFILE_EEPROM_FORMAT = 1;
+export type ColourProfileIdentity = {
+    serialNumber: string;
+    typeCode: string;
+    firmwareVersion: string;
+    offsetsHex: string;
+    whiteCalibrationHex: string;
+};
+export type ColourProfileStorageEvidence = {
+    source: "eeprom" | "local" | "firebase" | "defaultRules";
+    eeprom: {
+        status: "verified" | "empty" | "invalid" | "readFailed" | "writeFailed" | "firmwareNotAudited" | "notChecked";
+        address: typeof COLOUR_PROFILE_EEPROM_ADDRESS;
+        formatVersion: number;
+        hex?: string;
+        reason?: string;
+        checkedAtMs?: number;
+        writeAttempted?: boolean;
+        readbackMatches?: boolean;
+    };
+};
+export declare const supportsColourProfileEEPROM: (hardware: {
+    typeCode: string | null;
+    firmwareVersion: string | null;
+}) => boolean;
+/** Format 1: version(2), R/G/B air excursions(6 each), coordinate checksum(12). Big endian. */
+export declare const encodeColourProfileEEPROM: (identity: ColourProfileIdentity, signal: ColourSignalProfile) => string;
+export declare const decodeColourProfileEEPROM: (hex: string, identity: ColourProfileIdentity) => {
+    status: "verified";
+    signal: ColourSignalProfile;
+} | {
+    status: "empty" | "invalid";
+    reason: string;
+};

package/dist-types/src/utils/colour-profile-eeprom.js

@@ -0,0 +1,88 @@
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+// The documented four-byte gap between air offsets and the white reference.
+export var COLOUR_PROFILE_EEPROM_ADDRESS = "401c";
+export var COLOUR_PROFILE_EEPROM_FORMAT = 1;
+var RAW_NOISE_MARGIN = 3;
+var CHANNELS = ["red", "green", "blue"];
+// 1.4.1 retains its existing calibration path, but its source has not been audited for this new allocation.
+export var supportsColourProfileEEPROM = function (hardware) {
+    return (hardware.typeCode === "97" && hardware.firmwareVersion === "1.3.1") ||
+        (hardware.typeCode === "98" && hardware.firmwareVersion === "1.4.0");
+};
+var coordinates = function (identity) {
+    if (!supportsColourProfileEEPROM(identity) || !/^[a-zA-Z0-9_-]{1,128}$/.test(identity.serialNumber) ||
+        !/^[a-f0-9]{8}$/i.test(identity.offsetsHex) || !/^[a-f0-9]{16}$/i.test(identity.whiteCalibrationHex)) {
+        throw new Error("unsupportedProfileCoordinates");
+    }
+    var offsets = CHANNELS.map(function (_, i) { return parseInt(identity.offsetsHex.slice((i + 1) * 2, (i + 2) * 2), 16); });
+    var white = CHANNELS.map(function (_, i) { return parseInt(identity.whiteCalibrationHex.slice((i + 1) * 4, (i + 2) * 4), 16); });
+    if (white.some(function (value) { return value < 10 || value > 255; }))
+        throw new Error("invalidWhiteReference");
+    return { offsets: offsets, white: white };
+};
+// CRC-12 polynomial 0x80f, MSB-first, initial value zero, no reflection or final XOR.
+var checksum = function (payload, identity) {
+    var bytes = __spreadArray(__spreadArray(__spreadArray(__spreadArray([payload >>> 16, (payload >>> 8) & 255, payload & 255], Array.from((identity.offsetsHex + identity.whiteCalibrationHex).match(/../g), function (byte) { return parseInt(byte, 16); }), true), [Number(identity.typeCode)], false), identity.firmwareVersion.split(".").map(Number), true), Array.from(identity.serialNumber, function (character) { return character.charCodeAt(0); }), true);
+    var crc = 0;
+    for (var _i = 0, bytes_1 = bytes; _i < bytes_1.length; _i++) {
+        var byte = bytes_1[_i];
+        for (var bit = 7; bit >= 0; bit--) {
+            var feedback = ((crc >>> 11) ^ (byte >>> bit)) & 1;
+            crc = ((crc << 1) & 0xfff) ^ (feedback ? 0x80f : 0);
+        }
+    }
+    return crc;
+};
+/** Format 1: version(2), R/G/B air excursions(6 each), coordinate checksum(12). Big endian. */
+export var encodeColourProfileEEPROM = function (identity, signal) {
+    var _a = coordinates(identity), offsets = _a.offsets, white = _a.white;
+    var excursions = CHANNELS.map(function (channel, i) {
+        var rawMax = signal.airMax[channel] * white[i] / 255;
+        var margin = signal.margin[channel] * white[i] / 255;
+        var excursion = Math.round(rawMax) - (identity.typeCode === "97" ? offsets[i] : 0);
+        // Calibration's steadiness check guarantees this range; never silently quantise arbitrary legacy profiles.
+        if (!Number.isFinite(rawMax) || Math.abs(rawMax - Math.round(rawMax)) > 1e-7 ||
+            !Number.isFinite(margin) || Math.abs(margin - RAW_NOISE_MARGIN) > 1e-7 ||
+            excursion < 0 || excursion > 63 || excursion + offsets[i] >= 255 || excursion > Math.max(4, offsets[i] * 0.15)) {
+            throw new Error("profileNotRepresentable");
+        }
+        return excursion;
+    });
+    var payload = COLOUR_PROFILE_EEPROM_FORMAT * Math.pow(2, 18) + excursions[0] * Math.pow(2, 12) + excursions[1] * Math.pow(2, 6) + excursions[2];
+    return (payload * Math.pow(2, 12) + checksum(payload, identity)).toString(16).padStart(8, "0");
+};
+export var decodeColourProfileEEPROM = function (hex, identity) {
+    if (!/^[a-f0-9]{8}$/i.test(hex))
+        return { status: "invalid", reason: "invalidLength" };
+    if (["00000000", "ffffffff"].includes(hex.toLowerCase()))
+        return { status: "empty", reason: "noProfile" };
+    try {
+        var _a = coordinates(identity), offsets_1 = _a.offsets, white_1 = _a.white;
+        var word = parseInt(hex, 16);
+        var payload = Math.floor(word / Math.pow(2, 12));
+        if (Math.floor(payload / Math.pow(2, 18)) !== COLOUR_PROFILE_EEPROM_FORMAT)
+            return { status: "invalid", reason: "unknownFormat" };
+        if (word % Math.pow(2, 12) !== checksum(payload, identity))
+            return { status: "invalid", reason: "checksumOrCalibrationMismatch" };
+        var excursions_1 = [Math.floor(payload / Math.pow(2, 12)) % 64, Math.floor(payload / Math.pow(2, 6)) % 64, payload % 64];
+        if (excursions_1.some(function (value, i) { return value + offsets_1[i] >= 255 || value > Math.max(4, offsets_1[i] * 0.15); }))
+            return { status: "invalid", reason: "invalidAirExcursion" };
+        var airMax = Object.fromEntries(CHANNELS.map(function (channel, i) {
+            return [channel, (excursions_1[i] + (identity.typeCode === "97" ? offsets_1[i] : 0)) * 255 / white_1[i]];
+        }));
+        var margin = Object.fromEntries(CHANNELS.map(function (channel, i) { return [channel, RAW_NOISE_MARGIN * 255 / white_1[i]]; }));
+        // Measured air minima and capture history remain in diagnostics; classification needs only max + margin.
+        return { status: "verified", signal: { airMax: airMax, margin: margin } };
+    }
+    catch (_b) {
+        return { status: "invalid", reason: "invalidCoordinates" };
+    }
+};

package/dist-types/src/utils/colour-sensor-diagnostics.d.ts

@@ -1,6 +1,7 @@
 import colourPolicy from "./marty-colour-policy.json";
 import { ColourConfidenceFactors, ColourSignalProfile } from "./colour-classifier";
-import { ColourSensorProfile } from "./colour-sensor-profile";
+import { ActiveColourSensorProfile } from "./colour-sensor-profile";
+import { ColourProfileStorageEvidence } from "./colour-profile-eeprom";
 import type { RaftObserver } from "../application/RAFTs/RaftObserver";
 import type { RestMessageOptions } from "../types/communication-between-apps/wrapper-communication";
 import { SensorRead, RawColourFrame, ColourSensorSetup } from "./colour-sensor-registers";
@@ -94,7 +95,8 @@ export type ColourSnapshot = {
         airFlagTakesPrecedence: boolean;
         boundaries: typeof BLOCKS_COLOUR_BOUNDARIES;
         signal?: typeof colourPolicy.signal;
-        profile?: ColourSensorProfile;
+        profile?: ActiveColourSensorProfile;
+        profileStorage?: ColourProfileStorageEvidence;
         clearBoundsUsedForClassification?: boolean;
         confidence?: typeof colourPolicy.confidence;
     };

package/dist-types/src/utils/colour-sensor-diagnostics.js

@@ -72,7 +72,8 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
 import packageInfo from "../../package.json";
 import colourPolicy from "./marty-colour-policy.json";
 import { classifyColour, colourChannelsFromValues } from "./colour-classifier";
-import { getActiveColourSensorProfile } from "./colour-sensor-profile";
+import { getActiveColourSensorProfile, hydrateColourSensorProfile, clearActiveColourSensorProfile } from "./colour-sensor-profile";
+import { COLOUR_PROFILE_EEPROM_ADDRESS, COLOUR_PROFILE_EEPROM_FORMAT } from "./colour-profile-eeprom";
 import { lockColourSensorOperation, waitForColourProfileRead } from "./colour-sensor-operation";
 import { getPendingColourCalibration } from "./colour-calibration-reconnect";
 import { collectColourSensorSetup, readRawColourSensor } from "./colour-sensor-registers";
@@ -165,7 +166,7 @@ var delay = function (ms, signal) { return new Promise(function (resolve, reject
         abort();
 }); };
 var captureUnlocked = function (sensor, expectedColour, session, signal) { return __awaiter(void 0, void 0, void 0, function () {
-    var startedAtMs, checkActive, sensorSetup, sampleWindowStartedAtMs, samples, rawSamples, rawController, abortRaw, rawFailure, collectRaw, rawCapture, index, reading;
+    var startedAtMs, checkActive, sensorSetup, profileStorage, hardware, sampleWindowStartedAtMs, samples, rawSamples, rawController, abortRaw, rawFailure, collectRaw, rawCapture, index, reading;
     var _a, _b, _c, _d, _e, _f;
     return __generator(this, function (_g) {
         switch (_g.label) {
@@ -187,6 +188,21 @@ var captureUnlocked = function (sensor, expectedColour, session, signal) { retur
                     throw new ColourDiagnosticError("sensorPowerFailed");
                 if (sensorSetup.hardware.status === "ok" && sensorSetup.hardware.value.commsOk === 0)
                     throw new ColourDiagnosticError("sensorOffline");
+                profileStorage = { source: "defaultRules", eeprom: {
+                        status: "notChecked", address: COLOUR_PROFILE_EEPROM_ADDRESS, formatVersion: COLOUR_PROFILE_EEPROM_FORMAT,
+                        reason: "sensorDetailsUnavailable",
+                    } };
+                clearActiveColourSensorProfile(sensor);
+                if (!(sensorSetup.hardware.status === "ok" && sensorSetup.offsets.status === "ok" && sensorSetup.whiteCalibration.status === "ok")) return [3 /*break*/, 3];
+                hardware = sensorSetup.hardware.value;
+                if (!(hardware.serialNumber && hardware.typeCode && hardware.firmwareVersion)) return [3 /*break*/, 3];
+                return [4 /*yield*/, hydrateColourSensorProfile(sensor, { serialNumber: hardware.serialNumber,
+                        typeCode: hardware.typeCode, firmwareVersion: hardware.firmwareVersion,
+                        offsetsHex: sensorSetup.offsets.value.hexRd, whiteCalibrationHex: sensorSetup.whiteCalibration.value.hexRd }, signal, checkActive)];
+            case 2:
+                profileStorage = _g.sent();
+                _g.label = 3;
+            case 3:
                 readColourSensor(sensor);
                 sampleWindowStartedAtMs = Date.now();
                 samples = [];
@@ -228,42 +244,42 @@ var captureUnlocked = function (sensor, expectedColour, session, signal) { retur
                     });
                 }); };
                 rawCapture = collectRaw();
-                _g.label = 2;
-            case 2:
-                _g.trys.push([2, , 7, 9]);
+                _g.label = 4;
+            case 4:
+                _g.trys.push([4, , 9, 11]);
                 index = 0;
-                _g.label = 3;
-            case 3:
-                if (!(index <= CAPTURE_DURATION_MS / CAPTURE_INTERVAL_MS)) return [3 /*break*/, 6];
+                _g.label = 5;
+            case 5:
+                if (!(index <= CAPTURE_DURATION_MS / CAPTURE_INTERVAL_MS)) return [3 /*break*/, 8];
                 checkActive();
                 if (rawFailure)
                     throw rawFailure;
                 reading = readColourSensor(sensor);
                 if (!samples.length || samples[samples.length - 1].receivedAtMs !== reading.receivedAtMs)
                     samples.push(reading);
-                if (!(index < CAPTURE_DURATION_MS / CAPTURE_INTERVAL_MS)) return [3 /*break*/, 5];
+                if (!(index < CAPTURE_DURATION_MS / CAPTURE_INTERVAL_MS)) return [3 /*break*/, 7];
                 return [4 /*yield*/, delay(CAPTURE_INTERVAL_MS, signal)];
-            case 4:
+            case 6:
                 _g.sent();
-                _g.label = 5;
-            case 5:
-                index++;
-                return [3 /*break*/, 3];
-            case 6: return [3 /*break*/, 9];
+                _g.label = 7;
             case 7:
+                index++;
+                return [3 /*break*/, 5];
+            case 8: return [3 /*break*/, 11];
+            case 9:
                 rawController.abort();
                 signal.removeEventListener("abort", abortRaw);
                 return [4 /*yield*/, rawCapture];
-            case 8:
+            case 10:
                 _g.sent();
                 return [7 /*endfinally*/];
-            case 9:
+            case 11:
                 if (rawFailure)
                     throw rawFailure;
                 if (samples.length < 2)
                     throw new ColourDiagnosticError("staleReading");
                 return [2 /*return*/, __assign(__assign({ schemaVersion: 2, sessionId: session.sessionId, sessionStartedAtMs: session.startedAtMs, captureId: createId(), expectedColour: expectedColour, startedAtMs: startedAtMs, finishedAtMs: Date.now(), appVersion: packageInfo.version, classifier: { source: colourPolicy.source, airFlagTakesPrecedence: false, boundaries: BLOCKS_COLOUR_BOUNDARIES,
-                            signal: colourPolicy.signal, profile: getActiveColourSensorProfile(sensor), clearBoundsUsedForClassification: false,
+                            signal: colourPolicy.signal, profile: getActiveColourSensorProfile(sensor), profileStorage: profileStorage, clearBoundsUsedForClassification: false,
                             confidence: colourPolicy.confidence }, device: {
                             id: sensor.raftId, type: sensor.raft.type, name: ((_c = (_b = sensor.raft).getFriendlyName) === null || _c === void 0 ? void 0 : _c.call(_b)) || sensor.raftId,
                             firmwareVersion: ((_d = sensor.raft.systemInfo) === null || _d === void 0 ? void 0 : _d.SystemVersion) || null, connectionMethod: sensor.raft.connectionMethod || null,

package/dist-types/src/utils/colour-sensor-profile.d.ts

@@ -1,5 +1,6 @@
 import type { ColourSensor } from "./colour-sensor-diagnostics";
 import { ColourSignalProfile } from "./colour-classifier";
+import { ColourProfileIdentity, ColourProfileStorageEvidence } from "./colour-profile-eeprom";
 export type ColourSensorProfile = {
     schemaVersion: 1;
     serialNumber: string;
@@ -12,21 +13,26 @@ export type ColourSensorProfile = {
     purpleIncluded: boolean;
     groundDetection: "clearThreshold" | "rgbFallback" | "purpleSkipped";
 };
+export type ActiveColourSensorProfile = Omit<ColourSensorProfile, "capturedAtMs" | "purpleIncluded" | "groundDetection"> & Partial<Pick<ColourSensorProfile, "capturedAtMs" | "purpleIncluded" | "groundDetection">>;
 export declare const validColourSensorProfile: (value: unknown) => value is ColourSensorProfile;
 export declare const cacheColourSensorProfile: (profile: ColourSensorProfile) => void;
 export declare const colourSensorProfilePath: (profile: ColourSensorProfile) => string;
-export declare const bindColourSensorProfile: (sensor: ColourSensor, profile: ColourSensorProfile) => void;
-export declare const getActiveColourSensorProfile: (sensor: Pick<ColourSensor, "raft" | "key">) => ColourSensorProfile | undefined;
+export declare const bindColourSensorProfile: (sensor: ColourSensor, profile: ActiveColourSensorProfile) => void;
+export declare const getActiveColourSensorProfile: (sensor: Pick<ColourSensor, "raft" | "key">) => ActiveColourSensorProfile | undefined;
 export declare const getAddonColourSensorProfile: (raft: object, addon: {
     id: number;
     name: string;
-}) => ColourSensorProfile | undefined;
-export declare const clearActiveColourSensorProfile: (sensor: Pick<ColourSensor, "raft" | "key">) => boolean | undefined;
+}) => ActiveColourSensorProfile | undefined;
+export declare const getColourProfileStorage: (sensor: Pick<ColourSensor, "raft" | "key">) => ColourProfileStorageEvidence | undefined;
+export declare const setColourProfileStorage: (sensor: Pick<ColourSensor, "raft" | "key">, evidence: ColourProfileStorageEvidence) => void;
+export declare const clearActiveColourSensorProfile: (sensor: Pick<ColourSensor, "raft" | "key">) => void;
 export declare const classifyColourAddon: (addon: {
     id: number;
     name: string;
     vals: Record<string, number | boolean>;
 }) => import("./colour-classifier").ColourName;
+/** Caller owns the raw-command lock and has freshly read hardware, offsets and white references. */
+export declare const hydrateColourSensorProfile: (sensor: ColourSensor, identity: ColourProfileIdentity, signal: AbortSignal, check: () => void) => Promise<ColourProfileStorageEvidence>;
 export declare const loadColourSensorProfile: (sensor: ColourSensor, signal: AbortSignal) => Promise<void>;
 /** Read-only browser/WebView hydration. Never wakes sleeping sensors or modifies their registers. */
 export declare const startColourSensorProfileSync: () => () => void;

package/dist-types/src/utils/colour-sensor-profile.js

@@ -1,3 +1,14 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -39,9 +50,11 @@ import { classifyColour, colourChannelsFromValues } from "./colour-classifier";
 import { lockColourSensorOperation } from "./colour-sensor-operation";
 import { readColourSensorHardware, readColourSensorReadiness, readColourSensorRegister } from "./colour-sensor-registers";
 import { getPendingColourCalibration } from "./colour-calibration-reconnect";
+import { COLOUR_PROFILE_EEPROM_ADDRESS, COLOUR_PROFILE_EEPROM_FORMAT, decodeColourProfileEEPROM, supportsColourProfileEEPROM } from "./colour-profile-eeprom";
 var PREFIX = "marty-colour-signal-profile:";
 var memory = new Map();
 var active = new WeakMap();
+var storage = new WeakMap();
 var retries = new WeakMap();
 var profileKey = function (profile) {
     return "".concat(profile.serialNumber, "/").concat(profile.offsetsHex).concat(profile.whiteCalibrationHex);
@@ -57,7 +70,7 @@ export var validColourSensorProfile = function (value) {
             var _a, _b, _c, _d, _e, _f;
             var c = channel;
             return [(_b = (_a = profile.signal) === null || _a === void 0 ? void 0 : _a.airMin) === null || _b === void 0 ? void 0 : _b[c], (_d = (_c = profile.signal) === null || _c === void 0 ? void 0 : _c.airMax) === null || _d === void 0 ? void 0 : _d[c], (_f = (_e = profile.signal) === null || _e === void 0 ? void 0 : _e.margin) === null || _f === void 0 ? void 0 : _f[c]]
-                .every(function (v) { return Number.isFinite(v) && v >= 0; }) && profile.signal.airMin[c] <= profile.signal.airMax[c] && profile.signal.margin[c] > 0;
+                .every(function (v) { return typeof v === "number" && Number.isFinite(v) && v >= 0; }) && profile.signal.airMin[c] <= profile.signal.airMax[c] && profile.signal.margin[c] > 0;
         });
 };
 export var cacheColourSensorProfile = function (profile) {
@@ -82,7 +95,20 @@ export var bindColourSensorProfile = function (sensor, profile) {
 };
 export var getActiveColourSensorProfile = function (sensor) { var _a; return (_a = active.get(sensor.raft)) === null || _a === void 0 ? void 0 : _a.get(sensor.key); };
 export var getAddonColourSensorProfile = function (raft, addon) { var _a; return (_a = active.get(raft)) === null || _a === void 0 ? void 0 : _a.get(JSON.stringify([addon.id, addon.name])); };
-export var clearActiveColourSensorProfile = function (sensor) { var _a; return (_a = active.get(sensor.raft)) === null || _a === void 0 ? void 0 : _a.delete(sensor.key); };
+export var getColourProfileStorage = function (sensor) { var _a; return (_a = storage.get(sensor.raft)) === null || _a === void 0 ? void 0 : _a.get(sensor.key); };
+export var setColourProfileStorage = function (sensor, evidence) {
+    var entries = storage.get(sensor.raft);
+    if (!entries) {
+        entries = new Map();
+        storage.set(sensor.raft, entries);
+    }
+    entries.set(sensor.key, evidence);
+};
+export var clearActiveColourSensorProfile = function (sensor) {
+    var _a, _b;
+    (_a = active.get(sensor.raft)) === null || _a === void 0 ? void 0 : _a.delete(sensor.key);
+    (_b = storage.get(sensor.raft)) === null || _b === void 0 ? void 0 : _b.delete(sensor.key);
+};
 export var classifyColourAddon = function (addon) {
     var _a;
     var raft = Object.values(window.applicationManager.connectedRafts).find(function (candidate) {
@@ -91,96 +117,156 @@ export var classifyColourAddon = function (addon) {
     });
     return classifyColour(colourChannelsFromValues(addon.vals), raft ? (_a = getAddonColourSensorProfile(raft, addon)) === null || _a === void 0 ? void 0 : _a.signal : undefined).classifiedColour;
 };
-// Check physical identity and the complete saved coordinate system before using a persisted profile.
-export var loadColourSensorProfile = function (sensor, signal) { return __awaiter(void 0, void 0, void 0, function () {
-    var release, check, readiness, hardware, white, offsets, identity, key_1, profile, stored, controller_1, abort, timeout, response, records, _a, state, current;
+/** Caller owns the raw-command lock and has freshly read hardware, offsets and white references. */
+export var hydrateColourSensorProfile = function (sensor, identity, signal, check) { return __awaiter(void 0, void 0, void 0, function () {
+    var evidence, profile, result, decoded, key_1, cached, stored, controller_1, abort, timeout, response, records, _a, hardware, unavailable, state, current;
     var _b;
     return __generator(this, function (_c) {
         switch (_c.label) {
             case 0:
-                release = lockColourSensorOperation(sensor.raft, true);
-                if (!release)
-                    return [2 /*return*/];
-                check = function () { return assertColourSensorActive(sensor, signal); };
-                _c.label = 1;
-            case 1:
-                _c.trys.push([1, , 13, 14]);
                 check();
                 clearActiveColourSensorProfile(sensor);
-                return [4 /*yield*/, readColourSensorReadiness(sensor, signal, check)];
+                evidence = { source: "defaultRules", eeprom: {
+                        status: "firmwareNotAudited", address: COLOUR_PROFILE_EEPROM_ADDRESS, formatVersion: COLOUR_PROFILE_EEPROM_FORMAT,
+                    } };
+                if (!supportsColourProfileEEPROM(identity)) return [3 /*break*/, 2];
+                return [4 /*yield*/, readColourSensorRegister(sensor, COLOUR_PROFILE_EEPROM_ADDRESS, signal, check)];
+            case 1:
+                result = _c.sent();
+                evidence.eeprom.checkedAtMs = result.receivedAtMs;
+                if (result.status === "ok") {
+                    decoded = decodeColourProfileEEPROM(result.value, identity);
+                    evidence.eeprom = __assign(__assign(__assign({}, evidence.eeprom), { status: decoded.status, hex: result.value }), (decoded.status === "verified" ? { readbackMatches: true } : { reason: decoded.reason }));
+                    if (decoded.status === "verified") {
+                        profile = __assign(__assign({ schemaVersion: 1 }, identity), { signal: decoded.signal });
+                        evidence.source = "eeprom";
+                    }
+                }
+                else {
+                    evidence.eeprom.status = "readFailed";
+                    evidence.eeprom.reason = result.reason;
+                }
+                _c.label = 2;
             case 2:
-                readiness = _c.sent();
-                if (readiness.status !== "ok" || !readiness.value)
-                    return [2 /*return*/];
-                return [4 /*yield*/, readColourSensorHardware(sensor, signal, check)];
-            case 3:
-                hardware = _c.sent();
-                if (hardware.status !== "ok" || hardware.value.commsOk === 0 || !hardware.value.serialNumber ||
-                    !/^[a-zA-Z0-9_-]{1,128}$/.test(hardware.value.serialNumber))
-                    return [2 /*return*/];
-                return [4 /*yield*/, readColourSensorRegister(sensor, "4020", signal, check)];
-            case 4:
-                white = _c.sent();
-                if (white.status !== "ok")
-                    return [2 /*return*/];
-                return [4 /*yield*/, readColourSensorRegister(sensor, "4018", signal, check)];
-            case 5:
-                offsets = _c.sent();
-                if (offsets.status !== "ok")
-                    return [2 /*return*/];
-                identity = { serialNumber: hardware.value.serialNumber, offsetsHex: offsets.value, whiteCalibrationHex: white.value };
+                if (!!profile) return [3 /*break*/, 10];
                 key_1 = profileKey(identity);
-                profile = memory.get(key_1);
+                cached = memory.get(key_1);
                 try {
                     stored = JSON.parse(localStorage.getItem(PREFIX + key_1) || "null");
-                    if (validColourSensorProfile(stored))
-                        profile = stored;
+                    if (validColourSensorProfile(stored) && profileKey(stored) === key_1)
+                        cached = stored;
                 }
                 catch ( /* Native WebViews may have temporary or unavailable storage. */_d) { /* Native WebViews may have temporary or unavailable storage. */ }
-                if (!!profile) return [3 /*break*/, 12];
+                if (!(cached && profileKey(cached) === key_1 && cached.typeCode === identity.typeCode && cached.firmwareVersion === identity.firmwareVersion)) return [3 /*break*/, 3];
+                profile = cached;
+                evidence.source = "local";
+                return [3 /*break*/, 10];
+            case 3:
                 controller_1 = new AbortController();
                 abort = function () { return controller_1.abort(); };
                 signal.addEventListener("abort", abort, { once: true });
+                if (signal.aborted)
+                    abort();
                 timeout = setTimeout(abort, 5000);
-                _c.label = 6;
-            case 6:
-                _c.trys.push([6, 10, 11, 12]);
+                _c.label = 4;
+            case 4:
+                _c.trys.push([4, 8, 9, 10]);
                 return [4 /*yield*/, fetch("".concat(COLOUR_DATABASE_URL, "/colourSensorProfiles/").concat(key_1, ".json"), { signal: controller_1.signal })];
-            case 7:
+            case 5:
                 response = _c.sent();
-                if (!response.ok) return [3 /*break*/, 9];
+                if (!response.ok) return [3 /*break*/, 7];
                 return [4 /*yield*/, response.json()];
-            case 8:
+            case 6:
                 records = _c.sent();
                 if (records && typeof records === "object")
                     profile = Object.values(records).filter(validColourSensorProfile)
-                        .filter(function (value) { return profileKey(value) === key_1; }).sort(function (a, b) { return b.capturedAtMs - a.capturedAtMs; })[0];
-                _c.label = 9;
-            case 9: return [3 /*break*/, 12];
-            case 10:
+                        .filter(function (value) { return profileKey(value) === key_1 && value.typeCode === identity.typeCode && value.firmwareVersion === identity.firmwareVersion; })
+                        .sort(function (a, b) { return b.capturedAtMs - a.capturedAtMs; })[0];
+                if (profile) {
+                    evidence.source = "firebase";
+                    cacheColourSensorProfile(profile);
+                }
+                _c.label = 7;
+            case 7: return [3 /*break*/, 10];
+            case 8:
                 _a = _c.sent();
-                return [3 /*break*/, 12];
-            case 11:
+                return [3 /*break*/, 10];
+            case 9:
                 clearTimeout(timeout);
                 signal.removeEventListener("abort", abort);
                 return [7 /*endfinally*/];
-            case 12:
+            case 10:
                 check();
+                return [4 /*yield*/, readColourSensorHardware(sensor, signal, check)];
+            case 11:
+                hardware = _c.sent();
+                if (hardware.status !== "ok" || hardware.value.commsOk === 0 || hardware.value.serialNumber !== identity.serialNumber ||
+                    hardware.value.typeCode !== identity.typeCode || hardware.value.firmwareVersion !== identity.firmwareVersion) {
+                    unavailable = __assign(__assign({}, evidence), { source: "defaultRules", eeprom: __assign(__assign({}, evidence.eeprom), { status: "notChecked", reason: "sensorIdentityChangedOrUnavailable", readbackMatches: false }) });
+                    setColourProfileStorage(sensor, unavailable);
+                    return [2 /*return*/, unavailable];
+                }
                 state = sensor.raft.raftStateInfo;
                 current = state.addOnInfo.addons.find(function (addon) { return addon.id === sensor.addon.id && addon.name === sensor.addon.name; });
                 if (!current || (current.status !== undefined && !(current.status & 128)) ||
-                    Date.now() - state.addOnInfoValidMs > 1500 || state.addOnInfoValidMs > Date.now() || ((_b = state.power) === null || _b === void 0 ? void 0 : _b.powerStatus.power5VIsOn) === false)
-                    return [2 /*return*/];
-                if (profile && profileKey(profile) === key_1 && profile.typeCode === hardware.value.typeCode &&
-                    profile.firmwareVersion === hardware.value.firmwareVersion) {
-                    cacheColourSensorProfile(profile);
-                    bindColourSensorProfile(sensor, profile);
+                    Date.now() - state.addOnInfoValidMs > 1500 || state.addOnInfoValidMs > Date.now() || ((_b = state.power) === null || _b === void 0 ? void 0 : _b.powerStatus.power5VIsOn) === false) {
+                    return [2 /*return*/, __assign(__assign({}, evidence), { source: "defaultRules", eeprom: __assign(__assign({}, evidence.eeprom), { status: "notChecked", reason: "sensorNotFresh" }) })];
                 }
-                return [3 /*break*/, 14];
-            case 13:
+                if (profile)
+                    bindColourSensorProfile(sensor, profile);
+                setColourProfileStorage(sensor, evidence);
+                return [2 /*return*/, evidence];
+        }
+    });
+}); };
+// Check physical identity and the complete saved coordinate system before using a persisted profile.
+export var loadColourSensorProfile = function (sensor, signal) { return __awaiter(void 0, void 0, void 0, function () {
+    var release, check, readiness, hardware, white, offsets;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                release = lockColourSensorOperation(sensor.raft, true);
+                if (!release)
+                    return [2 /*return*/];
+                check = function () { return assertColourSensorActive(sensor, signal); };
+                _a.label = 1;
+            case 1:
+                _a.trys.push([1, , 7, 8]);
+                check();
+                clearActiveColourSensorProfile(sensor);
+                return [4 /*yield*/, readColourSensorReadiness(sensor, signal, check)];
+            case 2:
+                readiness = _a.sent();
+                if (readiness.status !== "ok" || !readiness.value)
+                    return [2 /*return*/];
+                return [4 /*yield*/, readColourSensorHardware(sensor, signal, check)];
+            case 3:
+                hardware = _a.sent();
+                if (hardware.status !== "ok" || hardware.value.commsOk === 0 || !hardware.value.serialNumber ||
+                    !/^[a-zA-Z0-9_-]{1,128}$/.test(hardware.value.serialNumber))
+                    return [2 /*return*/];
+                return [4 /*yield*/, readColourSensorRegister(sensor, "4020", signal, check)];
+            case 4:
+                white = _a.sent();
+                if (white.status !== "ok")
+                    return [2 /*return*/];
+                return [4 /*yield*/, readColourSensorRegister(sensor, "4018", signal, check)];
+            case 5:
+                offsets = _a.sent();
+                if (offsets.status !== "ok")
+                    return [2 /*return*/];
+                if (!hardware.value.typeCode || !hardware.value.firmwareVersion)
+                    return [2 /*return*/];
+                return [4 /*yield*/, hydrateColourSensorProfile(sensor, { serialNumber: hardware.value.serialNumber,
+                        typeCode: hardware.value.typeCode, firmwareVersion: hardware.value.firmwareVersion,
+                        offsetsHex: offsets.value, whiteCalibrationHex: white.value }, signal, check)];
+            case 6:
+                _a.sent();
+                return [3 /*break*/, 8];
+            case 7:
                 release();
                 return [7 /*endfinally*/];
-            case 14: return [2 /*return*/];
+            case 8: return [2 /*return*/];
         }
     });
 }); };

package/dist-types/src/utils/colour-sensor-registers.d.ts

@@ -43,7 +43,7 @@ export type ColourSensorSetup = {
     offsets: SensorRead<Channels>;
     whiteCalibration: SensorRead<Channels>;
 };
-export type ColourSensorRegister = "4014" | "4018" | "4020";
+export type ColourSensorRegister = "4014" | "4018" | "401c" | "4020";
 export declare const readColourSensorRegister: (sensor: ColourSensor, address: ColourSensorRegister, signal: AbortSignal, checkActive: () => void) => Promise<SensorRead<string>>;
 export declare const readColourSensorHardware: (sensor: ColourSensor, signal: AbortSignal, checkActive: () => void) => Promise<SensorRead<SensorHardware>>;
 export declare const wakeColourSensor: (sensor: ColourSensor, signal: AbortSignal, checkActive: () => void) => Promise<SensorRead<boolean>>;

package/dist-types/src/utils/colour-sensor-registers.js

@@ -138,7 +138,7 @@ var readHex = function (sensor, hexWr, bytes, signal, checkActive) {
     });
 };
 export var readColourSensorRegister = function (sensor, address, signal, checkActive) {
-    return readHex(sensor, "10".concat(address), { "4014": 2, "4018": 4, "4020": 8 }[address], signal, checkActive);
+    return readHex(sensor, "10".concat(address), { "4014": 2, "4018": 4, "401c": 4, "4020": 8 }[address], signal, checkActive);
 };
 var mapRead = function (result, convert) {
     return result.status === "ok" ? __assign(__assign({}, result), { value: convert(result.value) }) : result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robotical/webapp-types",
-  "version": "3.25.10",
+  "version": "3.25.12",
   "description": "Type definitions for the Application Manager",
   "main": "dist/application-manager.d.ts",
   "types": "dist/application-manager.d.ts",