Custom Capabilities and CLI - Issues

Developer Programs Support
1

I thought I’d start a separate thread for perceived issues with the Custom Capabilities and CLI Developer Preview, as Jody suggested. I believe he had in mind one thread per issue, but that would be an awful lot of threads. I am keeping this initial post updated.

Apart from sometimes thinking the argument handling is a little inconsistent (sometimes it seems to want an =, sometimes it doesn’t mind), the only real issue I have with the CLI is probably actually an API issue. Update: But not anymore, more issues and and at least one is the CLI.

  • If you are working on changing capability presentations, but you already have a stable device config, there doesn’t seem to be any way to generate a new device presentation to include the new capability presentations.

  • (16th July) I understand the idea of avoiding generating duplicate device presentations, but if a device handler is using a custom capability that I created, I expect it to also use the capability presentation that I created too, not an older, possibly broken version of it. I know there are version numbers but they aren’t helpful when custom capabilities are still being developed.

  • Around about version pre8 (the internal version number isn’t always updated correctly), creating presentations from device configs stopped producing summary output by default, instead spewing out a device config file in JSON format.

  • Around about September, the API started adding presentationId and manufacturerName to device configs. Unfortunately the CLI and/or API cannot consume files with those fields resulting in an error.

  • The order of the entries in a device config is ignored when creating device presentations, however the order of the dashboard states and actions arrays fundamentally affects the tile display. So the first vid created, whoever created it, wins and the correct presentation can never be created.

Most of my issues are with rendering in the mobile app. These may well involve user error but include:

  • Dashboard state using a custom capability attribute works with alternative text but the state never seems to change. It is just stuck on active. As of 25th August, this is now working.

  • Dashboard actions using a ‘toggleSwitch’ with a custom capability either crash the app or do nothing at all. They certainly don’t run commands.

  • Detail view ‘state’ does not seem to respect alternative text for custom capabilities.

  • Detail view ‘switch’ does not seem to respect alternative text, and neither does it seem to respect text in the label other than the {{ … }} interpolation. The alternative text started working by mid-September.

  • Detail view ‘switch’ and ‘toggleSwitch’ command actions return the usual ‘network or server error’ pretty much instantly and do not run device handler commands.

  • Only one displayType is rendered per custom capability. Admittedly the custom capability being used for testing only has one attribute and this hasn’t been tested for capabilities with more than one. So this may not be an issue.

Observations regarding standard capabilities:

  • The standard capabilities structure their ‘commands’ differently. They don’t have the extra ‘name:’ inside the named command object. It is not possible to create a custom capability using the CLI or the API that doesn’t have this ‘name:’ in it. If you omit it, it is added automagically. They are out of spec with the documented API and SDK. (12th August) This now seems like it may have been corrected. Some of the blurb in the API documentation still has the extra ‘name:’ but the CLI isn’t adding it.

  • The standard capability presentations do not always correspond with the rendering in the mobile app. For example, temperatureMeasurement has a ‘slider’ displayType yet actually displays as a numeric value and a link to a graph. Similarly temperatureMeasurement and relativeHumidityMeasurement seem to be grouped together with a graph even though there is nothing in the capability presentation, device config or resulting device presentation suggesting this. So the device presentation isn’t the whole story. What else might be happening? How can we know what to reasonably expect?

Observations (added 15th July) adding to the above, and regarding Quick Controls:

  • Some standard capabilities such as ‘Switch’ and ‘Button’ are presented with ‘Quick Controls’ on the details page as a shortcut for specifying Automation actions. I have not had Quick Controls appear for the Switch capability in my own custom handlers, but I have had them appear for the Button capability.

  • No problem with there being Quick Controls, but there is absolutely nothing in the capability presentations or device configs that make any reference to these things. They are being magicked out of thin air in ways outside of our control. It is a bit soul destroying when you are methodically creating stuff according to a published API, knowing that what you end up might not actually be what you asked for, even if you’ve done everything correctly.

An observation (added 15th July) about the stock SmartWeather Station Tile DTH which has been updated with custom capabilities:

  • Existing custom attributes have been explicitly retained (i.e. attribute "attributeName" alongside the custom capability, which includes the same attribute names), apparently for backwards compatibility.

  • Attributes are set using BOTH sendEvent( name: "nameSpace.capabilityID.attributeName", value: "value") AND sendEvent( name: "attributeName", value: "value"), with the latter seemingly again for backward capability.

  • The CLI/Custom Capability tutorial makes no suggestions of either needing to retain backward capability, or of using nameSpace.capabilityID.attributeName in event maps, yet the one live example of using custom capabilities seems to be doing just that. That is a very confusing message.

Another observation, just because it is going to be mentioned sooner or later:

  • We can all see the tempting ‘iconUrl’ in the device config. The ‘ocfDeviceType’ in a DTH clearly has an influence on the icon used in the app. Those who have played with Device Profiles know you can do the same by specifying the device type from a limited list and the resulting icon appears in the presentation. So what is the score here?

Oh, and the long standing question:

  • It seems that when you change the ‘vid:’, and perhaps other elements of the definition, for a DTH in use by an existing device, this doesn’t get picked up by the mobile app unless you update the device (for example, editing the device in the IDE, changing the name, and updating). Is this how it is supposed to work? Are there other ways of doing the job? I know it isn’t an issue with the custom capabilities or the CLI, but it is rather fundamental to exploiting them.

  • Update (15th July 2020): In a thread discussing device profiles and UI manifests, @nayelyz seems to have suggested that the app caches the presentation (I believe twelve hours was implied), and so clearing the app cache can speeds things up. That might be consistent with what I see, with twiddling with the device busting the cache from the server end. If so that is really helpful, as we’ve been trying to coax this information out of ST for about a year now.

5 Likes
2

I believe that this is going to be deprecated in future. The iconUrl is definitely an attraction, but how it works is a mystery. If the dashboard component supports multiple states, you will need different icons for each state. I’m going to guess it’s an array or json structure to give it maximum flexibility.

3

I suppose I ought to add ‘Quick Controls’ as being another of the gifts that might be bestowed by the details page fairy. There really is an awful lot going on before presentations get rendered.

1 Like
4

Are you referring to the automation controls that show up in the detailView page? Like for Switch (timers controls) and Buttons (pushed/held actions)? If so, I’d be very interested in to know how they do that and how to replicate them.

5

Precisely what I mean.

They appear for the Switch capability in stock handlers (including virtual switches) but I don’t see them in my own virtual devices that are using the Switch capability in combination with others.

I do see them in my own Button handlers as long as the supportedButtonValues attribute has been defined.

6

UX plugins the short answer…

7

That is certainly what I assumed was responsible. It wasn’t so much a question, more just adding another example of features that are completely undocumented. It just feels like the plugin is overreaching itself somewhat. Stuff is going on down there that should be in the remit of the device config.

1 Like
8

@orangebucket
This!!

I just found this thread of yours. And I’m so glad I did.

I have encountered a lot of your mentioned issues already in the very short time that I have been looking into custom capabilities.

As you know, I have been posting a lot of questions in other threads in the last few days regarding custom capabilities and the CLI, in order to further my understanding of things in this particular field.

With the issues I have encountered to date, I thought I was just not fully understanding how things work, or going mad, or both. Finding this thread has reassured me that this is not necessarily the case.

So it seems that despite us following the instructions for creating custom capabilities and their associated presentations, as well as device configs, to the absolute letter, in addition to reading the documented API, there are some gremlins at play, part of an elite unit, which add some automagicness behind the scenes, completely outside of the control of our custom JSON configs?

Is that a fair statement to make?

9

I’d forgotten about this thread. The idea of separate threads didn’t seem to take off.

The really confusing thing now is that the way custom capability presentations work has changed. They now seem to directly take effect upon devices using them and I’ve found no way of bypassing caching of them so I have to wait up to twelve hours to see them.

I now find myself in the odd position of having written many mini-essays on the forum about how to handle the CLI, presentations and custom capabilities, yet having pretty much given up touching them myself as I no longer know what works.

An elite unit of gremlins dispensing automagicness seems to pretty much nail it.

The app was doing fancy stuff with stock capabilities long before the CLI and custom capabilities came along, and indeed not all stock capabilities even had a capability presentation when the punters were first introduced to them. I suspect you could probably find some that still don’t. So I think capability presentations for many stock capabilities are more like placeholders to make device presentations work.

Don’t get me wrong, some of the stuff the app produces is great. It is just completely undocumented. I’d rather the capability presentations just said they were using custom types instead of pretending they were using the same functionality we have to work with. As it stands they are nonsense.

In a vaguely related note, we see apps like STHM, ST Find and Smart Lock Guest Access displaying on cards on the dashboard. I don’t mind not being able to that in a custom app but it would at least be nice to acknowledge what it is I can’t do instead of just being taunted with it.

1 Like
10

I remember seeing the main thread get posted back in June. I was so hopeful.

Life got busy, and just now I noticed I cant open the old app at all. So I thought i’d give it a go and convert my custom DTH’s to the new app.

I completed all the steps for one of the easiest DTH’s I have (its my hot tub water stats, no commands multiple attributes) and am having issues. I thought lets go through that thread and see what i might be missing. So much scrolling, So many issues. over 1000 posts of people having issues, questions and the sort.

I cant possibly make it through 1000 comments to get up to speed of the current events, my stuff doesn’t work, so either:

  • Im doing it wrong
  • I need to wait 12 hours to see i did it wrong
  • There’s a bug i don’t know about
  • What im trying to do isn’t supported

Either there’s another thread I cant find and everyone’s stuff is working, or every ones custom shit is broke… right?