Actions on Google - What is the relationship between commands/devices/executions in the Google Home EXEC input and response?

Question

This question concerns the Actions on Google Smart Home documentation Create a Smart Home App, specifically the action.devices.EXECUTE section.

We are somewhat confused regarding the exact relationship between the list of 'Command' objects and their associated lists of Devices and Executions, especially regarding how these are translated to a response.

Based on the documentation, we believe that the intent is for Commands to be processed in order: top to bottom. Per Command, each Execution is processed (again, top to bottom) for each device ID in the Command.

A response, if we understand the description correctly, could include up to 4 Commands per initial Command in the input (one for SUCCESS, PENDING, OFFLINE & ERROR), each with a list of device IDs for which that result is appropriate.

There is no mention of Executions in the response, however. Does this mean that if 1 execution for a device fails (out of multiple) that in the response it is listed under ERROR, despite other executions for the device succeeding?

For example, if a command comes in to turn on a light and set its color to blue. Turning it on succeeds, but some arbitrary error prevents the color from being set, then what should the response format look like?

Thank you for reading.

Answer 1

A commands array will contain all of the devices that are supposed to controlled with this command. There is an additional execution array which provides the command and parameters.

If some devices could not successfully be controlled, there should be an error returned for that device id, as shown in the documentation.

For any particular device, it may be odd to think of a scenario where one command is successful but another failing. In that case, you will need to think of the reason that makes the most sense, perhaps error protocolError or unknownError.

Every command is meant to be processed simultaneously, or in parallel. If you cannot make all of the changes that the user requested, it may be more consistent if no command was executed at all. So your device could be turned on/off, but if color is broken it should fail if both commands are sent at the same time.