Hi there guys! I’m hoping some folks can help me make heads or tails of the documentation for device handlers and the options available for the arduino shields. I’m trying to create a simple app that listens to my arduino which is taking 3 measurements (temp, Ph, and ORP). They’re all floating point, and I’m not sure how to write the code for the arduino to pass the data up to the device handler, how to do multiple tiles with the device handler, etc. Any answers to some of the below questions will get me closer to my goal of actually writing the app. Technically it “shouldn’t” be too difficult.

1). The simulator code block, what is it actually doing? Is that only needed for testing, debugging, or does it serve another purpose outside of the webui and is necessary for production code?

2). How do I nest tile blocks? The behavior I want to emulate is a single tile on the main screen, and then if its selected to offer another “expanded view” of the device to show the additional values. That way on the major block I can show a generic status “hot tub fine”, “hot tub close to imbalance”, “hot tub urgent care needed”. Then once the status icon is selected, display the tiles for the ph, orp, and temp of the tub. Very much like what was shown in the thermostat example.

3). How do I programmatically control the color, display MSG, and the icon associated with the status icon? I’m not sure if that behavior testing (checking the range of values of ph, temp,orp are within tolerances) the state of the tub belongs in a smart app or in the device handler. I’m guessing the handler since its changing or controlling the UI. Is there a list of the icons anywhere so I can pick them out?

4). Is there a list of the available tile types? I couldn’t find it anywhere in the docs. I noticed some examples have standard.tile, and this example uses value.tile. It’d be great to understand what’s available and what they look and feel like. Its possible I need to choose another type to serve the floating point needs of the nested tiles (the ph and orp have a decimal to 2 places).

5). Is there any doc describing the taxonomy of how to use the tile statement? I can see from the examples that there’s a number of options available, but I’m unsure of how to order them, declare them properly, or what produces an error. Ie I can see that the first field is probably the name of the tile for callbacks, but what is state, main, and details calling? What are the available options? How do they change the functionality of the tile? What should I use to get the functionality I want?

6). My device is going to attempt to be sending 3 values simultaneously as zigbee events to the device handler? Do you have any examples of that? I’m confused on how the zigbee statements get declared (again, couldn’t find anything in the docs) so that I can have the handler assign the values of those inputs properly, display them in the right tiles, and use them in logic. Do you have any examples of the arduino shield code that passes the values up as events correctly.

How are guys writing these specialized device handlers without documentation? Examples like the recently featured ones are using command structures that i can’t find any docs on and would to have access to? I’m willing to bribe folks to share what they can. Any help would be appreciated!

Rick, Right now I think they are focusing most of their efforts on getting the Android side on par with the iOS side. Once Android is out of beta I think we’ll see them start to fill out things like documentation and getting their store online so we can buy more things.

I understand they have a lot going on, especially with the Android app being in the somewhat rocky state it is in. At the same time, documentation for developers seems like it should be a pretty high priority since developers are the ones who are going to make or break the platform.

Also, shouldn’t the documentation people be different from the Android people?

Whelp this certainly is their priority to set, but I hope they do understand the impact of those decisions. For myself, while I have 3 SmartThings arduino shields staring at me, I haven’t implemented them in my projects due to the lack of documentation. I’ve taken the course of getting my projects working with an arduino wireless shield. Dumber, certainly…but my prototyping is faster since it’s very clear how to use the capabilities of that system.

The downstream effects should also be considered. If developers (and I use that term for myself loosely) like me aren’t implementing the device in to their projects because it’s hard to get started, then feature and bug requests will also slow to build momentum.

I know there are developer google hangouts, but those really aren’t the best forum to get information that you’ll need in coding. For example, there a ton of class objects in the SmartThings system, and they’re not documented anywhere. I can’t tell what properties these objects have, how to link them together, or what I can even configure (and what impact it’ll have). It’s massively unclear how some of the featured builders (like the baby monitor video) put together their code, and what best practices they’re using.

To me, SmartThings feels like a great remote control Zigbee app for their very specific release of branded devices (power, 1 sensor, etc.). This of course misses the point of what got all the makers very excited for this infrastructure and why we backed it in the first place.

Also, let me be very clear…I’m still excited to build with this infrastructure and think the potential is there. I just lack the tools to capitalize on that potential.

We recognize the lack of device type documentation and are working on having a basic device type reference document available next week that will include a list of tile types. Thanks for bearing with us.

Some quick answers in the meantime:

The simulator block is only used for testing in the IDE. It does not affect the operation or real devices or the appearance of devices in the mobile apps.

There isn’t currently a way to nest tiles arbitrarily, although we are working on expanding the tile definitions to be a lot more flexible as to what you can do. Right now all of the tiles listed in the “details” list will appear when you flip the main tile over by touching its lower left corner.

The Aeon Multisensor is a good example to look at for controlling background colors and the Zwave Switch is a good example for controlling color and icon. The basic mechanism is to use multiple “state” entries within the tile definition. The system selects one of those entries based on its name and the value of the tile’s attribute. The reference documentation will describe these options.

The current tile types are standardTile, valueTile, and controlTile. The Aeon Multisensor is a good example of value tiles and the Dimmer Switch has an example of a controlTile. The only control available right now is a slider.

Docs are not there now, but on the way

We’ll work on pulling together more complete examples. This post may shed some light on Zigbee messages from the shield.