@yarkivaev/scada 2.3.90 → 2.3.113

package/src/application/deploy/releases.js

@@ -0,0 +1,115 @@
+import expand from './expand.js';
+import { assertHeld, edgesOf } from './releaseEdges.js';
+import { profileFor, serverFor } from './releaseNodes.js';
+import { bindModules, busesFor, machinesOf, passedApps, routesFor } from './releaseValues.js';
+import frozen from './frozen.js';
+
+/**
+ * Starts release values from the scada app and the profile modules.
+ *
+ * @param {object} profile - resolved profile
+ * @returns {object} image and module values
+ * @example
+ *   withImage({ apps: { scada: { image: 'example.invalid/plant:1' } }, modules: {} });
+ */
+function withImage(profile) {
+    const app = profile.apps && profile.apps.scada;
+    const image = app && app.image;
+    if (!image) {
+        throw new Error('system document has no scada image');
+    }
+    return { image, ...bindModules(profile, app.secret) };
+}
+
+/**
+ * Copies process fields the chart reads beside the image.
+ *
+ * @param {object} values - release values
+ * @param {object} profile - resolved profile
+ * @param {object} server - selected server
+ * @returns {object} values with command, service, env, and pull secret
+ * @example
+ *   withProcess({ image: 'example.invalid/plant:1' }, { apps: { scada: {} } }, {});
+ */
+function withProcess(values, profile, server) {
+    const app = profile.apps && profile.apps.scada;
+    const copy = { ...values };
+    if (profile.command) {
+        copy.command = profile.command;
+    }
+    if (app && app.pullSecret) {
+        copy.pullSecret = app.pullSecret;
+    }
+    if (server.service) {
+        copy.service = server.service;
+    }
+    if (profile.env) {
+        copy.env = profile.env;
+    }
+    return copy;
+}
+
+/**
+ * Copies machines, sites, and bus addresses when the server has any.
+ *
+ * @param {object} values - release values
+ * @param {object[]} owned - local fan-in records
+ * @param {object[]} routes - incoming sites
+ * @param {object[]} buses - fan-out bus bindings
+ * @returns {object} values with those lists
+ * @example
+ *   withFlows({ image: 'example.invalid/plant:1' }, [], [], []);
+ */
+function withFlows(values, owned, routes, buses) {
+    const copy = { ...values };
+    if (owned.length > 0) {
+        copy.machines = owned;
+    }
+    if (routes.length > 0) {
+        copy.sites = routes;
+    }
+    if (buses.length > 0) {
+        copy.buses = buses;
+    }
+    return copy;
+}
+
+/**
+ * Chart values for one server.
+ *
+ * @param {object} document - expanded document
+ * @param {object} server - selected server
+ * @param {object} profile - resolved profile
+ * @param {object[]} edges - directed edges
+ * @returns {object} scada release values
+ * @example
+ *   scadaRelease({ servers: [] }, { fan_in: [], fan_out: [], id: 'cell' }, { apps: { scada: { image: 'example.invalid/plant:1' } } }, []);
+ */
+function scadaRelease(document, server, profile, edges) {
+    const buses = busesFor(document, server);
+    const owned = machinesOf(server);
+    const routes = routesFor(document, edges, server);
+    const values = withImage(profile);
+    return withFlows(withProcess(values, profile, server), owned, routes, buses);
+}
+
+/**
+ * Cuts one cluster out of a system document.
+ *
+ * @param {object} document - system document
+ * @param {string} cluster - release selector
+ * @returns {{apps: object[], scada: object}} scada values and the profile's other apps
+ * @example
+ *   releases({ profiles: {}, servers: [] }, 'missing');
+ */
+export default function releases(document, cluster) {
+    const expanded = expand(document);
+    const host = serverFor(expanded, cluster);
+    const links = edgesOf(expanded);
+    const profile = profileFor(expanded, host);
+    assertHeld(expanded, links);
+    return frozen({
+        apps: passedApps(profile),
+        scada: scadaRelease(expanded, host, profile, links)
+    });
+}

package/src/application/deploy/withCollectors.js

@@ -0,0 +1,28 @@
+/**
+ * Adds collector rows the chart groups by command.
+ *
+ * The plant supplies the argv. Mapping is copied as the machine has it.
+ *
+ * @example
+ *   withCollectors({ machines: [{ from: 'modbus://192.0.2.10:502', name: 'mill/electrical' }] }, () => { return ['node', 'bin/modbus-to-mqtt.js']; });
+ *
+ * @param {object} values - release values
+ * @param {function} command - address and stream to argv
+ * @returns {object} values whose collectors carry command, address, and path
+ */
+export default function withCollectors(values, command) {
+    return {
+        ...values,
+        collectors: (values.machines || []).map((machine) => {
+            const item = {
+                address: machine.from,
+                command: command(machine.from, machine.name),
+                path: machine.name
+            };
+            if (machine.mapping) {
+                item.mapping = machine.mapping;
+            }
+            return item;
+        })
+    };
+}

package/src/bin/modbus-to-mqtt.js

@@ -0,0 +1,57 @@
+/**
+ * Modbus collector entry point.
+ *
+ * Polls ADDRESS or MODBUS_DEVICES and publishes STREAM + MAPPING document paths.
+ */
+process.on('unhandledRejection', (err) => {
+    process.stderr.write(`Unhandled rejection: ${String(err)}\n`);
+    process.exit(1);
+});
+
+import modbusPublish from '../infrastructure/ingest/mqtt/modbusPublish.js';
+
+/**
+ * Parses a JSON array environment value.
+ *
+ * @param {string|undefined} text - environment value
+ * @returns {Array|undefined} parsed array
+ */
+function jsonList(text) {
+    if (typeof text !== 'string' || !text.startsWith('[')) {
+        return undefined;
+    }
+    return JSON.parse(text);
+}
+
+/**
+ * Parses an optional integer environment value.
+ *
+ * @param {string|undefined} text - environment value
+ * @returns {number|undefined} parsed integer
+ */
+function integer(text) {
+    if (typeof text !== 'string' || text.length === 0) {
+        return undefined;
+    }
+    const value = parseInt(text, 10);
+    if (Number.isNaN(value)) {
+        throw new Error(`Expected a number, got: ${text}`);
+    }
+    return value;
+}
+
+const addresses = jsonList(process.env.ADDRESS);
+const pipeline = modbusPublish(process.env.MQTT_URL, {
+    address: integer(process.env.MODBUS_ADDRESS),
+    addresses,
+    clientId: process.env.CLIENT_ID,
+    count: integer(process.env.MODBUS_COUNT),
+    devices: process.env.MODBUS_DEVICES,
+    interval: parseInt(process.env.POLL_INTERVAL || '5', 10),
+    maps: jsonList(process.env.MAPPING) || [],
+    streams: jsonList(process.env.STREAM) || [],
+    threshold: parseInt(process.env.CIRCUIT_THRESHOLD || '5', 10),
+    timeout: parseInt(process.env.CIRCUIT_TIMEOUT || '60', 10)
+});
+
+pipeline.start();

package/src/infrastructure/ingest/mqtt/addressWindow.js

@@ -0,0 +1,79 @@
+/**
+ * Numeric query parameter on a device address.
+ *
+ * @param {URL} url - device address
+ * @param {string} key - query key
+ * @returns {number|undefined} parsed value
+ */
+function queryNumber(url, key) {
+    const text = url.searchParams.get(key);
+    if (text === null) {
+        return undefined;
+    }
+    const value = parseInt(text, 10);
+    if (Number.isNaN(value) || value < 0) {
+        throw new Error(`Address ${key} must be a non-negative number, got: ${text}`);
+    }
+    return value;
+}
+
+/**
+ * Modbus TCP spec from a modbus URL.
+ *
+ * @param {string} name - device name
+ * @param {URL} url - device address
+ * @returns {string} name:host:port
+ */
+function tcpSpec(name, url) {
+    const port = parseInt(url.port, 10);
+    if (url.hostname.length === 0 || Number.isNaN(port) || port <= 0) {
+        throw new Error(`Modbus address must be modbus://host:port, got: ${url.href}`);
+    }
+    return `${name}:${url.hostname}:${port}`;
+}
+
+/**
+ * Modbus RTU spec from an rtu URL.
+ *
+ * @param {string} name - device name
+ * @param {URL} url - device address
+ * @returns {string} name:rtu:path:baud:line:slave
+ */
+function rtuSpec(name, url) {
+    const parts = url.pathname.split(':');
+    const path = parts[0];
+    const baud = parseInt(parts[1], 10);
+    const line = parts[2] || '8N1';
+    const slave = parts[3] || '1';
+    if (!path.startsWith('/dev/') || Number.isNaN(baud) || baud <= 0) {
+        throw new Error(`RTU address must be rtu:///dev/ttyX:baud:line:slave, got: ${url.href}`);
+    }
+    return `${name}:rtu:${path}:${baud}:${line}:${slave}`;
+}
+
+/**
+ * Connection spec and optional register window for one device URL.
+ *
+ * TCP addresses are `modbus://host:port`. RTU addresses are
+ * `rtu:///dev/ttyX:baud:line:slave`. `at` and `count` are the poll window.
+ *
+ * @example
+ *   addressWindow('modbus://192.0.2.11:502?at=4000&count=2', 'bay/voltage');
+ *
+ * @param {string} address - device URL
+ * @param {string} name - device name in the modbus spec
+ * @returns {{address: number|undefined, count: number|undefined, spec: string}} connection
+ */
+export default function addressWindow(address, name) {
+    const url = new URL(address);
+    const spec = url.protocol === 'modbus:' ? tcpSpec(name, url) : '';
+    const serial = url.protocol === 'rtu:' ? rtuSpec(name, url) : spec;
+    if (serial.length === 0) {
+        throw new Error(`Device address scheme must be modbus or rtu, got: ${address}`);
+    }
+    return Object.freeze({
+        address: queryNumber(url, 'at'),
+        count: queryNumber(url, 'count'),
+        spec: serial
+    });
+}

package/src/infrastructure/ingest/mqtt/modbusPublish.js

@@ -0,0 +1,277 @@
+import addressWindow from './addressWindow.js';
+import modbusMqtt from './modbusMqtt.js';
+import { parsePoint } from './registerPoint.js';
+import registerPublish, { measurementPlans } from './registerPublish.js';
+
+export { measurementPlans };
+
+/**
+ * Device name used in a modbus spec.
+ *
+ * The document path is the name when it has no colon. An empty stream
+ * gets a positional name.
+ *
+ * @param {string} stream - document path
+ * @param {number} index - device index
+ * @returns {string} spec name
+ */
+function deviceName(stream, index) {
+    if (typeof stream !== 'string' || stream.length === 0) {
+        return `device-${index}`;
+    }
+    if (stream.includes(':')) {
+        throw new Error(`Document path must not contain a colon, got: ${stream}`);
+    }
+    return stream;
+}
+
+/**
+ * Stream path at one device index.
+ *
+ * @param {object} config - pipeline config
+ * @param {number} index - device index
+ * @returns {string} document path or empty
+ */
+function streamOf(config, index) {
+    const streams = Array.isArray(config.streams) ? config.streams : [];
+    return typeof streams[index] === 'string' ? streams[index] : '';
+}
+
+/**
+ * Point map at one device index.
+ *
+ * @param {object} config - pipeline config
+ * @param {number} index - device index
+ * @returns {object} parameter id to register point
+ */
+function mapOf(config, index) {
+    const maps = Array.isArray(config.maps) ? config.maps : [];
+    return maps[index] || {};
+}
+
+/**
+ * Devices from ADDRESS urls or a MODBUS_DEVICES list.
+ *
+ * @param {object} config - pipeline config
+ * @returns {Array<object>} connection rows
+ */
+function listed(config) {
+    const addresses = Array.isArray(config.addresses) ? config.addresses : [];
+    if (addresses.length > 0) {
+        return addresses.map((address, index) => {
+            const name = deviceName(streamOf(config, index), index);
+            return { ...addressWindow(address, name), name };
+        });
+    }
+    const devices = typeof config.devices === 'string' ? config.devices : '';
+    if (devices.length === 0) {
+        throw new Error('Modbus publish needs ADDRESS or MODBUS_DEVICES');
+    }
+    return devices.split(',').map((spec) => {
+        const trimmed = spec.trim();
+        return {
+            address: undefined,
+            count: undefined,
+            name: trimmed.split(':')[0],
+            spec: trimmed
+        };
+    });
+}
+
+/**
+ * Requires STREAM and MAPPING to match the device count when present.
+ *
+ * @param {object} config - pipeline config
+ * @param {number} count - device count
+ */
+function assertAligned(config, count) {
+    const maps = Array.isArray(config.maps) ? config.maps : [];
+    const streams = Array.isArray(config.streams) ? config.streams : [];
+    if (maps.length > 0 && maps.length !== count) {
+        throw new Error(`MAPPING has ${maps.length} maps for ${count} devices`);
+    }
+    if (streams.length > 0 && streams.length !== count) {
+        throw new Error(`STREAM has ${streams.length} paths for ${count} devices`);
+    }
+}
+
+/**
+ * Requires unique device names.
+ *
+ * @param {Array<object>} rows - connection rows
+ */
+function assertNames(rows) {
+    const seen = new Set();
+    rows.forEach((row) => {
+        if (seen.has(row.name) || row.name.length === 0) {
+            throw new Error(`Device name must be unique and non-empty, got: ${row.name}`);
+        }
+        seen.add(row.name);
+    });
+}
+
+/**
+ * Lowest and highest PDU touched by a publish plan.
+ *
+ * @param {Array<{point: string}>} points - publish plan
+ * @returns {{end: number|undefined, start: number|undefined}} span
+ */
+function cover(points) {
+    if (points.length === 0) {
+        return { end: undefined, start: undefined };
+    }
+    return points.reduce((box, item) => {
+        const parsed = parsePoint(item.point);
+        return {
+            end: Math.max(box.end, parsed.address + parsed.width),
+            start: Math.min(box.start, parsed.address)
+        };
+    }, { end: 0, start: Number.MAX_SAFE_INTEGER });
+}
+
+/**
+ * Rejects a point that falls outside the poll window.
+ *
+ * @param {Array<{point: string}>} points - publish plan
+ * @param {number} address - window start
+ * @param {number} count - window length
+ * @param {string} name - device name
+ */
+function assertFit(points, address, count, name) {
+    points.forEach((item) => {
+        const parsed = parsePoint(item.point);
+        const index = parsed.address - address;
+        if (index < 0 || index + parsed.width > count) {
+            throw new Error(`Register point ${item.point} is outside ${address}+${count} on ${name}`);
+        }
+    });
+}
+
+/**
+ * Poll window for one device.
+ *
+ * Query `at` and `count` win, then config, then the span of the points.
+ *
+ * @param {object} row - connection row
+ * @param {Array<{point: string}>} points - publish plan
+ * @param {object} config - pipeline config
+ * @returns {{address: number, count: number}} window
+ */
+function resolveWindow(row, points, config) {
+    const box = cover(points);
+    const address = row.address ?? config.address ?? box.start;
+    const count = row.count ?? config.count ?? (box.end - address);
+    if (!Number.isInteger(address) || !Number.isInteger(count) || count <= 0) {
+        throw new Error(`Register window is missing for ${row.name}`);
+    }
+    assertFit(points, address, count, row.name);
+    return { address, count };
+}
+
+/**
+ * One shared window for every device in the process.
+ *
+ * @param {Array<object>} rows - connection rows
+ * @param {Array<Array<{point: string}>>} plans - publish plans
+ * @param {object} config - pipeline config
+ * @returns {{address: number, count: number}} window
+ */
+function oneWindow(rows, plans, config) {
+    const windows = rows.map((row, index) => {
+        return resolveWindow(row, plans[index], config);
+    });
+    const first = windows[0];
+    const mismatch = windows.some((item) => {
+        return item.address !== first.address || item.count !== first.count;
+    });
+    if (mismatch) {
+        throw new Error('Modbus collectors on one process must share one register window');
+    }
+    return first;
+}
+
+/**
+ * Publish plans in device order.
+ *
+ * @param {Array<object>} rows - connection rows
+ * @param {object} config - pipeline config
+ * @returns {Array<Array<{point: string, topic: string}>>} plans
+ */
+function plansFor(rows, config) {
+    return rows.map((row, index) => {
+        return measurementPlans(streamOf(config, index), mapOf(config, index));
+    });
+}
+
+/**
+ * Validates modbusPublish arguments.
+ *
+ * @param {string} mqtt - MQTT broker URL
+ * @param {object} config - pipeline config
+ */
+function assertPublish(mqtt, config) {
+    if (typeof mqtt !== 'string' || mqtt.length === 0) {
+        throw new Error('MQTT URL must be a non-empty string');
+    }
+    if (!config || typeof config !== 'object') {
+        throw new Error('Config must be an object');
+    }
+    if (typeof config.interval !== 'number' || typeof config.threshold !== 'number') {
+        throw new Error('interval, threshold, and timeout must be numbers');
+    }
+    if (typeof config.timeout !== 'number') {
+        throw new Error('interval, threshold, and timeout must be numbers');
+    }
+}
+
+/**
+ * Polls Modbus and publishes measurements named by STREAM and MAPPING.
+ *
+ * A point is `holding:<pdu>`, `holding:<pdu>:abcd`, or `holding:<pdu>:cdab`.
+ * The topic is the document path `stream/parameter`. Devices come from
+ * ADDRESS urls or a MODBUS_DEVICES list. One process shares one window.
+ *
+ * @example
+ *   const pipeline = modbusPublish('mqtt://127.0.0.1:1883', {
+ *     addresses: ['modbus://192.0.2.11:502?at=4000&count=2'],
+ *     interval: 5,
+ *     maps: [{ voltage: 'holding:4000:abcd' }],
+ *     streams: ['mill/electrical'],
+ *     threshold: 5,
+ *     timeout: 60
+ *   });
+ *   pipeline.start();
+ *
+ * @param {string} mqtt - MQTT broker URL
+ * @param {object} config - addresses or devices, streams, maps, interval, threshold, timeout
+ * @returns {object} pipeline with start() and stop()
+ */
+export default function modbusPublish(mqtt, config) {
+    assertPublish(mqtt, config);
+    const rows = listed(config);
+    assertAligned(config, rows.length);
+    assertNames(rows);
+    const plans = plansFor(rows, config);
+    const frame = oneWindow(rows, plans, config);
+    const specs = rows.map((row) => {
+        return row.spec;
+    }).join(',');
+    const byName = new Map(rows.map((row, index) => {
+        return [row.name, plans[index]];
+    }));
+    return modbusMqtt(mqtt, specs, {
+        address: frame.address,
+        clientId: config.clientId || 'scada-modbus',
+        count: frame.count,
+        interval: config.interval,
+        threshold: config.threshold,
+        timeout: config.timeout,
+        transformerFactory(name, collector) {
+            const plan = byName.get(name);
+            if (!plan) {
+                throw new Error(`Modbus device ${name} has no map`);
+            }
+            return registerPublish(plan, frame.address, collector);
+        }
+    });
+}

package/src/infrastructure/ingest/mqtt/registerPoint.js

@@ -0,0 +1,90 @@
+const orders = Object.freeze({
+    abcd: 'abcd',
+    cdab: 'cdab',
+    uint16: 'uint16'
+});
+
+/**
+ * Parses a holding-register point.
+ *
+ * `holding:<address>` is one uint16. `holding:<address>:abcd` and
+ * `holding:<address>:cdab` are float32 word orders. The address is the
+ * same PDU number as the poll window.
+ *
+ * @example
+ *   parsePoint('holding:4000:cdab');
+ *
+ * @param {string} point - register point
+ * @returns {{address: number, order: string, width: number}} parsed point
+ */
+export function parsePoint(point) {
+    const parts = String(point).split(':');
+    const address = parseInt(parts[1], 10);
+    const order = parts[2] || orders.uint16;
+    if (parts[0] !== 'holding' || Number.isNaN(address) || address < 0) {
+        throw new Error(`Register point must be holding:<address>, got: ${point}`);
+    }
+    if (!Object.hasOwn(orders, order)) {
+        throw new Error(`Register word order must be uint16, abcd, or cdab, got: ${point}`);
+    }
+    return Object.freeze({
+        address,
+        order,
+        width: order === orders.uint16 ? 1 : 2
+    });
+}
+
+/**
+ * Float32 word order for a pair of uint16 registers.
+ *
+ * @param {string} order - abcd or cdab
+ * @param {number} first - first register in the window
+ * @param {number} second - second register in the window
+ * @returns {number[]} high word then low word
+ */
+function placed(order, first, second) {
+    if (order === orders.cdab) {
+        return [second, first];
+    }
+    return [first, second];
+}
+
+/**
+ * Decodes a float32 from two uint16 registers.
+ *
+ * @param {string} order - abcd or cdab
+ * @param {number} first - first register in the window
+ * @param {number} second - second register in the window
+ * @returns {number} decoded float
+ */
+function floatOf(order, first, second) {
+    const pair = placed(order, first, second);
+    const buffer = new ArrayBuffer(4);
+    const view = new DataView(buffer);
+    view.setUint16(0, pair[0]);
+    view.setUint16(2, pair[1]);
+    return view.getFloat32(0);
+}
+
+/**
+ * Decodes one holding point from a register window.
+ *
+ * @example
+ *   decodePoint('holding:4000:cdab', 4000, [0, 16256]);
+ *
+ * @param {string} point - register point
+ * @param {number} origin - first PDU address in the window
+ * @param {Array<number>} registers - uint16 window
+ * @returns {number} decoded value
+ */
+export function decodePoint(point, origin, registers) {
+    const parsed = parsePoint(point);
+    const index = parsed.address - origin;
+    if (!Array.isArray(registers) || index < 0 || index + parsed.width > registers.length) {
+        throw new Error(`Register point ${point} is outside the window at ${origin}`);
+    }
+    if (parsed.order === orders.uint16) {
+        return registers[index];
+    }
+    return floatOf(parsed.order, registers[index], registers[index + 1]);
+}