I would like to understand how to get a full list of capabilities.
I try to list capabilities using the rest API call : api/v1/capabilities.
But for example, I’ve got a cooktop device from samsung.
When I ask capabilities for this device, I’ve got some result with samsungce prefix, for exemple:
{
“id”: “samsungce.deviceIdentification”,
“version”: 1,
“status”: “proposed”,
“name”: “Device Identification”,
“ephemeral”: false,
…
But if I call the listing endpoint (api.smartthings.com/v1/capabilities), the capability is not there.
That endpoint only lists standard capabilities. I am not aware of an endpoint that lists all capabilities. @orangebucket might know of an unpublished API that might.
I am not aware of one, but I don’t really see why there would be one. The /capabilities endpoint shows the stock capabilities and users can see the custom capabilities created in their own namespaces, or those of any organisations that they are members of, with /capabilities/namespaces/{{namespace}}. I can’t see why users should expect to be able to get listings of all the custom capabilities created by another user or organisation (such as those with the samsungce namespace which is Samsung Consumer Electronics).
Obviously capabilities have to be public to be useful but only the stock capabilities in the defaultsmartthings namespace are really a shared resource. Developers should be using the stock capabilities and if those aren’t adequate they should be using their own custom capabilities. If they use those belonging to another user or organisation they risk them being changed or deleted without warning.
My question is because when you ask a device for it capabilites, they will return stock capabilites as well as custom capabilites.
This is the case for example for my oven devices:
If I undestand you, the correct way to do things is to ignore this organization / custom capabilities, and just work with stock capabilities.
To let you undestand better my test case, I’m currently working on an integration between smartthings and a thid party home automation system (openhab).
So I try to expose almost all capabilities that i’ve found during device enumeration, and it seems that there is some interesting value to get from custom capabilities.
Hi, @lo92fr. Welcome to the SmartThings Community!
It’s not about a correct/wrong way of doing it. The thing is that custom capabilities are a special case where only the device integrator has further information on how they work. In this case, Samsung, since those capabilities don’t belong to SmartThings.
So, in case you expose it to users, they could work as expected or not, especially because Samsung devices use the OCF protocol which means they work on the App level (more details here) and we’ve seen in the past that commands that come from the API are not processed as expected by the physical device even when we use standard capabilities in the request.
The above depends on how the device was integrated, sometimes you can also see there are capabilities populated in the app but the values in the API are empty and that’s because the device integrator must expose this information there as well, otherwise, they will be only visible in the app due to how the communication works.
So, this kind of device is a special integration that you should be careful to work with.
Custom capabilities are created by users or organisations for their own purposes. We don’t know what those purposes are or how the capabilities are intended to be used unless they tell us. If we see how they are used in written code or monitor the attributes in real use we may be able to draw some reasonable conclusions, but that is about it. We also don’t know the history or plans for the capabilities. Again we may draw some conclusions based on whether they are being used and for what, and indeed by who created them. The bottom line is that the user or organisation that created a custom capability can modify or delete it at their discretion, regardless of whether it is still in active use.
When I claimed ‘Developers should be using the stock capabilities and if those aren’t adequate they should be using their own custom capabilities’ I was presenting my own interpretation of how custom capabilities are intended to be used, and I was particularly thinking about their use in creating device integrations. If you are using a custom capability created by a third party you are giving away a degree of control. Innocent changes made by the owner of a custom capability may directly affect how your device is presented in the app or even completely break it.
It sounds like your use case is more about consuming custom capabilities and it could be argued that they are no different to any other capability in many respects, with the major difference being that there is more example material and documentation to work with for stock capabilities. You rather have to make your own judgement as to what they can offer you.
Nayely has also pointed out that Samsung appliances tend to be particularly quirky as they were developed around OCF protocols based on device to mobile app communications and basically using the app as a fancy remote control. The SmartThings model is based on device to hub, device to cloud and cloud to cloud communication with the app largely being a client for the cloud based API. There has been some integration of the Samsung stuff into SmartThings but the users have never had any real explanation of how and where it is being done.
