SmartThings Community

Z-Wave DTHs: Changes to Encapsulation Handling Starting in 0.25.X Hub Firmware Release

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
}
5 Likes

Tagging @rboy @krlaframboise @TheSmartestHouse @Eric_Inovelli @ZebraBlinds @tgauchat @prjct92eh2 @erocm1231 @Fuzzyligic @ajpri

5 Likes

Tagging @RobinWinbourne @zcapr17 @Mike_Maxwell @CopyCat73 @doncaruana @nuttytree @Robert_Vandervoort @Kriskit @johnconstantelo

1 Like

Tagging @ClassicGOD @storageanarchy @MichaelS @mlebaugh
@cjcharles @Xu_Harrison

OK, off the top of my head, in these three posts I have tagged some people that I know have previously written popular device type handlers for Zwave devices with encapsulation features. I’m sure I have left some people out, and some of the projects may have been one offs and the authors will no longer be interested in this news, but I just wanted to try to hit some of the grandmaster zwave DTH coders in the community so the news of this change gets disseminated more quickly. :sunglasses:

Also, I included some of the manufacturer representatives that I know are active in the community.

5 Likes

Thanks @JDRoberts and great thinking on your part.

1 Like

@ethayer

This affects DTH Z-Wave Lock Reporting.

1 Like

@Kianoosh_Karami is there a pull request(s) to a standard DTH in the ST public repo we can reference for changes that might need to be made?

1 Like

Working on it as we speak, I can post that here once up and ready.

3 Likes

Also, @Jim , is there any chance of including some of these smartthings – specific platform implementations in the regular documentation?

@Kianoosh_Karami has been really helpful in providing these kinds of specifics in occasional forum posts but it would be great to see them as an appendix in the developer documentation since you aren’t going to find them in any of the third-party documentation. :sunglasses:

2 Likes

There are devices which support/report both S0 and None for certain command classes (switches, locks etc). However when using S0 they won’t work well with certain command classes, so the DTH uses non encapsulated commands when sending messages as it’s more reliable for those command classes and secure for others.
Are you saying that now with 25.x the hub will automatically start encapsulating all these messages if the device reports that it supports it? If so, I don’t think that’s a good idea. The DTH should decide the best way to communicate, that’s the job of the DTH to see what works best for each device for each command class.

1 Like

Do you have a specific example?

Some Monoprice outlets, atleast one lock, don’t recall at the top of my mind the brand / model but yes I have encountered these issues in the past and the DTH was tailored to use both types of communication specific to command classes to improve reliability.

Is there a way to force the platform to say hey don’t auto encapsulate these messages?

A. I really would a very specific case, which commands and in what scenarios

B. Not currently, I will make a ticket to enable the ability to do that

1 Like

I had worked with Duncan at the time to isolate the issues. Let me dig through my archives and PM you.

1 Like

@MichaelS took over the dths I wrote.

1 Like
4 Likes

Hi RBoy - came across this and it explains my Kwikset lock now not working when manually locking (I have it to turn off lights when locked). Is there an upcoming update/fix for the smart lock app you have?

1 Like

It’s for DTH’s (no changes required for SmartApps) and it was released 2 months ago well before the 25.x firmware was deployed:

FYI - this topic isn’t related to the Feb release. There were other changes we had incorporated for the 25.x which should fix your locking/unlocking trigger actions.

All our DTH’s are compliant with this update requirement from the get go so it shouldn’t have any impact for most devices. My conversation is Kianoosh is related to a different matter for specific devices which don’t like using secure encapsulation for a specific subset of commands.

1 Like

Thanks @JDRoberts
I’ve had a skim through my device handlers and dont think I use or reference the security/crc encapsulation of the commands. It’s been so long since I last looked at ZWave commands, it’s a bit of a distant memory, and have been so short of time recently I havent made as many improvements as I wanted to. Luckily I think Im stress free for this change on my device handlers.

2 Likes