-
Notifications
You must be signed in to change notification settings - Fork 1
sendReceiveTools
sendReceiveTools is a collection of driver functions for sending to and receiving from Zwave devices using S2 and security.
This is a simple library implementing security and S2 support. The following table briefly describes the functional interfaces. A longer explanation follows.
| Description | This library implements Z-wave Send functions including both security and S2 supervision. |
|---|---|
| zwaveEvent handling | void parse(String description) void zwaveEvent(hubitat.zwave.commands.securityv1.SecurityMessageEncapsulation cmd) void zwaveEvent(hubitat.zwave.commands.multichannelv4.MultiChannelCmdEncap cmd) void zwaveEvent(hubitat.zwave.Command cmd, ep = null ) void zwaveEvent(hubitat.zwave.commands.supervisionv1.SupervisionGet cmd, ep = null ) void zwaveEvent(hubitat.zwave.commands.supervisionv1.SupervisionReport cmd, ep = null ) |
| User Functions | The Main function to send and receive is: void advancedZwaveSend(hubitat.zwave.Command cmd, ep = null ) |
| Secondary functions void basicZwaveSend(hubitat.zwave.Command cmd, ep = null ) // A simple Z-wave send void sendUnsupervised(hubitat.zwave.Command cmd, ep = null ) // Same as basicZwaveSend void sendSupervised(hubitat.zwave.Command cmd, ep = null ) // Send a command using S2 supervision if the device supports S2. |
|
| Customizations | The operation of these tools can be customized by defining the following fucntions in your driver code. This is explained below. (optional) Map getUserParseMap() (optional) Integer getS2MaxRetries() { return 3} // Max # of S2 retries (optional) Integer getS2RetryPeriod() { return 1500 } // Time between S2 retries, in Milliseconds (optional) List<Map> getUserPoorSupervisionSuppportMap() (optional) List<Map> getUserSupervisionBrokenMap() (optional) List<String> getUserDefinedSupervisionList() |
| S2 Support | Yes. On both Send and Receive. |
| Dependencies | None. |
| Sleep / Wake Support | None. |
void advancedZwaveSend(hubitat.zwave.Command cmd, ep = null )
The advancedZwaveSend function is your primary function for sending to Z-Wave devices. This function will automatically determine whether a particular command should or should not be supervised and will then call the appropriate Secondary Sending Function (see section 2.1, below).
The command operates by doing a simple check to see of the command being sent is on a list of commands that are allowed to be supervised or not. The appropriate function is then called.
At present, the list of commands that I supervise are:
List<String> superviseThese = [ "2501", // Switch Binary
"2601", "2604", "2605", // Switch MultiLevel
"7601", // Lock V1
"3305", // Switch Color Set
]
Please post to github "issues" if you think there are others that should be added. Your driver can customize this list by defining the List getUserDefinedSupervisionList() function described below.
This tool set implements two secondary functions for sending commands to Z-Wave devices. In general, you should not need to use these functions unless you want to override the automatic selection of advancedZwaveSend (that should be very rare!).
void sendSupervised(hubitat.zwave.Command cmd, ep = null )
sendSupervised() is a simple function for sending Z-Wave commands to a Z-wave device using both S2 security and S2 supervision if they are supported by the device.
- Use sendSupervised() if you are requesting that a device do something. For example, turning a switch on/off or adjusting a dimmer, locking/unlocking a lock.
- Do NOT use sendSupervised if you are requesting that the device report something. So, for example, a "get" should not be supervised.
- IF you use sendSupervised() for a "reporting" type of function, nothing will happen and you will typically not get an error!
- The rules for when to use supervision are set out in the Z-wave standards, but they are confusing!
void sendUnsupervised(hubitat.zwave.Command cmd, ep = null )
void basicZwaveSend(hubitat.zwave.Command cmd, ep = null )
The sendUnsupervised(cmd, ep) function is a simple function for sending Z-wave commands to a device without using S2 supervision. It will, however, still use security if supported by the device.
Note that SendUnsupervised and basiZwaveSend are functionally identical.
Integer getS2MaxRetries() { return 3}
Integer getS2RetryPeriod() { return 1500 }
By default, S2 devices are retried 3 times with attempts spaced at 1500 mSeconds.
You can override this number of tries by defining the getS2MaxRetries function in your code. The library enforces a minimum number of 1 and a maximum of 5 attempts.
Similarly, you can override the spacing between attempts by defining getS2RetryPeriod. This should return the time between retries in milliseconds. The library enforces a minimum of 500 mSeconds and a maximum of 5000 mSeconds
I have found that some devices just don't implement S2 correctly. There are two variations of this issue: 1) Its completely messed up; or 2) S2 seems to work, but an incorrect status code gets returned from the device. You can customize the driver to address these issues by defining getUsersupervisionBrokenMap or getUserPoorsupervisionSupportMap as explained below.
List<Map> getUserSupervisionBrokenMap()
{
[
[ manufacturer:798, deviceType:14, deviceId: 1 ], // Inovelli LZW36 firmware 1.36 supervision is broken!
]
}
getUserSupervisionBrokenMap() returns a list of maps as in the example, above. If your device is on this list, the code will not attempt supervision for a command (even if you send it with sendSupervised()
List<Map> getUserPoorSupervisionSuppportMap()
{
[
[ manufacturer:12, deviceType:17479, deviceId: 12340 ], // HomeSeer WD100 S2 is buggy!
[ manufacturer:12, deviceType:17479, deviceId: 12342 ], // HomeSeer WD200 is buggy!
]
}
getUserPoorSupervisionSuppportMap() returns a list of maps as in the example, above. If your device is on this list, the code will send usingsupervision for a command (if you are using sendSupervised), but will ignore the return Supervision code and always treat the command as if it had succeeded.
List<String> getUserDefinedSupervisionList() { [ "2501", "2601"]}
Returns a List of hex code strings identifying commands that should be supervised. This is added to the "built-in" list in the library. This is in case the library is missing something.
This code handles endpoints.
To make using supervision a bit easier, I plan to implement a function advancedZwaveSend() which will automatically choose to supervise or not.
Update: there's now a function void advancedZwaveSend(hubitat.zwave.Command cmd, Integer ep = null ) which does this. It looks at the cmd.CMD field to determine whether the command should be supervised or not.