Updating and Browsing State

A thing can upload its state to Thing Interaction Framework. You can browse the uploaded state.

In this guide, we will explain how to upload a state from a thing and how to browse the uploaded state on the developer portal.

Uploading state

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 a trait registered in Registering Thing Capability. See State Registration and Retrieval 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 have registered 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);

On the basis of 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 members 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];

  /* Set the JSON string to the buffer. */
  sprintf(buf,
      "{\"LiquidLevelMeterAlias\":{\"level\":%d}}",
      get_currentLevel());

  /* If the writer failed to write 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 sample trait definition introduced in Add Trait.

{"LiquidLevelMeterAlias":{"level":40}}

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 gets the state, otherwise returns 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.

Browsing state

You can browse the state on the Thing Console of the developer portal.

See Manage States for how to use the console.