@atelieruldetehnologii/node-red-custome-solutions 0.62.22

package/multi-battery/multi-battery.js

@@ -0,0 +1,668 @@
+module.exports = function (RED) {
+
+    "use strict";
+
+const { runLicensedNode } = require("../lib/licensing/node-guard");
+
+
+    const {
+        clamp,
+        extractTimestampMs,
+        getByPath,
+        parseBooleanLike
+    } = require("../bess-control/lib/helpers");
+
+    const {
+        proportionalAllocation
+    } = require("../bess-control/lib/allocation");
+
+    const {
+        distributionIsValid,
+        normalizeBatteries
+    } = require("../bess-control/lib/batteries");
+
+    const {
+        extractBatteryId,
+        extractBatteryTelemetry,
+        isFeedbackMessage
+    } = require("../bess-control/lib/messages");
+
+    const {
+        evaluateRuntimeBatteries
+    } = require("../bess-control/lib/runtime");
+
+    const {
+        atLeast
+    } = require("../lib/numbers");
+
+
+    function toCommandValue(msg, fieldNames) {
+
+        const payload = msg && msg.payload && typeof msg.payload === "object" ? msg.payload : null;
+
+        if (!payload) {
+            return undefined;
+        }
+
+        for (let index = 0; index < fieldNames.length; index += 1) {
+
+            const field = fieldNames[index];
+
+            if (payload[field] !== undefined) {
+                return payload[field];
+            }
+
+        }
+
+        return undefined;
+
+    }
+
+
+    function toFiniteNumber(value) {
+
+        const numeric = Number(value);
+        return Number.isFinite(numeric) ? numeric : null;
+
+    }
+
+
+    function extractIncomingCommand(msg) {
+
+        const payload = msg && msg.payload && typeof msg.payload === "object" ? msg.payload : null;
+        let powerW = null;
+        let externalControl = null;
+        let socMinPct = null;
+        let socHystPct = null;
+
+        if (payload) {
+
+            const powerWRaw = toCommandValue(msg, ["power_w", "limit_w", "value_w", "watts"]);
+            const powerKwRaw = toCommandValue(msg, ["power_kw", "limit_kw", "value_kw", "kw", "power"]);
+            const externalRaw = toCommandValue(msg, [
+                "external_control",
+                "externalControl",
+                "enable_external_control",
+                "enableExternalControl",
+                "control_extern",
+                "enabled",
+                "enable"
+            ]);
+            const socMinRaw = toCommandValue(msg, [
+                "soc_min_pct",
+                "soc_min",
+                "min_soc_pct",
+                "socMinPct"
+            ]);
+            const socHystRaw = toCommandValue(msg, [
+                "soc_hyst_pct",
+                "soc_hysteresis_pct",
+                "soc_hyst",
+                "socHystPct"
+            ]);
+
+            if (powerWRaw !== undefined) {
+                powerW = toFiniteNumber(powerWRaw);
+            } else if (powerKwRaw !== undefined) {
+                const powerKw = toFiniteNumber(powerKwRaw);
+                powerW = Number.isFinite(powerKw) ? Math.round(powerKw * 1000) : null;
+            }
+
+            if (externalRaw !== undefined) {
+                externalControl = parseBooleanLike(externalRaw);
+            }
+
+            if (socMinRaw !== undefined) {
+                socMinPct = toFiniteNumber(socMinRaw);
+            }
+
+            if (socHystRaw !== undefined) {
+                socHystPct = toFiniteNumber(socHystRaw);
+            }
+
+        }
+
+        return {
+            hasCommand: powerW !== null || externalControl !== null || socMinPct !== null || socHystPct !== null,
+            powerW: powerW,
+            externalControl: externalControl,
+            socMinPct: socMinPct,
+            socHystPct: socHystPct
+        };
+
+    }
+
+
+    function MultiBatteryNode(config) {
+
+        RED.nodes.createNode(this, config);
+
+        const node = this;
+
+        runLicensedNode(node, RED, config, function startLicensedRuntime() {
+
+
+        node.name = String(config.name || "").trim();
+        node.batterySocPath = String(config.batterySocPath || "payload.battery_soc").trim();
+        node.externalControlStatusPath = String(config.externalControlStatusPath || "payload.external_control_status").trim();
+        node.alarmLevelPath = String(config.alarmLevelPath || "payload.battery_alarm_level").trim();
+        node.operatingStatusPath = String(config.operatingStatusPath || "payload.battery_operating_status").trim();
+        node.deratingReasonPath = String(config.deratingReasonPath || "payload.battery_derating_reason").trim();
+        node.availableChargePath = String(config.availableChargePath || "").trim();
+        node.availableDischargePath = String(config.availableDischargePath || "").trim();
+        node.feedbackTimeoutMs = atLeast(config.feedbackTimeoutMs, 0, 5000);
+        node.staleTimeoutMs = atLeast(config.staleTimeoutMs, 0, 0);
+        node.strategy = config.strategy || "fixed_share";
+        node.outputTopic = String(config.outputTopic || "bess/setpoint").trim();
+        node.enableDebugOutput = !!config.enableDebugOutput;
+        node.batteryCount = atLeast(config.batteryCount, 1, 1);
+        node.batteries = normalizeBatteries(config.batteries, node.batteryCount);
+
+
+        let lastExternalControl = null;
+        let lastRequestedPowerW = 0;
+        let lastCommandTs = null;
+        let watchdogTimer = null;
+        let lastWatchdogSignature = "";
+        const batteryState = {};
+
+        function applyGlobalSocOverrides(batteries, overrides) {
+
+            return batteries.map(function (battery) {
+                return Object.assign({}, battery, {
+                    socMin: Number.isFinite(overrides.socMinPct) ? overrides.socMinPct : battery.socMin,
+                    socHyst: Number.isFinite(overrides.socHystPct) ? overrides.socHystPct : battery.socHyst
+                });
+            });
+
+        }
+
+
+        function configuredBatteryIds() {
+
+            return node.batteries.map(function (battery) {
+                return battery.id;
+            }).filter(Boolean);
+
+        }
+
+        function buildRuntimeBatteries(batteries, now) {
+            return evaluateRuntimeBatteries(
+                batteries,
+                batteryState,
+                {
+                    staleTimeoutMs: node.staleTimeoutMs,
+                    feedbackTimeoutMs: node.feedbackTimeoutMs
+                },
+                now
+            ).map(function (runtime) {
+                const config = runtime.config;
+                const state = runtime.state;
+                return Object.assign({}, config, {
+                    enabled: !runtime.excluded,
+                    reason: runtime.excludedReasons.length ? runtime.excludedReasons.join(",") : "ready",
+                    currentSocPct: state.soc,
+                    externalControlStatus: state.externalControlStatus,
+                    alarmLevel: state.alarmLevel,
+                    operatingStatus: state.operatingStatus,
+                    deratingReason: state.deratingReason,
+                    availableChargeW: runtime.availableChargeW,
+                    availableDischargeW: runtime.availableDischargeW,
+                    feedback: state.feedback,
+                    telemetryTs: state.ts,
+                    feedbackTs: state.feedbackTs,
+                    telemetryStale: runtime.telemetryStale,
+                    feedbackStale: runtime.feedbackStale,
+                    dischargeAllowed: runtime.dischargeAllowed
+                });
+            });
+        }
+
+        function validateDistribution(batteries) {
+            const valid = distributionIsValid(batteries);
+            return {
+                valid: valid,
+                reasons: valid ? [] : ["charge/discharge shares must total 100%"]
+            };
+        }
+
+
+        function updateTelemetry(msg, now, msgTs) {
+
+            const telemetry = extractBatteryTelemetry(msg, {
+                getByPath: getByPath,
+                parseBooleanLike: parseBooleanLike,
+                batterySocPath: node.batterySocPath,
+                externalControlStatusPath: node.externalControlStatusPath,
+                alarmLevelPath: node.alarmLevelPath,
+                operatingStatusPath: node.operatingStatusPath,
+                deratingReasonPath: node.deratingReasonPath,
+                availableChargePath: node.availableChargePath,
+                availableDischargePath: node.availableDischargePath
+            });
+
+            const incomingBatteryId = extractBatteryId(msg);
+            const batteryIds = configuredBatteryIds();
+
+
+            const hasTelemetry =
+                telemetry.soc !== null ||
+                telemetry.externalControlStatus !== null ||
+                telemetry.alarmLevel !== undefined ||
+                telemetry.operatingStatus !== undefined ||
+                telemetry.deratingReason !== undefined ||
+                telemetry.availableChargeW !== null ||
+                telemetry.availableDischargeW !== null;
+
+            if (!hasTelemetry) {
+                return false;
+            }
+
+
+            let targetIds = [];
+
+            if (incomingBatteryId) {
+
+                if (batteryIds.indexOf(incomingBatteryId) !== -1) {
+                    targetIds = [incomingBatteryId];
+                } else {
+                    node.warn("multi-battery: batteryId necunoscut: " + incomingBatteryId);
+                    return false;
+                }
+
+            } else if (batteryIds.length === 1) {
+
+                targetIds = [batteryIds[0]];
+
+            } else {
+
+                node.warn("multi-battery: mesaj de baterie fara batteryId pentru configuratie multi-baterie");
+                return false;
+
+            }
+
+
+            targetIds.forEach(function (batteryId) {
+
+                const current = batteryState[batteryId] || {};
+
+                batteryState[batteryId] = Object.assign({}, current, {
+                    soc: telemetry.soc !== null ? telemetry.soc : current.soc,
+                    externalControlStatus: telemetry.externalControlStatus !== null ? telemetry.externalControlStatus : current.externalControlStatus,
+                    alarmLevel: telemetry.alarmLevel !== undefined ? telemetry.alarmLevel : current.alarmLevel,
+                    operatingStatus: telemetry.operatingStatus !== undefined ? telemetry.operatingStatus : current.operatingStatus,
+                    deratingReason: telemetry.deratingReason !== undefined ? telemetry.deratingReason : current.deratingReason,
+                    availableChargeW: telemetry.availableChargeW !== null ? telemetry.availableChargeW : current.availableChargeW,
+                    availableDischargeW: telemetry.availableDischargeW !== null ? telemetry.availableDischargeW : current.availableDischargeW,
+                    ts: msgTs || now
+                });
+
+            });
+
+
+            return true;
+
+        }
+
+
+        function updateFeedback(msg, now, msgTs) {
+
+            if (!isFeedbackMessage(msg)) {
+                return false;
+            }
+
+            const batteryId = extractBatteryId(msg);
+            const configuredIds = configuredBatteryIds();
+
+            if (batteryId) {
+
+                if (configuredIds.indexOf(batteryId) === -1) {
+                    node.warn("multi-battery: feedback pentru batteryId necunoscut: " + batteryId);
+                    return false;
+                }
+
+                const current = batteryState[batteryId] || {};
+                batteryState[batteryId] = Object.assign({}, current, {
+                    feedback: msg.payload,
+                    feedbackTs: msgTs || now,
+                    writeFeedback: {
+                        status: msg.payload && msg.payload.status,
+                        ts: msgTs || now
+                    }
+                });
+                return true;
+
+            }
+
+            if (configuredIds.length === 1) {
+                const onlyId = configuredIds[0];
+                const current = batteryState[onlyId] || {};
+                batteryState[onlyId] = Object.assign({}, current, {
+                    feedback: msg.payload,
+                    feedbackTs: msgTs || now,
+                    writeFeedback: {
+                        status: msg.payload && msg.payload.status,
+                        ts: msgTs || now
+                    }
+                });
+                return true;
+            }
+
+            node.warn("multi-battery: feedback fara batteryId pentru configuratie multi-baterie");
+            return false;
+
+        }
+
+
+        function buildDiagnostic(command, runtimeBatteries, validation) {
+
+            return {
+                topic: node.outputTopic,
+                payload: {
+                    command: {
+                        requested_power_w: lastRequestedPowerW,
+                        external_control: lastExternalControl,
+                        received_power_w: command.powerW,
+                        received_external_control: command.externalControl,
+                        soc_min_pct: command.socMinPct,
+                        soc_hyst_pct: command.socHystPct,
+                        last_command_ts: lastCommandTs
+                    },
+                    strategy: node.strategy,
+                    valid: validation.valid,
+                    reasons: validation.reasons,
+                    batteries: runtimeBatteries.map(function (battery) {
+                        return {
+                            id: battery.id,
+                            enabled: battery.enabled,
+                            reason: battery.reason,
+                            requested_power_w: battery.requestedPowerW,
+                            clamped_power_w: battery.clampedPowerW,
+                            current_soc_pct: battery.currentSocPct,
+                            soc_min_pct: battery.socMin,
+                            soc_hyst_pct: battery.socHyst,
+                            external_control_status: battery.externalControlStatus,
+                            alarm_level: battery.alarmLevel,
+                            operating_status: battery.operatingStatus,
+                            derating_reason: battery.deratingReason,
+                            available_charge_w: battery.availableChargeW,
+                            available_discharge_w: battery.availableDischargeW,
+                            feedback: battery.feedback,
+                            telemetry_ts: battery.telemetryTs,
+                            feedback_ts: battery.feedbackTs
+                        };
+                    })
+                }
+            };
+
+        }
+
+
+        function sendOutputs(command, runtimeBatteries, validation) {
+
+            const outputs = [];
+
+            runtimeBatteries.forEach(function (battery) {
+
+                const msg = {
+                    topic: node.outputTopic,
+                    batteryId: battery.id,
+                    payload: {
+                        battery_id: battery.id,
+                        external_control: !!lastExternalControl,
+                        power_w: battery.clampedPowerW,
+                        requested_power_w: battery.requestedPowerW,
+                        soc_min_pct: battery.socMin,
+                        soc_hyst_pct: battery.socHyst,
+                        strategy: node.strategy
+                    }
+                };
+
+                outputs.push(msg);
+
+            });
+
+            if (node.enableDebugOutput) {
+                outputs.push(buildDiagnostic(command, runtimeBatteries, validation));
+            }
+
+            while (outputs.length < node.batteryCount + (node.enableDebugOutput ? 1 : 0)) {
+                outputs.push(null);
+            }
+
+            node.send(outputs);
+
+        }
+
+
+        function applyDistribution(totalPowerW, runtimeBatteries) {
+
+            const chargeTargets = runtimeBatteries.map(function (battery) {
+                return battery.shareChargePct;
+            });
+
+            const dischargeTargets = runtimeBatteries.map(function (battery) {
+                return battery.shareDischargePct;
+            });
+
+            const bySocWeights = runtimeBatteries.map(function (battery) {
+                const soc = Number.isFinite(battery.currentSocPct) ? battery.currentSocPct : 0;
+                return totalPowerW >= 0 ? soc : Math.max(0, 100 - soc);
+            });
+
+            const byAvailablePowerWeights = runtimeBatteries.map(function (battery) {
+                return totalPowerW >= 0
+                    ? Math.max(0, battery.availableChargeW || battery.maxChargeW || 0)
+                    : Math.max(0, battery.availableDischargeW || battery.maxDischargeW || 0);
+            });
+
+            let weights;
+
+            switch (node.strategy) {
+                case "by_soc":
+                    weights = bySocWeights;
+                    break;
+                case "by_available_power":
+                    weights = byAvailablePowerWeights;
+                    break;
+                case "hybrid":
+                    weights = chargeTargets.map(function (target, index) {
+                        const base = totalPowerW >= 0 ? target : dischargeTargets[index];
+                        const socWeight = bySocWeights[index];
+                        const availableWeight = byAvailablePowerWeights[index];
+                        return (base * 0.5) + (socWeight * 0.25) + (availableWeight * 0.25);
+                    });
+                    break;
+                case "fixed_share":
+                default:
+                    weights = totalPowerW >= 0 ? chargeTargets : dischargeTargets;
+                    break;
+            }
+
+            const entries = runtimeBatteries.map(function (battery, index) {
+                const capW = totalPowerW >= 0
+                    ? Math.min(battery.maxChargeW, battery.availableChargeW)
+                    : (battery.dischargeAllowed ? Math.min(battery.maxDischargeW, battery.availableDischargeW) : 0);
+                return {
+                    id: battery.id,
+                    weight: weights[index],
+                    capW: battery.enabled ? capW : 0
+                };
+            });
+            const allocated = proportionalAllocation(totalPowerW, entries);
+            const signed = runtimeBatteries.map(function (battery) {
+                return Number(allocated[battery.id] || 0);
+            });
+
+            return signed;
+
+        }
+
+
+        function updateStatus(runtimeBatteries, validation) {
+
+            const enabled = runtimeBatteries.filter(function (battery) { return battery.enabled; }).length;
+            const total = runtimeBatteries.length;
+
+            if (!validation.valid) {
+                node.status({
+                    fill: "red",
+                    shape: "ring",
+                    text: "invalid: " + validation.reasons.join(", ")
+                });
+                return;
+            }
+
+            if (!lastExternalControl) {
+                node.status({
+                    fill: "yellow",
+                    shape: "ring",
+                    text: "external control off"
+                });
+                return;
+            }
+
+            node.status({
+                fill: enabled === total ? "green" : "yellow",
+                shape: enabled === total ? "dot" : "ring",
+                text: enabled + "/" + total + " active | " + lastRequestedPowerW + "W"
+            });
+
+        }
+
+
+        node.on("input", function (msg, send, done) {
+
+            const now = Date.now();
+            const msgTs = extractTimestampMs(msg, now);
+
+            let handled = false;
+
+            if (updateTelemetry(msg, now, msgTs)) {
+                handled = true;
+            }
+
+            if (updateFeedback(msg, now, msgTs)) {
+                handled = true;
+            }
+
+            const command = extractIncomingCommand(msg);
+
+            if (command.hasCommand) {
+
+                handled = true;
+
+                if (command.externalControl !== null) {
+                    lastExternalControl = command.externalControl;
+                }
+
+                if (command.powerW !== null) {
+                    lastRequestedPowerW = Math.round(command.powerW);
+                }
+
+                lastCommandTs = msgTs || now;
+
+                const batteriesWithOverrides = applyGlobalSocOverrides(node.batteries, command);
+
+                const runtimeBatteries = buildRuntimeBatteries(batteriesWithOverrides, now);
+
+                const validation = validateDistribution(batteriesWithOverrides);
+
+                if (validation.valid) {
+
+                    const allocations = applyDistribution(lastRequestedPowerW, runtimeBatteries);
+
+                    runtimeBatteries.forEach(function (battery, index) {
+                        const requested = allocations[index] || 0;
+                        const limit = requested >= 0
+                            ? Math.min(
+                                Math.max(0, Number(battery.maxChargeW || 0)),
+                                Math.max(0, Number(battery.availableChargeW || 0))
+                            )
+                            : (battery.dischargeAllowed
+                                ? Math.min(
+                                    Math.max(0, Number(battery.maxDischargeW || 0)),
+                                    Math.max(0, Number(battery.availableDischargeW || 0))
+                                )
+                                : 0);
+
+                        battery.requestedPowerW = requested;
+                        battery.clampedPowerW = battery.enabled ? clamp(requested, -limit, limit) : 0;
+                    });
+
+                } else {
+
+                    runtimeBatteries.forEach(function (battery) {
+                        battery.requestedPowerW = 0;
+                        battery.clampedPowerW = 0;
+                    });
+
+                }
+
+                updateStatus(runtimeBatteries, validation);
+                sendOutputs(command, runtimeBatteries, validation);
+
+            } else if (!handled) {
+
+                node.debug("multi-battery: mesaj ignorat fara command, telemetry sau feedback utile");
+
+            }
+
+            if (done) {
+                done();
+            }
+
+        });
+
+        if (node.staleTimeoutMs > 0) {
+            watchdogTimer = setInterval(function () {
+                if (!lastCommandTs) {
+                    return;
+                }
+
+                const now = Date.now();
+                const runtimeBatteries = buildRuntimeBatteries(node.batteries, now);
+                const validation = validateDistribution(node.batteries);
+                if (!runtimeBatteries.some(function (battery) { return battery.telemetryStale; })) {
+                    lastWatchdogSignature = "";
+                    return;
+                }
+                const signature = JSON.stringify(runtimeBatteries.map(function (battery) {
+                    return [battery.id, battery.enabled, battery.reason];
+                }));
+
+                if (signature === lastWatchdogSignature) {
+                    return;
+                }
+                lastWatchdogSignature = signature;
+
+                runtimeBatteries.forEach(function (battery) {
+                    battery.requestedPowerW = 0;
+                    battery.clampedPowerW = 0;
+                });
+                updateStatus(runtimeBatteries, validation);
+                sendOutputs({
+                    hasCommand: false,
+                    powerW: null,
+                    externalControl: null,
+                    socMinPct: null,
+                    socHystPct: null
+                }, runtimeBatteries, validation);
+            }, Math.max(250, Math.min(node.staleTimeoutMs, 1000)));
+        }
+
+        node.on("close", function (done) {
+            if (watchdogTimer) {
+                clearInterval(watchdogTimer);
+                watchdogTimer = null;
+            }
+            if (done) done();
+        });
+
+    
+        });
+    }
+
+    RED.nodes.registerType("multi-battery", MultiBatteryNode);
+
+};