Implementation Guidelines

Please note the following points when implementing things with the Thing-IF SDK v2.

TIO instance

Thing-IF SDK v2 uses the following two instances to handle its jobs.

  • tio_handler_t instance

    An instance for onboarding and managing resources for tasks that send and receive commands.

  • tio_updater_t instance

    An instance for onboarding and managing resources for tasks that update states.

You can use either instance for onboarding, and then share the registration information between two instances.

Tasks

When implementing with the Thing-IF SDK v2, you will need to handle multiple tasks (threads).

For example, you will implement some callback functions in your thing program. These callback functions will be executed from the dedicated tasks managed by the SDK. For some features, like the SDK initialization, the thing program will create a task and invoke the SDK.

The following table summarizes the tasks.

Process Which task executes the process? Description
Onboarding Any task in your program Any task in your program can execute the SDK initialization. Once the initialization is done, there is no more SDK execution the task needs to make. The task can idle or execute non-Thing Interaction Framework processes.
Executing Action Handler Command reception task The SDK manages a dedicated task for receiving a command. This task will execute the action handler.
Executing State Uploader State updating task The SDK manages a dedicated task for updating state. This task will execute the state uploader at regular intervals. Upon the execution, the following two callback functions will be executed.
  • Callback function for requesting state size
  • Callback function for requesting state data
The SDK acquires the state to upload using these two callback functions and send it to the server.
Allocating Resource for Parsing JSON Any task requesting to parse JSON The thing program can have a callback function to allocate the necessary resources for parsing JSON tokens. This callback function will be executed from the tasks that request the JSON parsing. Multiple JSON parsing requests can come simultaneously, so the callback function must be reentrant or need to be serialized with the synchronous process.
You do not need to set any callback function if the necessary resources are prepared beforehand.

Note:

  • All the APIs on the thing are blocking APIs. Once a task calls any API, it freezes until the API completes.

Data types

Many data types are used in the Thing-IF SDK v2. In the guide, we will introduce them as they appear in the sample code. Here, we present a commonly-used one.

tio_bool_t

The following tio_bool_t is the boolean data type commonly used throughout the SDK. It is actually an alias to kii_bool_t.

typedef kii_bool_t tio_bool_t;
typedef enum kii_bool_t {
    KII_FALSE = 0,
    KII_TRUE
} kii_bool_t;

This data type will be imported automatically when you include tio.h.

String handling

All strings handled by the Thing-IF SDK v2's C library are null-terminated UTF-8 strings unless described otherwise.

You should have no problem handling characters in the ASCII range. Should you need to use the characters outside the ASCII range (e.g., in the command parameters), you need to handle them as the UTF-8's multibyte characters.

Memory management

The Thing-IF SDK v2 receives designated memory spaces for particular uses from the user program.

Processing with designated spaces

The SDK gets designated memory spaces for the following purposes when it is initialized. The user program reserves these memory spaces and initializes an instance with the initialization API.

  • Space for processing HTTP communication in tio_handler_t
  • Space for processing MQTT communication in tio_handler_t
  • Space for processing HTTP communication in tio_updater_t

The following settings are optional. If you do not set them, the SDK will automatically allocate memory spaces from heap memory.

  • Space for processing HTTP headers in tio_handler_t
  • Space for processing HTTP bodies in tio_handler_t
  • Space for processing HTTP headers in tio_updater_t
  • Space for processing HTTP bodies in tio_updater_t

See the sample code of SDK initialization for how to allocate the memory spaces.

Macros for build settings

The Thing-IF SDK v2 provides some rooms for customizing the build conditions with macros. Usually, you do not need to touch these macros. When you need some deep customization and need to dig into the SDK's source code, please use the following information as your reference.

The following table summarizes the available macros. The "default" column in the table shows the default value set in the reference implementation.

Symbol Default Description
HANDLER_KEEP_ALIVE_SEC 300 Set the number of seconds for the MQTT keep alive timer. Kii recommends setting a value which is greater than or equal to 60.
JKII_NOASSERT Undefined Define this macro if the system library does not support assert. The reference implementation will automatically define the macro according to the running environment, so you can leave it undefined.
JSMN_PARENT_LINKS Undefined The setting for the library the SDK internally uses for parsing JSON. Please leave it undefined.
JSMN_STRICT Undefined The setting for the library the SDK internally uses for parsing JSON. Please leave it undefined.