Difference between device presentation and device config

[McDoD]

I am trying to clarify the difference between device presentation and device config.
For the first one we have the smartthings devices:presentation [ID] API
while for the second one we can use smartthings presentation:device-config:generate ID to generate the config and then smartthings presentation:device-config:create to apply the desired configs.

Looking to the output of smartthings devices:presentation [ID] there are some options there to handle for example labels, capability state labels etc while the smartthings presentation:device-config:create is more like a definition for the capability order, capability values and things like that.

So from what I understand, for example to change the label of a capability we should define a device presentation. There is no API to write a device presentation.

So my questions are:

• what is device presentation used for
• what is device config used for
• can I override/customize the default labels for standard capabilities using device presentation
• how can I apply a custom device presentation

[orangebucket (Graham)]

@McDoD

• what is device presentation used for
• what is device config used for
• can I override/customize the default labels for standard capabilities using device presentation
• how can I apply a custom device presentation

The device presentation is a configuration ‘file’ that instructs clients how to present the UI of the device, specifically on the dashboard, the detail view and in automations. The most common clients are the mobile apps so that equates to the dashboard tile, the device details page and the automations and scenes editors. You don’t write device presentations as they are maintained automagically in the cloud.

The device config is basically the user configurable bits of the device presentation. Each capability has a capability presentation that defines how it should be presented when used as the dashboard state, dashboard action, dashboard basic plus (me neither), detail view, automation condition and/or automation action. The device config essentially says which of the capabilities you actually want to be used in those six places, though it can make other tweaks. When you do a smartthings presentation:device-config:create you are requesting your local text file in JSON or YAML format be used to create a device config in the cloud, and that a device presentation be generated from that by adding in the capability presentations and some other stuff.

In theory you can override the default capability labels by using the device config. Whether it will actually work is another matter as a lot of the stock capabilities use custom presentations that are a law unto themselves. In theory I believe the following would patch the label of a contact sensor in the detail view.

       {
            "component": "main",
            "capability": "contactSensor",
            "version": 1,
            "values": [],
            "patch": [
                {
                    "op": "replace",
                    "path": "/0/label",
                    "value": "A Patched Contact Sensor"
                }
            ]
        },

Yes, the patch looks hideous, but I believe it is actually a well known way of tweaking JSON so that is presumably why it has been used. They have to start somewhere.

Whether it achieves anything is another matter. I can’t remember. I did the same sort of thing with buttons and I could see that the resulting device presentation had indeed been patched with the new label, however the app didn’t take any notice. That’s the apps for you. We don’t know what they are supposed to be able to do, and even when we think they are supposed to do something they don’t do it.

You can’t apply a custom device presentation to stock devices or any devices installed as an end user. To apply it to your own custom devices involves specifying a manufacturerName and presentationID in the metadata in an appropriate place depending on the type of integration. You will also see these referred to as mnmn and vid in certain places and for the typical home brew developer they will be SmartThingsCommunity and a UUID.

I should stress that in this discussion a ‘device’ is referring to a device type, not an individual instance of a device, and everything is very much happening at the developer level. There currently isn’t any way to override the presentation of an individual instance of a device and nothing going on at the end user level.

[McDoD]

Thanks for your quick answer @orangebucket

So whatever YAML/JSON config is returned by smartthings devices:presentation [ID] is for information only and is automatically generate based on the device-profile, device-config, used capabilities etc.

For example I was looking to the custom-capability driver from the sample-drivers repository…and there is a presentation file there in which we can see something like (I know that one is for a custom capability…just using it as an example):

dashboard:
  states:
    - label: '{{fancySwitch.value}}'
      alternatives:
        - key: 'On'
          value: Fancy on
        - key: 'Off'
          type: inactive
          value: Fancy off
  actions:
    - displayType: toggleSwitch
      toggleSwitch:
        command:
          'on': fancyOn
          'off': fancyOff
        state:
          value: fancySwitch.value
          'on': 'On'
          'off': 'Off'
  basicPlus: []

Notice the dashboard > states > label for example. This key is not something that I can use in smartthings presentation:device-config:create like let’s say?

        {
            "component": "main",
            "capability": "switch",
                        "label": "My Custom Label",
            "version": 1,
            "values": [],
        },

My main goal for now is when I use a momentary button in my driver, I want the button to be called for example “Lock device” instead of the default “Momentary” label.

[orangebucket (Graham)]

@McDoD

So whatever YAML/JSON config is returned by smartthings devices:presentation [ID] is for information only and is automatically generate based on the device-profile, device-config, used capabilities etc.

Pretty much so. The device profile is largely incidental.

@McDoD

Notice the dashboard > states > label for example. This key is not something that I can use in smartthings presentation:device-config:create like let’s say?

OK, here is where we probably need @nayelyz or @erickv or indeed anyone else who really understands it to help me out.

If we look at the API we are told that the values array can be used for A list of valid values for the command argument or attribute that can override those defined by the alternatives provided in the capability presentation. That seems to imply that it can be used to tweak the ‘alternatives’. The example is the equally vague …

"values": [
    {
       "label": "string",
       "alternatives":[]
    }
]

I am hoping that the documentation is out of date as I don’t really understand it.

When you delve into Device Presentations and Configurations the example is somewhat different.

{
            "component": "main",
            "capability": "switchLevel",
            "values": [
                {
                    "key": "level",
                    "range": [
                        10,
                        80
                    ],
                    "step": 1
                }
            ]
        },

If that said slider instead of level I would understand it as it would be overriding some of the contents of the slider key. However label would also be a key so how would that be changed?

I still suspect that tweaking the label may require of the patch array as I described but I am even less confident now.

[erickv (Erick)]

@orangebucket @McDoD

At the moment, is not possible to patch stock capability presentation labels, but is something that our team is looking forward.

---

@orangebucket

I still suspect that tweaking the label may require of the patch array as I described but I am even less confident now.

You’re right, this update would be applied through the patch attribute.