Custom capability with list of supported commands

Developer Programs Writing Edge Drivers
1

Hi,

I’d like to create a custom capability that can be used by different devices.
Some devices support only a subset of commands. I think I need something similar to windowShade’s supported commands, where the device during initialization will provide the list of supported values/commands.
Is such functionality supported for custom capabilities?

My use case is for wall switch backlight support.
There are 2 values (on,off) that are supported by all devices. However, some switches allow the third mode, where the color of backlight changes, depending on the switch state.
I’d like to allow setting the third mode only for devices that actually support it.

Thanks

2

IMHO the backlight color belongs to the settings page as users will not change this setting often.

Also please think about 3rd party integrations.
I am afraid that the custom capability is not discoverable for Alexa/Google, so even basic on/off feature will be unavailable for users.

3

@veonua ,
Thank you for your replay.
I personally don’t see any problem displaying rarely used capability in detail view.

On the other hand, putting it into settings would mean the following:

  1. The current state of the device can not be
    queried/updated. This means the setting shown in settings page might not reflect the actual device state/configuration
  2. It is not possible to control backlight from automation.

Further, I think backlight logically fits better into capabilities model. It is actually a capability of the device, not its configuration.

1 Like
4

it can’t be true. settings are just a permanent storage under the hood so you can query update fields as you like.

It is not possible to control backlight from automation.

It’s an interesting case, never thought it would be popular to use the backlight in automation.
Just curious what kind of device it is.

5

In theory, yes. However even some of the most basic functionality of capability presentations that I’ve been waiting on since day one doesn’t seem to have be implemented yet (like using basic commands instead of setter commands) so I have no idea what actually works. @nayelyz and @erickv know stuff like that, and some other developers might have touched upon it.

Anyway the bottom line seems to be that for the list display types you can use the supportedValues key. That should be set to an attribute value of your choice that holds an array of the commands (so I guess the equivalent of supportedButtons or supportedWindowShadeCommands).

So in a Detail View the structure would be:

"detailView": [
  {
    "list": {
      "command": {
        "name": "setDoor",
        "supportedValues": "supportedValues.value"
      },

In the Automations it would be:

"automation": {
    "conditions": [
        {
            "list": {
                "supportedValues": "supportedValues.value",
...
    "actions": [
        {
            "list": {
                "supportedValues": "supportedValues.value",

I think that’s right anyway. Certainly supportedValues is the magic word that should help you find information.

1 Like
6

The difference would be in which enums for the command you can select? Eg. In windowShade you can select that in the list only appear the options “open” and “close”.

The option mentioned by @orangebucket is correct,supportedValues should be an attribute in the capability (it won’t be displayed) and it allows you to change the available alternatives for each device without having to create a specific device-config.

You can check other similar capabilities like thermostatMode as a reference.

7

@nayelyz ,
Thank you.
That is correct, some devices will show a subset (on,off), while others will show all three options (on, off, state).
I already looked at windowShade and thermostatMode capabilities, I just wanted to make sure that supportedValues attribute can be used also for custom capabilities.

8

No problem! Let me know how it goes :smiley:

1 Like
9

@orangebucket @ygerlovin @nayelyz I found this very helpful and wanted to check to see if anyone has published a generic capability as described. I am looking for one to use with a virtual device that uses the capability as input from a custom rule to get the temperature and humidity from multiple devices. Calculate dewpoint and alert when temperature intercepts dewpoint to alert potential condensation event. I have implemented this using the commands from heating and cooling setpoint capabilities for now but thought there should be a cleaner generic solution for anyone that wants to add command capability to augment a production capability and continue to leverage the default presentations. This would be an awesome addition to a virtual device example for newbies like me.

10

I should have said a bit more. I was thinking the generic command setter would take as input “component_name” ,“capability id”, “attribute name”, “attribute value”. So the generic capability handler would emit event to a virtual component, capability, attribute, value. And in my case call to calculate condensation and alert appropriately.

11

Hi, @Keith_Collins

Have you made any progress on your use case?
A single command cannot accept multiple arguments, but there’s the option to use several inputs, and each one would refer to an attribute and its setter.

12

@nayelyz Thanks for following up. It is disappointing that the automation UI doesn’t have an equivalent of the advance webUI that shows any command and it’s associated set of parameters and allows you to test the command with all of it’s inputs. I did figure out how to do a set of commands each setting in single attribute. I have written a custom rule to read from a device and set the attributes but not what I had hope for.

But maybe you can answer this:
Is there a way in the standard rules automation to capture the value of a device and send it to another? If zigbee device temperature updates then update virtual device temperature with that value?

13
14

@Andreas_Roedl Thanks. I used this very post as the model to write my own rule. I was hoping to find a solution using the app rules automation so none tech users could attach physical devices as input to virtual devices.

15

So, do you mean in the Routines tab on the SmartThings app? If so, it isn’t possible because it’s an advanced automation.
In the Advanced Users app, there’s a UI to create Rules. You just have to copy the IDs from the “Devices” section and use the correct JSON. This means only the “actions” section of the Rule (second key of JSON). For example:

[
      {
        "if": {
          "changes": {
            "operand": {
              "device": {
                "devices": [
                  "deviceId"
                ],
                "component": "main",
                "capability": "switchLevel",
                "attribute": "level"
              }
            }
          },
          "then": [
            {
              "command": {
                "devices": [
                  "deviceId"
                ],
                "commands": [
                  {
                    "component": "main",
                    "capability": "switchLevel",
                    "command": "setLevel",
                    "arguments": [
                      {
                        "device": {
                          "devices": [
                            "deviceId"
                          ],
                          "component": "main",
                          "capability": "switchLevel",
                          "attribute": "level"
                        }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
   }
]

It would help those users who aren’t experts using other tools like CLI and Postman, for example.

16

@nayelyz This example is helpful. I do find navigating the doc difficult and this was a concise example and link. Can you help me navigate to the complete set of actions available. This link Rules | Developer Documentation | SmartThings for example doesn’t show doc for “every” “interval” as in this example “every”: {
“interval”: {
“value”: {
“integer”: 1
},
“unit”: “Minute”
},

17

Do you mean to know other possible units you can use for the interval? In the API reference, you can find the properties supported by the Rules endpoint: API | Developer Documentation | SmartThings

18

I am
Feeling really dense. I don’t see anything in this link that documents interval and its parameters. Do I have to use the rules api to retrieve the valid set of parameters?

19

To confirm we’re on the same page, did you open the details of the properties listed there?
In this picture I highlighted the arrows where you need to click to open the details of such JSON key, starting with the array “actions”.

image
image777×771 29.6 KB

20

Got it. Now where do I find doc that defines conditions such as remains and was? The doc on automation just talks about the standard if, else, … TIA