Define main tile in new app DH

Hi All,
I’m new to the Device Handlers world, as a first experiment I wanted to modify a device handler for a sensor I have (

To display temperature instead of motion as a main tile. I read the old documentation and editing the main() in the tiles configuration correctly changes the displayed value, but only in the old app. the new one still displays motion.

Is there any documentation to explain behaviors of “old-format” device handlers on the new app without rewriting them completely? a typical usecase for me is changing the main value and icon displayed in the main tile.


1 Like

Here is one of several flags I have knitted on the forum …

You may also the following broadly interesting. You may need to scroll back a few posts in a rather long thread to get the context, but I was quite pleased with it.

I do recommend going back to post 1 in that thread and reading the intro.

The following is something I wrote in a private messages thread:

DTHs have always allowed custom attributes and commands to be added, that is to say the attribute and command lines. They were always accessible to any legacy app that bothered to look, webCoRE being particularly effective at working with them. However apps like Smart Lighting and ActionTiles that are based on a limited selection of stock capabilities, couldn’t work with them.

In the new environment everything is based on well defined capabilities so custom attributes and commands don’t have a future. Instead it is possible to create custom capabilities in the same format as the stock capabilities to absorb the attributes and commands. This doesn’t make any difference to the status quo, but it does open up options in the future. You can build basic custom capabilities in minutes with the aid of the CLI tool (really just a front end to the SmartThings API). They just add to your DTH in a format like capability 'treebanana12123.myCapability' and get used just like other capabilities.

A related problem is that community developers had a habit of using non-standard attribute values, just because they could. This is really not a good idea any more, but the solution is pretty much as above.

The real issues come about with the UI. The ‘tiles’ used for the Classic app UI had plenty of scope for abuse, including supporting the non-standard values above, displaying custom attributes and running custom commands by pressing buttons.

The UI is now completely based on capabilities. If you are using a custom capability you also define a ‘capability presentation’, written in JSON or YAML, that describes in broad terms (various buttons and switches, sliders, plain text, lists etc) how you want your custom capability to be presented if it is used for the status on the dashboard tile, if it is used as the action icon on the dashboard tile, and how it is presented in on the device details page. You can also define how the capability is presented as a condition in the Automations, or as an action in the Automations. This latter functionality hasn’t started to become available yet but it will all be new when it does arrive.

At a device level, you can leave the app to figure out for itself what to do, but more typically you create a device config, which is again available as YAML or JSON. The device config allows you to specify which capabilities in the device are used in the status in the dashboard tile in which order (only the first one is used in the mobile app), in the action in the dashboard tile (ditto), on the devices pages, and in the automation conditions and actions. The device config is expanded into a device presentation which incorporates the capability presentation and shed loads of internationalisation text for the stock capabilities.

Using the CLI and the ID of your DTH from the URL when you edit it, you can generate a basic device config file suitable for devices using that DTH in seconds. If you want to change anything about it, such as change the attributes used for the dashboard tiles or remove stuff you aren’t interested in seeing, you just use a text editor, then the CLI will take a matter of seconds to use this file to create the full device presentation and assign it a ‘vid’ (a UUID in this instance).

The DTH then needs to be edited with mnmn: 'SmartThingsCommunity', vid: <the UUID>' in the definition() and that is pretty much job done.

It should be pointed out that there are stock ‘vids’ available for common combinations of stock capabilities so you will see e.g. mnmn: 'SmartThings', vid: 'generic-switch-4' .

Device presentations aren’t really a big deal. It is creating the capability presentations that can be the most time consuming as you have to choose different types of tiles and configure them. It is also the problem area.

As (most of) the available stock capabilities have capability presentations available you might assume that implementing custom capabilities in the app is a matter of accessing the custom presentations and then doing whatever they were already doing for stock capabilities. It doesn’t seem like it ought to be a massive job. However the reality is that basically nothing in the UI fully worked at all when custom capabilities were launched in preview a few months back, and since then bits have trickled through at a snail’s pace. It is like it is all totally new. Much of it still doesn’t work. Automations haven’t even been started on.

I’ve been wondering if actually the stock capabilities are being implemented completely differently and so it is all new. Certainly several stock capabilities display in a way that bears little resemblance to what the presentations say.

Oh I overlooked the icon. At the moment the best way of dealing with that is to define the ocfDeviceType in the DTH definition. You have to use a value that ST recognises and has an icon for. I do have a brain dump of sorts that includes a list of known devices I extracted from the Developer Workspace. Your mileage may vary.


Wow! thanks a lot @orangebucket for putting together all these pointers, very helpful. By the way I use all yours DHs for the aqara sensors :+1: thanks also for that.