Starting with 0.25.X hub firmware release, the handling of encapsulation for Z-Wave messages are now delegated to the hub. This change was mainly driven from the forthcoming of Z-Wave S2 to our platform and instead of having to add additional encapsulation functionality to the DTHs, we decided that it is best to perform auto encapsulation at the hub level and remove any encapsulation added to the message in order to reduce the responsibilities of the DTHs.
There are two main changes starting in 0.25.X hub firmware release that we should discuss and the impact it will have on the DTHs.
Auto Encapsulation (Security 0, CRC-16, None) of Outgoing Z-Wave Messages
Auto encapsulation of messages is based on the properties of the device and command classes, reported by the device itself. In past, the decision to encapsulate messages (S0, CRC or None) was handled mostly by the DTHs. This new change will also mean that the Hubs with 0.25.X or later will ignore any specified encapsulation by the DTH, however you must still continue to encapsulate outgoing messages as there are hubs in the field that may not have received 0.25.X firmware yet.
What this means to developers?
- Are there specific devices or messages that may require a way to force a particular encapsulation? Let us know.
- DTHs MUST STILL continue to encapsulate outgoing messages. there are still lots of hubs and different platforms that have not received 0.25.X firmware, so the DTH must still support the encapsulation of messages that must be encapsulated.
DTHs to Receive Incoming Messages Without the Encapsulation Wrapping
Basically, starting with hubs on 0.25.X release, any messages that were received with a particular encapsulation will no longer have the indication of the wrapping the messages were received with (S0, CRC-16) when sent from the Hub to DTHs. The primary reason for this change was the forthcoming of S2 feature and having to add extra encapsulation handling to all DTHs in use.
What this means to developers?
You would have to ensure that when parsing incoming messages, the DTH uses the same command class versions for all instances where Z-Wave message is parsed. Our suggestion would be use a helper function to return the command class version mapping.
Example:
This implementation leads to MissingMethodException when receiving a command for Alarm V2 Report command if the hub is on 0.25.X hub firmware or later.
Wrong Implementation:
def zwaveEvent(physicalgraph.zwave.commands.alarmv2.AlarmReport cmd) {}
def zwaveEvent(physicalgraph.zwave.commands.securityv1.SecurityMessageEncapsulation cmd) {
def encapsulatedCommand = cmd.encapsulatedCommand([0x62: 1, 0x71: 2, 0x80: 1, 0x85: 2, 0x63: 1, 0x98: 1, 0x86: 1])
if (encapsulatedCommand) {
zwaveEvent(encapsulatedCommand)
}
}
def parse(String description) {
if (description.startsWith("Err")) {
} else {
def cmd = zwave.parse(description, [ 0x98: 1, 0x62: 1, 0x63: 1]) // Hint: Missing version for 0x71
if (cmd) {
result = zwaveEvent(cmd)
}
}
result
}
Correct Implementation:
private getCommandClassVersions() {
[0x62: 1, 0x71: 2, 0x80: 1, 0x85: 2, 0x63: 1, 0x98: 1, 0x86: 1]
}
def zwaveEvent(physicalgraph.zwave.commands.alarmv2.AlarmReport cmd) {}
def zwaveEvent(physicalgraph.zwave.commands.securityv1.SecurityMessageEncapsulation cmd) {
def encapsulatedCommand = cmd.encapsulatedCommand(commandClassVersions)
if (encapsulatedCommand) {
zwaveEvent(encapsulatedCommand)
}
}
def parse(String description) {
if (description.startsWith("Err")) {
} else {
def cmd = zwave.parse(description, commandClassVersions)
if (cmd) {
result = zwaveEvent(cmd)
}
}
result
}