Can MakerAPI be used to activate a device command that uses named parameters?
If not, please consider that as a future addition. E.g., maybe something like ...
I don't follow what this is for. Please provide a real example and explanation.
Sure. I've put together a fairly comprehensive set of libraries for use by Matter developers supporting clusters 0x0006, 0x0003, 0x0008, 0x0300 and I'm continuing to add others from my library as I clean up the code. See Build with Matter - Hubitat . Each of the commands in the library expands upon the standard Hubitat capabilities by adding support for endpoint selection as well as optional Matter command features. All of the commands use named parameters for clarity.
Since I was making these available for use by anybody developing a Matter driver, I was checking to see if these could be used without having a loss of "additional" functionality, such as the use of MakerAPI. If MakerAPI can't use named parameters, then that will just be a tradeoff that people have to make if they want to use these libraries.
I just realized, maybe a way for me to solve this is for all the named parameters to be included in a JSON-formatted string structure which can be passed by the existing MakerAPI as the Secondary Value", and have a version of each method in my library that accepts a String which then gets JSON-decoded and sent along to the named-parameter methods.
OK, I don't see this being something we'd put energy into right now. You're essentially making custom extensions, and that isn't a role for Maker API.
You shouldn't need to do this, or at least you don't need to go quite that far.
You'll definitely need to to take a Map as a parameter in your method; that is how "named parameters" in Groovy are implemented in the first place (I assume a creative "hack" on the part of the language designers for compatibility since Java has only positional parameters). That's one piece of the puzzle.
The second piece is that conversion from JSON objects to Groovy Maps is handled automatically for you. So, the "secondary value"/parameter in your Maker API call just needs to be a JSON object representing the Groovy Map -- again, no conversion back to a Map on your part is necessary.
Putting this all together: if you want to call a method in your driver like myCommand(param1: 1, param2: 2) from Maker API, all you'd need to do is pass this as the "secondary value" (parameter) in the Maker API call:`
{"param1": 1, "param2": 2}
...but URL-encoded, so with all the pieces of the URL, something like:
http://<hubIp>/apps/api/<appId>/devices/<deviceId>/myCommand/%7B%22param1%22%3A%201%2C%20%22param2%22%3A%202%7D?access_token=<accessToken>
I can't think of many built-in commands that take Maps as parameters, but setColor() is one, and this approach works for that (perhaps easier to think about since for whatever reason I think people always see this one actually as a Map instead of named parameters, but again, there's no difference).
6 Likes
Thank you. This JSON decode-to-map is the part that I was unaware of - with this, I think there is already the support I was hoping for, and it looks like java.net.URLEncoder is an allowed import, so that handles the URL encoding.
2 Likes
It is, but this seems like an odd use -- if you're trying to call this command from the hub, which seems like the only case where you'd need to use URLEncoder (as opposed to calling Maker API from some external sytem as you normally would), then you wouldn't need Maker API in the first place. I assume you know what you are doing but just wanted to mention this. 
