Custom Capability and CLI Developer Preview

I was replacing a custom attribute that was only being used to display information and it was a string so it would always display with 2 decimals places.

The new apps UI is more consistent so that isn’t important and I did end up using a number to workaround that issue.

Exactly so the app shouldn’t be attempting to convert strings or integers into date/time no matter what value you set them to…

For mine, the string attribute is a hexadecimal value, received from a RF/IR bridge.

Actual displays as in “History”. For example,

“0X20DF40BF” displays as “551,502,015”
“41770C” displays as “41770C”
“375003” displays as “375,003”

The display value on the dashboard is correct, only the history is not.
How do I make them display correctly in the History?

I’m trying to migrate some of my DH but nothing different seems to be happening on the UI side. I then use the example on the tutorial but although i did not received any error on the API side, I don’t think this is working.

Could someone upload what it should look like? The slider goes to 9000 on the UI despite that the range on the custom capability is set at 7000 ?

Some questions

  1. How can we provide a custom namespace during the capability creation? Seems like this command:
    C:\bin\smartthings capabilities:create --token myToken does generate a namespace of circlechapter36197 ? I have no clue where is this namespace is coming from - autogenerated?

  2. Should the mnmm always be SmartThingsCommunity? What is this value used for exactly?

  3. Is there any documentation on how the “new UI” is being generated based on the definition device handler? For example, in the demo code, there are 11 capabilities but only 3 box on the UI being generated. My assumption is that some capabilities has UI components built-it but it would be nice to know which one would generate what in the UI?

  1. You can’t. You need to use the namespace provided.
  2. Yes, because this tells it you are using a custom namespace and vid
  3. No, there are no screenshots in the documentation, you just have to enable the capability and initialize it (sendEvent to set it to some status) to get it to appear and see what it looks like in the UI.
  1. The namespace is auto generated for each account.

  2. The mnmn originates as the manufacturer name and is unique to an organisation of some sort. The vid is only unique for that organisation. For community development SmartThingsCommunity is a proxy organisation. If you want to use stock presentations you can use SmartThings with the appropriate vid e.g. generic-switch and if some other organisation has created a presentation that you want to use then I believe that works too.

  3. Actuator, Sensor and Light are all deprecated capabilities and the first two are just tags - they have no attributes or commands. The Health Check capability is more about enabling functionality and there isn’t really anything for the UI to do. I haven’t tried it but I saw it suggested that Refresh is called automatically when the device page is opened and also by a pull down action on the page. Configure just means there is a configure() command. I’d have thought that was worthy of a button myself for when a manual configure is required. The only really obvious missing one is Switch and the functionality of that may have been absorbed into the dimmer control perhaps?

It is possible to display the capability presentations for the stock capabilities via the CLI (or accessing the API in other ways). However as the UI for them often bears no relationship to those presentations there is indeed no way of predicting what will happen. Whether the presentations are being ignored, or they actually are a new concept that needs to be somehow retrofitted, isn’t clear.

awesome - thanks.

Would it be possible to valide/provide what the end result UI should look like in the custom capability tutorial? I’m wondering if this is expected behaviour or my custom capability is just not working.

I’m not sure to understand your statement about the lack of link between the capability presentation and the UI rendering. Could the UI be completely different than the one specified in the prensentation? What and who’s using the capability prensentation? In the tutorial, I see there are two xml files and I’m assuming one is being used as the capability presentation and the other one in the UI guess that’s the two you are referring two here? Is there any documentation that explains those basics stuff? I do see the API specification documentation but not “concepts” per say?

Also, is there any way to debug “UI” device components, like logs or something? I feel this is hard to debug? Like if we are missing tags, or just invalid attributes, typos, things like that. Currently, it’s more about, try and see (and probably hope for the best) type of thing. Seems like that would be benefical for developers.

Here is the capability presentation for Temperature Measurement:

smartthing capabilities:presentation temperatureMeasurement -j
{
    "dashboard": {
        "states": [
            {
                "label": "{{temperature.value}} {{temperature.unit}}",
                "alternatives": [
                    {
                        "key": "C",
                        "value": "°C",
                        "type": "active"
                    },
                    {
                        "key": "K",
                        "value": "°K",
                        "type": "active"
                    },
                    {
                        "key": "F",
                        "value": "°F",
                        "type": "active"
                    }
                ]
            }
        ],
        "actions": [],
        "basicPlus": []
    },
    "detailView": [
        {
            "label": "___PO_CODE_SMARTTHINGS_DREAM_SAC_TMBODY_TEMPERATURE",
            "displayType": "slider",
            "slider": {
                "range": [
                    -20,
                    50
                ],
                "unit": "temperature.unit",
                "value": "temperature.value",
                "valueType": "number"
            }
        }
    ],
    "automation": {
        "conditions": [
            {
                "label": "___PO_CODE_SMARTTHINGS_DREAM_SAC_TMBODY_TEMPERATURE",
                "displayType": "numberField",
                "numberField": {
                    "value": "temperature.value",
                    "valueType": "number",
                    "unit": "temperature.unit",
                    "range": [
                        -20,
                        50
                    ]
                }
            }
        ],
        "actions": []
    },
    "id": "temperatureMeasurement",
    "version": 1
}

It specifies the device type slider for the details view. Now here is what you get if you use it in a handler that also has the Relative Humidity Sensor:

I see nothing in the presentation about displaying temperature in the humidity in the same widget, or indeed having a link to a graph. Not saying it doesn’t look OK but I didn’t specify it.

Similarly a Switch has a label in its capability presentation but none in the UI, and uses a different type of button, and you can do it with other capabilities.

I see a couple of possibilities:

  1. The device plugin (the bit of the app that actually does the rendering into HTML) is just ignoring the capability presentations and doing its own thing with whatever it finds.
  2. The concept of capability presentations is relatively recent and is currently only applied to custom capabilities, with the stock capabilities being handled differently.

Either the only way to predict what you will end up is a combination of the API where it is working for custom capabilities, and guesses based on previous experience for stock capabilities.

1 Like

If a manufacturer is using the CLI to create a presentation for one of their handlers, is it possible for them to use their company name for the mnmn instead of SmartThingsCommunity"?

how do you update a device-config if you edit it after the first create? presentation:device-config:update seems to throw the following error:

[2020-10-17T11:12:57.259] [ERROR] cli - caught error Error: Request failed with status code 400: {“requestId”:“FD8EC6D2-127D-4129-A197-B87267880DA4”,“error”:{“code”:“BadRequestError”,“target”:null,“message”:“The request is malformed.”,“details”:}}

thank you.

edit: the error was from running create not update. sorry.

I didn’t think there was an ‘update’. You don’t really update device presentations, you create new ones.

ok. so if i

  • generate device config json from a dth
  • edit the generated json and run presentation:device-config:create
  • subsequently edit the dth to add a capability
  • generate device config json from the edited dth
  • again edit the generated json then …

… how do i “update” the previously generated presentation device config for this edited dth?

thank you.

Just run create again. There is no update.

my bad … had a typo … that error was from running create again.

I usually don’t re-run the generate unless I have added capabilities in editing. If you re-run the generate, be sure you re-delete the bad lines it inserts at the end:

"presentationId": "blah",
"manufacturerName": "SmartThingsCommunity",

Other than that, it should work the same as the first time. I have run the create multiple times on the same dth with no issues.

1 Like

right. i only reran the generate because I had added capabilities in editing.

this solved it. thank you :slight_smile:

and the custom capability doesnt show up in the dashboard or in the details. its almost as if the custom capability, capabiliy presentation and device presentation that were created does not exist from a runtime perspective. the only place i see the custom capability getting updated is in the history but otherwise nothing. but maybe thats just the old attribute version of the custom capability getting updated and not the new custom capability.

you would think if there is an issue with any of those you would see an error or warning either on the console while executing the CLI commands or in the live logs during runtime.

edit: well the good news is the custom capability changes do show up in the history for the new app … YAY! … but nothing shows in the presentation … BOO!

My understanding, probably not totally correct, is:

The vid, aka the presentationId, is an ID that is a hash of the contents (not order) of a device config and also identifies a device presentation. The device config is the user configurable template for the full device presentation which adds in the capability presentations and the internationalization and other bits and bobs. You can potentially query the API with a vid and get a device config and device presentation returned.

When you generate, the DTH is being used to suggest a suitable device config. You typically save a copy of the config locally so you can use it as the basis of a create. This just saves you hand crafting the config.

When you create you are supplying input in the format of a device config. This is hashed to form a vid and if the vid is new the device config is saved and a device presentation built from it. This makes it rather first come, first served, for the presentation.

There is never any updating going on.

Personally I think the vid needs to be order specific.

1 Like

first time the presentation device config is created it seems to work fine using the generated device config as is. on subsequent creates it seems the presentationID and manufacturerName needs to be deleted from the generated device config before the create will work.

in either case the vid doesnt seem to change independent of the ordering which as you said needs to be a true hash covering both capabilities and ordering of those for each device.

Have you done the required cache busting? The app caches presentations for 12 hours. You can clear the app cache but I always edit the device in the IDE, change the device name or something equally significant, and update. It usually works, just sometimes it pretends not to for a little while just to wind you up.

1 Like

Yes, the API documentation has been updated with those new key names, unfortunately the API itself has only had half the job done.