Initializing and Onboarding

To use the Thing SDK Embedded, you need to initialize the SDK and set callback functions for OS-dependent processes such as socket and task creation.

Follow these steps in order:

Usually, you can skip only implementing OS-dependent processes when you use the Thing-IF SDK with the Thing SDK Embedded.

Initializing the SDK

Call the initialization API of the Thing SDK Embedded.

kii_t kii;

/* Initialize Kii SDK Embedded. */
kii_impl_init(&kii, EX_APP_SITE, EX_APP_ID, EX_APP_KEY);

In the EX_APP_SITE, set the server location you've selected on the developer portal ("JP", "US", "CN3", "SG" or "EU"). In the EX_APP_ID and EX_APP_KEY, specify the AppID and AppKey you've got on the developer portal.

The kii_t structure stores the initialization result. Keep this information until the program exists because it is necessary to call the APIs of the Thing SDK Embedded.

In the following API sections, specify this initialized kii_t structure where &kii is placed.

If you use the Thing-IF SDK with the Thing SDK Embedded

The command_handler and state_updater members of the kii_thing_if_t structure of the Thing-IF SDK are initialized kii_t structures. Therefore, in principle, it is possible to use them to call the APIs of the Thing SDK Embedded. However, it might conflict with internal processes of the Thing-IF SDK.

Initialize a new kii_t structure to call the APIs of the Thing SDK Embedded unless you enhance processes of the Thing-IF SDK purposefully.

Executing the SDK Functions from Multiple Tasks or Threads

When you execute the SDK functions from multiple tasks or threads, initialize a kii_t structure for each task. Do not share any initialized kii_t structure across tasks.

Preparing Spaces for Communication

Initialize communication buffers to call the APIs in the kii_t structure.

See below for the sample code which contains SDK initialization and buffer preparation.

#define EX_BUFFER_SIZE 4096

kii_t kii;
char buffer[EX_BUFFER_SIZE];

/* Initialize Kii SDK Embedded. */
kii_impl_init(&kii, EX_APP_SITE, EX_APP_ID, EX_APP_KEY);

/* Initialize the space used by the SDK for communication. */
memset(buffer, 0x00, sizeof(buffer) / sizeof(buffer[0]));
kii.kii_core.http_context.buffer = buffer;
kii.kii_core.http_context.buffer_size = sizeof(buffer) / sizeof(buffer[0]);

/* Initialize the space used for the socket. */
kii.kii_core.http_context.socket_context.app_context = NULL;

Specify the space used by the SDK for communication in the kii.kii_core.http_context.buffer and kii.kii_core.http_context.buffer_size. The specified space is shared by the sending and receiving processes.

The size is 4096 bytes in this example. However, you need to adjust it based on what is transferred by the REST API. For example, if you need to process large JSON strings to create and get objects, prepare a space which can accommodate such a JSON string and other data used by the REST API, such as HTTP headers.

The kii.kii_core.http_context.socket_context.app_context is a space for application to process the socket described in the below section, Implementing OS-dependent Processes. You can store the pointer to the structure if socket implementation requires context information. NULL is specified in the above example because socket implementation in Linux does not require context information. See sample implementations for various environments in the source code downloaded from GitHub to learn how to use the app_context.

Implementing OS-dependent Processes

The Thing SDK Embedded has high portability through externalizing OS-dependent processes such as communication process and task generation. Develop such OS-dependent processes in the user program and set function pointers to those processes in the target members of the kii_t structure.

In general, you can port the SDK to any platform on which a C compiler works just by preparing OS-dependent implementation shown in this section.

See below for such an implementation in the kii_imple_init function of the Linux sample.

/* Set http socket callbacks. */
kii->kii_core.http_context.connect_cb = s_connect_cb;
kii->kii_core.http_context.send_cb = s_send_cb;
kii->kii_core.http_context.recv_cb = s_recv_cb;
kii->kii_core.http_context.close_cb = s_close_cb;

/* Set a logger callback. */
kii->kii_core.logger_cb = logger_cb;

/* Set MQTT socket callbacks. */
kii->mqtt_socket_connect_cb = mqtt_connect_cb;
kii->mqtt_socket_send_cb = mqtt_send_cb;
kii->mqtt_socket_recv_cb = mqtt_recv_cb;
kii->mqtt_socket_close_cb = mqtt_close_cb;

/* Set task callbacks. */
kii->task_create_cb = task_create_cb;
kii->delay_ms_cb = delay_ms_cb;

This code initializes the below functions required in the OS-dependent processes.

Category Function kii_t Member to Reference Position in the Linux Sample
Communication
Process
(HTTP/HTTPS)
Connect to server kii_t.kii_core.
http_context.connect_cb
/kii-core/linux/
kii_core_secure_socket.c: s_connect_cb()
Send data kii_t.kii_core.
http_context.send_cb
/kii-core/linux/
kii_core_secure_socket.c: s_send_cb()
Receive data kii_t.kii_core.
http_context.recv_cb
/kii-core/linux/
kii_core_secure_socket.c: s_recv_cb()
End connection kii_t.kii_core.
http_context.close_cb
/kii-core/linux/
kii_core_secure_socket.c: s_close_cb()
Log Output Output to log kii_t.kii_core.logger_cb Linux/kii_init_impl.c: logger_cb()
Communication
Process
(MQTT)
Connect to server kii_t.mqtt_socket_connect_cb /Linux/kii_socket_impl.c: mqtt_connect_cb()
Send data kii_t.mqtt_socket_send_cb /Linux/kii_socket_impl.c: mqtt_send_cb()
Receive data kii_t.mqtt_socket_recv_cb /Linux/kii_socket_impl.c: mqtt_recv_cb()
End connection kii_t.mqtt_socket_close_cb /Linux/kii_socket_impl.c: mqtt_close_cb()
Task Management Generate thread/task kii_t.task_create_cb Linux/kii_init_impl.c: logger_cb()
Pause execution with sleep kii_t.delay_ms_cb /Linux/kii_task_impl.c: delay_ms_cb()

You can use the sample program without changes for Linux. Provide OS-dependent processes for the other environments as described below.

  • Intel Edison and Ti CC3200

    Sample implementations are provided in the INTEL and IT directories under the KiiThingSDK-Embedded directory created from the download from GitHub. You can build the samples in those directories and also use them as a skeleton.

  • The other environments

    Prepare processes corresponding to the functions in the above table for the target platform.

    The KiiThingSDK-Embedded directory also has the gt202, MTK, and WinnerMicro directories. Note that those files were created for testing purposes when the SDK was developed. If you refer to those files, test your implementation thoroughly and make necessary changes because you might encounter problems due to differences of versions and environments.