Executing Commands

The mobile application will send commands to control the thing. The thing will process the commands to achieve various services. See here for the overview.

A program running on a thing will be informed of the command's reception by the callback function (i.e., action handler) specified in tio_handler_start. Commands are delivered from Thing Interaction Framework to Thing via an MQTT push notification. When the SDK receives an MQTT push notification, it executes the action handler.

When a command contains multiple actions, the action handler will be executed multiple times per action. The execution of the action handler will be in the order that the actions were stored in the action array on the mobile application side.

The action handler callback function is executed from the push notification reception task (thread). Depending on the logic of the callback function, you may need to implement some exclusive control. See here for more discussion on the task control.

Please note that the SDK will automatically execute the MQTT related processes like the initialization. If you are using the reference implementation, you do not need to implement any logic.

Start command reception task

By executing the tio_handler_start method while setting an action handler callback function and user data (action_handler_userdata in the sample code) as its arguments, the command reception task will be created and executed.

You need kii_author_t for this execution. Get the value from the instance that you've used for onboarding. In this example, we are getting the value from the tio_handler_t instance. If you've onboard with the tio_updater_t instance, use the tio_updater_get_author method instead.

const kii_author_t* author = tio_handler_get_author(&handler);

tio_handler_start(
    &handler,
    author,
    tio_action_handler,
    &action_handler_userdata);

Action handler callback function

An prototype for the action handler callback function is as follows:

typedef tio_bool_t (*TIO_CB_ACTION)(
    tio_action_t* action,
    tio_action_err_t* err,
    tio_action_result_data_t* data,
    void* userdata);

You will define the action handler on the basis of this prototype.

tio_bool_t tio_action_handler(
    tio_action_t* action,
    tio_action_err_t* err,
    tio_action_result_data_t* data,
    void* userdata)
{
   /* Do something. */

  return KII_TRUE;
}

The callback should return KII_TRUE when the specified action is successfully executed. Otherwise, it should return KII_FALSE. In case when the action execution failed, you can put an error message in the err. You can also put an arbitrary message in the data regardless of if the action execution succeeded or failed.

Parsing actions

For each action, you need to parse parameters in the action and execute the corresponding process.

Before start parsing the JSON, please check the following:

• Check the alias parameter

  Check if the value matches with a known trait name. You can check its length with the alias_length parameter.

Then, identify and execute the designated action as follows. The action handler should return the execution result as its return value.

• Check the action_name parameter

  Identify the target action by checking the string in the action_name parameter. You can check its length with the alias_length parameter. The action name specified in the trait definition is stored in the action_name parameter. For example, the string like turnPower and setPresetTemperature are contained in the parameter. By making the string comparison, the action handler can determine which action to execute.

• Check the action_value parameter

  Parse the parameter and execute the requested action. The action_value stores the tio_action_value_t union containing various values.

Action result

The thing returned the execution result of each action in the command as the action result.

The SDK automatically generates the action result from the value returned by the action handler. The SDK will upload the returned values of the action handler (tio_bool_t, err, and data parameters) as the command result. When the command result is registered, Thing Interaction Framework will notify the mobile application via the push notification network. The mobile application thereby will be able to know the result of the command execution by the thing.