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

package/examples/alphaess-modbus-example.json

@@ -0,0 +1,420 @@
+[
+  {
+    "id": "tab1",
+    "type": "tab",
+    "label": "AlphaESS Modbus",
+    "disabled": false,
+    "info": "Example for @impact0815/node-red-contrib-alphaess-modbus. Set the IP address in the connection config. Write commands only work when \"Allow write access\" is enabled – use at your own risk."
+  },
+  {
+    "id": "cfg1",
+    "type": "alphaess-modbus-config",
+    "name": "AlphaESS",
+    "host": "192.168.1.100",
+    "port": 502,
+    "unitId": 85,
+    "timeout": 2000,
+    "delay": 20
+  },
+  {
+    "id": "i1",
+    "type": "inject",
+    "z": "tab1",
+    "name": "read now",
+    "props": [
+      {
+        "p": "topic",
+        "vt": "str"
+      },
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "read",
+    "payload": "",
+    "payloadType": "date",
+    "x": 190,
+    "y": 60,
+    "wires": [
+      [
+        "node1"
+      ]
+    ]
+  },
+  {
+    "id": "i2",
+    "type": "inject",
+    "z": "tab1",
+    "name": "read device info",
+    "props": [
+      {
+        "p": "topic",
+        "vt": "str"
+      },
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "readInfo",
+    "payload": "",
+    "payloadType": "date",
+    "x": 190,
+    "y": 100,
+    "wires": [
+      [
+        "node1"
+      ]
+    ]
+  },
+  {
+    "id": "i3",
+    "type": "inject",
+    "z": "tab1",
+    "name": "read raw 0x0850 (SOC scale check)",
+    "props": [
+      {
+        "p": "topic",
+        "vt": "str"
+      },
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "readRaw",
+    "payload": "{\"address\":2128,\"count\":1}",
+    "payloadType": "json",
+    "x": 190,
+    "y": 140,
+    "wires": [
+      [
+        "node1"
+      ]
+    ]
+  },
+  {
+    "id": "c1",
+    "type": "comment",
+    "z": "tab1",
+    "name": "Control – requires \"Allow write access\", use at your own risk",
+    "info": "",
+    "x": 260,
+    "y": 200,
+    "wires": []
+  },
+  {
+    "id": "i4",
+    "type": "inject",
+    "z": "tab1",
+    "name": "charge 3 kW to 90 % for 15 min",
+    "props": [
+      {
+        "p": "topic",
+        "vt": "str"
+      },
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "dispatch",
+    "payload": "{\"power\":-3000,\"soc\":90,\"duration\":900,\"mode\":2}",
+    "payloadType": "json",
+    "x": 190,
+    "y": 240,
+    "wires": [
+      [
+        "node1"
+      ]
+    ]
+  },
+  {
+    "id": "i5",
+    "type": "inject",
+    "z": "tab1",
+    "name": "discharge 2 kW for 10 min",
+    "props": [
+      {
+        "p": "topic",
+        "vt": "str"
+      },
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "dispatch",
+    "payload": "{\"power\":2000,\"soc\":20,\"duration\":600,\"mode\":2}",
+    "payloadType": "json",
+    "x": 190,
+    "y": 280,
+    "wires": [
+      [
+        "node1"
+      ]
+    ]
+  },
+  {
+    "id": "i6",
+    "type": "inject",
+    "z": "tab1",
+    "name": "stop dispatch",
+    "props": [
+      {
+        "p": "topic",
+        "vt": "str"
+      },
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "dispatchStop",
+    "payload": "",
+    "payloadType": "date",
+    "x": 190,
+    "y": 320,
+    "wires": [
+      [
+        "node1"
+      ]
+    ]
+  },
+  {
+    "id": "i7",
+    "type": "inject",
+    "z": "tab1",
+    "name": "feed-in limit 70 %",
+    "props": [
+      {
+        "p": "topic",
+        "vt": "str"
+      },
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "feedIn",
+    "payload": "70",
+    "payloadType": "num",
+    "x": 190,
+    "y": 360,
+    "wires": [
+      [
+        "node1"
+      ]
+    ]
+  },
+  {
+    "id": "i8",
+    "type": "inject",
+    "z": "tab1",
+    "name": "night charge 01:00-05:00",
+    "props": [
+      {
+        "p": "topic",
+        "vt": "str"
+      },
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "timePeriod",
+    "payload": "{\"flag\":1,\"chargeCutSoc\":90,\"charge1\":{\"start\":\"01:00\",\"stop\":\"05:00\"}}",
+    "payloadType": "json",
+    "x": 190,
+    "y": 400,
+    "wires": [
+      [
+        "node1"
+      ]
+    ]
+  },
+  {
+    "id": "i9",
+    "type": "inject",
+    "z": "tab1",
+    "name": "UPS reserve 20 %",
+    "props": [
+      {
+        "p": "topic",
+        "vt": "str"
+      },
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "timePeriod",
+    "payload": "{\"upsReserveSoc\":20}",
+    "payloadType": "json",
+    "x": 190,
+    "y": 440,
+    "wires": [
+      [
+        "node1"
+      ]
+    ]
+  },
+  {
+    "id": "node1",
+    "type": "alphaess-modbus",
+    "z": "tab1",
+    "name": "",
+    "server": "cfg1",
+    "interval": 15,
+    "slowInterval": 300,
+    "staleAfter": 180,
+    "topic": "alphaess/modbus",
+    "platform": "EMS3.x",
+    "block_grid": true,
+    "block_pvMeter": false,
+    "block_battery": true,
+    "block_inverter": true,
+    "block_systemRun": true,
+    "block_systemConfig": true,
+    "block_timePeriod": true,
+    "block_dispatch": true,
+    "block_info": true,
+    "includePvMeter": false,
+    "contextStore": "",
+    "mqttBroker": "",
+    "mqttPrefix": "alphaess",
+    "mqttQos": "0",
+    "mqttRetain": false,
+    "mqttDetails": false,
+    "allowWrite": false,
+    "maxPower": "5000",
+    "writeInterval": 10,
+    "socScale": 0.1,
+    "x": 520,
+    "y": 240,
+    "wires": [
+      [
+        "dbg1",
+        "ch1"
+      ],
+      [
+        "dbg2"
+      ],
+      [
+        "dbg4"
+      ]
+    ]
+  },
+  {
+    "id": "dbg1",
+    "type": "debug",
+    "z": "tab1",
+    "name": "data",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 750,
+    "y": 180,
+    "wires": []
+  },
+  {
+    "id": "ch1",
+    "type": "change",
+    "z": "tab1",
+    "name": "daily consumption",
+    "rules": [
+      {
+        "t": "set",
+        "p": "payload",
+        "pt": "msg",
+        "to": "payload.daily.consumption",
+        "tot": "msg"
+      }
+    ],
+    "x": 770,
+    "y": 220,
+    "wires": [
+      [
+        "dbg3"
+      ]
+    ]
+  },
+  {
+    "id": "dbg3",
+    "type": "debug",
+    "z": "tab1",
+    "name": "kWh today",
+    "active": false,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": true,
+    "complete": "payload",
+    "targetType": "msg",
+    "statusVal": "payload",
+    "statusType": "auto",
+    "x": 970,
+    "y": 220,
+    "wires": []
+  },
+  {
+    "id": "dbg2",
+    "type": "debug",
+    "z": "tab1",
+    "name": "alarm",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 750,
+    "y": 260,
+    "wires": []
+  },
+  {
+    "id": "dbg4",
+    "type": "debug",
+    "z": "tab1",
+    "name": "command response",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "true",
+    "targetType": "full",
+    "x": 770,
+    "y": 300,
+    "wires": []
+  }
+]

package/lib/commands.js

@@ -0,0 +1,145 @@
+'use strict';
+/**
+ * Encoders for the whitelisted writable AlphaESS registers.
+ * Every encoder returns { address, values } for an FC16 write.
+ * Deliberately NOT supported: safety test (0x1000+), reset/ATE (0x1100+),
+ * CT calibration (0x11B9+), network/Modbus settings, battery MOS control,
+ * dispatch test modes (BurnIn, OSW modes, aging parameters 0x0889/0x088A).
+ */
+
+const DISPATCH_OFFSET = 32000;
+
+/** dispatch modes that may be written (Note 7 / Note 29); test and off-grid modes are excluded */
+const DISPATCH_WRITE_MODES = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 19];
+
+function num(v, name) {
+	const n = Number(v);
+	if (v === null || v === '' || !Number.isFinite(n)) throw new TypeError(`${name} must be a number`);
+	return n;
+}
+
+function clamp(v, min, max, name) {
+	if (v < min || v > max) throw new RangeError(`${name} must be between ${min} and ${max} (got ${v})`);
+	return v;
+}
+
+const split32 = (v) => { const u = v >>> 0; return [(u >>> 16) & 0xFFFF, u & 0xFFFF]; };
+
+/**
+ * Dispatch (0x0880..0x0888)
+ * @param {object} p
+ * @param {number} p.power           W, + = discharge, - = charge (same sign as battery power)
+ * @param {number} [p.mode=2]        Note 7 (2 = State of Charge control)
+ * @param {number} [p.soc]           target SOC in %, default 100 when charging, 10 when discharging
+ * @param {number} [p.duration=300]  seconds
+ * @param {number} [p.reactivePower=0]
+ * @param {number} [p.maxPower]      optional safety limit in W
+ */
+function encodeDispatch(p) {
+	p = p || {};
+	const power = Math.round(num(p.power, 'power'));
+	const limit = p.maxPower !== undefined ? num(p.maxPower, 'maxPower') : DISPATCH_OFFSET - 1;
+	clamp(Math.abs(power), 0, limit, 'power');
+	const reactive = Math.round(num(p.reactivePower === undefined ? 0 : p.reactivePower, 'reactivePower'));
+	clamp(Math.abs(reactive), 0, DISPATCH_OFFSET - 1, 'reactivePower');
+	const mode = Math.round(num(p.mode === undefined ? 2 : p.mode, 'mode'));
+	if (!DISPATCH_WRITE_MODES.includes(mode)) {
+		throw new RangeError(`mode must be one of ${DISPATCH_WRITE_MODES.join(', ')} (got ${mode})`);
+	}
+	const soc = num(p.soc === undefined ? (power < 0 ? 100 : 10) : p.soc, 'soc');
+	clamp(soc, 0, 100, 'soc');
+	const duration = Math.round(num(p.duration === undefined ? 300 : p.duration, 'duration'));
+	clamp(duration, 1, 0xFFFFFFFF, 'duration');
+	return {
+		address: 0x0880,
+		values: [1, ...split32(DISPATCH_OFFSET + power), ...split32(DISPATCH_OFFSET + reactive),
+			mode, Math.round(soc / 0.4), ...split32(duration)]
+	};
+}
+
+function encodeDispatchStop() {
+	return { address: 0x0880, values: [0, ...split32(DISPATCH_OFFSET), ...split32(DISPATCH_OFFSET), 0, 0, 0, 0] };
+}
+
+/** Max feed into grid in percent (0x0800) */
+function encodeFeedIn(percent) {
+	const v = Math.round(num(percent, 'percent'));
+	clamp(v, 0, 100, 'percent');
+	return { address: 0x0800, values: [v] };
+}
+
+function parseHm(s, name) {
+	const m = /^(\d{1,2}):(\d{2})$/.exec(String(s));
+	if (!m) throw new TypeError(`${name} must be "HH:MM"`);
+	const h = Number(m[1]), min = Number(m[2]);
+	clamp(h, 0, 23, name + ' hour');
+	clamp(min, 0, 59, name + ' minute');
+	return [h, min];
+}
+
+/**
+ * Time period control (0x084F..0x0861) – read-modify-write.
+ * @param {number[]} current  19 raw registers as read from 0x084F
+ * @param {object} p  { flag, upsReserveSoc, chargeCutSoc, charge1:{start,stop}, charge2, discharge1, discharge2 }
+ * @param {number} [socScale=0.1]  %/bit according to the documentation
+ */
+function encodeTimePeriod(current, p, socScale) {
+	if (!Array.isArray(current) || current.length !== 19) throw new TypeError('current must contain 19 registers');
+	const scale = socScale || 0.1;
+	const v = current.slice();
+	const idx = (a) => a - 0x084F;
+	p = p || {};
+	if (p.flag !== undefined) v[idx(0x084F)] = clamp(Math.round(num(p.flag, 'flag')), 0, 3, 'flag');
+	if (p.upsReserveSoc !== undefined) {
+		v[idx(0x0850)] = Math.round(clamp(num(p.upsReserveSoc, 'upsReserveSoc'), 0, 100, 'upsReserveSoc') / scale);
+	}
+	if (p.chargeCutSoc !== undefined) {
+		v[idx(0x0855)] = Math.round(clamp(num(p.chargeCutSoc, 'chargeCutSoc'), 0, 100, 'chargeCutSoc') / scale);
+	}
+	// [hour start, hour stop, minute start, minute stop]
+	const slots = {
+		discharge1: [0x0851, 0x0852, 0x085A, 0x085B],
+		discharge2: [0x0853, 0x0854, 0x085C, 0x085D],
+		charge1: [0x0856, 0x0857, 0x085E, 0x085F],
+		charge2: [0x0858, 0x0859, 0x0860, 0x0861]
+	};
+	Object.keys(slots).forEach((k) => {
+		if (!p[k]) return;
+		const a = slots[k];
+		if (p[k].start !== undefined) { const [h, m] = parseHm(p[k].start, k + '.start'); v[idx(a[0])] = h; v[idx(a[2])] = m; }
+		if (p[k].stop !== undefined) { const [h, m] = parseHm(p[k].stop, k + '.stop'); v[idx(a[1])] = h; v[idx(a[3])] = m; }
+	});
+	return { address: 0x084F, values: v };
+}
+
+/**
+ * Compares the current register values with the new ones and returns one
+ * FC16 frame per contiguous run of changed registers. Unchanged registers are
+ * never written. An empty array means: nothing to write.
+ * @param {number} address  address of current[0] / next[0]
+ * @param {number[]} current
+ * @param {number[]} next
+ */
+function diffFrames(address, current, next) {
+	if (!Array.isArray(current) || !Array.isArray(next) || current.length !== next.length) {
+		throw new TypeError('current and next must be arrays of the same length');
+	}
+	const frames = [];
+	let run = null;
+	for (let i = 0; i < next.length; i++) {
+		if ((current[i] & 0xFFFF) === (next[i] & 0xFFFF)) {
+			run = null;
+			continue;
+		}
+		if (!run) {
+			run = { address: address + i, values: [] };
+			frames.push(run);
+		}
+		run.values.push(next[i] & 0xFFFF);
+	}
+	return frames;
+}
+
+module.exports = {
+	encodeDispatch, encodeDispatchStop, encodeFeedIn, encodeTimePeriod, diffFrames, DISPATCH_OFFSET, DISPATCH_WRITE_MODES
+};

package/lib/context-store.js

@@ -0,0 +1,30 @@
+'use strict';
+/**
+ * Checks whether a context store name is configured in Node-RED's settings.js.
+ * Node-RED silently falls back to the default store (usually memory) for an
+ * unknown store name, so a typo or a missing contextStorage entry would make
+ * the daily values non-persistent without any visible error.
+ *
+ * @param {string} name             store name selected in the node ('' = default)
+ * @param {object} contextStorage   RED.settings.contextStorage (may be undefined)
+ * @returns {boolean}
+ */
+function isStoreConfigured(name, contextStorage) {
+	if (!name || name === 'default') return true;
+	if (!contextStorage || typeof contextStorage !== 'object') {
+		// without contextStorage Node-RED only provides the in-memory store
+		return name === 'memory';
+	}
+	return Object.prototype.hasOwnProperty.call(contextStorage, name);
+}
+
+/** reads RED.settings.contextStorage without failing on older/stub runtimes */
+function getContextStorage(RED) {
+	try {
+		return RED.settings ? RED.settings.contextStorage : undefined;
+	} catch (err) {
+		return undefined;
+	}
+}
+
+module.exports = { isStoreConfigured, getContextStorage };