Please improve the documentation for Device Preferences

Meta
1

The documentation is very poor on this page. Please make it better
http://docs.smartthings.com/en/latest/device-type-developers-guide/device-preferences.html

It says to use two device types as examples but neither example is very good. They both have one preference and they are very simple.

Please document how to use enum and other data types as preferences.

Also WHY can’t preferences be sliders ? I need a Percentage preference and can only use number or enum…Slider would be PERFECT ! I know that isn’t documentation issue but just saying…

Tag @Jim

1 Like
2

It’s in our backlog to improve it. It may end up being something that isn’t looked at until post v2 or beyond, but we are aware of the need for improvement.

4

OK, here are a few questions I have

input takes both title and description but only title seems to be used. What is description for ?

What data types are valid ? I have used enum and number. I notice number still returns a string so you have to do something like
def reaNumber = prefNumber as int

Are there any special attributes other than title, description, default and options (options used for enum.

Anyone is free to answer :smile:

5

This all seems to be from my experience, but I think there may be some mix-up between the input structure for DeviceTypes vs SmartApps or that the structure is actually the same, but the available options and how they are used differ.

Only title is used in either case. In the SmartApp documentation, description is listed as: “default value of the input element”; which doesn’t make much sense to me. I would just ignore/omit description from the DeviceType.

I’ve used enum, number and boolean as data types. The main function of the type field seems to be deciding how the input is structured. (ie. enum gives you the radio buttons for the options, number brings up a numeric keyboard, boolean gives you a toggle switch. The actual variable does seem to always be a string, which is probably why my boolean didn’t work as I thought it would. I think you can also use: decimal, text, time, password or email based on the SmartApp list. I don’t know if the other options would make sense in a DeviceType.

I’m not sure about all the special attributes, but you can use the following.

defaultValue: "No"
required: false
displayDuringSetup: true

6

I agree but the documentation doesn’t which is confusing, this page http://docs.smartthings.com/en/latest/device-type-developers-guide/device-preferences.html

Says to look at “HomeSeer Multisensor” device code for good example.

Taken from “HomeSeer Multisensor” device code

	input "intervalMins", "number", title: "Multisensor report  (minutes)", description: "Minutes between temperature/illuminance readings", defaultValue: 20, required: false, displayDuringSetup: true

Includes both title and description.

I have come to many of the same “Guessed conclusions” as you but this is sad that we are all hacking away trying things because the documentation is so bad.

It can’t be good for the servers either. I am always crashing my app, throwing exceptions etc as I hack. I am also doing rapid edit, save, publish, test, edit, save, publish, test sequences because I have to use trial and error (mostly error) to figure out what should have been very easy to document.

BTW: Sample code is NOT documentation. I have seen so many documentation pages that say “Here is a sample of how to use this method for documentation”
createButton(“save”,“save”,“save”,“required”)

With not explanation. That the first save is the button label, the second save is the method to call, the third save is the description of the button. So we have to try changing the values and seeing what the effects are.

1 Like