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.

The thing will receive commands from the mobile application. When you initialize the Thing-IF SDK, you will register a pointer to the callback function (i.e., action handler) for handling the command. When a command is sent from the mobile application, Thing Interaction Framework will deliver it to the thing via the MQTT push notification. When the thing receives the MQTT push notification, the SDK will execute 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 logics.

Action Handler

The following shows the prototype of the action handler callback function.

typedef kii_bool_t
  (*KII_THING_IF_ACTION_HANDLER)
    (const char* schema,
     int schema_version,
     const char* action_name,
     const char* action_params,
     char error[EMESSAGE_SIZE + 1]);

Based on this prototype, you will implement the action handler like the following. When you initialize the SDK, you will pass a pointer to this callback function as the action_handler member of the kii_thing_if_command_handler_resource_t struct.

kii_bool_t action_handler(const char* schema,
    int schema_version,
    const char* action_name,
    const char* action_params,
    char error[EMESSAGE_SIZE + 1]) {

  /* Do something. */

  return KII_TRUE;
}

The callback should return KII_TRUE when the specified action is successfully executed. Otherwise, it should return KII_FALSE. This return value will be notified to the mobile application as the Action Result.

The meaning of each parameter is as follows.

• schema: The name of the schema. Please set the same name that you've specified in the schema definition (Android, iOS).
• schema_version: the version of the schema. Please set the same version that you've specified in the schema definition.
• action_name: the name of the action in the command. Please use the same name that you've specified in the schema definition.
• action_params: the parameter of the command. The parameter will be passed as a JSON string.
• error: a pointer to the buffer for returning an error message. This is an output parameter. You do not need to set anything if the return value is KII_TRUE. If the return value is KII_FALSE, you can return an error message up to EMESSAGE_SIZE + 1 bytes (i.e., 51 bytes string with a NULL string terminator).

Parsing Actions

The action handler needs to parse and interpret the JSON string stored in the action_params for each action.

Before start parsing the JSON, please check the following:

• Check the schema and schema_version parameters

  We recommend you to check if there is no mismatch in the schema and its version. The version mismatch could occur between the mobile application and the program on the thing. Please read the overview for more discussion.

  How to handle the version mismatch depends on your service. You might, for example, accept the command sent from old mobile applications to ensure the backward compatibility while reject the command sent from new mobile applications.

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. The action name specified in the schema definition (Android, iOS) 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_params parameter

  Parse the parameter and execute the requested action. The action_params parameter contains the JSON string like this one:

  {"turnPower":true}
  

  The action handler can parse a JSON string in any way as long as the parsing is done safely. We recommend using the kii_json library that is embedded in the reference implementation.

Action Result

The thing returned the execution result of each action in the command as the action result. The mobile application can later browse the action result to check if the command executions were successful.

The SDK automatically generates the action result from the value returned by the action handler. The returned values of the action handler (kii_bool_t and error parameter) will be uploaded by the SDK 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.