@aurora-blue/signalk-connector 0.2.0-dev.40 → 0.2.0-dev.41

package/README.md

@@ -135,4 +135,8 @@ See the canonical [integration and handover documentation](../aurora-blue-docume
 
 ## Unpublished AC input-limit control
 
-The local inputLimitControlEnabled option defaults to false. When explicitly enabled, a paired active Connector exchanges only bounded native AC input-current-limit operations. Eligibility requires one inverter, fresh Shore source/current-limit observations, source identity, supportsPut and explicit minValue/maxValue metadata. Missing provider capabilities disable control. The source-specific PUT is sent once and success requires new matching readback; callbacks, stale data or transport retries never manufacture success. Commands are not journaled or replayed after restart. This local implementation is not a published release or physical equipment qualification. Canonical policy: ADR-0266 in aurora-blue-documentation.
+The local inputLimitControlEnabled option defaults to false. When explicitly enabled, a paired active Connector exchanges only bounded native AC input-current-limit operations. Eligibility requires one inverter, fresh Shore source/current-limit observations, source identity, supportsPut and explicit minValue/maxValue metadata. Missing provider capabilities disable control. The source-specific PUT is sent once and success requires new matching readback; callbacks, stale data or transport retries never manufacture success. Commands are not journaled or replayed after restart. Physical equipment control qualification remains separate. Canonical policy: ADR-0271 in aurora-blue-documentation.
+
+### Equipment identity enrichment
+
+An updated paired Server must advertise equipment_identity=true before this optional collection starts. The Connector reads existing NMEA 2000 product information and may use the existing GX D-Bus ProductName reader on Linux. It associates names by received source, never by numeric instance guesses. Queries are read-only, bounded and optional; no new native dependency is installed. Only bounded product/manufacturer string fields are added to the usual durable batch, with explicit metadata provenance and a null source timestamp. Serial/firmware fields and raw frames are not collected, and opaque identifier-like names are excluded. New/changed values are captured after startup; unchanged values are not repeatedly emitted by this adapter. Standard telemetry and default-off equipment control remain independent. See ADR-0272 in the canonical documentation.

package/VERSION

@@ -1 +1 @@
-0.2.0-dev.40
+0.2.0-dev.41

package/dist/src/connector.d.ts

@@ -24,6 +24,11 @@ export declare class ConnectorRuntime {
     private readonly now;
     private readonly random;
     private readonly unsubscribes;
+    private identitySupported;
+    private identityStarted;
+    private identityPolls;
+    private identityTimer;
+    private readonly identityValues;
     private timer;
     private safetyTimer;
     private runtimeConfigurationTimer;
@@ -77,6 +82,7 @@ export declare class ConnectorRuntime {
     private publishAnchorTransition;
     private publishAnchorState;
     private schedule;
+    private startEquipmentIdentity;
     private startEnergyControl;
     private pollEnergyControl;
     private scheduleRuntimeConfigurationPoll;

package/dist/src/connector.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectorRuntime = exports.CONNECTOR_VERSION = void 0;
+const equipment_identity_1 = require("./equipment-identity");
 const energy_control_1 = require("./energy-control");
 const node_path_1 = require("node:path");
 const noforeignland_1 = require("./noforeignland");
@@ -37,6 +38,11 @@ class ConnectorRuntime {
     now;
     random;
     unsubscribes = [];
+    identitySupported = false;
+    identityStarted = false;
+    identityPolls = 0;
+    identityTimer = null;
+    identityValues = new Map();
     timer = null;
     safetyTimer = null;
     runtimeConfigurationTimer = null;
@@ -185,6 +191,7 @@ class ConnectorRuntime {
         await this.updateStatus();
         this.scheduleRuntimeConfigurationPoll(0);
         this.startEnergyControl();
+        this.startEquipmentIdentity();
         if (this.operatingMode !== "disabled") {
             this.schedule(0);
         }
@@ -194,6 +201,8 @@ class ConnectorRuntime {
     }
     async stop() {
         this.stopped = true;
+        if (this.identityTimer)
+            clearTimeout(this.identityTimer);
         this.energyExecutor?.stop();
         if (this.energyTimer)
             clearTimeout(this.energyTimer);
@@ -221,7 +230,7 @@ class ConnectorRuntime {
             return;
         }
         const receivedAt = this.now();
-        const events = (0, delta_1.eventsFromDelta)(delta, this.bootId, receivedAt, subscriptionScope);
+        const events = (0, delta_1.eventsFromDelta)(delta, this.bootId, receivedAt, subscriptionScope).filter((event) => this.identitySupported || !(0, equipment_identity_1.isEquipmentIdentityPath)(event.path));
         for (const event of events)
             this.publisher?.observe(event);
         // Safety observes current positions immediately, even when historical
@@ -549,6 +558,54 @@ class ConnectorRuntime {
             void this.flush();
         }, delay);
     }
+    startEquipmentIdentity() {
+        if (!this.identitySupported ||
+            this.identityStarted ||
+            !this.autoSchedule ||
+            this.stopped)
+            return;
+        this.identityStarted = true;
+        const poll = async () => {
+            try {
+                if (this.identitySupported &&
+                    this.pairingState === "paired" &&
+                    this.operatingMode === "active") {
+                    const identities = await (0, equipment_identity_1.equipmentIdentities)(this.app.getSelfPath("electrical"), typeof this.app.getPath === "function"
+                        ? this.app.getPath("/sources")
+                        : {});
+                    for (const identity of identities) {
+                        if (this.stopped ||
+                            !this.identitySupported ||
+                            this.operatingMode !== "active")
+                            break;
+                        const key = identity.path + "\0" + identity.source;
+                        if (this.identityValues.get(key) === identity.value)
+                            continue;
+                        await this.capture({
+                            context: "vessels.self",
+                            updates: [
+                                {
+                                    $source: identity.source,
+                                    values: [{ path: identity.path, value: identity.value }],
+                                },
+                            ],
+                        });
+                        this.identityValues.set(key, identity.value);
+                        if (this.identityValues.size > 384)
+                            this.identityValues.delete(this.identityValues.keys().next().value);
+                    }
+                }
+            }
+            catch {
+                /* Optional identity reads never interrupt ordinary telemetry. */
+            }
+            if (!this.stopped)
+                this.identityTimer = setTimeout(() => {
+                    void poll();
+                }, this.identityPolls++ < 5 ? 30_000 : 600_000);
+        };
+        void poll();
+    }
     startEnergyControl() {
         if (this.stopped ||
             this.energyExecutor ||
@@ -623,6 +680,7 @@ class ConnectorRuntime {
             this.pairingState = "paired";
             await this.applyRuntimeConfiguration(response.runtime_configuration);
             this.startEnergyControl();
+            this.startEquipmentIdentity();
             if (this.unsubscribes.length === 0) {
                 this.operatingMode = response.runtime_configuration.operating_mode;
                 this.configureSubscriptions();
@@ -668,6 +726,7 @@ class ConnectorRuntime {
         await this.updateStatus();
     }
     async applyRuntimeConfiguration(configuration) {
+        this.identitySupported = configuration.equipment_identity === true;
         const previousMode = this.operatingMode;
         this.runtimeConfigurationPollMs = configuration.poll_after_seconds * 1_000;
         this.runtimeConfigurationState = "current";

package/dist/src/equipment-identity.d.ts

@@ -0,0 +1,10 @@
+export interface EquipmentIdentity {
+    path: string;
+    value: string;
+    source: string;
+}
+/** Optional GX adapter. Fixed executable, fixed read-only method, no shell or writes. */
+export declare function readVictronProductName(service: string): Promise<string | null>;
+/** Capture identity only for received electrical sources, plus identified GX controllers. */
+export declare function equipmentIdentities(electrical: unknown, sources: unknown, readProduct?: typeof readVictronProductName): Promise<EquipmentIdentity[]>;
+export declare const isEquipmentIdentityPath: (path: string) => boolean;

package/dist/src/equipment-identity.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEquipmentIdentityPath = void 0;
+exports.readVictronProductName = readVictronProductName;
+exports.equipmentIdentities = equipmentIdentities;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+const text = (value) => typeof value === "string" &&
+    value.trim() &&
+    value.length <= 120 &&
+    !/[\x00-\x1f]/.test(value)
+    ? value.trim()
+    : null;
+const productText = (value) => {
+    const name = text(value);
+    return name && !/^[A-Za-z0-9]{12,}$/.test(name) ? name : null;
+};
+const servicePattern = /^com\.victronenergy\.(?:vebus|solarcharger|battery|charger|alternator)\.[A-Za-z0-9_]{1,100}$/;
+/** Optional GX adapter. Fixed executable, fixed read-only method, no shell or writes. */
+function readVictronProductName(service) {
+    if (process.platform !== "linux" || !servicePattern.test(service))
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        (0, node_child_process_1.execFile)("/usr/bin/dbus-send", [
+            "--system",
+            "--print-reply",
+            `--dest=${service}`,
+            "/ProductName",
+            "com.victronenergy.BusItem.GetValue",
+        ], { timeout: 1500, maxBuffer: 8192 }, (error, stdout) => {
+            if (error)
+                return resolve(null);
+            const match = /variant\s+string\s+("(?:[^"\\]|\\.)*")/.exec(stdout);
+            try {
+                resolve(match ? productText(JSON.parse(match[1])) : null);
+            }
+            catch {
+                resolve(null);
+            }
+        });
+    });
+}
+/** Capture identity only for received electrical sources, plus identified GX controllers. */
+async function equipmentIdentities(electrical, sources, readProduct = readVictronProductName) {
+    const found = [];
+    const nmea = new Map();
+    for (const [provider, collection] of Object.entries(record(sources)).slice(0, 64)) {
+        for (const [address, device] of Object.entries(record(collection)).slice(0, 128)) {
+            const identity = record(record(device).n2k);
+            const model = productText(identity.modelId ?? identity["Model ID"]);
+            if (!model)
+                continue;
+            nmea.set(`${provider}.${address}`, {
+                model,
+                manufacturer: text(identity.manufacturerCode ?? identity["Manufacturer Code"]),
+                stable: `${provider}:${text(identity.canName) ?? address}`,
+            });
+        }
+    }
+    const products = new Map();
+    for (const group of [
+        "inverters",
+        "chargers",
+        "solar",
+        "batteries",
+        "alternators",
+    ]) {
+        for (const [instance, raw] of Object.entries(record(record(electrical)[group])).slice(0, 32)) {
+            if (!/^[A-Za-z0-9_:-]{1,80}$/.test(instance))
+                continue;
+            const upstream = new Set();
+            const visit = (node, depth) => {
+                if (depth > 3)
+                    return;
+                const item = record(node);
+                if (typeof item.$source === "string")
+                    upstream.add(item.$source);
+                for (const child of Object.values(item))
+                    if (child && typeof child === "object")
+                        visit(child, depth + 1);
+            };
+            visit(raw, 0);
+            // An aggregate with competing providers cannot establish one product identity.
+            if (upstream.size !== 1)
+                continue;
+            const source = [...upstream][0];
+            const native = nmea.get(source);
+            let model = native?.model ?? null;
+            let manufacturer = native?.manufacturer ?? null;
+            let provenance = `aboard.metadata.nmea2000:${source}`;
+            const service = source.startsWith("venus.") ? source.slice(6) : "";
+            if (servicePattern.test(service)) {
+                if (!products.has(service) && products.size < 16)
+                    products.set(service, readProduct(service));
+                model = productText(await products.get(service));
+                manufacturer =
+                    model &&
+                        /^(?:Quattro|MultiPlus|EasySolar|SmartSolar|BlueSolar|Lynx Shunt|SmartShunt|BMV(?:-|\s))/i.test(model)
+                        ? "Victron Energy"
+                        : null;
+                provenance = `aboard.metadata.dbus:${service}`;
+            }
+            if (!model)
+                continue;
+            const base = `electrical.${group}.${instance}`;
+            found.push({
+                path: `${base}.productName`,
+                value: model,
+                source: provenance,
+            });
+            if (manufacturer)
+                found.push({
+                    path: `${base}.manufacturer`,
+                    value: manufacturer,
+                    source: provenance,
+                });
+        }
+    }
+    for (const [source, identity] of nmea) {
+        if (identity.manufacturer !== "Victron Energy" ||
+            !/^(?:Ekrano GX|Cerbo GX(?: MK2)?|Venus GX|Color Control GX|Octo GX)$/i.test(identity.model))
+            continue;
+        const id = (0, node_crypto_1.createHash)("sha256")
+            .update(identity.stable)
+            .digest("hex")
+            .slice(0, 16);
+        const base = `electrical.controllers.n2k_${id}`;
+        found.push({
+            path: `${base}.productName`,
+            value: identity.model,
+            source: `aboard.metadata.nmea2000:${source}`,
+        });
+        found.push({
+            path: `${base}.manufacturer`,
+            value: identity.manufacturer,
+            source: `aboard.metadata.nmea2000:${source}`,
+        });
+    }
+    return found.slice(0, 192);
+}
+const isEquipmentIdentityPath = (path) => /^electrical\.(?:inverters|chargers|solar|batteries|alternators|controllers)\.[A-Za-z0-9_:-]+\.(?:productName|manufacturer)$/.test(path);
+exports.isEquipmentIdentityPath = isEquipmentIdentityPath;

package/dist/src/http-client.js

@@ -14,7 +14,9 @@ const runtimeConfigurationFrom = (value) => {
         return defaultRuntimeConfiguration();
     }
     const configuration = value;
-    if (typeof configuration.version !== "number" ||
+    if ((configuration.equipment_identity !== undefined &&
+        typeof configuration.equipment_identity !== "boolean") ||
+        typeof configuration.version !== "number" ||
         !Number.isInteger(configuration.version) ||
         configuration.version < 1 ||
         !["active", "standby", "disabled"].includes(String(configuration.operating_mode)) ||

package/dist/src/telemetry-catalog.js

@@ -21,6 +21,14 @@ const ais = (path, valueKind, changeKind, minimumIntervalMs, maximumHeartbeatMs,
     changeThreshold,
 });
 exports.SELF_TELEMETRY = [
+    ...[
+        "inverters",
+        "chargers",
+        "solar",
+        "batteries",
+        "alternators",
+        "controllers",
+    ].flatMap((group) => ["productName", "manufacturer"].map((field) => self(`electrical.${group}.*.${field}`, "string", "identity", 0, 600_000, 0))),
     // GX-owned sensor names and SI readings need no per-installation path mapping.
     self("environment.venus.*.name", "string", "identity", 0, 600_000, 0),
     self("environment.venus.*.temperature", "number", "scalar", 30_000, 60_000, 0.2),

package/dist/src/types.d.ts

@@ -5,6 +5,7 @@ export type ProtocolVersion = (typeof SUPPORTED_PROTOCOL_VERSIONS)[number];
 export type OperatingMode = "active" | "standby" | "disabled";
 export type PairingState = "unpaired" | "verifying" | "paired" | "pairing-required";
 export interface RuntimeConfiguration {
+    equipment_identity?: boolean;
     version: number;
     operating_mode: OperatingMode;
     poll_after_seconds: number;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTOR_VERSION = "0.2.0-dev.40";
+export declare const CONNECTOR_VERSION = "0.2.0-dev.41";

package/dist/src/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONNECTOR_VERSION = void 0;
-exports.CONNECTOR_VERSION = "0.2.0-dev.40";
+exports.CONNECTOR_VERSION = "0.2.0-dev.41";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurora-blue/signalk-connector",
-  "version": "0.2.0-dev.40",
+  "version": "0.2.0-dev.41",
   "description": "Signal K edge connector for the Aurora Blue ABOARD ingest protocol",
   "private": false,
   "main": "dist/src/index.js",