Capability Presentations implementation status

It would be helpful if the reality of capability presentations could be documented somewhere so we can know what is supposed to be working, what has been overlooked, and what is broken.

In particular, for each capability:

  • Is there a capability presentation for the capability? I believe some might be missing. Don’t make me have to look.
  • If there is, which of dashboard state, dashboard action, detail view, automation condition and automation action are defined? Again I believe some might be incomplete. For example they might be completely ‘null’ presentations when they should reasonably have an automation command. Don’t make me have to look.
  • Which of the five bits just mentioned are actually implemented in the app and are they implemented as per the presentation or in a custom fashion? We need to know what we should be seeing to know that we aren’t seeing it.
  • Is it all supposed to be working?

We could also do with a status update on capability presentations with regard to custom capabilities. Specifically:

  • Which bits documented in the API are actually supposed to be working fully, which bits display something but aren’t working, and which bits aren’t implemented yet?

These questions are completely valid, thank you for sharing. We’re constantly updating the developer documentation.

Most capabilities have a presentation, the ones missing are generally those that are not used to display something in the app. Some can be identified because they have no attributes like configuration, healthCheck, etc. but that’s not always the case (Eg. Refresh) but this one includes a “pushButton” for those clients that don’t support the page swipe.

However, I can share with the corresponding team that it would be useful to see the details of each capability presentation in the “capabilities reference”.

Do you mean that an example of how these are shown?

  • Display types for a custom capability
  • Standard capabilities

I’ll also share this with the corresponding team, I understand it’s important to differentiate the features that shouldn’t have issues so we can report them when they do.

@nayelyz from what I understand the developers are asking, and have been for some time, is that the documentation has everything, literally everything documented in one place, not scattered and hard to find, with incomplete details. They spend a lot of time trying to understand what is and isn’t possible, instead of just working on doing stuff.
If the ST engineers made a list, and documented clearly everything they know about the platform as it is today, it would save a lot of time for the community developers, and I dare say a lot of your time responding to things that should be publicly available. So, in a word everything, everything should be documented in one easy to find place, let’s help the coders.

1 Like

I think @Alwas has pretty much nailed it on a general level.

It is really about knowing what is supposed to be working. If I look at something like the bypassable capability (whatever that is) I can see a live capability with an attribute that doesn’t have any presentation whatsoever. I’ve no idea of knowing if that is deliberate, an oversight, or one is pending. What I do know is missing capability presentations used to give errors when messing around with device configs.

Or if I look at speechSynthesis I can see a capability that has a presentation with a detail view but which doesn’t have an automation action defined (which is a crying shame). I don’t know if that is deliberate, pending or an oversight.

If I look at notification (another ridiculously overlooked capability) I can see a capability with a detail view and an automation action. When it was first introduced the detail view didn’t display and the automation action couldn’t be used because the automation couldn’t be saved. I had no way of knowing if it was supposed to be working or not. Incidentally the detail view still doesn’t work.

We do need to know when capabilities aren’t implemented using their presentations, otherwise how do we know if there is an error?

One of the most infuriating things in the last year or two has been the capability presentations in the API. When those were first launched pretty much nothing in it had actually been implemented. I’ve still no idea which bits are working.

1 Like

Ok, thank you both for sharing your opinions about this. I’ll share them with the corresponding team. We encourage everyone to share their ideas on what to improve in the documentation.
Not all have the same experience when they start to interact with the ST platform and sharing what made you struggle is really helpful for the future developers. :+1: