Custom Capability and CLI Developer Preview

ahh … hadnt done that. given that issue was reported a while back … thought the xmen in blue had fixed that one.

so like need to change the name on this line save and publish?
name: “rooms occupancy”

and then if you change it back again immediately after publishing does the cache still get refreshed or it falls back on the old cache entry?

thank you.

1 Like

thats a first for me … docs getting updated before the code’s done :wink:

1 Like

I don’t know if that would help, but I meant editing the actual device not the DTH.


ahh got it. thanks again.

1 Like

looks like changing the device label from the IDE then restarting the new app picks up the changes.

I recommend changing to generic ocf device when forcing a cache clear because other dths may have different values assigned to them that could mess up your device settings.

is that an open issue? if the VID is meant to be a deterministic hash based on device type and device config other dths should not be impacting my device settings. unless off course the device type and device config is exactly the same which should never be because the generated namespace is supposed to be unique.

The only open issue is the cache issue. @mvevitsis was talking specifically about editing an actual device and changing its type to something else and then back to the desired type in order to clear the cache. If you change it to type that has conflicting values, there is a chance it could mess things up. I have never experienced this but I’m sure it could happen.

1 Like

I have, that’s why now I’m very careful to only use generic ocf device as my cache clearing tool.
Otherwise you’ll have to delete the device and start over if you mess up the values.


ahh … thank you.

i will stay away from changing the device type to clear cache. changing the label then restarting the app seems to do the trick for me.

I’ve been grappling with a new DTH today. It is a multi-component device that uses a custom capability and the Notification capability in the main component, with the components being my virtual button devices that use the Momentary and Button capabilities. I’m not really winning. My issues are:

  • The Notification capability never displayed in the details view but I can’t recall if text fields are working and I didn’t want it anyway. However if I try and add the Notification to an Automation I get an error saving it, and that I did want because it is an easy way of getting a string into a stock attribute. Anyone used the Notification capability?
  • I have the components displaying nicely in the app, just displaying the Momentary button as I requested and required (mind you the Button tiles weren’t updating). However the components are not listed in the Automation conditions. Indeed the device is not listed at all, even with something basic like Switch added. This is odd as the DTH code is not so dissimilar to the stock Ikea Button and that works fine. Anyone been using composite devices?

can’t figure out the automation section of a custom capability for displayType “list” presentation.

anyone have a working example that they might be able to please share?

thank you.

is it possible to display value of a device attribute as text in the detail view of the device?

thank you.

edit: alternately where may I find the documentation for the device presentation configuration?

You would need to add your components buttons to the automation conditions and actions in the configuration file. However I’ve reported bugs specifically with buttons as components which don’t work as expected in the automation tool or the UI. I don’t know if/when ST will fix the issue (they’re replicated it).

Ah thanks, I do notice a definite absence of the component Buttons in the conditions section, which doesn’t help, though I think I had them there yesterday at one point. They are definitely there now. However whatever I put in there, the device just never seems to be spotted.

The actions are working fine. Well I say fine. I basically get …

Press Momentary     [ ]
Press Momentary     [ ]
Press Momentary     [ ]

That’s it. No hints as to which component they come from …

Even where the component label is used it is teeny tiny.

That’s one of the bugs. Do report it to so they can document and prioritize it.

1 Like

I’m trying to follow this
but I’m just not grasping the mapping from classic DTH to new capabilities framework.

I have four attributes that display data on classicDTH:
attribute “thisCurrentMinFlow”, “string”
attribute “todayFlow”, “string”
attribute “monthFlow”, “string”
attribute “yearFlow”, “string”

One attribute that I monitor for user interaction:
attribute “suspend”, “enum”, [“pause”, “monitor”]

two commands that either “pause or monitor”
command “changeToPause”
command “changeToMonitor”

I have downloaded the CLI but it doesn’t generate the dashboard layout automatically. I’m not sure what it generated. Is it the detailed view?

More importantly how do this four attributes and commands get mapped using CLI.
@jody.albritton @nayelyz I just need one sample just one using my specific attribute and a command sample. I will take care of the others but one example is that asking for too much??
I’m thinking “state” displayType for now just want to test the mapping is working:

Let’s take for example todayFlow.
I start CLI. I name the capability waterMeter.
name the attribute todayFlow
create a setter Y
Generate the json file with CLI output command. Then using the capability ID change the classic DTH with ID.

Then do this below:
What exactly does this mean?
“Remove custom commands and attributes which were encapsulated in your custom capability. Update direct references to your custom attributes and instead reference them through \{capabilityId\}.\{attributeName\} .”

Using a sample classic/legacy DTH:
Can the documentation add “a before code” modified screenshot
then show the OneApp DTH “after code” is modified screenshot.

There are steps that might seem as trivial but if you’re new to this as I’m including the trivial steps might help fill in the gap on the proper process to migrate a legacy DTH to a new version.

It depends on how you want them displayed. There are only a few possible layouts for custom capabilities right now. You can see which ones are available in the documentation.

@nayelyz I sent you updated screenshots and a VID. The dashboard state presentation active/inactive icons does not work in iOS but it works in Android.

That is one of the first questions I ever asked about this process, months back. I never did get an answer. It just seems to differ from reality.

Let’s consider replacing attribute "todayFlow", "string" with a custom capability called waterMeter.

When you do …

smartthings capabilities:create

… that creates your capability for you. You will see if you call it “Water Meter” it will give it an ID munged into camel case and you will be assigned a unique namespace. So your custom capability has the capabilityId that looks something like strangehorse12345.waterMeter.

In your DTH you should replace attribute "todayFlow", "string"with capability "strangehorse12345.waterMeter". That is job done. You continue to create events for the todayFlow attribute. It doesn’t need the namespace anywhere else.

What that paragraph in the docs seems to be suggesting is that you need to refer to the attributes as e.g. strangehorse12345.waterMeter.todayFlow. There is a stock capability that even makes a point of adding that format as well as todayFlow. I’ve queried that on more than one occasion without getting an explanation. It just seems to be unnecessary yet the ST developers seemed to think otherwise. Simply using todayFlow just seems to work fine.

You define a capability presentation to go with your capability, using either JSON or YAML. I haven’t worked with YAML so find JSON easier to read. The capability presentation defines how you want your capability to be presented in five places: the status text on the dashboard tile; as the action icon on the dashboard tile; as a tile on the device details page; as a condition in an Automation; as an action in an Automation. If you only have an attribute in your capability you wouldn’t need to define either of the actions. If you only have a command in your capability you wouldn’t need the dashboard status or the condition. You only have to define it for the places you might want to use it. A simple example for you might be:

    "dashboard": {
        "states": [
                "label": "{{todayFlow.value}}",
                "alternatives": []
        "actions": [],
        "basicPlus": []
    "detailView": [
            "label": "Today Flow or other text of your choosing",
            "displayType": "state",
            "state": {
                "label": "{{todayFlow.value}}",
                "alternatives": []
    "automation": {
        "conditions": [
                "label": "Today Flow",
                "displayType": "list",
                "list": {
                    "alternatives": [],
                    "value": "todayFlow.value"
        "actions": []
    "id": "strangehorse12345.waterMeter",
    "version": 1

Let’s say you have created that as presentation.json. You create the capability presentation by doing:

smartthings capabilities:presentation:create --input=presentation.json

That will prompt you for the capability you are creating the presentation for. You can skip that by using command line arguments.

That’s the capability side of things done. Now you need to address the device side of things. What you are ultimately creating is a device presentation which tells the app how it should display a device. You start with a device config, which is the user configurable parts of the presentation. This is another JSON file that defines which capabilities should be used in various places: which ones can be used for the dashboard status (the app only uses the first one); which one for the actions (ditto); which ones should be displayed on the details page; which ones are offered as Automation conditions; which ones are shown as Automation actions.

You can generate a default config file based on your DTH (hence why it needs to have been updated for the custom capability already). You use the ID of the DTH (shown in the URL in the IDE). Let’s put it in config.json.

smartthings capabilities:device-config:generate <DTH ID> --dth --output=config.json

You can edit that file as required, but at the moment you just need to make sure that if it has the lines presentationId and manufacturerName they are removed (they are new keys that will ultimately replace vid and mnmn that the API generates but can’t currently consume).

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

That will save your device config into the system, expand it out into a presentation (using the capability presentations), and assign a unique vid (another UUID) that identifies the config and presentation.

You then need to edit your DTH again, adding mnmn: "SmartThingsCommunity", vid: "<vid>" into the definition() parameters.

That is pretty much it, but you will need to bust the cache on your mobile app for any existing devices. You can just clear the cache, but I prefer to edit each device using the IDE, change the device name slightly, then update. That should suffice but sometimes you need to reload the app, and sometimes it is easier to create a new device from scratch.

If you are curious to see what the actual presentation file looks like, you can ask the CLI to show you it using smartthings presentation <vid> -j. Expect rather a long file as it will include all the i8n stuff for the stock capabilities and there are a lot of languages supported.