How to change the value shown in the device card on the Home screen

Developer Programs Writing Device Types
10

OK, firstly bear in mind that you may find the process a bit arcane, complicated or think that it just sucks. Fair enough, but it is functionality designed for the ‘new’ environment being retrofitted into the legacy environment, it isn’t going to be pretty.

The following content is based on an actual example that appeared in another post. The object of the exercise was to have a device display the illuminance in the dashboard tile.

The tool that will be used is the CLI. Yes, that is CLI as in Command Line Interface. It is essentially being used to make it easier to use the SmartThings REST API.

Capabilities have their own ‘presentations’ that define how they look when they are used as the status on the dashboard tile, as the action on the dashboard tile, as tiles on the detail pages, and in automations. You don’t need to worry about those for the stock capabilities as they are already defined.

What you need to work with is the ‘device config’, which says which capabilities are to be used in the dashboard, details page and automations for anything using your device handler, and sometimes in what order.

This device config is combined with the info in the capability presentations, and some other fluff, to create a ‘device presentation’.

Prerequisites:

  • The UUID for your device handler as installed in your IDE. It is in the URL.
  • The CLI installed. Let’s call it ‘smartthings’.

First you need to generate a default device config for your DTH, using the UUID of your device handler in the below.

smartthings presentation:device-config:generate UUID --dth --output=config.json

The resulting config.json file is a device config. You can think of it as describing at a macro level how you want your device handler to be presented, but basically it is the user configurable bits of your device presentation. The bit of interest is near the top:

"dashboard": {
    "states": [
        {
            "component": "main",
            "capability": "illuminanceMeasurement",
            "version": 1,
            "values": [],
            "visibleCondition": null
        },
        {
            "component": "main",
            "capability": "battery",
            "version": 1,
            "values": [],
            "visibleCondition": null
        },
        {
            "component": "main",
            "capability": "configuration",
            "version": 1,
            "values": [],
            "visibleCondition": null
        },
        {
            "component": "main",
            "capability": "refresh",
            "version": 1,
            "values": [],
            "visibleCondition": null
        },
        {
            "component": "main",
            "capability": "sensor",
            "version": 1,
            "values": [],
            "visibleCondition": null
        },
        {
            "component": "main",
            "capability": "healthCheck",
            "version": 1,
            "values": [],
            "visibleCondition": null
        }
    ],

The first entry in the ‘states’ array is the one that is used to display the attribute status in the array. The other entries aren’t currently used by the app as dashboard tiles currently only support one state. In this case the illuminance measurement is shown first which was exactly what was required.

At the time of writing, there is a bug in the CLI/REST API that requires an extra edit to this file. The two lines containing presentationId and manufacturerName need to be deleted. These duplicate the lines vid and mnmn which are still needed. What is happening is that old terminology is being replaced by something more suitable and it hasn’t been implemented quite right yet.

Now you need to create a device presentation that is based on the description in your updated device config.

smartthings presentation:device-config:create --input=config.json

   Basic Information
    ┌──────┬──────────────────────────────────────┐
    │ VID  │ a3fe3c0d-1f51-3d51-9309-566ba1214f9b │
    ├──────┼──────────────────────────────────────┤
    │ MNMN │ SmartThingsCommunity                 │
    ├──────┼──────────────────────────────────────┤
    │ Type │ dth                                  │
    └──────┴──────────────────────────────────────┘

8< SNIP 8<

At the time of writing you will not actually see a summary like the above. You will get a full device config thrown back at you. That is a bug that has crept into the CLI and hasn’t crept out again yet. Fortunately the vid and mnmn lines will appear at the bottom of that file so you are OK.

Behind the scenes a perhaps surprisingly large JSON file has been created that is your device presentation. You now need to tell your device handler to use that presentation by adding the VID and MNMN from the above (NOT from the original config.json file, though they may be the same if no changes were made). So for example:

definition (name: "My Light Sensor", namespace: "fbloggs", author: "Fred Bloggs", mnmn: "SmartThingsCommunity", vid: "a3fe3c0d-1f51-3d51-9309-566ba1214f9b")

The new app needs to load this presentation for each device that is using your device handler. This is on a twelve hour cache (apparently), so you may need to give it a nudge. You can clear the cache on the app and that is said to do the job, but I prefer to update the devices in the IDE (you’ll need to change the name or something to make it a proper update).

That should do the job. Bear in mind that if anyone has already done this, you can use the ‘vid’ they created. It may well be the same anyway.

1 Like