@atelieruldetehnologii/node-red-custome-solutions 0.62.22

package/bess-control/bess-control.js

@@ -0,0 +1,541 @@
+module.exports = function (RED) {
+
+    "use strict";
+
+const { runLicensedNode } = require("../lib/licensing/node-guard");
+
+
+    const {
+        denormalizeByConvention,
+        extractTimestampMs,
+        getByPath,
+        normalizeByConvention,
+        parseBooleanLike
+    } = require("./lib/helpers");
+
+
+    function toFiniteNumber(value, fallback) {
+
+        const numeric = Number(value);
+        return Number.isFinite(numeric) ? numeric : fallback;
+
+    }
+
+
+    function toOptionalFiniteNumber(value) {
+
+        if (value === "" || value === null || value === undefined) {
+            return null;
+        }
+
+        const numeric = Number(value);
+        return Number.isFinite(numeric) ? numeric : null;
+
+    }
+
+
+    function firstFinite() {
+
+        for (let index = 0; index < arguments.length; index += 1) {
+
+            const numeric = Number(arguments[index]);
+
+            if (Number.isFinite(numeric)) {
+                return numeric;
+            }
+
+        }
+
+        return null;
+
+    }
+
+
+    function extractGridReference(msg, path) {
+
+        if (typeof msg.payload === "number") {
+            return Number(msg.payload);
+        }
+
+        if (typeof msg.payload === "string" && msg.payload.trim() !== "") {
+
+            const direct = Number(msg.payload);
+
+            if (Number.isFinite(direct)) {
+                return direct;
+            }
+
+        }
+
+        const payload = msg.payload;
+
+        if (!payload || typeof payload !== "object") {
+            return null;
+        }
+
+        const byPath = Number(getByPath(msg, path));
+
+        if (Number.isFinite(byPath)) {
+            return byPath;
+        }
+
+        return firstFinite(
+            payload.grid_reference_w,
+            payload.power_w,
+            payload.pcc_power,
+            payload.grid_power,
+            payload.power,
+            payload.value
+        );
+
+    }
+
+
+    function extractPhasePower(msg, path, fallbackPaths) {
+
+        const candidates = [];
+
+        if (path) {
+            candidates.push(getByPath(msg, path));
+        }
+
+        (Array.isArray(fallbackPaths) ? fallbackPaths : []).forEach(function (fallbackPath) {
+            candidates.push(getByPath(msg, fallbackPath));
+        });
+
+        for (let index = 0; index < candidates.length; index += 1) {
+            const value = Number(candidates[index]);
+            if (Number.isFinite(value)) {
+                return value;
+            }
+        }
+
+        return null;
+
+    }
+
+
+    function extractBessOff(msg) {
+
+        const payloadOverride = getByPath(msg, "payload.bess_off");
+        const parsed = parseBooleanLike(payloadOverride !== undefined ? payloadOverride : msg.bessOff);
+
+        return parsed;
+
+    }
+
+
+    function buildPrimaryPayload(powerW, externalControl, overrides) {
+
+        const payload = {
+            power_w: Math.round(powerW || 0),
+            external_control: !!externalControl
+        };
+
+        if (overrides && Number.isFinite(overrides.socMinPct)) {
+            payload.soc_min_pct = overrides.socMinPct;
+        }
+
+        if (overrides && Number.isFinite(overrides.socHystPct)) {
+            payload.soc_hyst_pct = overrides.socHystPct;
+        }
+
+        return payload;
+
+    }
+
+
+    function computeAbsoluteZeroFeedInTarget(phaseValues, options) {
+
+        const values = phaseValues.filter(function (value) {
+            return Number.isFinite(value);
+        });
+
+        const kRel = Math.max(0, Number(options && options.kRel));
+        const deadbandW = Math.max(0, Number(options && options.deadbandW));
+        const currentCommandW = Number(options && options.currentCommandW) || 0;
+
+        if (values.length !== 3) {
+            return {
+                totalPowerW: 0,
+                reason: "missing_phase_power",
+                valid: false
+            };
+        }
+
+        const allImport = values.every(function (value) { return value > 0; });
+        const allExport = values.every(function (value) { return value < 0; });
+        const minPhaseW = Math.min.apply(null, values);
+        const maxPhaseW = Math.max.apply(null, values);
+        const discharging = currentCommandW > 0;
+        const charging = currentCommandW < 0;
+
+        if (discharging || (!charging && allImport)) {
+
+            if (Math.abs(minPhaseW) <= deadbandW) {
+                return {
+                    totalPowerW: Math.max(0, currentCommandW),
+                    reason: "zero_feed_in_absolute_deadband",
+                    valid: true
+                };
+            }
+
+            return {
+                totalPowerW: currentCommandW + (3 * kRel * minPhaseW),
+                reason: minPhaseW < 0
+                    ? "zero_feed_in_absolute_reduce_discharge"
+                    : "zero_feed_in_absolute_discharge",
+                valid: true
+            };
+        }
+
+        if (charging || (!discharging && allExport)) {
+
+            if (Math.abs(maxPhaseW) <= deadbandW) {
+                return {
+                    totalPowerW: Math.min(0, currentCommandW),
+                    reason: "zero_feed_in_absolute_deadband",
+                    valid: true
+                };
+            }
+
+            return {
+                totalPowerW: currentCommandW + (3 * kRel * maxPhaseW),
+                reason: maxPhaseW > 0
+                    ? "zero_feed_in_absolute_reduce_charge"
+                    : "zero_feed_in_absolute_charge",
+                valid: true
+            };
+        }
+
+        if (allImport) {
+
+            const limitingPhaseW = minPhaseW;
+
+            if (Math.abs(limitingPhaseW) <= deadbandW) {
+                return {
+                    totalPowerW: 0,
+                    reason: "zero_feed_in_absolute_deadband",
+                    valid: true
+                };
+            }
+
+            return {
+                totalPowerW: 3 * kRel * limitingPhaseW,
+                reason: "zero_feed_in_absolute_discharge",
+                valid: true
+            };
+        }
+
+        if (allExport) {
+
+            const limitingPhaseW = maxPhaseW;
+
+            if (Math.abs(limitingPhaseW) <= deadbandW) {
+                return {
+                    totalPowerW: 0,
+                    reason: "zero_feed_in_absolute_deadband",
+                    valid: true
+                };
+            }
+
+            return {
+                totalPowerW: 3 * kRel * limitingPhaseW,
+                reason: "zero_feed_in_absolute_charge",
+                valid: true
+            };
+        }
+
+        return {
+            totalPowerW: 0,
+            reason: "zero_feed_in_absolute_mixed_phases",
+            valid: true
+        };
+
+    }
+
+
+    function BessControlNode(config) {
+
+        RED.nodes.createNode(this, config);
+
+        const node = this;
+
+        runLicensedNode(node, RED, config, function startLicensedRuntime() {
+
+
+        node.name = String(config.name || "").trim();
+        node.controlMode = config.controlMode || "grid_setpoint";
+        node.zeroFeedInMode = config.zeroFeedInMode || "relative";
+        node.signConvention = config.signConvention || "positive_import";
+        node.gridPowerPath = String(config.gridPowerPath || "payload.power_w").trim();
+        node.gridSetpointW = toFiniteNumber(config.gridSetpointW, 0);
+        node.nominalPowerW = toFiniteNumber(config.nominalPowerW, 0);
+        node.kRel = Math.max(0, toFiniteNumber(config.kRel, 0.3));
+        node.deadbandW = Math.max(0, toFiniteNumber(config.deadbandW, 1000));
+        node.staleTimeoutMs = Math.max(0, toFiniteNumber(config.staleTimeoutMs, 5000));
+        node.socMinPct = toOptionalFiniteNumber(config.socMinPct);
+        node.socHystPct = toOptionalFiniteNumber(config.socHystPct);
+        node.phasePowerPathL1 = String(config.phasePowerPathL1 || "payload.l1_power_w").trim();
+        node.phasePowerPathL2 = String(config.phasePowerPathL2 || "payload.l2_power_w").trim();
+        node.phasePowerPathL3 = String(config.phasePowerPathL3 || "payload.l3_power_w").trim();
+        node.bessOff = !!config.bessOff;
+        node.outputTopic = String(config.outputTopic || "bess/setpoint").trim();
+        node.enableDebugOutput = !!config.enableDebugOutput;
+
+
+        let lastGridNormalizedW = null;
+        let lastGridTs = null;
+        let lastPhaseRawW = { l1: null, l2: null, l3: null };
+        let lastPhaseNormalizedW = { l1: null, l2: null, l3: null };
+        let lastTotalCommandW = 0;
+        let bessOff = node.bessOff;
+        let lastMeasurementReceivedAtMs = null;
+        let watchdogSafeEmitted = false;
+        let watchdogTimer = null;
+
+
+        function refreshStatus(reason, totalPowerW) {
+
+            node.status({
+                fill: bessOff ? "blue" : "green",
+                shape: bessOff ? "ring" : "dot",
+                text: reason + " | total " + Math.round(totalPowerW || 0) + "W"
+            });
+
+        }
+
+
+        node.on("input", function (msg, send, done) {
+
+            try {
+
+                const msgTs = extractTimestampMs(msg);
+                const parsedBessOff = extractBessOff(msg);
+
+                if (parsedBessOff !== null) {
+                    bessOff = parsedBessOff;
+                }
+
+                const gridReference = extractGridReference(msg, node.gridPowerPath);
+                const updatedGrid = Number.isFinite(gridReference);
+                const phaseRawW = {
+                    l1: extractPhasePower(msg, node.phasePowerPathL1, ["payload.power_l1_w", "payload.l1_power_w"]),
+                    l2: extractPhasePower(msg, node.phasePowerPathL2, ["payload.power_l2_w", "payload.l2_power_w"]),
+                    l3: extractPhasePower(msg, node.phasePowerPathL3, ["payload.power_l3_w", "payload.l3_power_w"])
+                };
+
+                const phaseNormalizedW = {
+                    l1: Number.isFinite(phaseRawW.l1) ? normalizeByConvention(phaseRawW.l1, node.signConvention) : null,
+                    l2: Number.isFinite(phaseRawW.l2) ? normalizeByConvention(phaseRawW.l2, node.signConvention) : null,
+                    l3: Number.isFinite(phaseRawW.l3) ? normalizeByConvention(phaseRawW.l3, node.signConvention) : null
+                };
+
+                if (updatedGrid) {
+                    lastGridNormalizedW = normalizeByConvention(gridReference, node.signConvention);
+                    lastGridTs = msgTs;
+                    lastMeasurementReceivedAtMs = Date.now();
+                    watchdogSafeEmitted = false;
+                }
+
+                ["l1", "l2", "l3"].forEach(function (phaseKey) {
+                    if (Number.isFinite(phaseRawW[phaseKey])) {
+                        lastPhaseRawW[phaseKey] = phaseRawW[phaseKey];
+                        lastPhaseNormalizedW[phaseKey] = phaseNormalizedW[phaseKey];
+                        lastMeasurementReceivedAtMs = Date.now();
+                        watchdogSafeEmitted = false;
+                    }
+                });
+
+                let commandNormalizedW = lastTotalCommandW;
+                let reason = "hold_last_command";
+                let validMeasurement = true;
+
+                if (bessOff) {
+                    commandNormalizedW = 0;
+                    reason = "bess_off";
+                } else if (node.controlMode === "nominal_power") {
+                    commandNormalizedW = normalizeByConvention(node.nominalPowerW, node.signConvention);
+                    reason = "nominal_power";
+                } else if (node.controlMode === "zero_feed_in" && node.zeroFeedInMode === "absolute") {
+
+                    const absoluteResult = computeAbsoluteZeroFeedInTarget(
+                        [lastPhaseNormalizedW.l1, lastPhaseNormalizedW.l2, lastPhaseNormalizedW.l3],
+                        {
+                            kRel: node.kRel,
+                            deadbandW: node.deadbandW,
+                            currentCommandW: lastTotalCommandW
+                        }
+                    );
+
+                    commandNormalizedW = absoluteResult.totalPowerW;
+                    reason = absoluteResult.reason;
+                    validMeasurement = absoluteResult.valid;
+
+                } else {
+
+                    if (!Number.isFinite(lastGridNormalizedW)) {
+                        validMeasurement = false;
+                        reason = "missing_grid_power";
+                    } else {
+
+                        let targetNormalizedW = 0;
+
+                        if (node.controlMode === "grid_setpoint") {
+                            targetNormalizedW = normalizeByConvention(node.gridSetpointW, node.signConvention);
+                        } else {
+                            targetNormalizedW = 0;
+                        }
+
+                        const errorW = lastGridNormalizedW - targetNormalizedW;
+
+                        if (Math.abs(errorW) <= node.deadbandW) {
+                            commandNormalizedW = lastTotalCommandW;
+                            reason = "deadband_hold";
+                        } else {
+                            commandNormalizedW = lastTotalCommandW + (node.kRel * errorW);
+                            reason = node.controlMode === "grid_setpoint"
+                                ? "grid_setpoint_tracking"
+                                : "zero_feed_in_relative";
+                        }
+
+                    }
+
+                }
+
+                const overrides = {
+                    socMinPct: node.socMinPct,
+                    socHystPct: node.socHystPct
+                };
+
+                const primaryPayload = buildPrimaryPayload(
+                    denormalizeByConvention(commandNormalizedW, node.signConvention),
+                    !bessOff,
+                    overrides
+                );
+
+                const primaryMsg = {
+                    topic: node.outputTopic,
+                    payload: primaryPayload
+                };
+
+                if (msg._msgid) {
+                    primaryMsg._msgid = msg._msgid;
+                }
+
+                const debugMsg = {
+                    topic: node.outputTopic + "/debug",
+                    payload: {
+                        control_mode: node.controlMode,
+                        zero_feed_in_mode: node.zeroFeedInMode,
+                        sign_convention: node.signConvention,
+                        grid_reference_raw_w: updatedGrid ? gridReference : null,
+                        grid_reference_normalized_w: updatedGrid ? normalizeByConvention(gridReference, node.signConvention) : lastGridNormalizedW,
+                        grid_reference_timestamp_ms: lastGridTs,
+                        phase_power_raw_w: {
+                            l1: lastPhaseRawW.l1,
+                            l2: lastPhaseRawW.l2,
+                            l3: lastPhaseRawW.l3
+                        },
+                        phase_power_normalized_w: {
+                            l1: lastPhaseNormalizedW.l1,
+                            l2: lastPhaseNormalizedW.l2,
+                            l3: lastPhaseNormalizedW.l3
+                        },
+                        k_rel: node.kRel,
+                        deadband_w: node.deadbandW,
+                        total_command_normalized_w: Math.round(commandNormalizedW || 0),
+                        total_command_raw_w: Math.round(primaryPayload.power_w || 0),
+                        external_control: primaryPayload.external_control,
+                        bess_off: bessOff,
+                        reason: reason,
+                        valid_measurement: validMeasurement
+                    }
+                };
+
+                if (msg._msgid) {
+                    debugMsg._msgid = msg._msgid;
+                }
+
+                lastTotalCommandW = commandNormalizedW;
+                refreshStatus(reason, primaryPayload.power_w);
+
+                if (node.enableDebugOutput) {
+                    send([primaryMsg, debugMsg]);
+                } else {
+                    send(primaryMsg);
+                }
+
+                if (done) {
+                    done();
+                }
+
+            } catch (error) {
+
+                node.status({
+                    fill: "red",
+                    shape: "ring",
+                    text: "error"
+                });
+
+                if (done) {
+                    done(error);
+                } else {
+                    node.error(error, msg);
+                }
+
+            }
+
+        });
+
+        if (node.staleTimeoutMs > 0 && node.controlMode !== "nominal_power") {
+            watchdogTimer = setInterval(function () {
+                const nowMs = Date.now();
+                if (bessOff || watchdogSafeEmitted || !Number.isFinite(lastMeasurementReceivedAtMs) || (nowMs - lastMeasurementReceivedAtMs) <= node.staleTimeoutMs) {
+                    return;
+                }
+
+                watchdogSafeEmitted = true;
+                lastTotalCommandW = 0;
+                const primaryMsg = {
+                    topic: node.outputTopic,
+                    payload: buildPrimaryPayload(0, false, {
+                        socMinPct: node.socMinPct,
+                        socHystPct: node.socHystPct
+                    })
+                };
+                node.status({ fill: "yellow", shape: "ring", text: "watchdog stale | total 0W" });
+
+                if (node.enableDebugOutput) {
+                    node.send([primaryMsg, {
+                        topic: node.outputTopic + "/debug",
+                        payload: {
+                            reason: "watchdog_stale",
+                            valid_measurement: false,
+                            measurement_age_ms: nowMs - lastMeasurementReceivedAtMs,
+                            total_command_raw_w: 0,
+                            external_control: false
+                        }
+                    }]);
+                } else {
+                    node.send(primaryMsg);
+                }
+            }, 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("bess-control", BessControlNode);
+
+};

package/bess-control/lib/allocation.js

@@ -0,0 +1,149 @@
+"use strict";
+
+
+function positiveOrZero(value) {
+
+    const n = Number(value);
+
+    return Number.isFinite(n) && n > 0 ? n : 0;
+
+}
+
+
+function proportionalAllocation(total, entries) {
+
+    const result = {};
+
+
+    (entries || []).forEach(function (entry) {
+
+        result[entry.id] = 0;
+
+    });
+
+
+    if (!entries || !entries.length || !Number.isFinite(total) || total === 0) {
+
+        return result;
+
+    }
+
+
+    const positive = total > 0;
+
+    const requested = Math.abs(total);
+
+    let remaining = requested;
+
+    let active = entries.map(function (entry) {
+
+        return {
+
+            id: entry.id,
+
+            weight: positiveOrZero(entry.weight),
+
+            cap: Math.max(0, Number(entry.capW || 0))
+
+        };
+
+    }).filter(function (entry) {
+
+        return entry.cap > 0;
+
+    });
+
+
+    let pass = 0;
+
+    while (remaining > 0.5 && active.length > 0 && pass < 20) {
+
+        let totalWeight = active.reduce(function (sum, entry) {
+
+            return sum + (entry.weight > 0 ? entry.weight : 1);
+
+        }, 0);
+
+
+        if (totalWeight <= 0) {
+
+            totalWeight = active.length;
+
+        }
+
+
+        let allocatedThisPass = 0;
+
+        active.forEach(function (entry) {
+
+            const wanted = remaining * ((entry.weight > 0 ? entry.weight : 1) / totalWeight);
+
+            const current = Math.abs(result[entry.id] || 0);
+
+            const room = Math.max(0, entry.cap - current);
+
+            const delta = Math.min(room, wanted);
+
+
+            result[entry.id] = positive
+
+                ? (result[entry.id] || 0) + delta
+
+                : (result[entry.id] || 0) - delta;
+
+
+            allocatedThisPass += delta;
+
+        });
+
+
+        if (allocatedThisPass <= 0.001) {
+
+            break;
+
+        }
+
+
+        remaining -= allocatedThisPass;
+
+        active = active.filter(function (entry) {
+
+            return Math.abs(result[entry.id] || 0) < entry.cap - 0.001;
+
+        });
+
+        pass += 1;
+
+    }
+
+
+    Object.keys(result).forEach(function (id) {
+
+        result[id] = Math.round(result[id]);
+
+    });
+
+
+    return result;
+
+}
+
+
+function sumAllocation(map) {
+
+    return Object.keys(map || {}).reduce(function (sum, key) {
+
+        return sum + Number(map[key] || 0);
+
+    }, 0);
+
+}
+
+
+module.exports = {
+
+    proportionalAllocation,
+
+    sumAllocation
+
+};