@atelieruldetehnologii/node-red-custome-solutions 0.62.22

package/fronius-emulator/lib/fronius-register-map.js

@@ -0,0 +1,185 @@
+"use strict";
+
+const { stringToRegisters, float32ToRegisters } = require("./binary-codec");
+
+// These are effective addresses carried in the Modbus PDU. Use addressToPdu()
+// if a future profile needs 40001-style documentation addresses translated.
+const ADDRESS = Object.freeze({
+    GEN24_PROBE_A: 768,
+    GEN24_PROBE_B: 1706,
+    SUNSPEC: 40000,
+    COMMON_MODEL: 40002,
+    COMMON_DATA: 40004,
+    METER_MODEL: 40069,
+    METER_DATA: 40071,
+    ACTIVE_POWER: 40097,
+    EXPORT_ENERGY: 40129,
+    IMPORT_ENERGY: 40137,
+    METER_END: 40195,
+    COMPATIBILITY: 50000
+});
+
+const DEFAULT_MEASUREMENTS = Object.freeze({
+    power: 0,
+    powerL1: 0,
+    powerL2: 0,
+    powerL3: 0,
+    importEnergy: 0,
+    exportEnergy: 0,
+    voltageL1: 230,
+    voltageL2: 230,
+    voltageL3: 230,
+    currentL1: 0,
+    currentL2: 0,
+    currentL3: 0,
+    frequency: 50,
+    reactivePower: 0,
+    reactivePowerL1: 0,
+    reactivePowerL2: 0,
+    reactivePowerL3: 0,
+    apparentPower: 0,
+    apparentPowerL1: 0,
+    apparentPowerL2: 0,
+    apparentPowerL3: 0,
+    powerFactor: 1,
+    powerFactorL1: 1,
+    powerFactorL2: 1,
+    powerFactorL3: 1
+});
+
+const ZERO_FILL_RANGES = Object.freeze([
+    // GEN24 probes these legacy/vendor locations before scanning SunSpec.
+    Object.freeze([768, 768]),
+    Object.freeze([1706, 1706]),
+    Object.freeze([40000, 40255]),
+    Object.freeze([50000, 50063])
+]);
+
+function addressToPdu(address, mode) {
+    const numeric = Number(address);
+    if (!Number.isInteger(numeric)) throw new TypeError("address must be an integer");
+    return mode === "modbus-40001" ? numeric - 40001 : numeric;
+}
+
+function putWords(map, startAddress, words) {
+    words.forEach(function (word, index) { map.set(startAddress + index, word & 0xffff); });
+}
+
+function putFloat(map, address, value, dynamicAddresses) {
+    putWords(map, address, float32ToRegisters(value));
+    dynamicAddresses.add(address);
+    dynamicAddresses.add(address + 1);
+}
+
+function createFroniusRegisterMap(options) {
+    const settings = Object.assign({
+        manufacturer: "Fronius",
+        model: "Smart Meter 63A",
+        version: "1.0",
+        serialNumber: "00000001",
+        unitId: 1,
+        // Confirmed by community captures of a GEN24-compatible meter profile.
+        // This SunSpec DA is independent from the MBAP Unit ID selected in the UI.
+        deviceAddress: 240,
+        powerSignConvention: "import-positive"
+    }, options || {});
+
+    function build(measurements, stale, staleBehaviour) {
+        const values = Object.assign({}, DEFAULT_MEASUREMENTS, measurements || {});
+        const map = new Map();
+        const dynamicAddresses = new Set();
+
+        ZERO_FILL_RANGES.forEach(function (range) {
+            for (let address = range[0]; address <= range[1]; address += 1) map.set(address, 0);
+        });
+
+        putWords(map, ADDRESS.SUNSPEC, [0x5375, 0x6e53]);
+        putWords(map, ADDRESS.COMMON_MODEL, [1, 65]);
+        putWords(map, 40004, stringToRegisters(settings.manufacturer, 16));
+        putWords(map, 40020, stringToRegisters(settings.model, 16));
+        putWords(map, 40036, stringToRegisters("", 8));
+        putWords(map, 40044, stringToRegisters(settings.version, 8));
+        putWords(map, 40052, stringToRegisters(settings.serialNumber, 16));
+        map.set(40068, settings.deviceAddress & 0xff);
+
+        // Community compatibility profile: SunSpec meter model 213, float layout.
+        map.set(ADDRESS.METER_MODEL, 213);
+        map.set(ADDRESS.METER_MODEL + 1, 124);
+        const zeroFlow = stale && staleBehaviour === "zero-power";
+        const currentL1 = zeroFlow ? 0 : values.currentL1;
+        const currentL2 = zeroFlow ? 0 : values.currentL2;
+        const currentL3 = zeroFlow ? 0 : values.currentL3;
+        const totalCurrent = currentL1 + currentL2 + currentL3;
+        putFloat(map, 40071, totalCurrent, dynamicAddresses);
+        putFloat(map, 40073, currentL1, dynamicAddresses);
+        putFloat(map, 40075, currentL2, dynamicAddresses);
+        putFloat(map, 40077, currentL3, dynamicAddresses);
+        putFloat(map, 40079, (values.voltageL1 + values.voltageL2 + values.voltageL3) / 3, dynamicAddresses);
+        putFloat(map, 40081, values.voltageL1, dynamicAddresses);
+        putFloat(map, 40083, values.voltageL2, dynamicAddresses);
+        putFloat(map, 40085, values.voltageL3, dynamicAddresses);
+        putFloat(map, 40095, values.frequency, dynamicAddresses);
+
+        const stalePower = zeroFlow ? 0 : values.power;
+        const stalePowerL1 = zeroFlow ? 0 : values.powerL1;
+        const stalePowerL2 = zeroFlow ? 0 : values.powerL2;
+        const stalePowerL3 = zeroFlow ? 0 : values.powerL3;
+        const signedPower = settings.powerSignConvention === "export-positive" ? -stalePower : stalePower;
+        const signedPowerL1 = settings.powerSignConvention === "export-positive" ? -stalePowerL1 : stalePowerL1;
+        const signedPowerL2 = settings.powerSignConvention === "export-positive" ? -stalePowerL2 : stalePowerL2;
+        const signedPowerL3 = settings.powerSignConvention === "export-positive" ? -stalePowerL3 : stalePowerL3;
+        putFloat(map, ADDRESS.ACTIVE_POWER, signedPower, dynamicAddresses);
+        putFloat(map, 40099, signedPowerL1, dynamicAddresses);
+        putFloat(map, 40101, signedPowerL2, dynamicAddresses);
+        putFloat(map, 40103, signedPowerL3, dynamicAddresses);
+        putFloat(map, 40105, zeroFlow ? 0 : values.apparentPower, dynamicAddresses);
+        putFloat(map, 40107, zeroFlow ? 0 : values.apparentPowerL1, dynamicAddresses);
+        putFloat(map, 40109, zeroFlow ? 0 : values.apparentPowerL2, dynamicAddresses);
+        putFloat(map, 40111, zeroFlow ? 0 : values.apparentPowerL3, dynamicAddresses);
+        putFloat(map, 40113, zeroFlow ? 0 : values.reactivePower, dynamicAddresses);
+        putFloat(map, 40115, zeroFlow ? 0 : values.reactivePowerL1, dynamicAddresses);
+        putFloat(map, 40117, zeroFlow ? 0 : values.reactivePowerL2, dynamicAddresses);
+        putFloat(map, 40119, zeroFlow ? 0 : values.reactivePowerL3, dynamicAddresses);
+        putFloat(map, 40121, values.powerFactor, dynamicAddresses);
+        putFloat(map, 40123, values.powerFactorL1, dynamicAddresses);
+        putFloat(map, 40125, values.powerFactorL2, dynamicAddresses);
+        putFloat(map, 40127, values.powerFactorL3, dynamicAddresses);
+        // Cumulative energies are exposed as Wh and never have their sign inverted.
+        putFloat(map, ADDRESS.EXPORT_ENERGY, values.exportEnergy, dynamicAddresses);
+        putFloat(map, ADDRESS.IMPORT_ENERGY, values.importEnergy, dynamicAddresses);
+        map.set(ADDRESS.METER_END, 0xffff);
+        map.set(ADDRESS.METER_END + 1, 0);
+
+        // 50000 must remain zero-filled: GEN24 uses it as a pre-SunSpec probe.
+        return { map, dynamicAddresses };
+    }
+
+    function read(startAddress, quantity, state) {
+        if (!Number.isInteger(startAddress) || !Number.isInteger(quantity) || quantity < 1 || quantity > 125 || startAddress < 0 || startAddress + quantity > 65536) {
+            return { exceptionCode: 3, issueCode: "invalid_read_range" };
+        }
+        const current = state || {};
+        const image = build(current.measurements, !!current.stale, current.staleBehaviour || "zero-power");
+        if (current.stale && current.staleBehaviour === "modbus-exception") {
+            for (let address = startAddress; address < startAddress + quantity; address += 1) {
+                if (image.dynamicAddresses.has(address)) return { exceptionCode: 4, issueCode: "stale_dynamic_data" };
+            }
+        }
+        const registers = [];
+        for (let address = startAddress; address < startAddress + quantity; address += 1) {
+            if (!image.map.has(address)) return { exceptionCode: 2, issueCode: "illegal_data_address" };
+            registers.push(image.map.get(address));
+        }
+        return { registers };
+    }
+
+    return { read, build, addresses: ADDRESS };
+}
+
+module.exports = {
+    ADDRESS,
+    DEFAULT_MEASUREMENTS,
+    ZERO_FILL_RANGES,
+    addressToPdu,
+    createFroniusRegisterMap
+};

package/fronius-emulator/lib/modbus-parser.js

@@ -0,0 +1,61 @@
+"use strict";
+
+class ModbusParserError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "ModbusParserError";
+        this.code = code;
+    }
+}
+
+/** Stateful parser for fragmented or coalesced Modbus TCP ADUs. */
+class ModbusTcpParser {
+    constructor(options) {
+        const settings = options || {};
+        this.maxAduLength = Number(settings.maxAduLength || 260);
+        this.maxBufferLength = Number(settings.maxBufferLength || 4096);
+        this.buffer = Buffer.alloc(0);
+    }
+
+    push(chunk) {
+        if (!Buffer.isBuffer(chunk)) throw new TypeError("chunk must be a Buffer");
+        if (this.buffer.length + chunk.length > this.maxBufferLength) {
+            this.reset();
+            throw new ModbusParserError("BUFFER_LIMIT", "Modbus receive buffer limit exceeded");
+        }
+        this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : Buffer.from(chunk);
+        const frames = [];
+        while (this.buffer.length >= 7) {
+            const protocolId = this.buffer.readUInt16BE(2);
+            const length = this.buffer.readUInt16BE(4);
+            const frameLength = 6 + length;
+            if (length < 2 || frameLength > this.maxAduLength) {
+                this.reset();
+                throw new ModbusParserError("INVALID_LENGTH", "Invalid MBAP length: " + length);
+            }
+            if (protocolId !== 0) {
+                this.reset();
+                throw new ModbusParserError("INVALID_PROTOCOL", "Invalid Modbus protocol identifier: " + protocolId);
+            }
+            if (this.buffer.length < frameLength) break;
+            const frame = Buffer.from(this.buffer.subarray(0, frameLength));
+            this.buffer = Buffer.from(this.buffer.subarray(frameLength));
+            frames.push({
+                transactionId: frame.readUInt16BE(0),
+                protocolId,
+                length,
+                unitId: frame.readUInt8(6),
+                functionCode: frame.readUInt8(7),
+                pdu: Buffer.from(frame.subarray(7)),
+                adu: frame
+            });
+        }
+        return frames;
+    }
+
+    reset() {
+        this.buffer = Buffer.alloc(0);
+    }
+}
+
+module.exports = { ModbusTcpParser, ModbusParserError };

package/fronius-emulator/lib/modbus-tcp-server.js

@@ -0,0 +1,224 @@
+"use strict";
+
+const net = require("net");
+const { performance } = require("perf_hooks");
+const { ModbusTcpParser } = require("./modbus-parser");
+
+function adu(transactionId, unitId, pdu) {
+    const response = Buffer.allocUnsafe(7 + pdu.length);
+    response.writeUInt16BE(transactionId, 0);
+    response.writeUInt16BE(0, 2);
+    response.writeUInt16BE(pdu.length + 1, 4);
+    response.writeUInt8(unitId, 6);
+    pdu.copy(response, 7);
+    return response;
+}
+
+function exception(transactionId, unitId, functionCode, code) {
+    return adu(transactionId, unitId, Buffer.from([(functionCode | 0x80) & 0xff, code & 0xff]));
+}
+
+function readResponse(frame, registers) {
+    const pdu = Buffer.allocUnsafe(2 + registers.length * 2);
+    pdu.writeUInt8(frame.functionCode, 0);
+    pdu.writeUInt8(registers.length * 2, 1);
+    registers.forEach(function (word, index) { pdu.writeUInt16BE(word & 0xffff, 2 + index * 2); });
+    return adu(frame.transactionId, frame.unitId, pdu);
+}
+
+function createModbusTcpServer(options) {
+    const settings = Object.assign({
+        bindAddress: "0.0.0.0",
+        port: 1502,
+        unitId: 1,
+        maxClients: 5,
+        clientIdleTimeout: 30000,
+        maxAduLength: 260,
+        maxBufferLength: 4096,
+        allowWrites: false
+    }, options || {});
+    let server = null;
+    let stopping = false;
+    const clients = new Set();
+
+    function notify(name, payload) {
+        if (typeof settings[name] === "function") settings[name](payload);
+    }
+
+    function send(state, buffer) {
+        if (state.socket.destroyed) return;
+        if (state.blocked) {
+            state.pending.push(buffer);
+            if (state.pending.length > 32) state.socket.destroy(new Error("response queue limit exceeded"));
+            return;
+        }
+        state.blocked = !state.socket.write(buffer);
+    }
+
+    function drain(state) {
+        state.blocked = false;
+        while (!state.blocked && state.pending.length && !state.socket.destroyed) {
+            state.blocked = !state.socket.write(state.pending.shift());
+        }
+    }
+
+    function parseRead(frame) {
+        if (frame.pdu.length !== 5) return { response: exception(frame.transactionId, frame.unitId, frame.functionCode, 3) };
+        const startAddress = frame.pdu.readUInt16BE(1);
+        const quantity = frame.pdu.readUInt16BE(3);
+        if (quantity < 1 || quantity > 125 || startAddress + quantity > 65536) {
+            return { startAddress, quantity, response: exception(frame.transactionId, frame.unitId, frame.functionCode, 3) };
+        }
+        try {
+            const result = settings.readRegisters(startAddress, quantity, frame.functionCode, frame.unitId);
+            if (!result || result.exceptionCode) {
+                return { startAddress, quantity, response: exception(frame.transactionId, frame.unitId, frame.functionCode, result && result.exceptionCode || 4) };
+            }
+            if (!Array.isArray(result.registers) || result.registers.length !== quantity) {
+                return { startAddress, quantity, response: exception(frame.transactionId, frame.unitId, frame.functionCode, 4) };
+            }
+            return { startAddress, quantity, response: readResponse(frame, result.registers) };
+        } catch (error) {
+            notify("onError", error);
+            return { startAddress, quantity, response: exception(frame.transactionId, frame.unitId, frame.functionCode, 4) };
+        }
+    }
+
+    function performWrite(frame, broadcast) {
+        const fc = frame.functionCode;
+        if (!settings.allowWrites) return broadcast ? {} : { response: exception(frame.transactionId, frame.unitId, fc, 2) };
+        try {
+            if (fc === 6) {
+                if (frame.pdu.length !== 5) return broadcast ? {} : { response: exception(frame.transactionId, frame.unitId, fc, 3) };
+                const startAddress = frame.pdu.readUInt16BE(1);
+                const value = frame.pdu.readUInt16BE(3);
+                const result = typeof settings.writeRegisters === "function" ? settings.writeRegisters(startAddress, [value], frame.unitId) : { exceptionCode: 2 };
+                if (broadcast) return { startAddress, quantity: 1 };
+                if (!result || result.exceptionCode) return { startAddress, quantity: 1, response: exception(frame.transactionId, frame.unitId, fc, result && result.exceptionCode || 2) };
+                return { startAddress, quantity: 1, response: adu(frame.transactionId, frame.unitId, Buffer.from(frame.pdu)) };
+            }
+            if (frame.pdu.length < 6) return broadcast ? {} : { response: exception(frame.transactionId, frame.unitId, fc, 3) };
+            const startAddress = frame.pdu.readUInt16BE(1);
+            const quantity = frame.pdu.readUInt16BE(3);
+            const byteCount = frame.pdu.readUInt8(5);
+            if (quantity < 1 || quantity > 123 || startAddress + quantity > 65536 || byteCount !== quantity * 2 || frame.pdu.length !== 6 + byteCount) {
+                return broadcast ? { startAddress, quantity } : { startAddress, quantity, response: exception(frame.transactionId, frame.unitId, fc, 3) };
+            }
+            const values = [];
+            for (let index = 0; index < quantity; index += 1) values.push(frame.pdu.readUInt16BE(6 + index * 2));
+            const result = typeof settings.writeRegisters === "function" ? settings.writeRegisters(startAddress, values, frame.unitId) : { exceptionCode: 2 };
+            if (broadcast) return { startAddress, quantity };
+            if (!result || result.exceptionCode) return { startAddress, quantity, response: exception(frame.transactionId, frame.unitId, fc, result && result.exceptionCode || 2) };
+            const pdu = Buffer.allocUnsafe(5);
+            pdu.writeUInt8(16, 0);
+            pdu.writeUInt16BE(startAddress, 1);
+            pdu.writeUInt16BE(quantity, 3);
+            return { startAddress, quantity, response: adu(frame.transactionId, frame.unitId, pdu) };
+        } catch (error) {
+            notify("onError", error);
+            return broadcast ? {} : { response: exception(frame.transactionId, frame.unitId, fc, 4) };
+        }
+    }
+
+    function handleFrame(state, frame) {
+        const started = performance.now();
+        const isWrite = frame.functionCode === 6 || frame.functionCode === 16;
+        const broadcast = frame.unitId === 0 && isWrite;
+        const unitAllowed = typeof settings.isUnitIdAllowed === "function"
+            ? settings.isUnitIdAllowed(frame.unitId)
+            : frame.unitId === settings.unitId;
+        if (!unitAllowed && !broadcast) return;
+        let outcome;
+        if (frame.functionCode === 3 || frame.functionCode === 4) outcome = parseRead(frame);
+        else if (isWrite) outcome = performWrite(frame, broadcast);
+        else outcome = { response: exception(frame.transactionId, frame.unitId, frame.functionCode, 1) };
+        if (outcome.response) send(state, outcome.response);
+        notify("onRequest", {
+            remoteAddress: state.remoteAddress,
+            transactionId: frame.transactionId,
+            unitId: frame.unitId,
+            functionCode: frame.functionCode,
+            startAddress: outcome.startAddress,
+            quantity: outcome.quantity,
+            responseTimeMs: Number((performance.now() - started).toFixed(3))
+        });
+    }
+
+    function start() {
+        if (server) return Promise.resolve(server.address());
+        stopping = false;
+        return new Promise(function (resolve, reject) {
+            const instance = net.createServer(function (socket) {
+                if (clients.size >= settings.maxClients) {
+                    notify("onClientRejected", { remoteAddress: socket.remoteAddress || null });
+                    socket.destroy();
+                    return;
+                }
+                const state = {
+                    socket,
+                    parser: new ModbusTcpParser({ maxAduLength: settings.maxAduLength, maxBufferLength: settings.maxBufferLength }),
+                    remoteAddress: String(socket.remoteAddress || "").replace(/^::ffff:/, ""),
+                    pending: [],
+                    blocked: false
+                };
+                clients.add(state);
+                socket.setTimeout(settings.clientIdleTimeout);
+                notify("onClientConnected", { remoteAddress: state.remoteAddress, clients: clients.size });
+                socket.on("data", function (chunk) {
+                    try {
+                        state.parser.push(chunk).forEach(function (frame) { handleFrame(state, frame); });
+                    } catch (error) {
+                        notify("onProtocolError", { code: error.code || "PARSER_ERROR", message: error.message, remoteAddress: state.remoteAddress });
+                        socket.destroy();
+                    }
+                });
+                socket.on("drain", function () { drain(state); });
+                socket.on("timeout", function () { socket.destroy(); });
+                socket.on("error", function (error) { notify("onSocketError", error); });
+                socket.on("close", function () {
+                    if (!clients.delete(state)) return;
+                    state.pending.length = 0;
+                    notify("onClientDisconnected", { remoteAddress: state.remoteAddress, clients: clients.size });
+                });
+            });
+            server = instance;
+            function listenError(error) {
+                instance.removeListener("listening", listening);
+                server = null;
+                reject(error);
+            }
+            function listening() {
+                instance.removeListener("error", listenError);
+                instance.on("error", function (error) { notify("onError", error); });
+                resolve(instance.address());
+            }
+            instance.once("error", listenError);
+            instance.once("listening", listening);
+            instance.listen(settings.port, settings.bindAddress);
+        });
+    }
+
+    function stop() {
+        if (!server || stopping) return Promise.resolve();
+        stopping = true;
+        const instance = server;
+        server = null;
+        clients.forEach(function (state) { state.socket.destroy(); });
+        return new Promise(function (resolve) {
+            instance.close(function () {
+                clients.clear();
+                stopping = false;
+                resolve();
+            });
+        });
+    }
+
+    return {
+        start,
+        stop,
+        address: function () { return server ? server.address() : null; },
+        clientCount: function () { return clients.size; }
+    };
+}
+
+module.exports = { createModbusTcpServer, exception };

package/fronius-emulator/lib/validation.js

@@ -0,0 +1,206 @@
+"use strict";
+
+const MEASUREMENT_RULES = Object.freeze({
+    power: { min: -1e9, max: 1e9 },
+    powerL1: { min: -1e9, max: 1e9 },
+    powerL2: { min: -1e9, max: 1e9 },
+    powerL3: { min: -1e9, max: 1e9 },
+    importEnergy: { min: 0, max: 1e15 },
+    exportEnergy: { min: 0, max: 1e15 },
+    voltageL1: { min: 0, max: 10000 },
+    voltageL2: { min: 0, max: 10000 },
+    voltageL3: { min: 0, max: 10000 },
+    currentL1: { min: 0, max: 1e6 },
+    currentL2: { min: 0, max: 1e6 },
+    currentL3: { min: 0, max: 1e6 },
+    frequency: { min: 0, max: 1000 },
+    reactivePower: { min: -1e9, max: 1e9 },
+    reactivePowerL1: { min: -1e9, max: 1e9 },
+    reactivePowerL2: { min: -1e9, max: 1e9 },
+    reactivePowerL3: { min: -1e9, max: 1e9 },
+    apparentPower: { min: 0, max: 1e9 },
+    apparentPowerL1: { min: 0, max: 1e9 },
+    apparentPowerL2: { min: 0, max: 1e9 },
+    apparentPowerL3: { min: 0, max: 1e9 },
+    powerFactor: { min: -1, max: 1 },
+    powerFactorL1: { min: -1, max: 1 },
+    powerFactorL2: { min: -1, max: 1 },
+    powerFactorL3: { min: -1, max: 1 }
+});
+
+const ALIASES = Object.freeze({
+    power: ["power", "activePower", "gridPower", "watts", "W", "power_w", "active_power_w"],
+    importEnergy: ["importEnergy", "energyImport", "importedEnergy", "importWh"],
+    exportEnergy: ["exportEnergy", "energyExport", "exportedEnergy", "exportWh"]
+});
+
+const FULL_PAYLOAD_FIELDS = Object.freeze([
+    Object.freeze({ key: "power", paths: ["summary.power.total_w"] }),
+    Object.freeze({ key: "powerL1", paths: ["summary.power.l1_w"] }),
+    Object.freeze({ key: "powerL2", paths: ["summary.power.l2_w"] }),
+    Object.freeze({ key: "powerL3", paths: ["summary.power.l3_w"] }),
+    Object.freeze({ key: "importEnergy", paths: ["summary.energy.import_kwh"], scale: 1000 }),
+    Object.freeze({ key: "exportEnergy", paths: ["summary.energy.export_kwh"], scale: 1000 }),
+    Object.freeze({ key: "voltageL1", paths: ["summary.voltage.l1_n_v"] }),
+    Object.freeze({ key: "voltageL2", paths: ["summary.voltage.l2_n_v"] }),
+    Object.freeze({ key: "voltageL3", paths: ["summary.voltage.l3_n_v"] }),
+    Object.freeze({ key: "currentL1", paths: ["summary.current.l1_a"] }),
+    Object.freeze({ key: "currentL2", paths: ["summary.current.l2_a"] }),
+    Object.freeze({ key: "currentL3", paths: ["summary.current.l3_a"] }),
+    Object.freeze({ key: "frequency", paths: ["summary.frequency_hz"] }),
+    Object.freeze({ key: "reactivePower", paths: ["summary.reactive.total_var"] }),
+    Object.freeze({ key: "reactivePowerL1", paths: ["summary.reactive.l1_var"] }),
+    Object.freeze({ key: "reactivePowerL2", paths: ["summary.reactive.l2_var"] }),
+    Object.freeze({ key: "reactivePowerL3", paths: ["summary.reactive.l3_var"] }),
+    Object.freeze({ key: "apparentPower", paths: ["summary.apparent.total_va"] }),
+    Object.freeze({ key: "apparentPowerL1", paths: ["summary.apparent.l1_va"] }),
+    Object.freeze({ key: "apparentPowerL2", paths: ["summary.apparent.l2_va"] }),
+    Object.freeze({ key: "apparentPowerL3", paths: ["summary.apparent.l3_va"] }),
+    Object.freeze({ key: "powerFactor", paths: ["summary.power_factor.total", "summary.power_quality.power_factor.avg"] }),
+    Object.freeze({ key: "powerFactorL1", paths: ["summary.power_factor.l1"] }),
+    Object.freeze({ key: "powerFactorL2", paths: ["summary.power_factor.l2"] }),
+    Object.freeze({ key: "powerFactorL3", paths: ["summary.power_factor.l3"] })
+]);
+
+const COMPACT_PAYLOAD_FIELDS = Object.freeze([
+    Object.freeze({ key: "importEnergy", names: ["energy_import_kwh"], scale: 1000 }),
+    Object.freeze({ key: "exportEnergy", names: ["energy_export_kwh"], scale: 1000 }),
+    Object.freeze({ key: "voltageL1", names: ["voltage_l1_n_v"] }),
+    Object.freeze({ key: "voltageL2", names: ["voltage_l2_n_v"] }),
+    Object.freeze({ key: "voltageL3", names: ["voltage_l3_n_v"] }),
+    Object.freeze({ key: "currentL1", names: ["current_l1_a"] }),
+    Object.freeze({ key: "currentL2", names: ["current_l2_a"] }),
+    Object.freeze({ key: "currentL3", names: ["current_l3_a"] }),
+    Object.freeze({ key: "frequency", names: ["frequency_hz"] }),
+    Object.freeze({ key: "reactivePower", names: ["reactive_power_var", "reactive_total_var"] }),
+    Object.freeze({ key: "reactivePowerL1", names: ["reactive_power_l1_var", "reactive_l1_var"] }),
+    Object.freeze({ key: "reactivePowerL2", names: ["reactive_power_l2_var", "reactive_l2_var"] }),
+    Object.freeze({ key: "reactivePowerL3", names: ["reactive_power_l3_var", "reactive_l3_var"] }),
+    Object.freeze({ key: "apparentPower", names: ["apparent_power_va", "apparent_total_va"] }),
+    Object.freeze({ key: "apparentPowerL1", names: ["apparent_power_l1_va", "apparent_l1_va"] }),
+    Object.freeze({ key: "apparentPowerL2", names: ["apparent_power_l2_va", "apparent_l2_va"] }),
+    Object.freeze({ key: "apparentPowerL3", names: ["apparent_power_l3_va", "apparent_l3_va"] }),
+    Object.freeze({ key: "powerFactor", names: ["power_factor", "power_factor_total"] }),
+    Object.freeze({ key: "powerFactorL1", names: ["power_factor_l1"] }),
+    Object.freeze({ key: "powerFactorL2", names: ["power_factor_l2"] }),
+    Object.freeze({ key: "powerFactorL3", names: ["power_factor_l3"] }),
+    Object.freeze({ key: "powerL1", names: ["power_l1_w", "active_power_l1_w"] }),
+    Object.freeze({ key: "powerL2", names: ["power_l2_w", "active_power_l2_w"] }),
+    Object.freeze({ key: "powerL3", names: ["power_l3_w", "active_power_l3_w"] })
+]);
+
+function integerInRange(value, fallback, min, max) {
+    const numeric = Number(value);
+    return Number.isInteger(numeric) && numeric >= min && numeric <= max ? numeric : fallback;
+}
+
+function cleanText(value, fallback, maximumLength) {
+    const text = String(value == null ? "" : value).trim();
+    return (text || fallback).slice(0, maximumLength);
+}
+
+function canonicalKey(key) {
+    const text = String(key || "");
+    const direct = Object.prototype.hasOwnProperty.call(MEASUREMENT_RULES, text) ? text : null;
+    if (direct) return direct;
+    return Object.keys(ALIASES).find(function (canonical) {
+        return ALIASES[canonical].includes(text);
+    }) || null;
+}
+
+function finiteMeasurement(key, value) {
+    const rule = MEASUREMENT_RULES[key];
+    const numeric = value === null || value === undefined || value === "" ? NaN : Number(value);
+    if (!rule || !Number.isFinite(numeric) || numeric < rule.min || numeric > rule.max) {
+        throw new RangeError(key + " must be a finite number between " + (rule ? rule.min : "?") + " and " + (rule ? rule.max : "?"));
+    }
+    return numeric;
+}
+
+function getByPath(source, path) {
+    return String(path).split(".").reduce(function (value, part) {
+        return value && typeof value === "object" ? value[part] : undefined;
+    }, source);
+}
+
+function firstValue(source, paths) {
+    for (const path of paths) {
+        const value = getByPath(source, path);
+        if (value !== null && value !== undefined && value !== "") return value;
+    }
+    return undefined;
+}
+
+function setMeasurement(normalized, key, value, scale) {
+    if (Object.prototype.hasOwnProperty.call(normalized, key) || value === undefined) return;
+    normalized[key] = finiteMeasurement(key, Number(value) * (scale || 1));
+}
+
+function phasePowerFactor(source) {
+    const values = ["l1", "l2", "l3"].map(function (phase) {
+        const raw = getByPath(source, "summary.power_factor." + phase);
+        return raw === null || raw === undefined || raw === "" ? NaN : Number(raw);
+    }).filter(Number.isFinite);
+    return values.length ? values.reduce(function (sum, value) { return sum + value; }, 0) / values.length : undefined;
+}
+
+/** Normalize native emulator input and full meter payloads from this palette. */
+function normalizePayload(payload, requirePower, message) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new TypeError("msg.payload must be an object");
+    }
+    const normalized = {};
+    Object.keys(MEASUREMENT_RULES).forEach(function (key) {
+        const names = ALIASES[key] || [key];
+        const found = names.find(function (name) {
+            return Object.prototype.hasOwnProperty.call(payload, name);
+        });
+        if (found) normalized[key] = finiteMeasurement(key, payload[found]);
+    });
+
+    COMPACT_PAYLOAD_FIELDS.forEach(function (definition) {
+        const found = definition.names.find(function (name) {
+            return Object.prototype.hasOwnProperty.call(payload, name);
+        });
+        if (found) setMeasurement(normalized, definition.key, payload[found], definition.scale);
+    });
+
+    const envelope = message && typeof message === "object" ? message : {};
+    const fullSources = [payload, envelope.carloGavazzi, envelope.phoenixContact, envelope.janitza]
+        .filter(function (source, index, sources) {
+            return source && typeof source === "object" && !Array.isArray(source) && sources.indexOf(source) === index;
+        });
+    fullSources.forEach(function (source) {
+        FULL_PAYLOAD_FIELDS.forEach(function (definition) {
+            setMeasurement(normalized, definition.key, firstValue(source, definition.paths), definition.scale);
+        });
+        setMeasurement(normalized, "powerFactor", phasePowerFactor(source));
+    });
+
+    if (requirePower && !Object.prototype.hasOwnProperty.call(normalized, "power")) {
+        throw new Error("power is required (msg.payload.power or msg.payload.summary.power.total_w)");
+    }
+    const sourceTimestamp = fullSources.map(function (source) {
+        return firstValue(source, ["meta.timestamp", "timestamp"]);
+    }).find(function (value) { return value !== undefined; });
+    const timestamp = firstValue(payload, ["timestamp", "meta.timestamp"]) || sourceTimestamp || envelope.timestamp;
+    if (timestamp !== undefined) {
+        const date = new Date(timestamp);
+        if (Number.isNaN(date.getTime())) throw new RangeError("timestamp is invalid");
+        normalized.timestamp = date.toISOString();
+    }
+    return normalized;
+}
+
+module.exports = {
+    MEASUREMENT_RULES,
+    ALIASES,
+    FULL_PAYLOAD_FIELDS,
+    COMPACT_PAYLOAD_FIELDS,
+    integerInRange,
+    cleanText,
+    canonicalKey,
+    finiteMeasurement,
+    getByPath,
+    normalizePayload
+};