From 8c03d5dcd4ea7613fb91746cc392ebc4d423a5dc Mon Sep 17 00:00:00 2001
From: Marcus Davies <55892693+marcus-j-davies@users.noreply.github.com>
Date: Sun, 15 Oct 2023 08:43:06 +0100
Subject: [PATCH] V9 (#283)

* Docs and Package

* First Draft

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Guide

* Clean up

* extras

* Woah!

* Fix CMDF

* Fix scan issues

* Few fixes

* Update zwave-js.js

* Wrong API

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* Update APIChange-v9.md

* getValueTimestamp

* Update CHANGELOG.md

* Update CHANGELOG.md

* date format

* Update CHANGELOG.md

* Update package.json
---
 APIChange.md => APIChange-v4.md |   0
 APIChange-v9.md                 | 117 ++++++++++++++++++++++++++++++++
 CHANGELOG.md                    |  26 ++++++-
 package.json                    |  14 ++--
 resources/UITab/client.js       |  39 +++++------
 zwave-js/cmd-factory.js         |  64 +++++++----------
 zwave-js/zwave-device.js        |  46 +++++++++++++
 zwave-js/zwave-js.js            | 111 ++++++++++++++++++++++++++----
 8 files changed, 337 insertions(+), 80 deletions(-)
 rename APIChange.md => APIChange-v4.md (100%)
 create mode 100644 APIChange-v9.md

diff --git a/APIChange.md b/APIChange-v4.md
similarity index 100%
rename from APIChange.md
rename to APIChange-v4.md
diff --git a/APIChange-v9.md b/APIChange-v9.md
new file mode 100644
index 00000000..4aa5c7be
--- /dev/null
+++ b/APIChange-v9.md
@@ -0,0 +1,117 @@
+# New API (9.0.0) Migration Guide
+
+V9 begins the take down of the old API introduced in v4.
+
+The old APIs are now set for removal and will be removed in V10.  
+Below, I set out the changes that you will need to make - and I suggest you make these changes after updating to V9.
+
+without further ado.
+
+Every command is now designed to be a consistant format, and the  `payload` below will be the new format.  
+The reason for this change, is to make it easier for you (and me), to identify parts of the payload.
+
+Previously, setting a value using the Value API for instance, will involve sending an array of objects without any clue as to what they really are, this new format will address that.
+
+
+
+## Notes
+
+During this transition, the following APIs will be available using the new format : `DRIVER`, `ASSOCIATIONS`
+However, these will form part of the combined `CONTROLLER` API when V10 lands.
+
+The properties `responseThroughEvent` and `forceUpdate` will be supported in the new message format (at the root of `payload`)
+but support for them will be removed in V10 (please see change log)
+
+The `Node` API will be available in V10 and will house the `setName`, `setLocation` methods as well as a few new one 😃
+
+
+
+```javascript
+cmd:{
+    api: 'CONTROLLER' | 'VALUE' | 'CC' | 'NODE',  /* The API you want to use  */
+    method: string                                /* The method you are executing on this API  */
+},
+cmdProperties:{
+
+    nodeId: number,                               /* The target Node ID */
+
+    /* CC API */
+    commandClass: number,                         /* The Command class ID (CC) */
+    method: string,                               /* The CC's method you want to execute (CC) */    
+    endpoint: number,                             /* The endpoint you wish to target (CC) */
+
+    /* CC, CONTROLLER API */
+    args: any[],                                  /* The args for the command you are calling (CC, CONTROLLER) */
+
+    /* VALUE API */
+    valueId: object,                              /* The ValueID you are targeting (VALUE) */
+    setValueOptions: object,                      /* Set Value Options (VALUE) */
+
+    /* VALUE, NODE API */
+    value: any,                                   /* The Value you are providing (VALUE, NODE) */
+
+}
+```
+
+## Right!! so what do i do (we'll use the Wake Up CC for demonstration)
+```javascript
+/* This */
+let Message = {
+    payload: {
+        node: 37,
+        mode: "CCAPI",
+        class: "Wake Up",
+        method: "setInterval",
+        params: [3600]
+    }
+}
+return Message;
+
+/* Is now this */
+let Message = {
+    payload: {
+        cmd: {
+           api: 'CC',
+           method: 'invokeCCAPI'
+        },
+        cmdProperties: {
+            nodeId: 37,
+            commandClass: 0x84,
+            method: 'setInterval',
+            args: [3600]
+        }
+    }
+}
+return Message;
+```
+
+```javascript
+/* And this */
+let Message = {
+    payload: {
+        node: 5,
+        mode: "ValueAPI",
+        method: "setValue",
+        params: [<ValueID>,3600]
+    }
+}
+return Message;
+
+/* Is now this */
+let Message = {
+    payload: {
+        cmd: {
+            api: 'VALUE',
+            method: 'setValue'
+        },
+        cmdProperties: {
+            nodeId: 5,
+            valueId: <ValueID>,
+            value: 3600
+        }
+    }
+}
+return Message;
+```
+
+
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5495d5db..ded93721 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,29 @@
   # node-red-contrib-zwave-js Change Log
 
+  - 9.0.0
+
+    **Breaking Changes**
+      - The min node version is now 18
+      - If you execute certain methods your self, the following have been renamed
+        - `beginHealingNetwork` -> `beginRebuildingRoutes`
+        - `stopHealingNetwork` -> `stopRebuildingRoutes`
+        - `healNode` -> `rebuildNodeRoutes`
+
+    **New Features**
+      - Added `getValueTimestamp` to the `Value API` - args will be the single Value ID  
+        The event will be `VALUE_TIMESTAMP`
+
+    **Changes**  
+      - Bump ZWave JS to v12
+      - The `lastSeen` property will now use the Drivers internal value, which is persistant between reboots 
+
+    **Deprecations**
+      - The old message format has now been deprecated, and support will be removed in V10.
+        [PLEASE SEE MIGRATION GUIDE](/APIChange-v9.md)
+      - Support for `responseThroughEvent` will be removed in V10 (all methods will return in v10)
+      - Support for `forceUpdate` will be removed in V10 (you will be requied to manage this your self if using the CC API)
+      - Support for `getLastEvents` will be removed in V10 (the introdcution of the persistant `lastSeen` value and `getValueTimestamp` has made this somewhat bloatware)
+
   - 8.2.1
 
     **Changes**  
@@ -418,7 +442,7 @@
     - Bump Z-Wave JS to 7.12.1
 
   - 4.0.0 **Possible Breaking Changes**, **Deprecation Warnings**
-    - MAJOR API Transition : [PLEASE SEE MIGRATION GUIDE](/APIChange.md)
+    - MAJOR API Transition : [PLEASE SEE MIGRATION GUIDE](/APIChange-v4.md)
     - Added Node Firmware Update UI
     - Added Network Map UI
     - Added Association Group Managment UI
diff --git a/package.json b/package.json
index 1ef34ec8..ff96b70a 100644
--- a/package.json
+++ b/package.json
@@ -1,24 +1,24 @@
 {
 	"name": "node-red-contrib-zwave-js",
-	"version": "8.2.1",
+	"version": "9.0.0",
 	"license": "MIT",
 	"description": "The most powerful, high performing and highly polished Z-Wave node for Node-RED based on Z-Wave JS. If you want a fully featured Z-Wave framework in your Node-RED instance, you have found it.",
 	"dependencies": {
 		"limiter": "^2.1.0",
 		"lodash": "^4.17.21",
-		"winston": "^3.10.0",
-		"winston-transport": "^4.5.0",
-		"zwave-js": "^11.14.1"
+		"winston": "^3.11.0",
+		"winston-transport": "^4.6.0",
+		"zwave-js": "^12.1.1"
 	},
 	"devDependencies": {
-		"eslint": "^8.49.0",
+		"eslint": "^8.51.0",
 		"prettier": "^3.0.3"
 	},
 	"scripts": {
 		"validate": "node-red-dev validate -o validation_result.json"
 	},
 	"engines": {
-		"node": ">=14.13.0"
+		"node": ">=18.0.0"
 	},
 	"keywords": [
 		"node-red",
@@ -61,4 +61,4 @@
 		"url": "https://github.com/zwave-js/node-red-contrib-zwave-js/issues"
 	},
 	"homepage": "https://github.com/zwave-js/node-red-contrib-zwave-js#readme"
-}
\ No newline at end of file
+}
diff --git a/resources/UITab/client.js b/resources/UITab/client.js
index 2bebe1a4..1572e8e8 100644
--- a/resources/UITab/client.js
+++ b/resources/UITab/client.js
@@ -147,19 +147,19 @@ const DCs = {
 		name: 'unprovisionAllSmartStart',
 		noWait: false
 	},
-	healNode: {
+	rebuildNodeRoutes: {
 		API: 'ControllerAPI',
-		name: 'healNode',
+		name: 'rebuildNodeRoutes',
 		noWait: true
 	},
-	beginHealingNetwork: {
+	beginRebuildingRoutes: {
 		API: 'ControllerAPI',
-		name: 'beginHealingNetwork',
+		name: 'beginRebuildingRoutes',
 		noWait: false
 	},
-	stopHealingNetwork: {
+	stopRebuildingRoutes: {
 		API: 'ControllerAPI',
-		name: 'stopHealingNetwork',
+		name: 'stopRebuildingRoutes',
 		noWait: false
 	},
 	hardReset: {
@@ -1889,11 +1889,11 @@ const ZwaveJsUI = (function () {
 
 	function StartNodeHeal() {
 		ControllerCMD(
-			DCs.healNode.API,
-			DCs.healNode.name,
+			DCs.rebuildNodeRoutes.API,
+			DCs.rebuildNodeRoutes.name,
 			undefined,
 			[HoveredNode.nodeId],
-			DCs.healNode.noWait
+			DCs.rebuildNodeRoutes.noWait
 		).catch((err) => {
 			modalAlert(err.responseText || err.message, 'Could not start Node heal.');
 			throw new Error(err.responseText || err.message);
@@ -1902,11 +1902,11 @@ const ZwaveJsUI = (function () {
 
 	function StartHeal() {
 		ControllerCMD(
-			DCs.beginHealingNetwork.API,
-			DCs.beginHealingNetwork.name,
+			DCs.beginRebuildingRoutes.API,
+			DCs.beginRebuildingRoutes.name,
 			undefined,
 			undefined,
-			DCs.beginHealingNetwork.noWait
+			DCs.beginRebuildingRoutes.noWait
 		).catch((err) => {
 			modalAlert(
 				err.responseText || err.message,
@@ -1918,11 +1918,11 @@ const ZwaveJsUI = (function () {
 
 	function StopHeal() {
 		ControllerCMD(
-			DCs.stopHealingNetwork.API,
-			DCs.stopHealingNetwork.name,
+			DCs.stopRebuildingRoutes.API,
+			DCs.stopRebuildingRoutes.name,
 			undefined,
 			undefined,
-			DCs.stopHealingNetwork.noWait
+			DCs.stopRebuildingRoutes.noWait
 		).catch((err) => {
 			console.error(err);
 		});
@@ -2230,7 +2230,7 @@ const ZwaveJsUI = (function () {
 				},
 				{
 					id: 'controller-option-menu-start-heal',
-					label: 'Begin Network Heal',
+					label: 'Begin Rebuilding Routes',
 					onselect: function () {
 						IsDriverReady();
 						StartHeal();
@@ -2238,7 +2238,7 @@ const ZwaveJsUI = (function () {
 				},
 				{
 					id: 'controller-option-menu-stop-heal',
-					label: 'Stop Network Heal',
+					label: 'Stop Rebuilding Routes',
 					onselect: function () {
 						IsDriverReady();
 						StopHeal();
@@ -3179,7 +3179,7 @@ const ZwaveJsUI = (function () {
 				marginRight: '1px'
 			});
 			Heal.append('<i class="fa fa-medkit fa-lg"></i>');
-			RED.popover.tooltip(Heal, 'Heal Node');
+			RED.popover.tooltip(Heal, 'Rebuild Node Routes');
 			BA.append(Heal);
 
 			const Associations = $('<button>');
@@ -3570,7 +3570,8 @@ const ZwaveJsUI = (function () {
 
 				const Child = renderPropertyElement(Prop);
 				propertyList
-					.treeList('data')[Index].treeList.addChild({ element: Child });
+					.treeList('data')
+					[Index].treeList.addChild({ element: Child });
 
 				if (Writeable && Type !== 'any') {
 					const icon = Child.prev();
diff --git a/zwave-js/cmd-factory.js b/zwave-js/cmd-factory.js
index 41830786..501f2ee8 100644
--- a/zwave-js/cmd-factory.js
+++ b/zwave-js/cmd-factory.js
@@ -122,28 +122,18 @@ module.exports = function (RED) {
 				}
 			}
 
-			const RM = {};
-			RM.mode = 'ValueAPI';
-			RM.method = config.vapiMode;
-			RM.node = NodeID;
-			RM.params = [];
-			RM.params.push(ValueID);
-			if (config.vapiMode === 'setValue') {
-				RM.params.push(Value);
-				if (Options !== undefined) {
-					RM.params.push(Options);
+			const RM = {
+				cmd: {
+					api: 'VALUE',
+					method: config.vapiMode
+				},
+				cmdProperties: {
+					nodeId: NodeID,
+					value: Value,
+					valueId: ValueID,
+					setValueOptions: Options
 				}
-			}
-
-			if (RM.params.length < 1) {
-				delete RM['params'];
-			}
-
-			Object.keys(RM).forEach((K) => {
-				if (typeof RM[K] === 'undefined') {
-					delete RM[K];
-				}
-			});
+			};
 
 			msg.payload = RM;
 
@@ -218,23 +208,21 @@ module.exports = function (RED) {
 				}
 			}
 
-			const RM = {};
-			RM.mode = 'CCAPI';
-			RM.cc = config.cc;
-			RM.method = config.method;
-			RM.responseThroughEvent = NoEvent !== true;
-			RM.node = NodeID;
-			RM.endpoint = Endpoint;
-			RM.params = Params;
-			if (ForceUpdate !== undefined) {
-				RM.forceUpdate = ForceUpdate;
-			}
-
-			Object.keys(RM).forEach((K) => {
-				if (typeof RM[K] === 'undefined') {
-					delete RM[K];
-				}
-			});
+			const RM = {
+				cmd: {
+					api: 'CC',
+					method: 'invokeCCAPI'
+				},
+				cmdProperties: {
+					nodeId: NodeID,
+					endpoint: Endpoint,
+					commandClass: config.cc,
+					method: config.method,
+					args: Params
+				},
+				responseThroughEvent: NoEvent !== true,
+				forceUpdate: ForceUpdate
+			};
 
 			msg.payload = RM;
 
diff --git a/zwave-js/zwave-device.js b/zwave-js/zwave-device.js
index 33c33213..b375864f 100644
--- a/zwave-js/zwave-device.js
+++ b/zwave-js/zwave-device.js
@@ -155,8 +155,54 @@ module.exports = function (RED) {
 				);
 			}
 		}
+
+		const Convert = (msg) => {
+			if (msg.payload.cmd) {
+				const CMD = msg.payload.cmd;
+				const CMDProp = msg.payload.cmdProperties || {};
+				switch (CMD.api) {
+					case 'VALUE':
+						msg.payload = {
+							mode: 'ValueAPI',
+							method: CMD.method,
+							node: CMDProp.nodeId
+						};
+						msg.payload.params = [];
+
+						msg.payload.params.push(CMDProp.valueId);
+
+						if (CMD.method === 'setValue') {
+							msg.payload.params.push(CMDProp.value);
+							if (CMDProp.setValueOptions) {
+								msg.payload.params.push(CMDProp.setValueOptions);
+							}
+						}
+						break;
+
+					case 'CC':
+						msg.payload = {
+							mode: 'CCAPI',
+							cc: CMDProp.commandClass,
+							method: CMDProp.method,
+							node: CMDProp.nodeId,
+							endpoint: CMDProp.endpoint,
+							params: CMDProp.args,
+							responseThroughEvent: msg.payload.responseThroughEvent,
+							forceUpdate: msg.payload.forceUpdate
+						};
+
+						break;
+				}
+			}
+
+			return msg;
+		};
+
 		async function Input(msg, send, done) {
 			try {
+				// For my own sanity, i'll convert the new format back to old format if its being used, as this will be much easier during the transition phase
+				msg = Convert(msg);
+
 				AddIsolatedNodeID(msg);
 				switch (DeviceMode) {
 					case 'AS':
diff --git a/zwave-js/zwave-js.js b/zwave-js/zwave-js.js
index 25ceec04..e2bbf264 100644
--- a/zwave-js/zwave-js.js
+++ b/zwave-js/zwave-js.js
@@ -625,7 +625,76 @@ module.exports = function (RED) {
 
 		RedNode.on('input', Input);
 
+		const Convert = (msg) => {
+			if (msg.payload.cmd) {
+				const CMD = msg.payload.cmd;
+				const CMDProp = msg.payload.cmdProperties || {};
+				switch (CMD.api) {
+					case 'DRIVER':
+						msg.payload = {
+							mode: 'DriverAPI',
+							method: CMD.method,
+							params: CMDProp.args
+						};
+						break;
+
+					case 'ASSOCIATIONS':
+						msg.payload = {
+							mode: 'AssociationsAPI',
+							method: CMD.method,
+							params: CMDProp.args
+						};
+						break;
+
+					case 'CONTROLLER':
+						msg.payload = {
+							mode: 'ControllerAPI',
+							method: CMD.method,
+							params: CMDProp.args
+						};
+						break;
+
+					case 'VALUE':
+						msg.payload = {
+							mode: 'ValueAPI',
+							method: CMD.method,
+							node: CMDProp.nodeId
+						};
+						msg.payload.params = [];
+
+						msg.payload.params.push(CMDProp.valueId);
+
+						if (CMD.method === 'setValue') {
+							msg.payload.params.push(CMDProp.value);
+							if (CMDProp.setValueOptions) {
+								msg.payload.params.push(CMDProp.setValueOptions);
+							}
+						}
+						break;
+
+					case 'CC':
+						msg.payload = {
+							mode: 'CCAPI',
+							cc: CMDProp.commandClass,
+							method: CMDProp.method,
+							node: CMDProp.nodeId,
+							endpoint: CMDProp.endpoint,
+							params: CMDProp.args,
+							responseThroughEvent: msg.payload.responseThroughEvent,
+							forceUpdate: msg.payload.forceUpdate
+						};
+
+						break;
+				}
+			}
+
+			return msg;
+		};
+
 		async function Input(msg, send, done, internal) {
+			// For my own sanity, i'll convert the new format back to old format if its being used, as this will be much easier during the transition phase
+			msg = Convert(msg);
+
 			let Type = 'CONTROLLER';
 			if (internal !== undefined && internal) {
 				Type = 'EVENT';
@@ -1033,7 +1102,7 @@ module.exports = function (RED) {
 							isControllerNode: N.isControllerNode,
 							supportsBeaming: N.supportsBeaming,
 							keepAwake: N.keepAwake,
-							lastSeen: N.ZWNR_lastSeen || 0,
+							lastSeen: new Date(N.lastSeen).getTime(),
 							powerSource: {
 								type: N.supportsCC(CommandClasses.Battery)
 									? 'battery'
@@ -1136,7 +1205,7 @@ module.exports = function (RED) {
 					Send(undefined, 'CONTROLLER_RESET_COMPLETE', undefined, send);
 					break;
 
-				case 'healNode':
+				case 'rebuildNodeRoutes':
 					NodeCheck(Params[0]);
 					ReturnNode.id = Params[0];
 					Send(ReturnNode, 'NODE_HEAL_STARTED', undefined, send);
@@ -1146,7 +1215,9 @@ module.exports = function (RED) {
 						text: 'Node Heal Started: ' + Params[0]
 					});
 					UI.Status('Node Heal Started: ' + Params[0]);
-					const HealResponse = await Driver.controller.healNode(Params[0]);
+					const HealResponse = await Driver.controller.rebuildNodeRoutes(
+						Params[0]
+					);
 					if (HealResponse) {
 						SetFlowNodeStatus({
 							fill: 'green',
@@ -1171,8 +1242,8 @@ module.exports = function (RED) {
 					RestoreReadyStatus();
 					break;
 
-				case 'beginHealingNetwork':
-					await Driver.controller.beginHealingNetwork();
+				case 'beginRebuildingRoutes':
+					await Driver.controller.beginRebuildingRoutes();
 					Send(undefined, 'NETWORK_HEAL_STARTED', undefined, send);
 					SetFlowNodeStatus({
 						fill: 'yellow',
@@ -1182,8 +1253,8 @@ module.exports = function (RED) {
 					UI.Status('Network Heal Started.');
 					break;
 
-				case 'stopHealingNetwork':
-					await Driver.controller.stopHealingNetwork();
+				case 'stopRebuildingRoutes':
+					await Driver.controller.stopRebuildingRoutes();
 					Send(undefined, 'NETWORK_HEAL_STOPPED', undefined, send);
 					SetFlowNodeStatus({
 						fill: 'blue',
@@ -1254,6 +1325,12 @@ module.exports = function (RED) {
 			const ReturnNode = { id: ZWaveNode.id };
 
 			switch (Method) {
+				case 'getValueTimestamp':
+					if (Multicast) ThrowVirtualNodeLimit();
+					const TS = ZWaveNode.getValueTimestamp(Params[0]);
+					Send(ReturnNode, 'VALUE_TIMESTAMP', TS, send);
+					break;
+
 				case 'getDefinedValueIDs':
 					if (Multicast) ThrowVirtualNodeLimit();
 					const VIDs = ZWaveNode.getDefinedValueIDs();
@@ -1808,16 +1885,16 @@ module.exports = function (RED) {
 			let IsolatedNodeId;
 
 			if (Node !== undefined) {
-				PL.node = Node.id;
+				PL.node = Node.nodeId || Node.id;
 				IsolatedNodeId = Node.targetFlowNode || undefined;
 			}
 
 			if (Node !== undefined) {
-				const N = getNodeInfoForPayload(Node.id, 'name');
+				const N = getNodeInfoForPayload(Node.nodeId || Node.id, 'name');
 				if (N !== undefined) {
 					PL.nodeName = N;
 				}
-				const L = getNodeInfoForPayload(Node.id, 'location');
+				const L = getNodeInfoForPayload(Node.nodeId || Node.id, 'location');
 				if (L !== undefined) {
 					PL.nodeLocation = L;
 				}
@@ -1830,7 +1907,7 @@ module.exports = function (RED) {
 
 			let _Subject = '';
 			if (Node !== undefined) {
-				_Subject = '[Node: ' + Node.id + '] [' + Subject + ']';
+				_Subject = '[Node: ' + (Node.nodeId || Node.id) + '] [' + Subject + ']';
 			} else {
 				_Subject = '[' + Subject + ']';
 			}
@@ -1852,7 +1929,8 @@ module.exports = function (RED) {
 				'ALIVE',
 				'VALUE_ID_LIST',
 				'GET_VALUE_RESPONSE',
-				'GET_VALUE_METADATA_RESPONSE'
+				'GET_VALUE_METADATA_RESPONSE',
+				"VALUE_TIMESTAMP"
 			];
 
 			const TimestampSubjects = [
@@ -1864,9 +1942,12 @@ module.exports = function (RED) {
 			];
 
 			if (TimestampSubjects.includes(Subject)) {
-				Driver.controller.nodes.get(Node.id).ZWNR_lastSeen = PL.timestamp;
-				Driver.controller.nodes.get(Node.id).ZWNR_lastEvent = PL.event;
-				Driver.controller.nodes.get(Node.id).ZWNR_lastObject = PL.object;
+				Driver.controller.nodes.get(Node.nodeId || Node.id).ZWNR_lastSeen =
+					PL.timestamp;
+				Driver.controller.nodes.get(Node.nodeId || Node.id).ZWNR_lastEvent =
+					PL.event;
+				Driver.controller.nodes.get(Node.nodeId || Node.id).ZWNR_lastObject =
+					PL.object;
 			}
 
 			if (AllowedSubjectsForDNs.includes(Subject) && SendDNs) {