Custom Capabilities and CLI - Issues

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.


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.

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

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.

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.

UX plugins the short answer…

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