Updating State

A thing can upload its state to Thing Interaction Framework. Uploading the state can take place at regular interval and when the command execution is done. The state is to be generated in the JSON format based on the schema definition (Android, iOS). See here for the overview.

When you initialize the Thing-IF SDK, you will register two pointers to the callback functions that returns the state (i.e., the state handlers). In these functions, you will implement the process for constructing the state as a JSON string. In the initialization sample code, we are registering the same function for both callbacks. You can, of course, register different functions.

  • State handler for sending the state when the command execution is done

    The SDK will call the state handler when it receives a command with the MQTT command reception task and finishes executing all actions in the command. If the command contains multiple actions, the SDK will call the state handler only once per the command reception.

  • State handler for sending the state at regular intervals

    The SDK will create a task (thread) and call the state handler from this task at the regular intervals. The interval is to be set with the function pointer upon the initialization.

In both cases, the state uploading is solely controlled by the SDK. You cannot explicitly update the state from the thing program.

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.

State Handler

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

typedef kii_bool_t
  (*KII_THING_IF_STATE_HANDLER)
    (kii_t* kii,
     KII_THING_IF_WRITER writer);

Based on this prototype, you will implement the state handler like the following. When you initialize the SDK, you will pass a pointer to this callback function as the state_handler member of the command_handler_resource struct and the state_updater_resource struct.

kii_bool_t state_handler(
        kii_t* kii,
        KII_THING_IF_WRITER writer)
{
  char buf[256];

  /* If the writer failed to write the first key in the JSON string */
  if ((*writer)(kii, "{\"power\":") == KII_FALSE) {
    return KII_FALSE;
  }

  /* If the power is on */
  if (get_power() != 0) {
    /* If the writer failed to write the first value in the JSON string */
    if ((*writer)(kii, "true,") == KII_FALSE) {
      return KII_FALSE;
    }
  } else {
    /* If the writer failed to write the first value in the JSON string */
    if ((*writer)(kii, "false,") == KII_FALSE) {
      return KII_FALSE;
    }
  }

  /* Send the remaining part of the JSON string to the buffer. */
  sprintf(buf,
      "\"presetTemperature\":%d,\"fanSpeed\":%d,\"currentTemperature\":%d,\"currentHumidity\":%d}",
      get_presetTemperature(),
      get_fanspeed(),
      get_currentTemperature(),
      get_currentHumidity());

  /* If the writer failed to write the remaining part of the JSON string */
  if ((*writer)(kii, buf) == KII_FALSE) {
    return KII_FALSE;
  }

  return KII_TRUE;
}

In this example, we're creating a JSON string like the following. This JSON string corresponds to the class defined on the mobile side for getting state (Android, iOS).

{"power":true,"presetTemperature":25,"fanspeed":5,"currentTemperature":28,"currentHumidity":65}

The parameters of the callback function are as following:

  • kii: This is a struct pointer of the SDK. This is a part of the struct that has been initialized as the kii_thing_if_t. We need this to use the writer.
  • writer: This is a pointer to the function that output the JSON. It is the API for string output provided by the SDK. See KII_THING_IF_WRITER for more details.

The callback function should return KII_TRUE when it successfully get the state, otherwise return KII_FALSE. If it returns KII_FALSE, the SDK will not execute the state updating (i.e., will not upload the latest state to Thing Interaction Framework).

KII_THING_IF_WRITER

KII_THING_IF_WRITER will be passed to the state handler as a parameter. This is an API for writing the string. In the state handler, you can use this writer to output the state as a JSON string.

The prototype of the KII_THING_IF_WRITER is as follows:

typedef kii_bool_t (*KII_THING_IF_WRITER)(kii_t* kii, const char* buff);

  • kii: Specify the kii that is passed to the state handler as is. This is used internally by KII_THING_IF_WRITER to distinguish the target to write the state.

  • buff: This is a pointer to the string you want to write.

KII_TRUE will be returned when the output is successful. KII_FALSE will be returned otherwise.

KII_FALSE will be returned when the output buffer runs out. This buffer is to be specified as the buffer member of the kii_thing_if_state_updater_resource_t struct upon the SDK initialization.

Please refer to the state handler implementation example for an example of how to use the KII_THING_IF_WRITER.