When a smart app or the client calls a device command like
refresh, it’s not actually directly calling the method. The platform first takes the command and arguments and checks if it’s a command declared by a capability the device implements or a custom command, then it loads up the DTH and calls the command method, then it executes the string that’s returned as a hub action and creates a command event.
When the platform calls
parse() with a device message from the hub, it goes through the returned values and converts all Map objects to device events, and takes all HubAction, HubMultiAction, etc objects and executes the enclosed commands.
This API was put together pretty quickly when we first launched. They thought we’d only be needing to create events from parse and commands from command methods, so that’s why they went with the declarative interface. Obviously it’s a mess now and we want to revamp the whole DTH system, but there’s a lot going on.
There was a time before
sendHubCommand() was added when we realized we wanted to be able to execute commands from
updated() so we added code to execute any HubActions returned from that. We couldn’t just treat it like a device command because there were already lots of DTHs implementing
updated() and returning who-knows-what due to the dynamic nature of Groovy.