@impact0815/node-red-contrib-alphaess-modbus 0.0.0-stage → 0.4.0

package/lib/derived.js

@@ -0,0 +1,163 @@
+'use strict';
+/**
+ * Derived values: live power flows, daily energy, alarms.
+ * Sign conventions: grid + = import / - = export, battery + = discharge / - = charge.
+ */
+const { round } = require('./registers');
+
+const pct = (v) => round(Math.max(0, Math.min(100, v)), 1);
+
+/**
+ * Live values. Keys consumption/grid/modules/battery/soc are identical to the
+ * cloud node "Alpha ESS Monitoring" (node-red-contrib-alphaess).
+ */
+function computeLive(d, opts) {
+	opts = opts || {};
+	const s = {};
+	const withAc = opts.includePvMeter && d.pvMeter;
+	if (d.inverter || withAc) {
+		s.modules = (d.inverter ? d.inverter.pvPowerTotal : 0) + (withAc ? Math.abs(d.pvMeter.totalActivePower) : 0);
+	}
+	if (d.grid) s.grid = d.grid.totalActivePower;
+	if (d.battery) {
+		s.battery = d.battery.power;
+		s.soc = d.battery.soc;
+	}
+	if (s.modules !== undefined && s.grid !== undefined && s.battery !== undefined) {
+		s.consumption = Math.max(0, s.modules + s.grid + s.battery);
+		s.gridImport = Math.max(0, s.grid);
+		s.gridExport = Math.max(0, -s.grid);
+		s.batteryCharge = Math.max(0, -s.battery);
+		s.batteryDischarge = Math.max(0, s.battery);
+		s.selfConsumptionRate = s.modules > 0 ? pct((s.modules - s.gridExport) / s.modules * 100) : null;
+		s.autarky = s.consumption > 0 ? pct((s.consumption - s.gridImport) / s.consumption * 100) : null;
+	}
+	return s;
+}
+
+// ------------------------------------------------------------------ daily ----
+const COUNTERS = ['pv', 'gridFeed', 'gridImport', 'batteryCharge', 'batteryDischarge', 'batteryChargeFromGrid'];
+
+/** a day counts as complete if counting started at most this long after local midnight */
+const COMPLETE_TOLERANCE_MS = 15 * 60 * 1000;
+
+function localDay(ts) {
+	const d = new Date(ts);
+	return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+function localMidnight(ts) {
+	const d = new Date(ts);
+	return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+}
+
+function readCounters(d, opts) {
+	if (!d.grid || !d.battery || !d.inverter) return null;
+	if (opts.includePvMeter && !d.systemRun) return null;
+	return {
+		pv: d.inverter.totalPvEnergy + (opts.includePvMeter ? d.systemRun.pvInverterEnergy : 0),
+		gridFeed: d.grid.totalEnergyFeedToGrid,
+		gridImport: d.grid.totalEnergyConsumeFromGrid,
+		batteryCharge: d.battery.chargeEnergy,
+		batteryDischarge: d.battery.dischargeEnergy,
+		batteryChargeFromGrid: d.battery.energyChargeFromGrid
+	};
+}
+
+/**
+ * Daily energy from the lifetime counters (difference since local midnight).
+ * store: { get(key), set(key, value) } – e.g. Node-RED node context.
+ *
+ * daily.complete is true if counting started within COMPLETE_TOLERANCE_MS
+ * after local midnight, i.e. the values cover the whole day. It is false after
+ * a restart during the day without a persistent context store.
+ */
+class DailyTracker {
+	constructor(store, opts) {
+		this.store = store;
+		this.tolerance = (opts && opts.completeTolerance) || COMPLETE_TOLERANCE_MS;
+	}
+
+	update(d, now, opts) {
+		opts = opts || {};
+		const today = localDay(now);
+		let base = this.store.get('dayBase');
+		const last = this.store.get('dailyLast') || null;
+		let yesterday = this.store.get('yesterday') || null;
+		const c = readCounters(d, opts);
+		if (!c) return { daily: last && last.day === today ? last : null, yesterday };
+
+		let changed = false;
+		if (!base || base.day !== today) {
+			if (base && last && last.day === base.day) {
+				yesterday = last;
+				this.store.set('yesterday', yesterday);
+			}
+			base = { day: today, since: now, counters: Object.assign({}, c) };
+			changed = true;
+		}
+		if (typeof base.complete !== 'boolean') {
+			// also for bases stored by versions before 0.2.1
+			base.complete = base.since - localMidnight(base.since) <= this.tolerance;
+			changed = true;
+		}
+		const prevToday = (k) => (last && last.day === today && typeof last[k] === 'number' ? last[k] : 0);
+		const daily = { day: today, since: new Date(base.since).toISOString(), complete: base.complete };
+		COUNTERS.forEach((k) => {
+			if (typeof base.counters[k] !== 'number') {
+				base.counters[k] = c[k] - prevToday(k);
+				changed = true;
+			}
+			let diff = c[k] - base.counters[k];
+			if (diff < -0.05) {
+				// counter was reset or replaced – keep today's value and continue from the new counter
+				base.counters[k] = c[k] - prevToday(k);
+				diff = prevToday(k);
+				changed = true;
+			}
+			daily[k] = round(Math.max(0, diff), 2);
+		});
+		daily.consumption = round(Math.max(0,
+			daily.pv + daily.gridImport - daily.gridFeed + daily.batteryDischarge - daily.batteryCharge), 2);
+		const houseImport = Math.max(0, daily.gridImport - daily.batteryChargeFromGrid);
+		daily.selfConsumptionRate = daily.pv > 0 ? pct((daily.pv - daily.gridFeed) / daily.pv * 100) : null;
+		daily.autarky = daily.consumption > 0 ? pct((daily.consumption - houseImport) / daily.consumption * 100) : null;
+
+		if (changed) this.store.set('dayBase', base);
+		this.store.set('dailyLast', daily);
+		return { daily, yesterday };
+	}
+}
+
+// ----------------------------------------------------------------- alarms ----
+function collectAlarms(d, blocks) {
+	const alarms = [];
+	const warnings = [];
+	const addBits = (arr, prefix, b) => { if (b && b.active) b.active.forEach((a) => arr.push(`${prefix}: ${a.text}`)); };
+	const hex = (v) => '0x' + v.toString(16).toUpperCase().padStart(8, '0');
+
+	if (d.systemRun) addBits(alarms, 'System', d.systemRun.systemFault);
+	if (d.battery) {
+		addBits(alarms, 'Battery', d.battery.fault);
+		(d.battery.faults || []).forEach((v, i) => { if (v) alarms.push(`Battery fault${i + 1}: ${hex(v)}`); });
+		addBits(warnings, 'Battery', d.battery.warning);
+		(d.battery.warnings || []).forEach((v, i) => { if (v) warnings.push(`Battery warning${i + 1}: ${hex(v)}`); });
+	}
+	if (d.inverter) {
+		['fault1', 'fault2', 'faultExtend1', 'faultExtend2'].forEach((k) => addBits(alarms, 'Inverter', d.inverter[k]));
+		['faultExtend3', 'faultExtend4'].forEach((k) => { if (d.inverter[k]) alarms.push(`Inverter ${k}: ${hex(d.inverter[k])}`); });
+		if (d.inverter.workMode && d.inverter.workMode.raw === 4) alarms.push('Inverter: work mode Fault');
+		if (d.inverter.warningBits) {
+			addBits(warnings, 'Inverter', d.inverter.warningBits.warning1);
+			addBits(warnings, 'Inverter', d.inverter.warningBits.warning2);
+		} else {
+			['warning1', 'warning2'].forEach((k) => { if (d.inverter[k]) warnings.push(`Inverter ${k}: ${hex(d.inverter[k])}`); });
+		}
+	}
+	Object.keys(blocks || {}).forEach((k) => {
+		if (blocks[k].stale) alarms.push(`Stale data: ${k}` + (blocks[k].error ? ` (${blocks[k].error})` : ''));
+	});
+	return { alarms, warnings };
+}
+
+module.exports = { computeLive, DailyTracker, collectAlarms, localDay, localMidnight, COUNTERS, COMPLETE_TOLERANCE_MS };

package/lib/i18n.js

@@ -0,0 +1,57 @@
+'use strict';
+/**
+ * Runtime translations.
+ *
+ * In Node-RED, RED._() looks up the message catalogs in locales/<language>/alphaess-modbus.json
+ * (language of the Node-RED server). If RED._ is not available (tests, older runtimes) or the key
+ * is missing, the English catalog is used directly. The English catalog is therefore the single
+ * source of truth for all runtime texts.
+ *
+ * Placeholders use the Node-RED syntax __name__.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const FALLBACK_FILE = path.join(__dirname, '..', 'locales', 'en-US', 'alphaess-modbus.json');
+let fallbackCatalog = null;
+
+function loadFallback() {
+	if (!fallbackCatalog) {
+		try {
+			fallbackCatalog = JSON.parse(fs.readFileSync(FALLBACK_FILE, 'utf8'));
+		} catch (err) {
+			fallbackCatalog = {};
+		}
+	}
+	return fallbackCatalog;
+}
+
+/** "a.b.c" -> catalog.a.b.c */
+function lookup(catalog, key) {
+	return key.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), catalog);
+}
+
+function interpolate(text, vars) {
+	return String(text).replace(/__(\w+)__/g, (m, k) => (vars && vars[k] !== undefined ? String(vars[k]) : m));
+}
+
+/**
+ * @param {object} RED  Node-RED runtime API (RED._ is pre-scoped to this module)
+ * @returns {function(string, object=): string}
+ */
+function createTranslator(RED) {
+	return function t(key, vars) {
+		if (RED && typeof RED._ === 'function') {
+			try {
+				const s = RED._(key, vars);
+				if (typeof s === 'string' && s && s !== key && !s.endsWith(':' + key)) return s;
+			} catch (err) {
+				// fall through to the English catalog
+			}
+		}
+		const text = lookup(loadFallback(), key);
+		return typeof text === 'string' ? interpolate(text, vars) : key;
+	};
+}
+
+module.exports = { createTranslator, interpolate, lookup, FALLBACK_FILE };

package/lib/modbus-tcp.js

@@ -0,0 +1,204 @@
+'use strict';
+/**
+ * Minimal Modbus TCP client (FC03 read holding registers, FC16 write multiple registers).
+ * No external dependencies. Requests are serialised (one in flight), because
+ * the AlphaESS EMS does not handle parallel requests reliably.
+ */
+const net = require('net');
+const { EventEmitter } = require('events');
+
+const EXCEPTIONS = {
+	1: 'Illegal function',
+	2: 'Illegal data address',
+	3: 'Illegal data value',
+	4: 'Slave device failure',
+	5: 'Acknowledge',
+	6: 'Slave device busy',
+	10: 'Gateway path unavailable',
+	11: 'Gateway target failed to respond'
+};
+
+class ModbusError extends Error {
+	constructor(message, code) {
+		super(message);
+		this.name = 'ModbusError';
+		this.code = code;
+	}
+}
+
+class ModbusTcpClient extends EventEmitter {
+	/**
+	 * @param {object} opts
+	 * @param {string} opts.host
+	 * @param {number} [opts.port=502]
+	 * @param {number} [opts.unitId=85]
+	 * @param {number} [opts.timeout=2000]  ms per request
+	 * @param {number} [opts.delay=20]      ms pause between requests
+	 */
+	constructor(opts) {
+		super();
+		this.host = opts.host;
+		this.port = opts.port || 502;
+		this.unitId = opts.unitId === undefined ? 85 : opts.unitId;
+		this.timeout = opts.timeout || 2000;
+		this.delay = opts.delay === undefined ? 20 : opts.delay;
+		this.socket = null;
+		this.connecting = null;
+		this.buffer = Buffer.alloc(0);
+		this.queue = [];
+		this.current = null;
+		this.tid = 0;
+		this.closed = false;
+	}
+
+	get connected() {
+		return !!(this.socket && !this.socket.destroyed && !this.connecting);
+	}
+
+	_connect() {
+		if (this.connected) return Promise.resolve();
+		if (this.connecting) return this.connecting;
+		this.connecting = new Promise((resolve, reject) => {
+			const sock = net.createConnection({ host: this.host, port: this.port });
+			const timer = setTimeout(() => {
+				sock.destroy();
+				reject(new ModbusError(`Connect timeout ${this.host}:${this.port}`, 'ETIMEDOUT'));
+			}, this.timeout);
+			sock.setNoDelay(true);
+			sock.once('connect', () => {
+				clearTimeout(timer);
+				this.socket = sock;
+				this.buffer = Buffer.alloc(0);
+				this.emit('connect');
+				resolve();
+			});
+			sock.on('data', (d) => this._onData(d));
+			sock.on('error', (err) => {
+				clearTimeout(timer);
+				this.emit('socketError', err);
+				reject(err);
+			});
+			sock.on('close', () => {
+				if (this.socket === sock) this.socket = null;
+				this.emit('close');
+				if (this.current && this.current.sent) this._finish(new ModbusError('Connection closed', 'ECONNRESET'));
+			});
+		}).finally(() => { this.connecting = null; });
+		return this.connecting;
+	}
+
+	_onData(data) {
+		this.buffer = Buffer.concat([this.buffer, data]);
+		while (this.buffer.length >= 7) {
+			const frameLen = 6 + this.buffer.readUInt16BE(4);
+			if (this.buffer.length < frameLen) return;
+			const frame = this.buffer.subarray(0, frameLen);
+			this.buffer = this.buffer.subarray(frameLen);
+			this._onFrame(frame);
+		}
+	}
+
+	_onFrame(frame) {
+		const cur = this.current;
+		if (!cur || frame.length < 9) return;
+		if (frame.readUInt16BE(0) !== cur.tid) return; // stale answer of a timed-out request
+		const fc = frame[7];
+		if (fc & 0x80) {
+			const code = frame[8];
+			return this._finish(new ModbusError(
+				`Modbus exception ${code} (${EXCEPTIONS[code] || 'unknown'}) at 0x${cur.address.toString(16)}`, code));
+		}
+		if (fc !== cur.fc) return this._finish(new ModbusError(`Unexpected function code ${fc}`, 'EPROTO'));
+		if (fc === 3) {
+			const byteCount = frame[8];
+			const values = [];
+			for (let i = 0; i < byteCount / 2; i++) values.push(frame.readUInt16BE(9 + i * 2));
+			if (values.length !== cur.count) {
+				return this._finish(new ModbusError(`Expected ${cur.count} registers, got ${values.length}`, 'EPROTO'));
+			}
+			return this._finish(null, values);
+		}
+		return this._finish(null, { address: frame.readUInt16BE(8), quantity: frame.readUInt16BE(10) });
+	}
+
+	_finish(err, result) {
+		const cur = this.current;
+		if (!cur) return;
+		clearTimeout(cur.timer);
+		this.current = null;
+		if (err) cur.reject(err); else cur.resolve(result);
+		setTimeout(() => this._next(), this.delay);
+	}
+
+	_enqueue(job) {
+		if (this.closed) return Promise.reject(new ModbusError('Client closed', 'ECLOSED'));
+		return new Promise((resolve, reject) => {
+			this.queue.push(Object.assign(job, { resolve, reject }));
+			if (!this.current) this._next();
+		});
+	}
+
+	async _next() {
+		if (this.current || this.queue.length === 0) return;
+		const job = this.queue.shift();
+		this.current = job;
+		try {
+			await this._connect();
+		} catch (err) {
+			if (this.current === job) this.current = null;
+			job.reject(err);
+			return setTimeout(() => this._next(), this.delay);
+		}
+		if (this.current !== job) return;
+		this.tid = (this.tid + 1) & 0xFFFF;
+		job.tid = this.tid;
+		const adu = Buffer.alloc(7 + job.pdu.length);
+		adu.writeUInt16BE(job.tid, 0);
+		adu.writeUInt16BE(0, 2);
+		adu.writeUInt16BE(job.pdu.length + 1, 4);
+		adu[6] = this.unitId;
+		job.pdu.copy(adu, 7);
+		job.timer = setTimeout(() => {
+			// drop the connection: late answers would otherwise desync the stream
+			if (this.socket) this.socket.destroy();
+			this._finish(new ModbusError(`Timeout at 0x${job.address.toString(16)}`, 'ETIMEDOUT'));
+		}, this.timeout);
+		job.sent = true;
+		this.socket.write(adu);
+	}
+
+	/** FC03 – resolves with an array of uint16 */
+	readHoldingRegisters(address, count) {
+		if (count < 1 || count > 125) return Promise.reject(new RangeError('count must be 1..125'));
+		const pdu = Buffer.alloc(5);
+		pdu[0] = 3;
+		pdu.writeUInt16BE(address, 1);
+		pdu.writeUInt16BE(count, 3);
+		return this._enqueue({ fc: 3, address, count, pdu });
+	}
+
+	/** FC16 – values: array of uint16 */
+	writeRegisters(address, values) {
+		if (!Array.isArray(values) || values.length < 1 || values.length > 123) {
+			return Promise.reject(new RangeError('values must contain 1..123 registers'));
+		}
+		const pdu = Buffer.alloc(6 + values.length * 2);
+		pdu[0] = 16;
+		pdu.writeUInt16BE(address, 1);
+		pdu.writeUInt16BE(values.length, 3);
+		pdu[5] = values.length * 2;
+		values.forEach((v, i) => pdu.writeUInt16BE(v & 0xFFFF, 6 + i * 2));
+		return this._enqueue({ fc: 16, address, count: values.length, pdu });
+	}
+
+	close() {
+		this.closed = true;
+		const err = new ModbusError('Client closed', 'ECLOSED');
+		this.queue.splice(0).forEach((j) => j.reject(err));
+		if (this.current) this._finish(err);
+		if (this.socket) this.socket.destroy();
+		this.socket = null;
+	}
+}
+
+module.exports = { ModbusTcpClient, ModbusError };

package/lib/mqtt.js

@@ -0,0 +1,80 @@
+'use strict';
+/**
+ * Publishes to MQTT through an existing Node-RED "mqtt-broker" config node
+ * (core node), so no own MQTT client and no additional dependency is needed.
+ *
+ * Note: register()/publish()/deregister() are used by the core MQTT nodes but
+ * are not a documented public API.
+ */
+
+const LIVE_KEYS = ['consumption', 'grid', 'modules', 'battery', 'soc', 'gridImport', 'gridExport',
+	'batteryCharge', 'batteryDischarge', 'autarky', 'selfConsumptionRate'];
+
+const bool = (v) => v === true || v === 'true';
+
+class MqttPublisher {
+	constructor(RED, node, config) {
+		this.broker = null;
+		this.node = node;
+		const id = config.mqttBroker;
+		if (!id || id === '_ADD_') return;
+		const broker = RED.nodes.getNode(id);
+		if (!broker || typeof broker.publish !== 'function' || typeof broker.register !== 'function') {
+			node.warn('MQTT broker not found or not compatible – MQTT publishing disabled');
+			return;
+		}
+		this.broker = broker;
+		this.prefix = String(config.mqttPrefix || 'alphaess').replace(/\/+$/, '');
+		this.retain = bool(config.mqttRetain);
+		this.qos = [0, 1, 2].includes(Number(config.mqttQos)) ? Number(config.mqttQos) : 0;
+		this.details = bool(config.mqttDetails);
+		// The broker updates the status of all registered users on (dis)connect.
+		// A proxy keeps the status of our node untouched.
+		this.user = { id: node.id + ':mqtt', status: () => {} };
+		broker.register(this.user);
+	}
+
+	get enabled() {
+		return !!this.broker;
+	}
+
+	publish(topic, value, retain) {
+		if (!this.broker || value === undefined || value === null) return;
+		const payload = typeof value === 'object' ? JSON.stringify(value) : String(value);
+		try {
+			this.broker.publish({
+				topic: `${this.prefix}/${topic}`,
+				payload,
+				qos: this.qos,
+				retain: retain === undefined ? this.retain : retain
+			});
+		} catch (err) {
+			this.node.debug(`MQTT publish failed: ${err.message}`);
+		}
+	}
+
+	/** publish one poll cycle; alarm is only given when it changed */
+	publishCycle(payload, alarm) {
+		if (!this.broker) return;
+		LIVE_KEYS.forEach((k) => this.publish(k, payload[k]));
+		if (payload.daily) {
+			Object.keys(payload.daily).forEach((k) => {
+				if (k !== 'day' && k !== 'since') this.publish(`daily/${k}`, payload.daily[k]);
+			});
+		}
+		this.publish('status', payload.alarms.length ? 'alarm' : 'ok');
+		if (alarm) this.publish('alarm', alarm);
+		if (this.details) Object.keys(payload.details).forEach((b) => this.publish(`details/${b}`, payload.details[b]));
+	}
+
+	close(done) {
+		if (!this.broker) return done();
+		try {
+			this.broker.deregister(this.user, done, true);
+		} catch (err) {
+			done();
+		}
+	}
+}
+
+module.exports = { MqttPublisher, LIVE_KEYS };