node-red-contrib-zwave-js 6.2.0-beta.3 → 6.3.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
   # node-red-contrib-zwave-js Change Log
 
+  - 6.3.0
+
+    **Fixes**
+     - Fixed duplicated event handlers, after a new interview.
+
+    **New Features**
+     - Lock User Codes can now be optionally interviewed.  
+       Note: This will cause an increase in traffic - especially if your lock has many codes to query.
+     - Opt-in to Soft Reset USB device.  
+       This is needed for certain commands, like changing the RF.
+     - A new "UI Monitor", allowing you to capture/use the commands that are sent to the controller
+
+    **Changes**
+     - Changes to package content to reduce size (~9.0MB -> ~1.3MB)
+     - The node list is now sorted by Node ID
+     - Bump ZWJS to 8.5.1
+
   - 6.2.0 
   
     **New Features**
@@ -10,13 +27,16 @@
 
     **Changes**
      - Bump serialport package.
+     - Bump zwave-js.
      - The node status on the UI, has been updated to make use of icons, as opposed to text
+     - A Complete overhaul on Help/guide material for each node
+     - **Data Mode** has been renamed to **Network Mode** on the device node
 
     **Internal Changes**
      - Improvements to driver event sanitization routines
      - Security enhancements to the HTTP API
      - Moved all HTTP API endpoints to the ui/server.js module
-     - The **serialport** package is no longer forcibly compiled, and is left for serialport to decide  
+     - The **serialport** package is no longer forcibly compiled, and is now left for serialport to decide  
        if compilation is necessary.
 
     **Fixes**

package/README.md

@@ -7,45 +7,59 @@
 [![Node Version](https://img.shields.io/node/v/node-red-contrib-zwave-js)](https://www.npmjs.com/package/node-red-contrib-zwave-js)
 [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/zwave-js/node-red-contrib-zwave-js.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/zwave-js/node-red-contrib-zwave-js/context:javascript)
 [![Maintenance](https://img.shields.io/npms-io/maintenance-score/node-red-contrib-zwave-js)](https://www.npmjs.com/package/node-red-contrib-zwave-js)
-[![Dependencies](https://img.shields.io/david/marcus-j-davies/node-red-contrib-zwave-js)](https://www.npmjs.com/package/node-red-contrib-zwave-js)
+[![Dependencies](https://img.shields.io/librariesio/release/npm/node-red-contrib-zwave-js/latest)](https://www.npmjs.com/package/node-red-contrib-zwave-js)  
 
+The most powerful/fully integrated 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, look no further.
 
-THE most powerful Z-Wave node for node-red based on Z-Wave JS.  
-If you want a fully featured Z-Wave runtime in your node-red instance, look no further.  
-<br />  
-> ### ...node-red-contrib-zwave-js is _hands down the best zwave to node red option on the planet._  
+> ### ...node-red-contrib-zwave-js is _hands down the best Z-Wave to Node-RED option on the planet._  
 > [@CRXPorter](https://github.com/crxporter), July 2021.  
-<br />  
 
-  - 100% Javascript, so it's blazing fast and runs in the same memory space as your flows.
-  - Does not require a build of any static library
-  - Stable
-  - Supports ZWave S0 and S2 Security
-  - A Built in Node-Red User Interface tab:
-    - Device Configuration
-    - CC Value Updating
-    - Association Management
-    - Firmware Updating
-    - Network Map
-    - Network Actions (Include, Exclude, Heal etc etc)
-  - 2 Different API models, catering for both experienced and inexperienced users.
-  - Use one node for your entire network, or a node per Z-Wave device.
-  - An extremely advanced filter node, to route zwave messages around your flow(s).
-  - An extremely helpful command factory node, removing the need to learn the message format.
-  - Supports multicast to send commands to mulltiple nodes at the same time.
-  - Access to all supported CC's provided by Z-Wave JS.
+### What is it?
 
-**node-red-contrib-zwave-js** is based on  [&#x1F517;Z-Wave JS](https://zwave-js.github.io/node-zwave-js/#/).  
-Z-Wave JS is actively  maintained, fast and supports S0 and S2 secure devices.
+ - Part of the awesome [Z-Wave JS](https://github.com/zwave-js) org
+ - 100% Javascript, so its blazing fast!
+ - Does not require a build of any static library
+ - Stable
+ - The Ability to capture commands for later use.
+ - A deep integrated UI within in node red
+ - Full Z-Wave control inside Node-RED including:
+   - Device inclusion/exclusion wizard
+   - S0 and S2 security support
+   - Network mesh graph
+   - Firmware updates
+   - Associations management
+   - Filter node for handling incoming messages from your devices
+   - Factory node for simplifying the formatting of outgoing messages
+   - Multicast command support
 
-It offers a massive amount of flexibility and is packed full of features.   
-The node is straightforward to use, and removes all the complexities that you would otherwise need to deal with.
+Since `node-red-contrib-zwave-js` is based on [Z-Wave JS](https://zwave-js.github.io/node-zwave-js/#/), we have the support and active maintenance from the amazing group of developers who have built the libraries, APIs, and config files which run this contrib.
 
-![Image](./resources/Demo.png)  
+### The User Interface
 
- - [Wiki](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/getting-started)
- - [Change Log](./CHANGELOG.md)
+![Image](./resources/ZWUI.gif) 
 
+Included with the contrib is a [user interface](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/User-Interface) where Z-Wave network management is handled. The controller side of the UI is used to include/exclude devices, heal the network, update firmware, and view the network map for diagnosing problems. The device side of the UI is used to configure devices, manage associations, and provide setup help for the nodes which will be used in your flows.
 
+### The Nodes
 
+![Image](./resources/Demo.png)
 
+There are 4 node types included with this contrib ([click here](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/node-types) for full details about these nodes)
+ - `zwave-js`: this node is used to set up a connection to your USB Z-Wave controller, set security keys, and manage various advanced controller options
+ - `zwave-device`: this node is used to send and receive messages to one or more of the Z-Wave devices on your network
+ - `event-filter`: this node is used to filter and sort messages from your Z-Wave devices
+ - `cmd-factory`: this node simplifies creation of messages being sent to your Z-Wave devices
+
+### Getting Started Links
+ - [Installing](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/getting-started): system requirements and install instructions
+ - [Just Show Me How](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/First-Z-Wave-Flow-Setup): first day walkthrough
+ - [Wiki](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/getting-started): just about everything
+ - [Change Log](./CHANGELOG.md): whats changed?
+
+### Awesome People - Thanks!
+
+ - [marcus-j-davies](https://github.com/marcus-j-davies) our main developer who claims "*my software doesn't have bugs*"
+ - [AlCalzone](https://github.com/AlCalzone) for creating [ZWave-JS](https://github.com/zwave-js/node-zwave-js) that makes this possible
+ - [hufftheweevil](https://github.com/hufftheweevil) for creating the User Interface tab
+ - [CRXPorter](https://github.com/crxporter) for creating all the help material/finding this project
+ - [thk](https://github.com/thk-socal) for the relentless beta testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-zwave-js",
-  "version": "6.2.0-beta.3",
+  "version": "6.3.0",
   "license": "MIT",
   "description": "An extremely powerful, easy to use, and feature rich Z-Wave node for Node Red, based on Z-Wave JS.",
   "dependencies": {
@@ -10,10 +10,10 @@
     "serialport": "9.2.4",
     "winston": "^3.3.3",
     "winston-transport": "^4.4.0",
-    "zwave-js": "^8.4.1"
+    "zwave-js": "^8.5.1"
   },
   "devDependencies": {
-    "eslint": "^7.32.0",
+    "eslint": "^8.0.1",
     "prettier": "^2.4.1"
   },
   "engines": {

package/zwave-js/cmd-factory.html

@@ -31,9 +31,9 @@
 
 		const URL =
 			'https://zwave-js.github.io/node-zwave-js/#/api/CCs/' +
-			$('#node-input-cc').find(':selected').text().trim().replace(/ /g, '') +
+			$('#node-input-cc').val().replace(/ /g, '') +
 			'?id=' +
-			$('#node-input-method').find(':selected').text().trim().toLowerCase();
+			$('#node-input-method').val().toLowerCase();
 		var link = document.createElement('a');
 		link.href = URL;
 		link.setAttribute('target', '_blank');
@@ -91,23 +91,25 @@
 	}
 
 	function GetMethods(cb) {
-		const CC = $('#node-input-cc').find(':selected').text().trim();
-		$.getJSON('zwave-js/cfg-cclist/' + CC.replace(/ /g, '-'), (data) => {
-			$('#node-input-method').empty();
-			$('#node-input-method').append(
-				new Option('Select Method', 'Select Method')
-			);
-			data.forEach((M) => {
-				$('#node-input-method').append(new Option(M, M));
+		const CC = $('#node-input-cc').val();
+		if (CC) {
+			$.getJSON('zwave-js/cfg-cclist/' + CC.replace(/ /g, '-'), (data) => {
+				$('#node-input-method').empty();
+				$('#node-input-method').append(
+					new Option('Select Method', 'Select Method')
+				);
+				data.forEach((M) => {
+					$('#node-input-method').append(new Option(M, M));
+				});
+				if (typeof cb === 'function') {
+					cb();
+				}
 			});
-			if (typeof cb === 'function') {
-				cb();
-			}
-		});
+		}
 	}
 
 	function SortAPI(Value) {
-		const API = Value || $('#node-input-api').find(':selected').text().trim();
+		const API = Value || $('#node-input-api').val();
 		switch (API) {
 			case 'CCAPI':
 				$("[forapi='ValueAPI']").css({ display: 'none' });
@@ -124,13 +126,6 @@
 
 <script type="text/x-red" data-template-name="cmd-factory">
 
-	<p>
-	    All JSONata expressions are based on the root path of <strong>msg</strong>,
-		<br />i.e specifying <strong>payload</strong> will yield the object stored at <strong>msg.payload</strong><br /
-	</p>
-	<p>
-	    <strong>Basic Settings.</strong>
-	</p>
 	<div class="form-row">
 	    <label for="node-input-name" style="width:130px"><i class="fa fa-pencil"></i> Name</label>
 	    <input type="text" id="node-input-name" placeholder="ZWave CMD Factory">
@@ -143,10 +138,10 @@
 	    </select>
 	</div>
 	<p forapi="ValueAPI">
-	    <strong>ValueAPI Command Settings.</strong>
+	    <strong>ValueAPI Command Settings</strong>
 	</p>
 	<div class="form-row" forapi="ValueAPI">
-	    <label for="node-input-vapiMode" style="width:130px"><i class="fa fa-pencil"></i> Mode</label>
+	    <label for="node-input-vapiMode" style="width:130px"><i class="fa fa-pencil"></i> Method</label>
 		<select id="node-input-vapiMode">
 	        <option value="setValue">Set</option>
 			<option value="getValue">Get</option>
@@ -157,7 +152,7 @@
 	    <input style="width:50px" type="text" id="node-input-vapiValueId" placeholder="valueId">
 	</div>
 	<p forapi="CCAPI">
-	    <strong>Command Class.</strong>
+	    <strong>Command Class</strong>
 	</p>
 	<div class="form-row" forapi="CCAPI">
 	    <label for="node-input-cc" style="width:130px"><i class="fa fa-pencil"></i> CC</label>
@@ -170,7 +165,7 @@
 		<select style="margin-bottom:5px" id="node-input-method">
 	        <option value="Select Method">Select Method</option>
 	    </select><br />
-		<a style="margin-left:135px" onclick="GoToInfo()" href="#">View Parameter Definition</a>
+		<a style="margin-left:135px; color: blue;text-decoration: underline;" onclick="GoToInfo()" href="#">View Parameter Definition</a>
 	</div>
 	<div class="form-row" forapi="CCAPI">
 	    <label for="node-input-noEvent" style="width:130px"><i class="fa fa-pencil"></i> Await Result (Get)</label>
@@ -181,7 +176,7 @@
 	    <input style="width:50px" type="text" id="node-input-forceUpdate" placeholder="forceUpdate">
 	</div>
 	<p>
-	    <strong>Command Parameters.</strong>
+	    <strong>Command Parameters</strong>
 	</p>
 	<div class="form-row">
 	    <label for="node-input-node" style="width:130px"><i class="fa fa-pencil"></i> Node</label>
@@ -203,20 +198,51 @@
 	    <label for="node-input-vapiValue" style="width:130px"><i class="fa fa-pencil"></i> Value</label>
 	    <input style="width:50px" type="text" id="node-input-vapiValue" placeholder="payload">
 	</div>
+	<div class="form-tips" id="node-tip">
+		    All JSONata expressions are based on the root path of <code>msg</code>, i.e specifying <code>payload</code> will yield the object stored at <code>msg.payload</code>.
+		</div>
 </script>
 
-<script type="text/x-red" data-help-name="cmd-factory">
-	<p>A Command generator node.</p>
+<!-- prettier-ignore -->
+<script type="text/markdown" data-help-name="cmd-factory">
+<p>A Z-Wave command generator node.</p>
+ 
+The `cmd-factory` node is used to formulate messages which are ready to be sent to your Z-Wave device nodes. Messages output from this node should be passed directly to the Input of a `zwave-device` or `zwave-js` node. Details and examples are available on [this](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/Command-Factory) wiki page.
 
-	<p>
-	    <code>Input:</code><br />
-	    A <strong>msg</strong> object that is to be used as inputs to the command.
+<div class="form-tips" id="node-tip">
+    Fields labeled with the symbol <img src="red/images/typedInput/expr.svg" style="margin-right: 4px;height: 18px;"> must be either valid  <a href="http://jsonata.org/" target="_blank">JSONata</a> expressions or left empty if not used.
+</div>
 
-	</p>
+### Setup
 
-	<p>
-	    <code>Output:</code><br />
-	    A <strong>payload</strong> containing a valid zwave command.
+The node can formulate messages to a Z-Wave device using either [Value API](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/Value-API) or [CC API](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/CC-API). Little to no knowledge of the inner workings of Z-Wave JS are needed in order to use this node.
 
-	</p>
+Generally it is recommended to use the `CCAPI` option, as it is simpler to put together the commands.
+
+
+### Command Class (CCAPI)
+
+Please choose the `CC` which you would like to control (see the UI on your device to learn which it supports). Choose the `Method` which corresponds to the message you are wanting to send.
+
+`Await Result (Get)` Some CC **Get** type methods do not return a value via the event mechanism. Therefore, we need to wait for the value as part of the command instead of depending on an event.
+
+`Force Update` causes a poll on the property contained in this object (it must evaluate to a partial ValueID). This is needed if your target device does not acknowledge a recently updated value.
+
+### ValueAPI Command Settings (ValueAPI)
+
+Please choose the `Method` which you would like to use, either setting a value or retrieving a value.
+
+`ValueID` should evaluate to a valid Value ID. Value ID's can be viewed by double clicking a value title in the UI.
+
+### Command Parameters
+
+`Node` - this field should evaluate to an integer which will determine to which node the output message is sent. This may evaluate to `undefined` if you are sending to a device node set to `Specific Node`, `Multicast`, or `Multiple Nodes`.
+
+`Endpoint` - this field should evaluate to an integer which matches your device endpoint.
+
+`Params` (CCAPI) - this field should evaluate to an array containing the parameters for your selected `Method` under **Command Class**. Click the link "View Parameter Definition" for details on how the specific Params array should be formatted for this message.
+
+`Set Options` (ValueAPI) - this value should evaluate to an object specifying  parameters around your **Set** operation, i.e setting a duration for a brightness change being one example.
+
+`Value` (ValueAPI) - this field should evaluate to the value you are providing. It is only required for the **Set** method
 </script>

package/zwave-js/cmd-factory.js

@@ -70,23 +70,22 @@ module.exports = function (RED) {
 				Value = RED.util.evaluateJSONataExpression(EXP, msg);
 			}
 
-			if (typeof ValueID !== 'object') {
-				throw new Error(
-					'[ValueID] does not evaluate to an object. Evaluated type: ' +
-						typeof ValueID
-				);
+			if (ValueID === undefined) {
+				throw new Error('[ValueID] is missing.');
+			} else if (typeof ValueID !== 'object' || Array.isArray(ValueID)) {
+				throw new Error('[ValueID] does not evaluate to an object.');
 			}
+
 			if (Endpoint !== undefined) {
 				ValueID.endpoint = Endpoint;
 			}
 			if (config.vapiMode === 'setValue' && Value === undefined) {
 				throw new Error('[Value] is missing');
 			}
-			if (Options !== undefined && typeof Options !== 'object') {
-				throw new Error(
-					'[Set Options] do not evaluate to an object. Evaluated type: ' +
-						typeof Options
-				);
+			if (Options !== undefined) {
+				if (typeof Options !== 'object' || Array.isArray(Options)) {
+					throw new Error('[Set Options] do not evaluate to an object.');
+				}
 			}
 
 			const RM = {};
@@ -149,17 +148,16 @@ module.exports = function (RED) {
 				ForceUpdate = RED.util.evaluateJSONataExpression(EXP, msg);
 			}
 
-			if (Params !== undefined && !Array.isArray(Params)) {
-				throw new Error(
-					'[Params] do not evaluate to an array. Evaluated type: ' +
-						typeof Params
-				);
+			if (Params !== undefined) {
+				if (!Array.isArray(Params)) {
+					throw new Error('[Params] do not evaluate to an array.');
+				}
 			}
-			if (ForceUpdate !== undefined && typeof ForceUpdate !== 'object') {
-				throw new Error(
-					'[Force Update] does not evaluate to an object. Evaluated type: ' +
-						typeof ForceUpdate
-				);
+
+			if (ForceUpdate !== undefined) {
+				if (typeof ForceUpdate !== 'object' || Array.isArray(ForceUpdate)) {
+					throw new Error('[Force Update] does not evaluate to an object.');
+				}
 			}
 
 			const RM = {};

package/zwave-js/event-filter.html

@@ -258,30 +258,32 @@
 	      <input type="text" id="node-input-name" placeholder="Filter Name">
 	  </div>
 
-	  <p>
-	      Add your filter sets below.<br />
-	      each set of filters, becomes an output pin.<br /><br />
-	      A filter set can include the event(s) to be filtered, and optionally ValueID(s)
-	  </p>
-
 	  <div>
 	      <ol id="filtersets" style="min-height:450px;min-width:400px"> </ol>
 	  </div>
 </script>
 
-<script type="text/x-red" data-help-name="event-filter">
-	<p>A Z-Wave event filter.</p>
+<!-- prettier-ignore -->
+<script type="text/markdown" data-help-name="event-filter">
+<p>A Z-Wave event filter.</p>
+ 
+This node allows advanced filtration of the various value events that a node may send. It further allows filtering the type of data that was updated i.e. a Motion Event, Air Temp changes, Door Sensors, etc.
+
+The UI panel on the right can be used to provide the filter values, removing the need to write them yourself, but of course you can use manual entries if you prefer. Please visit our [event filter](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/Event-Filter-Node) wiki page for a detailed walkthrough on how to set up your filters.
+
+Essentially this node is a `switch` node with specific sorting for the values found in Z-Wave messages. The Input of this node should be from a `zwave-js` node or a `zwave-device` node.
+
+### Message Handling
+
+Inputs are unfiltered Z-Wave messages. The filter settings are used to decide if the message will be output from the node. The message will be output on the pin corresponding to the matched filter set. If there is a match, the node will stop searching for additional matches. If there is no match, the input message will stop with this node and nothing will be output.
+
+### Filter Options
 
-	<p>
-	    <code>Input:</code><br />
-	    A <strong>payload</strong> object from the controller or device-node to be processed.<br />
+**Name** - is a name for your filter. The output pin will match this name, and will be included in the output as `msg.filter.name`.
 
-	</p>
+**ValueIDs** - can include zero or more Value IDs for this filter set. Value IDs may be added using the UI or manually. See our [event filter](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/Event-Filter-Node) wiki page for more details.
 
-	<p>
-	    <code>Output:</code><br />
-	    A <strong>payload</strong> containing  the event if it had a matching rule.<br />
-	    A <strong>filter</strong> object will also be provided, that denotes the matched rule.
+**Strict** - if checked it will require the `Endpoint` property of the Input message to match the selected ValueIDs.
 
-	</p>
+**Events** - the four event types which may be output from a Z-Wave Device. At least one must be selected for any message to be output. See details about these events on [this](https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/Payload-Messaging-Format) wiki page.
 </script>