Kii Documentation
Programming Guides
Thing-IF SDK v1 Development Guides (Obsoleted)
Thing-IF SDK Development Guides (non-trait version)
Thing Development Guide
Initializing and Onboarding

Initializing and Onboarding

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

The onboarding can be made by the mobile application, or it can be made by both the thing and mobile application. You will get the same result for both, but their flows are a bit different.

Onboarding from the mobile app
Onboarding from both the thing and the mobile app

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

Onboarding from the mobile app

In this method, the mobile application will handle the most of the binding processes.

As explained in Onboarding in the Function Guide, you can make the implementation simple with this approach. You will need, however, to establish a secure connection between the mobile application and the thing (e.g., Bluetooth connection).

Step 1: Onboarding from the mobile app

First, the thing passes its vendorThingID and thingPassword to the mobile application. The mobile application needs this information to perform the onboarding.

How the thing passes this information is optional. See here for more discussion.

The mobile application executes the onboarding with the information. Please read here (Android, iOS) for more details.

Step 2: Initializing the Thing

The mobile application will get the thingID and access token when its onboarding is done. This information is then passed to the thing. Transfer the information in your preferred method. For example, you can use Bluetooth to transfer the information securely to the thing.

When the thing gets the thingID and access token, it executes the following code to initialize the SDK.

#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_with_onboarded_thing(&kii_thing_if, EX_APP_ID, EX_APP_KEY,
             EX_APP_SITE, thing_id, thing_access_token,
             &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_with_onboarded_thing function. If the function is successful, it will return KII_TRUE.

Here is a list of parameters that the init_kii_thing_if_with_onboarded_thing 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 are going to pass the initialized kii_thing_if_t struct. You 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

Please 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, please set https://api-jp.kii.com/ or "JP".
thing_id and thing_access_token

These are char type pointers representing the thingID and access token. You will specify the values that are passed from the mobile application in some ways(e.g., via Bluetooth).

Please read here (Android, iOS) to learn how to get these values on the mobile application side.

&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 the schema in the JSON format. The buffer size should be sufficient with 2048 bytes if your schema is not complex, like the one we are using as a sample (Android, iOS). 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 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 schema is not complex, like the one we are using as a sample (Android, iOS). 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 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 schema definition (Android, iOS) 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.

If you are onboarding from the mobile application, this is it for the initialization. The onboarding from the thing side is not required since it is already made on the mobile application side.

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.

Onboarding from both the thing and the mobile app

In this method, you first execute the onboarding request from a thing. Then, you execute the onboarding request from a mobile application.

You can actually start onboarding from either one of them. Both onboarding needs to be done, however, to start sending commands and getting thing states.

As explained in Onboarding in the Function Guide, this approach requires you to make the onboarding on both the mobile application and the thing. You will not need, however, to establish a secure connection between them.

Step 1: Initializing the Thing-IF SDK

First of all, you need to initialize the Thing-IF SDK.

Here is the sample code.

#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.

The parameters of the init_kii_thing_if function are the same as that of the init_kii_thing_if_with_onboarded_thing function (although some parameters are not available in the init_kii_thing_if). Please check here.

Step 2: Onboarding from the thing

Next, execute the onboarding from the thing and bind it to the mobile application.

/* Define the thing credentials and onboarding options. */
#define VENDOR_THING_ID "nbvadgjhcbn"
#define THING_PASSWORD "123456"
#define THING_TYPE "AirConditioner"
#define THING_PROPERTIES "{}"

kii_bool_t result;

/* Onboard the thing. */
result = onboard_with_vendor_thing_id(&kii_thing_if,
      VENDOR_THING_ID, THING_PASSWORD, THING_TYPE, THING_PROPERTIES);
if (result == KII_FALSE) {
  /* Handle the error. */
}

We are setting the following values in the sample code:

&kii_thing_if: Specify the struct that is initialized with the init_kii_thing_if function.
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 same type that you've specified in the schema definition (Android, iOS).
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.

In the sample code above, we introduced an API for executing the onboarding with the vendorThingID. There is also an API for executing the onboarding with the thingID (this one is to be used when you make the onboarding on the mobile application first). Please check the Thing-IF SDK Documentation and check the onboard_with_thing_id function for more details.

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.

Step 3: Onboarding from the mobile app

Next, perform the onboarding from the mobile application. Once the onboarding is done, the mobile application will be able to send commands and get the thing states.

The thing needs to notify the vendorThingID (or the thingID obtained in Step 2) and thingPassword to the mobile application beforehand. See here to see some examples of how you can make this notification.

For more information on how to implement the mobile application, please read here (Android, iOS, JavaScript).