Developer Documentation for Device handlers

Hi all,

I am currently trying to implement a device handler and looking for documentation on the subject. I am using the classic documentation found here through groovy. The last time this documentation was updated was July 07 2017, it still seems to work as the current documentation found on the new documentation website links to a github repo which points back to the classic documentation.

I am trying to implment a z-wave device handler and came across this z-wave command class reference. This lists the input types to the commands but there are no valid values/explanations of what they actually do an it is very vague. For example I am looking into the Meter Command Class Ver3, for the meter report command where can I find an explanation on the values associated with this command for example meterType, precision, scale, scale2 ... etc there must be something where it is explained what these actually mean.

Two different questions. :sunglasses:

  1. For now, the SmartThings platform is still using the old groovy DTHs for ā€œhub-connected devices,ā€ which means zwave and Zigbee. (ā€œConnected devicesā€ means cloud to cloud integration. That method is available now and thereā€™s quite a bit of documentation on it, but it doesnā€™t apply to Z wave devices.)

Eventually that will change and a new method for hub-connected devices will be available, but Maybe not for another year and thereā€™s very little documentation yet on what the new method will be, so for now, just use that same classic documentation that you found.

  1. The zwave commandsets are the standard Z wave commandsets that any certified Z wave controller users. For information on those values, see the documentation put out by the Zwave alliance or SI Labs.

The documentation that you found is just the list of which of the optional standard commandsets the smartthings hub supports and at which level (version one, version two, version three, etc.). You get the details For each commandset value from a zwave source. Like this one:

1 Like

Thank you, this is exactly what I was looking for. Just another quick question on device documentation, I know that there is a list of compatible devices here however it does not list any of the smart things device capabilities. What I have been doing to get capabilities of my devices is making a call to the rest API to list them, however these are only the default capabilities that come with the default device handler and not necessarily all the capabilities the device supports.

For example, the device that I am working with at the moment the Aeotec Smart Switch 6 this device supports voltage and current readings. The default device handler however does not support voltage and current readings only power and energy. So when I query the API for the capabilities these will not show as they are not defaults set up when first connected, its just I knew the device does support these readings from working with it through OpenHAB.

Is there any documentation on devices capability for individual devices that is a bit more detailed something like they have in OpenHAB here for the Aeotec plug for example?

Iā€™ll have to leave that to the coders to answer. Hopefully others will chime in soon. :sunglasses:

1 Like

Unfortunately not. Devices can support many capabilities, but they can work with only a set of limited capabilities. Those capabilities are limited by the Device Handler. That is what you are querying through the API. If you need a list of the real possible capabilities what a device can support then you can look the devicesā€™ official documentations, if there is any.
Smartthings is built on the concept to have universal Device Handlers to fit for multiple device at the same time. Thatā€™s unfortunately means that specific capabilities are not exposed by those universal device handlers. But this approach gives availability to connect almost any device to the system with basic functionality, what it is really required.

1 Like

Every certified zwave device Will have a conformance statement posted online at the Z wave alliance products database. This will list all of the command sets it is capable of receiving and sending.

https://products.z-wavealliance.org/

I donā€™t know how this maps to ā€œcapabilitiesā€œ on the smartthings platform, though.

Anyway, for example:

https://products.z-wavealliance.org/products/3093?selectedFrequencyId=2

https://products.z-wavealliance.org/products/3093/classes

(I was a network engineer before I ever purchased smartthings for my own use. However, I am now quadriparetic and depend on text to speech. And trust me, you do not want to use groovy with text to speech. :wink: So I iā€™ve never done any coding on either the classic or the new SmartThings platform. but I am familiar with the network protocol specifications. )

2 Likes

I would love if the Z-wave Alliance would keep that list updated. I have came across a few devices which are certified Z-wave Plus devices, but not listed thereā€¦

Just an example:

https://products.z-wavealliance.org/Search/Index?regionId=-1&searchText=Mob.iq

The actual list of Z-wave devices sold by the company (documentation of those):

1 Like

Theyā€™ve historically done a very good job of keeping things up-to-date because the conformance statements are posted when the certification is issued.

If the company tells the alliance that the device is EOL, it may no longer appear even though it did once.

The other possibility is that the device is rebranded, but was actually certified by a different manufacturer.

I would ask the manufacturer for a copy of their Z wave conformance statement, and that would tell you whatā€™s going on as well as give you the list of the command sets.:sunglasses:

2 Likes

Otherwise might be due to translations. Most of the manuals are only in Polish.
But if you look at those remotes, they were designed to be primary (maybe secondary) controllers. But some with displays and built-in settings are far more than any remote.
They used to have even a Hub or Bridge for Zwave, but I couldnā€™t find any for sale since I know the company. Ive found some comments that the hardware was too weak for the purpose.

2 Likes

Hey folks. Most of my devices are working just fine following the migration to the new app. They look different, and one can argue about whether you like the new look, but thatā€™s not the topic here.

I have a device that reports voltage. You can see from the snip here the difference in appearance of the device in the two apps.

Q1: Iā€™m guessing that the Device Handler has to include different information to display voltage in the new app. Does anyone have a pointer to where I can find this info?

Q2: The new app shows a cloud with a line through it as though it is not seeing the device in a cloud connection. But this is a hub connected device. Is that a hint? Do I have to put something in the device handler to tell it that this is a hub-connected device in this brave new world?

Thanks all!

Paul

When you create events in the device handler, do you include unit: 'V'? Iā€™ve found that the new app likes to have the unit specified. Not necessarily everytime, but at least once. This is regardless of whether there is a default unit.

1 Like

Hi Paul,

I was having the same problem, what fixed it for me was not using multi - attribute tiles, instead only use value tiles and not declaring a tile as main only using tiles for details. My setup is shown below for the two different SmartThings apps. Ensure you have the capability "Voltage Measurement" defined for your device as well.

The code setup for my tiles is in the snippet below.

// tile definitions
tiles(scale: 2) {
     	// Current value of power
        valueTile("power", "device.power", decoration: "flat", width: 2, height: 2) {
			state "default", label:'${currentValue} W'
		} 
        // Current value of energy 
        valueTile("energy", "device.energy", decoration: "flat", width: 2, height: 2) {
			state "default", label:'${currentValue} kWh'
		} 
          
          // Current value of voltage 
        valueTile("voltage", "device.voltage", decoration: "flat", width: 2, height: 2) {
			state "default", label:'${currentValue} V'
		} 
        
        
        // Reset Button
		standardTile("reset", "device.energy", inactiveLabel: false, decoration: "flat",width: 2, height: 2) {
			state "default", label:'reset kWh', action:"reset"
		}
        // Refresh button
		standardTile("refresh", "device.power", inactiveLabel: false, decoration: "flat",width: 2, height: 2) {
			state "default", label:'', action:"refresh.refresh", icon:"st.secondary.refresh"
		}
        // Configuration Button
		standardTile("configure", "device.power", inactiveLabel: false, decoration: "flat",width: 2, height: 2) {
			state "configure", label:'', action:"configuration.configure", icon:"st.secondary.configure"
		}
        
        // Show the tiles 
		details(["power","energy","voltage", "reset","refresh", "configure"])
	}

Unfortunately the buttons I have defined which work in the classic app do not work in the new app, if anyone reading has suggestions on this let me know! The only one that seems to work is the refresh but its called when I scroll up to the very top and then let go to refresh in the app, there is no button.

As @orangebucket said as well I am including a unit for each event I am creating with the meter. In the code below it shows how I create the events, the first function is a bit redundant as all it does is call another function but I have not got chance to update. The code below is for a Z-Wave meter using the command class meter report V3 so may have to be slightly altered if you are using something different.

def zwaveEvent(physicalgraph.zwave.commands.meterv3.MeterReport cmd) {
	meterReport(cmd, cmd.scaledMeterValue)
}

private meterReport(cmd, value) {
	def meterTypes = ["Unknown", "Electric", "Gas", "Water"]
    def electricNames = ["energy", "energy", "power", "count",  "voltage", "current", "powerFactor",  "unknown"]
    def electricUnits = ["kWh",    "kVAh",   "W",     "pulses", "V",       "A",       "Power Factor", ""]
    def map = [ name: electricNames[cmd.scale], unit: electricUnits[cmd.scale], displayed: state.display]
    
	log.debug("Scale: ${cmd.scale} Type: ${electricNames[cmd.scale]} Units: ${electricUnits[cmd.scale]}")
	switch(cmd.scale) {
        case 0: //kWh
        	map.value = cmd.scaledMeterValue
	        break
        case 1: //kVAh
            map.value = cmd.scaledMeterValue
            break;
        case 2: //Watts
        	[name: "Power", value: value, unit: "W"]
            map.value = cmd.scaledMeterValue
            break;
        case 3: //pulses
            map.value = cmd.scaledMeterValue
            break;
        case 4: //Volts]
            map.value = cmd.scaledMeterValue
            break;
        case 5: //Amps
            map.value = cmd.scaledMeterValue
            break;
        case 6: //Power Factor
        	 map.value = cmd.scaledMeterValue
             break
        case 7: //Unknown
            map.value = cmd.scaledMeterValue
            break;
        default:
            break;
    }
    createEvent(map)
}

Hope this helps!

1 Like

This is super helpful.

Note to self: Multi attribute tiles may not be happy campers in the new app.

@ogiewonā€¦ If Iā€™m successful in refactoring the ST_Anything Voltage Child Sensor, Iā€™ll volunteer to help with refactoring others. May need a little adult supervision to make sure I donā€™t break anything.

@Warren1 Thanks. @orangebucket Ditto.

Happy weekend everyone.

2 Likes

FYI - The units were added to the Child Voltage Sensor DTH about a month ago. I just checked and if you click on the device in the new ST App, the voltage is properly displayed.

However, the voltage value is not displayed in the ā€˜Roomā€™ view tile for the deviceā€¦

OK. Iā€™ll try to work through it. Right now Iā€™m still getting the crossed-out cloud icon in the detail view, and though I see the events in the log there is no history under the history link in the detail page for the device. I suspect that Iā€™m not mapping the device correctly yet.

Are you using the latest ā€œChild Voltage Sensorā€ DTH from my GitHub? If so, one thing to try is to simply delete the Voltage Child Device (assuming it is not being used in a bunch of Apps/Automations/Dashboards/etcā€¦) I just deleted it from within the New ST App, and it was automagically recreated by the Parent DTH as expected.

I agree that there is NO HISTORY whatsoever. But I do see ā€œConnectedā€ on the small tile, and the proper voltage when in the full screen device view.

I am guessing that the new App is not handling the ā€œVoltage Measurementā€ Capability properly. I have no clue who to even ask.

Yeah that voltage measurement capability seems awkward to work with, for devices that support electrical meter readings it seems rare to have that capability set up in the default device handler from what I have seen. There is always some manual work involved which makes me question why not just add it in by default if the meter is designed to support these readings?

Just a question also have any of you had any luck implementing a current, power factor, apparent power or any other ā€œElectrical Readingā€ capability other than the energy meter, power meter and voltage measurement? I can read these values in through the Z-Wave command classes and they appear in my logs shown below (Donā€™t mind the unknown value) but its awkward to get at through the API if its not within a capability, still have to look into custom capabilities but if anyone has any suggestions it would be helpful!