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

package/README.md

@@ -132,3 +132,7 @@ The connector can publish observed own-vessel tracks through an independent, bou
 This development integration is not yet qualified for live replacement. Provider approval, actual API delivery, settings UI verification, backlog handover and onboard resource measurements remain pending. Arbitrary cron expressions, automatic import of the original queue and unlimited sent-track archives are not implemented. Ambiguous acknowledgements can cause a replay; exactly-once delivery is not claimed.
 
 See the canonical [integration and handover documentation](../aurora-blue-documentation/docs/NOFOREIGNLAND_CONNECTOR.md) and ADR-0151. Never reuse the official plugin's embedded application key or include credentials in diagnostic output.
+
+## 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.

package/VERSION

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

package/dist/src/config.d.ts

@@ -3,6 +3,7 @@ import type { StorageProfile } from "./storage-budget";
 import type { OperatingProfile } from "./telemetry-reducer";
 import type { NoForeignLandConfig } from "./noforeignland";
 export interface ConnectorConfig {
+    inputLimitControlEnabled?: boolean;
     noforeignland?: NoForeignLandConfig;
     targetUrl: string;
     deviceName: string;
@@ -150,6 +151,12 @@ export declare const pluginSchema: {
             readonly maximum: 120000;
             readonly default: 5000;
         };
+        readonly inputLimitControlEnabled: {
+            readonly type: "boolean";
+            readonly default: false;
+            readonly title: "Allow confirmed AC input-limit changes from ABOARD";
+            readonly description: "Requires a writable provider with explicit current bounds. Never buffers or retries equipment commands.";
+        };
         readonly adaptiveTelemetryEnabled: {
             readonly type: "boolean";
             readonly title: "Reduce telemetry by change or heartbeat";

package/dist/src/config.js

@@ -157,6 +157,7 @@ const resolveConfig = (input) => {
         bufferSegmentBytes: integer(raw.bufferSegmentKilobytes, 256, 64, 2_048, "Buffer segment size in kilobytes") * 1024,
         compressionEnabled: raw.compressionEnabled !== false,
         compressionThresholdBytes: integer(raw.compressionThresholdBytes, 1_024, 256, 65_536, "Compression threshold"),
+        inputLimitControlEnabled: raw.inputLimitControlEnabled === true,
         adaptiveTelemetryEnabled: raw.adaptiveTelemetryEnabled !== false,
         operatingProfile: operatingProfile,
         anchorAlarm: {
@@ -286,6 +287,12 @@ exports.pluginSchema = {
             maximum: 120000,
             default: 5000,
         },
+        inputLimitControlEnabled: {
+            type: "boolean",
+            default: false,
+            title: "Allow confirmed AC input-limit changes from ABOARD",
+            description: "Requires a writable provider with explicit current bounds. Never buffers or retries equipment commands.",
+        },
         adaptiveTelemetryEnabled: {
             type: "boolean",
             title: "Reduce telemetry by change or heartbeat",

package/dist/src/connector.d.ts

@@ -17,6 +17,9 @@ export declare class ConnectorRuntime {
     private readonly app;
     private readonly store;
     private readonly config;
+    private energyTimer;
+    private energyExecutor;
+    private energyResult;
     private readonly bootId;
     private readonly now;
     private readonly random;
@@ -74,6 +77,8 @@ export declare class ConnectorRuntime {
     private publishAnchorTransition;
     private publishAnchorState;
     private schedule;
+    private startEnergyControl;
+    private pollEnergyControl;
     private scheduleRuntimeConfigurationPoll;
     private pollRuntimeConfiguration;
     private requirePairing;

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 energy_control_1 = require("./energy-control");
 const node_path_1 = require("node:path");
 const noforeignland_1 = require("./noforeignland");
 const node_crypto_1 = require("node:crypto");
@@ -29,6 +30,9 @@ class ConnectorRuntime {
     app;
     store;
     config;
+    energyTimer = null;
+    energyExecutor = null;
+    energyResult = null;
     bootId;
     now;
     random;
@@ -180,6 +184,7 @@ class ConnectorRuntime {
         this.startSafetyTimer();
         await this.updateStatus();
         this.scheduleRuntimeConfigurationPoll(0);
+        this.startEnergyControl();
         if (this.operatingMode !== "disabled") {
             this.schedule(0);
         }
@@ -189,6 +194,9 @@ class ConnectorRuntime {
     }
     async stop() {
         this.stopped = true;
+        this.energyExecutor?.stop();
+        if (this.energyTimer)
+            clearTimeout(this.energyTimer);
         if (this.timer !== null) {
             clearTimeout(this.timer);
             this.timer = null;
@@ -541,6 +549,47 @@ class ConnectorRuntime {
             void this.flush();
         }, delay);
     }
+    startEnergyControl() {
+        if (this.stopped ||
+            this.energyExecutor ||
+            !this.config.inputLimitControlEnabled ||
+            !this.autoSchedule)
+            return;
+        this.energyExecutor = new energy_control_1.InputLimitExecutor(this.app, this.bootId, () => !this.stopped &&
+            this.pairingState === "paired" &&
+            this.operatingMode === "active");
+        void this.pollEnergyControl();
+    }
+    async pollEnergyControl() {
+        if (this.stopped ||
+            !this.energyExecutor ||
+            !this.client?.exchangeEnergyControl)
+            return;
+        try {
+            const state = await this.store.summary();
+            if (state.access_token &&
+                state.target_url === this.config.targetUrl &&
+                this.pairingState === "paired") {
+                const requestedAt = Date.now();
+                const response = await this.client.exchangeEnergyControl(state.access_token, {
+                    session: this.bootId,
+                    capability: this.energyExecutor.capability(),
+                    result: this.energyResult,
+                });
+                this.energyResult = null;
+                if (response.command && !this.stopped) {
+                    this.energyResult = await this.energyExecutor.execute(response.command, new Date(Date.parse(response.server_time) + Date.now() - requestedAt).toISOString());
+                }
+            }
+        }
+        catch {
+            /* Never repeat an equipment write after uncertain transport. */
+        }
+        if (!this.stopped)
+            this.energyTimer = setTimeout(() => {
+                void this.pollEnergyControl();
+            }, 5000);
+    }
     scheduleRuntimeConfigurationPoll(delay) {
         if (this.stopped || !this.autoSchedule) {
             return;
@@ -573,6 +622,7 @@ class ConnectorRuntime {
             }
             this.pairingState = "paired";
             await this.applyRuntimeConfiguration(response.runtime_configuration);
+            this.startEnergyControl();
             if (this.unsubscribes.length === 0) {
                 this.operatingMode = response.runtime_configuration.operating_mode;
                 this.configureSubscriptions();

package/dist/src/energy-control.d.ts

@@ -0,0 +1,47 @@
+import type { ServerAPI } from "@signalk/server-api";
+export interface InputLimitCapability {
+    path: string;
+    source: string;
+    value: number;
+    minimum: number;
+    maximum: number;
+}
+export interface InputLimitCommand {
+    installation_maximum: number;
+    configuration_version: number;
+    id: string;
+    session: string;
+    path: string;
+    source: string;
+    previous_value: number;
+    value: number;
+    expires_at: string;
+}
+export interface InputLimitResult {
+    id: string;
+    state: "completed" | "rejected" | "unconfirmed";
+}
+export interface EnergyControlExchange {
+    session: string;
+    capability: InputLimitCapability | null;
+    result: InputLimitResult | null;
+}
+export interface EnergyControlResponse {
+    command: InputLimitCommand | null;
+    server_time: string;
+}
+/** Only an explicitly writable, bounded, fresh native AC input is eligible. */
+export declare function inputLimitCapability(app: ServerAPI, now?: number): InputLimitCapability | null;
+export declare class InputLimitExecutor {
+    private readonly app;
+    private readonly session;
+    private readonly active;
+    private readonly now;
+    private readonly wait;
+    private stopped;
+    private readonly seen;
+    constructor(app: ServerAPI, session: string, active: () => boolean, now?: () => number, wait?: (ms: number) => Promise<void>);
+    stop(): void;
+    capability(): InputLimitCapability | null;
+    execute(command: InputLimitCommand, serverTime: string): Promise<InputLimitResult>;
+}

package/dist/src/energy-control.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InputLimitExecutor = void 0;
+exports.inputLimitCapability = inputLimitCapability;
+const presets = [6, 10, 16, 20, 25, 32];
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+/** Only an explicitly writable, bounded, fresh native AC input is eligible. */
+function inputLimitCapability(app, now = Date.now()) {
+    const source = record(app.getSelfPath("electrical.venus.acSource"));
+    const fresh = (leaf) => typeof leaf.timestamp === "string" &&
+        Date.parse(leaf.timestamp) <= now + 30000 &&
+        now - Date.parse(leaf.timestamp) < 120000;
+    if (source.value !== "shore" || !fresh(source))
+        return null;
+    const inverters = Object.keys(record(app.getSelfPath("electrical.inverters")));
+    if (inverters.length !== 1 || !/^[A-Za-z0-9_:-]+$/.test(inverters[0]))
+        return null;
+    const path = `electrical.inverters.${inverters[0]}.acin.currentLimit`;
+    const leaf = record(app.getSelfPath(path));
+    const meta = record(leaf.meta);
+    if (meta.supportsPut !== true ||
+        !fresh(leaf) ||
+        typeof leaf.$source !== "string" ||
+        !leaf.$source ||
+        typeof leaf.value !== "number" ||
+        !Number.isFinite(leaf.value) ||
+        typeof meta.minValue !== "number" ||
+        !Number.isFinite(meta.minValue) ||
+        meta.minValue < 0 ||
+        typeof meta.maxValue !== "number" ||
+        !Number.isFinite(meta.maxValue) ||
+        meta.maxValue < meta.minValue ||
+        meta.maxValue > 1000 ||
+        leaf.value < meta.minValue ||
+        leaf.value > meta.maxValue)
+        return null;
+    return {
+        path,
+        source: leaf.$source,
+        value: leaf.value,
+        minimum: meta.minValue,
+        maximum: meta.maxValue,
+    };
+}
+class InputLimitExecutor {
+    app;
+    session;
+    active;
+    now;
+    wait;
+    stopped = false;
+    seen = new Set();
+    constructor(app, session, active, now = Date.now, wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+        this.app = app;
+        this.session = session;
+        this.active = active;
+        this.now = now;
+        this.wait = wait;
+    }
+    stop() {
+        this.stopped = true;
+    }
+    capability() {
+        return !this.stopped && this.active()
+            ? inputLimitCapability(this.app, this.now())
+            : null;
+    }
+    async execute(command, serverTime) {
+        const reject = { id: command.id, state: "rejected" };
+        const remaining = Date.parse(command.expires_at) - Date.parse(serverTime);
+        const cap = this.capability();
+        if (!cap ||
+            this.seen.has(command.id) ||
+            command.session !== this.session ||
+            !Number.isFinite(remaining) ||
+            remaining <= 0 ||
+            remaining > 20000 ||
+            cap.path !== command.path ||
+            cap.source !== command.source ||
+            Math.abs(cap.value - command.previous_value) > 0.01 ||
+            !Number.isFinite(command.installation_maximum) ||
+            command.installation_maximum <= 0 ||
+            !Number.isInteger(command.configuration_version) ||
+            command.configuration_version < 1 ||
+            command.value > command.installation_maximum ||
+            !(presets.includes(command.value) ||
+                Math.abs(command.value - Math.min(command.installation_maximum, cap.maximum)) < 0.01) ||
+            command.value < cap.minimum ||
+            command.value > cap.maximum)
+            return reject;
+        this.seen.add(command.id);
+        if (this.seen.size > 64)
+            this.seen.delete(this.seen.values().next().value);
+        const started = this.now();
+        let failed = false;
+        try {
+            // Dispatch exactly once. A callback alone never proves equipment readback.
+            void Promise.resolve(this.app.putPath(`vessels.self.${cap.path}`, command.value, (error) => {
+                if (error)
+                    failed = true;
+            }, cap.source)).catch(() => {
+                failed = true;
+            });
+        }
+        catch {
+            return reject;
+        }
+        for (let attempt = 0; attempt < Math.min(32, Math.floor(remaining / 250)); attempt++) {
+            await this.wait(250);
+            if (this.stopped || !this.active() || failed)
+                return { id: command.id, state: "unconfirmed" };
+            const current = this.capability();
+            const leaf = record(this.app.getSelfPath(cap.path));
+            if (!current ||
+                current.path !== cap.path ||
+                current.source !== cap.source)
+                return { id: command.id, state: "unconfirmed" };
+            if (Math.abs(current.value - command.value) < 0.01 &&
+                typeof leaf.timestamp === "string" &&
+                Date.parse(leaf.timestamp) >= started)
+                return { id: command.id, state: "completed" };
+        }
+        return { id: command.id, state: "unconfirmed" };
+    }
+}
+exports.InputLimitExecutor = InputLimitExecutor;

package/dist/src/http-client.d.ts

@@ -1,5 +1,7 @@
+import type { EnergyControlExchange, EnergyControlResponse } from "./energy-control";
 import { type IngestAcknowledgement, type IngestBatch, type PairingResponse, type RuntimeConfigurationResponse } from "./types";
 export interface AuroraBlueClient {
+    exchangeEnergyControl?(accessToken: string, data: EnergyControlExchange): Promise<EnergyControlResponse>;
     pair(pairingCode: string, deviceName: string, connectorVersion: string): Promise<PairingResponse>;
     sendBatch(batch: IngestBatch, accessToken: string): Promise<IngestAcknowledgement>;
     fetchRuntimeConfiguration(accessToken: string): Promise<RuntimeConfigurationResponse>;
@@ -17,6 +19,7 @@ export declare class AuroraBlueHttpClient implements AuroraBlueClient {
     pair(pairingCode: string, deviceName: string, connectorVersion: string): Promise<PairingResponse>;
     sendBatch(batch: IngestBatch, accessToken: string): Promise<IngestAcknowledgement>;
     fetchRuntimeConfiguration(accessToken: string): Promise<RuntimeConfigurationResponse>;
+    exchangeEnergyControl(accessToken: string, data: EnergyControlExchange): Promise<EnergyControlResponse>;
     private request;
     private readJson;
 }

package/dist/src/http-client.js

@@ -104,6 +104,18 @@ class AuroraBlueHttpClient {
             server_time: response.server_time,
         };
     }
+    async exchangeEnergyControl(accessToken, data) {
+        const response = await this.request("/api/v1/devices/self/energy-control", {
+            method: "POST",
+            headers: { Authorization: `Bearer ${accessToken}` },
+            body: JSON.stringify(data),
+        });
+        if (typeof response.server_time !== "string" ||
+            !Number.isFinite(Date.parse(response.server_time))) {
+            throw new Error("Invalid energy-control response.");
+        }
+        return response;
+    }
     async request(path, init) {
         const abort = new AbortController();
         const timeout = setTimeout(() => abort.abort(), this.timeoutMs);

package/dist/src/version.d.ts

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

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.38";
+exports.CONNECTOR_VERSION = "0.2.0-dev.40";

package/package.json

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