Custom Capability and CLI Developer Preview

You have to be aware that the dashboard tile has a ‘state’, which is the text written on it, and an ‘action’, which is the icon top right that you can press to run commands. These don’t have to come from the same capability. They are independent.

For the ‘state’ (the presentation has a ‘states’ array but only the first one is used in the dashboard), you are just displaying some text (the "label":). You might define that using interpolation of attribute values and then define some alternate text to be a bit more flowery. For standard attributes that is how the additional languages are handled.

For the ‘action’ you have to define which commands to run depending on the current attribute value. However you haven’t told it what the attribute is yet. That is what the "state": { "value": "attributeName.value", ... } is doing. Personally I think there should be an arm wrestling competition between the ‘state’ and ‘attribute’ camps in SmartThings, because they clearly are still battling it out for supremacy despite the confusion it caused in the the classic environment.

Well ‘working’ would be an exaggeration given I can’t get the mobile app to see my point of view. However I have:

"dashboard": {
        "states": [
            {
                "label": "{{binary.value}}",
                "alternatives": [
                    {
                        "key": "active",
                        "value": "Binary Sensor Active",
                        "type": "active"
                    },
                    {
                        "key": "inactive",
                        "value": "Binary Sensor Inactive",
                        "type": "inactive"
                    }
                ]
            }
        ],
        "actions": [
            {
                "displayType": "toggleSwitch",
                "toggleSwitch": {
                    "command": {
                        "on": "binaryactive",
                        "off": "binaryinactive"
                    },
                    "state": {
                        "value": "binary.value",
                        "on": "active",
                        "off": "inactive"
                    }
                }
            }
        ],
        "basicPlus": []
    },

At some stage that was output from the CLI, hence the ‘basicPlus’ on the end.

Yes, according to the SDK and the API there isn’t such a displayType as ‘status’, it is actually called ‘state’. Why on earth you’d want to call it that is a mystery. It is getting a bit like the Google Home app defining homes, with the default being ‘home’, which include Google Home devices. Doesn’t anyone have a thesaurus?

3 Likes

@erickv there’s a bug in the documentation:

In the detailView , under list for command , under name it says:

name refers to command name and key of the alternatives is the argument of the command

However the alternatives description it’s something completely different (looks like a copy paste from the dashboard description):

So now the question is what should be the value (assuming the key is the argument) for alternatives in a list command?

Also, how does one create multiple commands for each item in a list instead of using a single command with arguments ?

Thanks, that was the missing key for me. For some reason the CLI didn’t flag this and was returning other errors which kept throwing me off. I was missing the displayType definition. Onto the next step.

Completely re-wrote the tutorial and updated the tutorial to include screens from the video version of the tutorial.

1 Like

Does the ‘namespace:’ in the definition, which is historically typically the github username, need to be changed to match the namespace for the custom capabilities? It is shown as needing personalisation in a screenshot but it isn’t clear if it is meant to imply they are the same. I am pretty sure they aren’t but I thought it worth checking.

Can someone enlighten me why the temperatureMeasurement’s presentation use the “slider” displayType for the detailView, meanwhile using the states for the dashboard? Am i missing something with its logic? I would assume, that the detailView should be states as well.

@orangebucket, @erickv, @jody.albritton

{
    "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"
            }
        }
    ],
    "automation": {
        "conditions": [
            {
                "label": "___PO_CODE_SMARTTHINGS_DREAM_SAC_TMBODY_TEMPERATURE",
                "displayType": "numberField",
                "numberField": {
                    "value": "temperature.value",
                    "unit": "temperature.unit",
                    "range": [
                        -20,
                        50
                    ]
                }
            }
        ],
        "actions": []
    },
    "id": "temperatureMeasurement",
    "version": 1
}

Ok, I’ve got it working, and displaying what I want, but that is absolutely wrong with the slider in the stock capability presentations. I used temperatureMeasurement and atmosphericPressureMeasurement as reference. And it is so wrong. That should be state. Disregarding the UX plugin in the the background.

The ‘dashboard’ is just defining the layout of the elements used on the dashboard. In the mobile app you have a standard tile layout, the number of ‘states’ is one, and it is the line of text below the device name. Arguably it would have been better to use a different name for it to avoid confusion.

The ‘detailView’ is defining the tiles used on the detail pages. The ‘displayType’ is defining the design of the tile as a whole. Instead of just showing the temperature as text, a slider is being used for a visual view. That is just a design choice. It would seem more appropriate in a virtual temperature sensor where you could add a command to set it.

Again, we are going back to trial and error. Why on Earth would all the measurements have a slider as displaytype of the standard capabilities, when they are, as the name suggest, measurements. Nowhere has been displayed with the standard capabilities if temperature measurement was used the slider next to the value. (Instead it was using the graph UX.)

It is so much misleading and confusing. As I would believe that the measurement should be displayed with slider, as the standard capabilities using it.

It is ok to have a slider with the colors, but with a big dot in the middle. Even worth, it gives a numberField when I press it. Probably because I followed again the standard capabilities presentations.

In all my examples I make it the same as the capability namespace that is generated.

Ah I think I see what you mean, as it is something that has been bothering me. The capability presentations and device configs/presentations don’t necessarily match what you actually see in the app.

For example, temperature and humidity seem to be grouped together whether you like it or not. There is nothing obvious in the presentations to explain why this is happening.

The trouble is, if even the standard capabilities apparently don’t display as documented, why should we assume our custom capabilities pass through the process unharmed?

1 Like

If you could document each case you come across and make a new topic. We need to get feedback to the development team to address some of these issues.

Jody,

It is definitely the unspoken UX plugins in the back. The presentation uses slider, but the UX plugin defines it differently.

Ie.: Battery is a slider, a horizontal line, with colors ranges from 0 to 100. The adjusting knob is not there, the line has colors, the filling is according the percentage. And the adjusting option is not there as the knob is missing.
There are big differences in this regard between slider and slider, as the UX is different.
It is not complete this process without the connected UX plugins.

@jody.albritton
It is possible to use these custom capabilities in Direct Connected device ?
There are specific files in SDK , each capability has one.

So, in this case, I have to build my capability C file?

I don`t know if this is the best place to talk about this topic, but, I didnt found the information anywhere. Appreciate your help

Anyone used the iconUrl for the device configuration?

@jody.albritton is this the device icon on the dashboard page? What kind of files can be used here?

I updated the top post again with a video.

5 Likes

Thanks Jody, this is useful. What would really help is a working example of a custom DTH which implements a custom Dashboard control (e.g. toggleSwitch with a custom action), a custom command in the DTH and custom detailView with a few custom controls (e.g. a List, Switch and playStop controls, each with actions) and a custom Automation. I.e. a fully featured custom DTH with Capabilities, Presentation and Config sample.

2 Likes

More examples coming. This is just the basic how-to video. Need to cover the basics before launching into the more complex areas. We also need to gather feedback about issues with the basics first.

1 Like