Action and Command Execution
You can send commands to manipulate things from mobile apps. The things return the result of the command execution and error information. This information will be notified to the mobile apps via the push notification.
If you are using a gateway, you can send commands to end nodes. You cannot send commands to the gateway.
The mobile app, through its UI, gets the command for manipulating the target thing. The command is sent to Thing Interaction Framework. Here, the command can have some parameters like "turnPower:true".
Thing Interaction Framework uses the MQTT push notification to send the command to the target thing.
When the thing receives the push notification, the SDK automatically calls the action handler. By writing the program for controlling the thing hardware in the action handler, you can manipulate the thing based on the given parameters.
The thing will report the command result to Thing Interaction Framework. The command result summarizes if the command execution was a success or not.
Thing Interaction Framework sends a push notification to tell the mobile app that the command was executed. At this point, only the command ID will be notified.
The push notification can be sent via the available push notificatin networks, depending on the mobile app platform.
If the owner is a pseudo user, the command ID notification is sent only to the device that has sent the command. No push notification will be sent to other devices that share the thing. If the owner is a normal user, the command ID notification is sent to all the devices associated with the owner by "device installation" (Android, iOS, REST).
The push notification sent to the mobile app only contains the command ID. The mobile app can use this command ID to get the command and its result.
By getting the command result, the user will be able to know if the command execution was a success and if there was any error.
As illustrated in the figure below, a command is composed of an array of one or more actions. The order in the array has the meaning; the thing that receives the command will execute the actions in the order they are listed in the array.
Each action can have a parameter in the JSON format. You can use any JSON format. You can, for example, use the JSONObject and JSONArray to define multiple fields (e.g., the RGB value of the LED light).
The following figure shows an example of data sent to Thing Interaction Framework when we send the command "Turn the power of the air conditioner on, set the preset temperature to 25 degrees, and set the fan speed to 5". The figure illustrates the data send to Thing Interaction Framework.
A command is composed of multiple actions to accommodate various situations. A set of necessary actions depends on the situations. When you want to turn on the air conditioner, for example, you will need a set of three actions ("Power on/off", "Set the Preset Temperature", and "Set Fan Speed"). When you want to turn off the air conditioner, however, you will need only one action ("Power on/off"). When designing actions, you will need to define not only conceptual sets of actions but also sets of actions which are appropriate for situations where those are sent to things as a command.
Also, make sure to design actions based on the capability of the target thing. On the thing, the callback function (action handler) will be called per action when the command is received. If the restriction of the thing hardware forces you to handle parameters for multiple operations in one shot, you might want to put these operations into one action to make the implementation easy.
You will define the actions you've designed as the thing schema.
Each action has the action result. An action result is composed of the success/failure status and the error message.
In the flow diagram at the top of this page, we've shown the command result as the independent data. Actually, there is no class for the command result in the SDK. The following figure illustrates the actual data structure. As you can see in the figure, the command will have an array of the commands and their command results.
You cannot put any parameters on the command result. Please use the State if you want to pass some values from the thing to the mobile apps.
When a command is executed by the request from a mobile app or is fired by the Trigger, the command is first registered on Thing Interaction Framework.
A command ID is assigned to the registered command. The command ID becomes a key for getting the latest command status. In particular, a mobile app can use the command ID to get the command result after the thing returns the execution result.
There are two ways of getting the command:
- Get a command with its command ID.
- Get all registered commands.
Please read the Thing-IF SDK development guides for the details.
Command details can be registered when a command is sent to Thing Interaction Framework. Such registered details can be fetched by the feature of getting command.
Thing Interaction Framework does not interpret command details. You can register any information such as strings or icons to be displayed on the user interface of your mobile app.
You can register these items as command details. All the fields are optional. These details will be associated with the command and saved as shown in the below figure.
Command title. You can register any string of up to 50 characters.
Command description. You can register any string of up to 200 characters.
Command metadata. You can specify data which will be used by the application in any JSON format.