Custom Capability and CLI Developer Preview

Erick any updates? Stuck on a holding pattern here until the controls start working.

Same here.

I’ve been able to use custom capabilities to replace custom attributes and commands in all my device handlers, but only because only webCoRE really knew what to do with them in the first place, and it still does. Also I do not support the Classic app.

When it comes to the app I see no evidence of any support for them being any more than incidental, or indeed accidental.

@RBoy @orangebucket can you give details on the exact nature of the issue. I think the context is spread out over a few posts in the thread.

Jody, I’ve sent Erick a detailed PM with how to replicate the issue and I believe he’s been able to replicate them. I’ve also provided examples above to replicate the issues.

Essentially most controls do not work as documented.

  • using a toggleSwitch on the dashboard with a command, it causes the iOS app to crash or become unresponsive
  • Using a list with commands in the detailView, the commands don’t work and the app throws an error
  • The controls don’t show the alternative options presented (the UI shows the attribute state names instead of the alternative text).

I’m wondering if all UI components have been tested along with the respective commands/features as per the documentation


I have just updated the opening post of another thread to give @Rboy a clearer run in this one. My bottom line is that the app doesn’t seem to be presenting things as documented in the API, yet at the same time it is happily doing lots of undocumented stuff and that really doesn’t help.

Hi, @RBoy

I’ve been able to trigger commands from a test integration supporting the List display type. The issue is that argument passed at the setter command is the key itself and not the respective value. In conclusion, values that SmartThings app is using are the defined keys instead the value. I’ve already shared this details with our team, so it’ll be reviewed soon.

Here’s an example on how I’ve designed the capability’s presentation for a to-do custom capability:

    "detailView": [
            "label": "To-Do list:",
            "displayType": "list",
            "list": {
                "state": {
                    "label": "todo.value",
                    "value": "todo.value",
                    "alternatives": [
                            "key": "cut",
                            "value": "Cut"
                            "key": "copy",
                            "value": "Copy"
                            "key": "paste",
                            "value": "Paste"
                "command": {
                    "name": "setTodo",
                    "alternatives": [
                            "key": "Do cut",
                            "value": "cut"
                            "key": "Do copy",
                            "value": "copy"
                            "key": "Do paste",
                            "value": "paste"

@erickv it doesn’t work on the iOS app v1.6.49-413. Are you also using an iOS app?

The JSON you’ve posted is almost identical to the one I posted above here. The setter command is also specified in the capability JSON as:

 "commands": {
        "setMode": {
            "name": "setMode",
            "arguments": [
                    "name": "mode",
                    "optional": false,
                    "schema": {
                        "type": "string",
                        "enum": [

When I try to select an option from the list the ST mobile app throws an error “A network or server occured. Try again later”. I looked at the IDE and the setter command isn’t invoked either. I’m assuming that as per the instructions from @jody.albritton in the first post since the setter command is specified in the capability JSON the “command” metadata is not required in the DTH.

It has been 2 weeks since I reported this issue.

Also according to the docs:

  1. the list state doesn’t require a label key, I noticed that you’ve included it in your sample - is it required?
  2. list command supports supportedValues, but in practice the list control doesn’t seem to be using it. The control ignores the values in the specified attribute and instead shows all the commands listed in the presentation JSON. This is how it’s defined in the presentation JSON, is this correct? "supportedValues": "supportedModes.value", where supportedModes is an attribute specified in the capability JSON, which contains a list of values that is initialized by the DTH.
  3. The alternatives isn’t working either

Hi, @RBoy

The results that I’ve shared were reproduced at Android. I’ll proceed to test these results at iOS.

About the example implementation, I’ve set both label and value for a better reference of the result that I wanted to have. Also, since this is a basic implementation, without enum values or restrictions for supported values, I’ll proceed to create an implementation following these resource limitations and report them accordingly.

Another bug @erickv @nayelyz with changes to presentations not being reflected.

  1. Create a capability, presentation (with a custom “state” component in the detailView) and then device-config:create
  2. The platform will generate a VID (which I understand is a unique hash of the components in the configuration)
  3. Delete the custom capability
  4. Change the presentation custom component in detailView from “state” to “list”
  5. Regenerate the capability, presentation and configuration (don’t make any changes to the capability or configuration, the only change is to the custom control from “state” to “list” in the presentation above)
  6. The UI still renders the custom components as a “state” instead of a “list”

The bug is replicable consistently and the UI refuses to either generate a new VID or update the presentation for that VID.

Here’s is a custom VID I created that originally had a “state” as the custom control in the detailView. Then I deleted the capability and created it all again ONLY changing the presentation control from “state” to “list”, however the presentation:device-config:create command still returns the same VID and it still renders the component as “state” and not a “list”: 7c7c3ec0-db88-3fc2-b498-d4135a2a22dd

In this VID the custom control detailView in the presentation is defined as:

“detailView”: [
“label”: “Arm Mode”,
"displayType": “list”,
“list”: {

Where as when I query the VID it returns:

“capability”: “xxx”,
“version”: 1,
“label”: “Arm Mode”,
"displayType": “state”,

Notice it’s not taking the updated presentation for the control (I’ve deleted the capability and started over so it should pick up the latest presentation JSON).

If I change the configuration JSON (even a minor change not related to the custom component, e.g. change the dashboard control to something else) then presentation:device-config:create will generate a new VID and it renders the custom component correctly (as a “list” now since it was changed from “state” to “list” in the presentation JSON). It looks like once the VID is generated it doesn’t seem to want to update the presentation layout (displayType) for that VID.

Is there a way to force the platform to update the VID when the presentation changes? Let me know if you need more details.

EDIT: I tried it again by changing the presentation for the custom control from “state” to “stepper” and it still generates the same VID and renders it as a “state” (unless I make some other un-related change the configuration JSON which forces it to generate a new VID and then display the control correctly as a stepper)


Thanks for these details, @RBoy

As @nayelyz has shared at this post, the UI metadata is being cached and queried twice a day, and to avoid vid duplications, where the only changes were at the capability’s presentation, the system is not creating new vids.

However, it will create a new vid when the device-config changes (or when the DTH - Device profile is updated).

Also, this seems to be a workaround to improve testing new presentations. I will test it out and share the results with the team.

Hi, @RBoy

I’ve tested different formats of a capability supporting list display type, and below are my results:

  • When the attribute supports for enum values (this is part of the issue reported that commands are sending the key as argument). If the device handler uses directly the argument from the command, the response will trigger an error.

  • When the capability has a “supportedValues” attribute. Just like you’ve mentioned, all the values/arguments will be displayed ignoring the values declared at the attribute’s array (issue documented and reported).

Regarding this post, I’ve been able to make it work, so I’ll keep creating some implementations to collect the necessary information to document it.

All these results have been tested at:

  • Android app v1.7.50-21

  • iOS app v1.6.49-413

Erick, I don’t quite understand what you meant by this. You’re saying that the key should be passed as the argument. Can tell me what is the expected argument in your example that the command should receive?

Can you explain what you mean by:

How should the device handler use the argument?

From your example above, I would expect the DTH to define the command as:

def setTodo(argument)

And from your example above, what would be the argument passed by the control? (do cut or cut)

Hi, @RBoy

The issue that I’ve noticed is that the key assigned at the command’s alternative is being passed as the argument of the setter command instead of the value, e.g. I would expect that when I hit the command from the list (the visual key), receive as argument the value defined (cut, copy or paste).

Also, here’s an example on how this issue is impacting from the API’s perspective as well:

    "component": "main",
    "capability": "namespace.toDoList",
    "command": "setTodo",
    "arguments": ["Do Cut"] <--- This is the actual argument that is being passed

This would be considerably increasing the flow-control coding to parse their respective values (e.g. Button alike custom capabilities).

1 Like

Okay so you’re saying that it’s calling the command with an incorrect argument value (being substituted from the alternative list).

However, are you able to see the command being invoked (albeit with an incorrect argument value)?

I’m not seeing the command being invoked in the IDE Live Logs (just an error message on the screen) on iOS.

1 Like

Hi, @RBoy

I’ve been able to deploy the previous example (toDoList capability) with a basic DTH and just like you’ve mentioned, events are not being registered at the IDE.

Addionally, based on the activity from the mobile logs extracted, I’ve noticed that commands are being triggered following the patter mentioned Here but, they’re not getting correctly to the device’s handler.

This issue has been documented and reported properly.

1 Like

Appreciate the update Erick. Any idea on the ETA to get these fixed so I can continue with the migration efforts?


Is there a way to refresh a device in the new app following a DTH update (new publish) or a capability update through the CLI? so far I couldn’t do it without deleting the device and recreating a new one. In the Classic app there is no such problem.

Is there a list of all the displayType with visual examples? There are some that I can’t find. for ex - what is the displayType used for the colorControl capability?

Is there a way to create a displayType or is it a closed list?

Hello @SZaf,

For the DTH update, you could try the workaround of changing its name instead of creating a new device. We mentioned above that the device configuration presentation is cached, so you can also try the workaround mentioned there.

As for the available displayTypes, currently, the list is fixed, if you want to see the presentation of a predefined capability, you can use the command below to visualize the configuration in JSON format.

smartthings capabilities:presentation capabilityName -j

1 Like

Thank you @nayelyz

One more question: I couldn’t find any documentation regarding icons.
Below is a section from the switch capability’s JSON under dashboard. Is the ___PO_CODE_SMARTTHINGS_DREAM_SAC_SBODY_ON_T_SAMSUNG_CONNECT an icon?

If so, is there a list of all the icons for the new app, similar to (that is used in tiles)?

“alternatives”: [
“key”: “on”,
“type”: “active”

Hi @SZaf,
No, that value in the switch capability is not an icon, is part of the conventions of the predefined capabilities.

Here’s a list that was shared previously in this thread. You can use these values in the device profile metadata, for example:

  "name": "deviceIconTest",
  "components": [
          "label": "main",
          "id": "main",
          "capabilities": [
                  "id": "capabilityID",
                  "version": 1
          "categories": []
  "metadata": {
      "deviceType": "Fan",
      "ocfDeviceType": "",
      "vid": "xxx-xxx-xxx",
      "mnmn": "SmartThingsCommunity"