Initializing SDK and Onboarding Thing

To allow a mobile application to manipulate a thing, you need to bind the application to the thing. This binding process is called Onboarding.

See Thing Onboarding in the Function Guide to learn the basics of the onboarding (e.g., flows and steps).

In this guide, we explain how you can onboard a thing in the following steps.

Step 1: Initialize Thing-IF SDK

First, we initialize the Thing-IF SDK.

The initialization code is as follows.

#define EX_COMMAND_HANDLER_BUFF_SIZE 4096
#define EX_STATE_UPDATER_BUFF_SIZE 4096
#define EX_MQTT_BUFF_SIZE 2048
#define EX_STATE_UPDATE_PERIOD 60

kii_bool_t result;
kii_thing_if_command_handler_resource_t command_handler_resource;
kii_thing_if_state_updater_resource_t state_updater_resource;
char command_handler_buff[EX_COMMAND_HANDLER_BUFF_SIZE];
char state_updater_buff[EX_STATE_UPDATER_BUFF_SIZE];
char mqtt_buff[EX_MQTT_BUFF_SIZE];
kii_thing_if_t kii_thing_if;

/* Prepare the command handler. */
memset(&command_handler_resource, 0x00, sizeof(command_handler_resource));
command_handler_resource.buffer = command_handler_buff;
command_handler_resource.buffer_size =
    sizeof(command_handler_buff) / sizeof(command_handler_buff[0]);
command_handler_resource.mqtt_buffer = mqtt_buff;
command_handler_resource.mqtt_buffer_size =
    sizeof(mqtt_buff) / sizeof(mqtt_buff[0]);
command_handler_resource.action_handler = action_handler;
command_handler_resource.state_handler = state_handler;

/* Prepare the state updater. */
memset(&state_updater_resource, 0x00, sizeof(state_updater_resource));
state_updater_resource.buffer = state_updater_buff;
state_updater_resource.buffer_size =
    sizeof(state_updater_buff) / sizeof(state_updater_buff[0]);
state_updater_resource.period = EX_STATE_UPDATE_PERIOD;
state_updater_resource.state_handler = state_handler;

/* Initialize the Thing-IF SDK. */
result = init_kii_thing_if(&kii_thing_if, EX_APP_ID, EX_APP_KEY, EX_APP_SITE,
        &command_handler_resource, &state_updater_resource, NULL);
if (result == KII_FALSE) {
  /* Handle the error. */
}

The initialization is complete by calling the init_kii_thing_if function. If the function is successful, it will return KII_TRUE.

Here is a list of parameters that the init_kii_thing_if function takes.

  • &kii_thing_if

    This is a pointer to the kii_thing_if_t struct that stores the SDK information. This is the API output parameter, so we are only passing the allocated memory.

    In the subsequent function, we will pass the initialized kii_thing_if_t struct. We need to preserve the initialized kii_thing_if_t struct while the program on the thing is running.

  • EX_APP_ID, EX_APP_KEY, and EX_APP_SITE

    Specify the AppID and AppKey you've got on the developer portal in the EX_APP_ID and EX_APP_KEY, respectively. See Create an Application for the details.

    In the EX_APP_SITE, set https://api-jp.kii.com/ or "JP".

  • &command_handler_resource

    This is a struct that stores the information for receiving the command and for sending the command result. This is the API input parameter, so you will prepare the following members.

    Member Description
    buffer The buffer the SDK uses for sending the command result. For most cases, the buffer size should be sufficient with 4096 bytes. If the buffer is too small, sending the command result will fail.
    buffer_size The size of the buffer in bytes.
    mqtt_buffer The buffer the SDK uses for receiving the push notification (i.e., command) from Thing Interaction Framework. The buffer is used to get the command as an MQTT data. The buffer size required is dependent on the size of command in the JSON format. The buffer size should be sufficient with 2048 bytes if your command is not complex, like the one we are defining in trait sample. If the buffer is too small, receiving the command as an MQTT push notification will fail.
    mqtt_buffer_size The size of the mqtt_buffer in bytes
    action_handler The function pointer to the action handler. To learn how to implement the action handler, see Executing Commands.
    state_handler The function pointer to the state handler that will be executed when the command execution is done. To learn how to implement the state handler, see Updating and Browsing State.


  • &state_updater_resource

    This is a struct that stores the information for sending the state at regular intervals. This is the API input parameter, so you will prepare the following members.

    Member Description
    buffer The buffer the SDK uses for sending the thing state. The buffer size required depends on the size of the state in the JSON format. The buffer size should be sufficient with 4096 bytes if your state is not complex, like the one we are defining in trait sample. If the buffer is too small, sending the state will fail.
    buffer_size The size of the buffer in bytes.
    period The state update interval in seconds. If you want to update once per minute, for example, please specify 60.
    state_handler The function pointer to the state handler that sends the state at regular intervals. To learn how to implement the state handler, see Updating and Browsing State.


  • NULL

    Here, you specify the callback function for allocating a buffer in the kii_json library. This callback function will be used when the library parses a JSON data and needs to allocate the buffer for tokens. In the above sample code, we are setting NULL because we are not setting any callback function. See here for more detailed discussion.

    If you compile your program while setting the size in the KII_JSON_FIXED_TOKEN_NUM macro, you can specify NULL here. In the reference implementation, we are setting 256 to secure the buffer for parsing 256 tokens. This setting should be sufficient for most cases, but it could be insufficient if your trait definition has complex parameters. In such a case, please consider increasing the number of the KII_JSON_FIXED_TOKEN_NUM or implementing the callback function for allocating the buffer.

After the initialization, your program will wait for the SDK to execute the callback functions. The callback functions will be executed in another task (thread) from the one you made the initialization. You can, therefore, idle or execute other non-Thing Interaction Framework codes in the thread that you've used for the initialization.

Step 2: Onboard thing

Next, execute the onboarding.

/* Define the thing credentials and onboarding options. */
#define VENDOR_THING_ID "nbvadgjhcbn"
#define THING_PASSWORD "123456"
#define THING_TYPE "gas-tank"
#define FIRMWARE_VERSION "1"
#define LAYOUT_POSITION "STANDALONE"
#define THING_PROPERTIES "{}"

kii_bool_t result;

/* Onboard the thing. */
kii_thing_if_error_t error;
result = onboard_with_vendor_thing_id(&kii_thing_if,
      VENDOR_THING_ID, THING_PASSWORD, THING_TYPE, FIRMWARE_VERSION,
      LAYOUT_POSITION, THING_PROPERTIES, &error);
if (result == KII_FALSE) {
  /* Handle the error. */
  /* You can check error details
  printf("Status: %d, Code: %s\n",
    error.http_status_code,
    error.error_code);
  */
}

We are setting the following values in the sample code:

  • &kii_thing_if: Specify the struct that is initialized in Step 1.
  • VENDOR_THING_ID: The ID of the thing defined by the vendor (developer). See here for more details.
  • THING_PASSWORD: The password of the thing. Put the unique password for each thing to secure the region allocated for the thing on Thing Interaction Framework.
  • THING_TYPE: The type of the thing. Please set the thing type that you've registered in Registering Thing Capability.
  • FIRMWARE_VERSION: The firmware version. Please set the firmware version that you've registered in Registering Thing Capability.
  • LAYOUT_POSITION: The layout position of the thing (STANDALONE, GATEWAY, or ENDNODE). See Gateway and End Nodes for the details.
  • THING_PROPERTIES: The thing properties in the JSON format. These properties are used when you leverage Kii Cloud SDK features. In the above sample code, we are setting an empty JSON.

After the initialization and onboarding, your program will wait for the SDK to execute the callback functions. The callback functions will be executed in another task (thread) from the one you made the initialization. You can, therefore, idle or execute other non-Thing Interaction Framework codes in the thread that you've used for the initialization.