Custom Capability and CLI Developer Preview

maybe I am not able to see, where does the first post explain how to use the added presentation within the DTH code ?
I want to start a function when the button is clicked and I want to set the value of “currentState.value” within the code at some point.

Not sure what you. mean by ‘use the presentation’. So you have your presentation showing. In you capability and presentation, did you link the button (switch) to a function? Did you create that function in your DTH? To set any device value, you have to use ‘sendEvent’.

“did you link the button to a function ?”
I don’t know how to do that. I have my functions from the DTH but how do I link the button to that function ? I could not find this information anywhere.

“to set any device value, you have to use ‘sendEvent’”
Ok. I already do that in my DTH for old ST app with its states.
But how do I address the new custom capability values with sendEvent ?

Ah OK, I think you may have skipped quite a few hours of learning here.

When you define your custom capability you define it with attributes and/or commands which then work exactly the same way as those for stock capabilities do.

When you are working with a stock capability like ‘Switch’ you define it in your code using capability "Switch". It has the attribute switch which takes the values on and off and also defines the commands on and off. When you click on an on/off button in the app, or use an automation, you are using the commands, which are implemented as the methods on() and off(). The actual value of the attribute is typically set in response to messages received in the parse() method using e.g. sendEvent(name: "switch", value: "on") (sometimes createEvent), or for devices that don’t communicate their current state you send the events in the on() and off() methods.

So suppose you have defined a custom capability ‘My Capability’. You will define that in your DTH using the namespace that gets allocated to you when you create the capability in the CLI, and the ID of the capability. So something like capability "ankletreehorse12345.myCapability". Supposing that has the attribute ‘currentState’ that takes the values ‘active’ and ‘inactive’ and the commands ‘setActive’ and ‘setInactive’. You will define the command methods setActive() and setInactive() and set the attribute using sendEvent(name: "currentState", value: "active") and sendEvent(name: "currentState", value: "inactive"). So basically the same approach as stock capabilities.

Now let’s look at the interesting bit of your capability presentation. I’ve given it a tweak to match the description above. It is telling the app to display your capability as a ‘toggleSwitch’ which is a type of on/off switch. As luck would have it, you’ve picked the same display type that I’ve been waiting on for the last how ever many months it is and it doesn’t actually work properly yet. However if it did …

"toggleSwitch": {
				"command": {
					"on": "setActive",
					"off": "setInactive"
				},
				"state": {
					"value": "currentState.value",
					"on": "active",
					"off": "inactive",
					"label": "{{currentState.value}}",
				}
}

The "state" section tells the app how to interpret the current state of your capability. From the top it says that the current value is the value of the currentState attribute, the value you want to correspond with the ‘on’ state of the switch is active, the value you want to correspond with the ‘off’ state is inactive, and you want the text description in the tile to be filled out with the value of currentState i.e. active or inactive. In theory you could have a label like "The current value is {{currentState.value}}" but last time I checked the extra text was being ignored. The double braces are signifying variable interpolation in a string, which is why you sometimes see {{currentState.value}} and elsewhere just currentState.value.

The "command" section says what is meant to happen when the button/switch is toggled. This doesn’t work at the moment. However what you do is define the command to be called when the button is being put into its ‘on’ state e.g. setActive, and for the ‘off’ state e.g. setInactive. So that would call the setActive() and setInactive() commands in your DTH.

Your original capability presentation has the extra entry “name” in the “command” section. That is used when your capability is defined with a ‘setter command’ instead of individual ones and the other entries define the arguments. So if you added "name": "setCurrentState" to the above your DTH would be called as setCurrentState("setActive") or setCurrentState("setInactive").

I think that is as much as I want to say on the subject at the moment.

10 Likes

thanks . it is clear for me now. I will try to implement this.

I tried with the following command:
sendEvent(name: "faithboard04631.androidTv.currentState", value: "on", isStateChange: true)
it works. now I can see the state “on” on the device view.
it also works with this one:
sendEvent(name: "currentState", value: "on", isStateChange: true)

However, I need a multi value display with following possible states:
on, off, playing, standby, stopped

So I changed my json as:

{
“dashboard”: {
“states”: [
{
“label”: “{{currentState.value}}”
}
],
“actions”: ,
“basicPlus”:
},
“detailView”: [
{
“label”: “Current State”,
“displayType”: “toggleSwitch”,
“toggleSwitch”: {
“command”: {
“on”: “setActive”,
“off”: “setInactive”
},
“state”: {
“value”: “currentState.value”,
“on”: “active”,
“playing”: “playing”,
“off”: “off”,
“stopped”: “stopped”,
“standby”: “standby”,
“label”: “{{currentState.value}}”,
}
}
}
],
“id”: “faithboard04631.androidTv”,
“version”: 1
}

but when it returns it does not return states other than off and on.
what can I use to display multi-value state ?

And if the toggleSwitch commands do not work, is there a working button to bind with my custom commands ?

thanks

is there a working profile that we can use as custom buttons in our custom capability ?

I can’t get this thing to authenticate for the life of me.
I’m on OS X. It’s installed in /usr/local/bin
Folder .config/@smartthings/cli exists
This is the error I get when trying to authenticate

You need a PAT token and the token goes into the config.yaml

default:
	token: xxxx-xxx-xxxx

@jody.albritton
I generated a token with all permissions, and copied your config.yaml except replaced the xxxx with my token.

This is what I get:

Thanks, was getting the same problem and removing those two lines fixed my issue.

@jody.albritton I’ll save my frustration details and will try to be a bit more pragmatic with some recommendations:

  1. Would it be possible to put a known issues section in the tutorial/first post with some work-around so devs doesn’t need to search/read over 600 posts?
  • I first ran into the authenticator issue
    received “server_error” error when trying to authenticate -> Generating the token manually works as a work-around. I think a lot of devs here ran into the same issue.
  • The request is malformed. when trying the presentation:device:config:create and needed to remove two lines as part of an auto-generated file as a work-around.
  1. Considering we are almost couple days of the dead-line of the migration and seems like lot of us is still going through the churn/issues that it’s not even solved, would it be possible to have a chat to see if there would have any possibility to extends that deadline?

It really does feel wrong to me that there seems to still have soo many issues but yet, the expectation is that we work around the clock to get all of the migration. We’ve invested a lot of time and effort to build the plateform, to grow the ecosystem and expecting everyone to go over all of the migration in such a short period of time does not really seems reasonable to me.

my 2 cents.

5 Likes

@jody.albritton @nayelyz

I cannot upload my device config. Here is the error I get.

And here is my json

You. need to remove presentationID and ManufacturerName. For some reason the generate adds these but create won’t accept them Another issue with the latest CLI.

Posted about this a while ago but, no comments and no fixes:

1 Like

This is something we have fixed and are pushing out to production very soon. The generated response shouldn’t have that presentation ID, that’s just confusing. Thanks for the salient feedback

ToggleSwitch by definition is going to be a 2 value button. It has some predefined commands like “on” and “off”

If you look in detailView -> list this display type supports multiple values that you would choose from a drop down, this seems like it might be a better fit for your use case?

For the sake of transparency these issues are being checked daily and we are hard at work to address these failing commands with the appropriate teams. We recognize the impact of display type commands not working and we in engineering are on this.

2 Likes

Thanks Morgan. There are many DTH’s released (given the upcoming deadline) with some controls coded in there that comply with the documentation. We’ve taken a “leap of faith” in releasing them, they’re not responding/working exactly they way the documentations says they should, but the hope is that the these controls will start working as documented when the reported bugs are fixed and pushed into production.

I can also say that a fix is being looked at in lower environments and is supposed to go to production next week for fixing toggleSwitch and textField not sending commands.

This should be a mobile only update, so existing presentations should start working for these 2 display types.

Can you describe the documentation discrepancies to me RBoy so I can review the difference between expected and actual? I assume by your description that these aren’t flat out “bugs” (something just not working) and that there is a difference in how they operate from what you expect?

Hard to say what’s a bug and what a “difference”. I’ve raised a lot of tickets in the past few weeks with detailed samples/codes to replicate of the bugs and differences I’ve come across. @nayelyz recently consolidated/grouped them.

One example ticket no 1060312. List detailView not processing key from state alternatives while displaying attribute values. Instead it’s matching the key from the command alternatives. As per the documentation the displayed value on the control should be matched against the key from state alternatives array where as the displayed value from the drop down list should be taken from the command alternatives array. In reality, it’s matching both from the command alternatives array. Not every attributes state will have a corresponding command, so you can many more display states alternative than command alternatives. I’ve added samples to my ticket to replicate the issues.

I’ve been told for “now” the list of alternatives in the command and state should be identical as a workaround. That’s not a practical situation and as per the documentation it can have differences (which is more realistic as I explained earlier), so technically while “list” is working, it’s not displaying what it should and so I don’t know if you’ll call this a bug or a difference. The hope is when the ticket is fixed it’ll display the alternative from the state so that the DTH (which is already released) will show the correct value.