Merge pull request #52 from zwave-js/dev

Dev

README.md

@@ -1,8 +1,7 @@
 ![Image](./ReadMe.png)  
 
 # node-red-contrib-zwave-js
-An extremely easy to use, zero dependency and feature rich Z-Wave node for Node Red, based on Z-Wave JS.
-
+An extremely easy to use, zero dependency and feature rich Z-Wave node for Node Red, based on Z-Wave JS.  
 The implementation is 100% javascript. it is therefore:  
   - Very fast
   - Does not require a build of any static library
@@ -57,22 +56,21 @@ You can address any zwave device, and recieve updates from them, using this node
 **ZWave Device**:  
 Works in conjunction with the Controller Node above, but represents a single zwave device.  
 Multiple copies of this node, can be used across different flows.  
-The Controller Node its self, can be used on its own if you so wish, but only 1 copy can be deployed.  
 ![Image](./FilterNode.PNG)  
 
-
 ## Usage Modes
-node-red-contrib-zwave-js, is split into 3 different usage modes.
+**node-red-contrib-zwave-js**, is split into 3 different usage modes.  
+The first 2 of these modes, is probably what you're intersted in.  
+Each have there own pros and cons.  
 
 [🔗Managed](./managed.md) (Z-Wave JS Command Classes API)  
-If you're wanting to get up and running quickly, or not familar with Z-Wave JS, then this is for you.
+This mode is quick to get up and running, and is a good starting point.
 
 [🔗Unmanaged](./unmanaged.md) (Z-Wave JS Value API)  
-If you're familar with Z-Wave JS, or a more hardened user, with various z-wave stack implementations, then this may be more usefull.  
+This mode requires a little more understanding, but is preferred by the pros.
 
 [🔗GUI](./GUI.md)   
 This mode comes as a node-red UI. It's more for managing your network, but can alter certain values.
-just open up the UI tab (on the right)
 
 Whatever your poison, the node will inject the following events, into your flow.
 
@@ -83,9 +81,11 @@ Whatever your poison, the node will inject the following events, into your flow.
 | NODE_NAME_SET               | The ID of the affected node         |                                 | Node name was set                 |
 | NODE_LOCATION_SET           | The ID of the affected node         |                                 | Node location was set             |
 | INCLUSION_STARTED           | "Controller"                        | Bool : Secure Include           | Include Mode Started              |
-| INCLUSION_STOPPED           | "Controller"                        |                                 | include Mode Stopped              |
+| INCLUSION_STOPPED           | "Controller"                        |                                 | Include Mode Stopped              |
+| INCLUSION_FAILED            | "Controller"                        |                                 | Include Failed                    |
 | EXCLUSION_STARTED           | "Controller"                        |                                 | Exclude Mode Started              |
 | EXCLUSION_STOPPED           | "Controller"                        |                                 | Exclude Mode Stopped              |
+| EXCLUSION_FAILED            | "Controller"                        |                                 | Exclude Failed                    |
 | NETWORK_HEAL_DONE           | "Controller"                        |                                 | Done Healing Network              |
 | NETWORK_HEAL_STARTED        | "Controller"                        |                                 | Started Healing Network           |
 | NETWORK_HEAL_STOPPED        | "Controller"                        |                                 | Stopped Healing Network           |
@@ -230,6 +230,14 @@ return Message
 
 ## Version History  
 
+  - 3.3.1
+    - Added an optional **forceUpdate** object for **Managed** mode usage. [#51](https://github.com/zwave-js/node-red-contrib-zwave-js/issues/51)  
+    - Added the realtime status of the controller to the Node status text. [#47](https://github.com/zwave-js/node-red-contrib-zwave-js/issues/47)  
+    - Z-Wave Node Name and Location are now stored on the target device (if supported)
+    - Improved Controller status events to further describe the order
+    - Updated the descriptions between Managed and Unmanaged Modes
+
+
   - 3.3.0 **Deprecation Warnings**
     - Bump Z-Wave JS
     - Added new Association management methods via a new **Associations** class

managed.md

@@ -1,12 +1,11 @@
-# Managed Usage.  
-
-First, lets get out the way, what Managed mode is.  
-Managed mode is where the node-red plugin it's self does a lot of the heavy lifting. Locating the correct command class, correct node, its endpoint, so on and so forth.  
-Underneath it all, this method uses the Z-Wave JS Command Classes API  
-
-Managed mode, allows easy accesss, the downside with Managed mode, is that command class support needs to be 'Bridged',  
-so that the command classes, can be used in an easy way.  
+# Managed Mode.  
 
+ - Uses the Z-Wave JS Command Classes API
+ - Does not verify that any Set commands have been confirmed by your device,  
+   its upto the device to send a value update (specifications suggest they should).
+ - Command Class support is specifically developed (listed below)
+ - The Node Red plugin its self, is doing a lot of the heavy lifting
+
 Some CCs require a JSON Object, which are documented at the bottom.  
 For those CCs that require an Enum value however, you can get all the valid Enums, by sending the following message:  
 ```javascript
@@ -142,6 +141,29 @@ Let Message = {
 return Message
 ```
 
+## Forcing Updates
+If you prefer Managed Mode, but have devices (or endpoints), that do not report back updated values,
+you can enforce an update by suppplying a **forceUpdate** object, and providing  
+a **property** and optionally **propertyKey** - both of which are avalable in VALUE_UPDATED events.  
+
+This will cause extra traffic in your network, so only use this if needed.
+
+```javascript
+let Message = {
+    payload: {
+        node: 12,
+        class: "BinarySwitch",
+        operation: "Set",
+        endpoint: 2,
+        forceUpdate: {
+          property: "currentValue"
+        },
+        params: [true]
+    }
+}
+return Message
+```
+
 ## Deprecated Association and AssociationGroupInfo
 These class' and operations will be removed in a future release  
 Please see the [🔗Associations](./README.md#controllerdriver-and-association-based-operations) class of operations:  

package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-zwave-js",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "license": "MIT",
   "description": "An extremely easy to use, zero dependency and feature rich Z-Wave node for Node Red, based on Z-Wave JS.",
   "dependencies": {

unmanaged.md

@@ -1,11 +1,9 @@
-# Unmanaged Usage.  
+# Unmanaged Mode.  
 
-Unmanaged usage, is more involved, and generally requires a little more understanding and poses certain limits on what can be done.  
-However, the reward here, is that Command Class support is only limited by ZWave-JS.  
-
-The difference with this approach, is that you supply a [🔗ValueID](https://zwave-js.github.io/node-zwave-js/#/api/valueid)  
-The ValueID interface uniquely identifies to which CC, endpoint and property a value belongs to.  
-These methods directly interact with the Z-Wave JS Value API.  
+ - Uses the Z-Wave JS Value API
+ - Ensures any Set Command is followed up with an Updated value event
+ - Command class support is only limited by whats supported in Z-Wave JS
+ - Limited in what can be done, ex: No transition times. Its mainly for primitive types.
 
 There is only 4 commands to use here.
 
@@ -35,7 +33,7 @@ return Message
 ```javascript
 /* Set a value */
 /* NOTE : setValue only supports providing 2 params, the ValueID its self, and the value to set. */
-/*        ValueID will be one of the ValueIDs returned from GetDefinedValueIDs                   */
+/*        ValueID will be one of the obejcts (not actual IDs) returned from GetDefinedValueIDs                   */
 
 let Message = {
     payload: {

zwave-js/FunctionMaps.json

@@ -76,7 +76,7 @@
                 "MapsToFunc": "getSupportedKeys",
                 "ParamsRequired": 0,
                 "ParamsOptional": 0,
-                "ResponseThroughEvent": false
+                "NoEvent": true
             }
         }
     },
@@ -168,7 +168,7 @@
                 "MapsToFunc": "getGroup",
                 "ParamsRequired": 1,
                 "ParamsOptional": 0,
-                "ResponseThroughEvent": false
+                "NoEvent": true
             },
             "AddNodes": {
                 "MapsToFunc": "addNodeIds",
@@ -189,7 +189,7 @@
                 "MapsToFunc": "getGroupCount",
                 "ParamsRequired": 0,
                 "ParamsOptional": 0,
-                "ResponseThroughEvent": false
+                "NoEvent": true
             }
         }
     },
@@ -200,7 +200,7 @@
                 "MapsToFunc": "getGroupName",
                 "ParamsRequired": 1,
                 "ParamsOptional": 0,
-                "ResponseThroughEvent": false
+                "NoEvent": true
             }
         }
     },

zwave-js/ui/client.js

@@ -283,7 +283,11 @@ let ZwaveJsUI = (function () {
           class: 'Controller',
           operation: 'InterviewNode',
           params: [+selectedNode]
-        }).catch(err => alert(err.responseText))
+        }).catch((err) => {
+          if(err.status !== 504){
+            alert(err.responseText)
+          }
+        })
       })
       .appendTo(optInterview)
     $('<span id="zwave-js-status-box-interview">')