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.
Overall flow
The following diagram summarizes the overall action and command execution flow.
Step 1: Sending command from mobile app
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".
Step 2: Validating command (actions)
Thing Interaction Framework validates actions in the command sent by the mobile app. The Framework validates the actions on the basis of the corresponding trait definition. See Command validation for more details.
The command will not be sent to the thing if it is invalid; an error will be returned.
Step 3: Receiving and executing commands by thing
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.
Step 4: Sending command result from thing
The thing will report the command result to Thing Interaction Framework. The command result summarizes if the
Step 5: Notifying mobile app by push notification
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 notification 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).
Step 6: Getting command result
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.
Command and actions
Command structure
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). Make sure to register a trait that defines the data format in advance. Also, make sure that the thing that will receive the command is associated with the trait.
When sending a command, the corresponding trait alias needs to be sent to Thing Interaction Framework. This following example illustrates how you will send a command "turn on and reset the sensor" 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 sensor, for example, you might need a couple of actions ("Power on/off" and "Reset the sensor"). When you want to turn off the sensor, however, you might 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.
Action result
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.
Command validation
Upon receiving a command from mobile apps, Thing Interaction Framework will validate actions in the command on the basis of the trait. The validation will be executed on the basis of the content described in the trait's payloadSchema
.
The command example above is taken from the sample shown in Trait Alias Registration. Thing Interaction Framework will refer the trait alias LiquidLevelMeterAlias
and acknowledge that the version 1
of the trait LiquidLevelMeter
is to be applied when validating the actions turnPower
and resetSensor
. The trait specifies boolean values as the expected parameter for both actions, so Thing Interaction Framework will return an error if the parameter is not a boolean value.
Getting the command
When a command is executed by 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
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.
title
Command title. You can register any string of up to 50 characters.
description
Command description. You can register any string of up to 200 characters.
metadata
Command metadata. You can specify data which will be used by the application in any JSON format.