Thing-IF SDK Structure
The following SDKs are provided for developing mobile apps and things (devices) with Thing Interaction Framework.
- Thing-IF SDK for C version 2 for implementing a program that runs on things.
- Thing-IF SDK for Android/iOS/JavaScript for implementing mobile apps.
By leveraging both thing and mobile app SDKs, you can build services that enable users to manipulate the things from mobile apps.
Thing-IF SDK for C version 1 for implementing a program that runs on things is now obsoleted.
Thing-IF SDK for C version 2
The Thing-IF SDK for C version 2 is a C program that runs on the things. The source code is open to the public. You can download and build it for your environment to start your development.
SDK structure
The following diagram illustrates the SDK structure.
The SDK is released in ebisu repository. You can leverage Thing Interaction Framework by using the SDK in your program.
Here are several important points you need to be aware of when using the Thing SDK:
You need only to implement callback functions to leverage Thing Interaction Framework features
After initializing the SDK and executing the start API, your program just needs to wait for the SDK to execute its callback functions (i.e., action handler and state setter).
All OS-related functions are ready for use
The ebisu defines the reference implementation for some specific environments. The APIs that are deeply dependent on the OS, like Socket and Task management, are already defined in the reference implementation. You can simply build them to use the functions. If you want to use the SDK in other environments, you need to provide equivalent functions for your environment by referring to the source code.
MQTT implementation is ready for use
The ebisu contains the implementation of the MQTT client so that you can leverage the MQTT push notification without any additional library. In your code, you will use the push notification for receiving commands.
Your program needs to prepare buffers
Your program needs to allocate memory for receiving commands and sending states. The allocated memory is passed to the SDK upon the initialization.
Some features require you to allocate heap memory inside the SDK. For those features, you can prepare callback functions that are equivalent to
malloc
andfree
. If you do not prepare the callback functions, the SDK will usemalloc
andfree
internally.See Initializing SDK in Reference Guide for more details on the buffer handling.
The jkii library is available for parsing JSON
When integrating with the mobile app, the thing needs to parse the JSON string.
You can use any implementation for parsing JSON string. You can keep your code simple and tidy by using the jkii library in your program. See Parsing JSON for more details.
The library will handle the communication control
The ebisu includes the implementation and controls of socket API calls for each OS. The implementations of the basic socket APIs such as
connect()
,close()
,send()
, andrecv()
are isolated from the caller, so you can customize their implementations for your target environment and leverage the SSL/TLS connection.The library also implements the reconnection logic; it will reestablish a new connection when the connection is lost while waiting for a command to be sent from the server via an MQTT channel.
Reference implementation
We are providing the reference implementation for the following environment:
- Linux
- GT202
- Ti CC3200
- Avnet IoT Starter Kit
If you want to use the SDK in other environments, please implement all OS-dependent processes like sockets and task (thread) generation for your environments. Refer sample source codes in the ebisu repository; you can find them under tio directory.
See Quick Start for more information.
Thing-IF SDK for mobile apps
We offer SDKs for building mobile apps which work with Thing Interaction Framework. These SDKs support the development of native apps for Android and iOS and web apps with JavaScript and TypeScript. With these SDKs, you can quickly develop mobile apps for manipulating things.
The supported environments are covered in SDKs and Supported Environments.
To use the Thing-IF SDK, you also need to use the Kii Cloud SDK.
Thing-IF SDK offers the ability to manipulate things, like sending commands and reading state.
Kii Cloud SDK provides the ability to get the access token and ID of the user who will own the thing. The access token and ID are needed when you are to initialize the thing.
The Thing Interaction Framework internally uses the Kii Cloud features (e.g., user and data management, push notifications) to realize the command and state transfer. We will present how to implement such features in the development guides. For the typical mobile app, here, you will just need to execute Kii Cloud SDK features just like the provided samples.
Kii Cloud and Thing Interaction Framework share the same application on the cloud. If you want to use features such as data management and push notifications, you can also call the function of the Kii Cloud SDK.
Thing-IF SDK for C version 1
The Thing-IF SDK for C version 1 is a C program that runs on the things. The source code is open to the public. You can download and build it for your environment to start your development.
This SDK is obsoleted. Do not use it for a new project.
SDK structure
The following diagram illustrates the SDK structure.
The SDK is composed of three repositories: thing-if-ThingSDK, KiiThingSDK-Embedded, and kii_json. Your code will leverage them to make use of the Thing Interaction Framework features.
Here are several important points you need to be aware of when using the Thing SDK:
You need only to implement the handlers
After your program initializes the SDK, it basically waits for the SDK to execute its callback functions (i.e., command handler and state handler).
The SDK internally uses the Thing SDK Embedded
The Thing-IF SDK internally uses the Thing SDK Embedded, which is an SDK written in C for embedded devices. This SDK supports key functionalities of the Kii Cloud SDK.
You can also use the Thing SDK Embedded directly. See Implementing Things with Thing SDK Embedded for more information. See Using kii-core to learn how to use kii-core, which is internally used in the Thing SDK Embedded.
All OS-related functions are ready for use.
The thing-if-ThingSDK defines the reference implementation for some specific environments. The APIs that are deeply dependent on the OS, like Socket and Task management, are already defined in the reference implementation. You can simply build it to use the functions. If you want to use the SDK in other environments, you need to provide equivalent functions for the environment by referring to the source code.
In the actual implementation, the thing-if-ThingSDK is integrating various OS dependent libraries that are included in the KiIThing-Embedded.
MQTT implementation is ready for use
The KiiThingSDK-Embedded contains the implementation of the MQTT client so that you can leverage the MQTT push notification without any additional library. In your code, you will use the push notification for receiving commands.
You need to prepare buffers in your program.
Your thing program needs to allocate memory for receiving commands and sending states. The allocated memory is passed to the SDK upon the initialization. The API for allocating memory from the heap (something equivalent to
malloc
) is not available in the SDK.See Initializing SDK and Onboarding Thing for more details on the buffer handling.
The kii_json library is available for parsing JSON.
When integrating with the mobile app, the thing needs to parse the JSON string.
You can use any implementation for parsing JSON string. You can keep your code simple by using the kii_json library in your program. See Parsing JSON for more details.
The library will handle the communication control.
The library in the thing-if-ThingSDK implements and controls socket API calls for each OS. The implementations of the basic socket APIs such as
connect()
,close()
,send()
, andrecv()
are isolated from the caller, so you can customize their implementations for your target environment and leverage the SSL/TLS connection.The library also implements the reconnection logic; it will reestablish a new connection when the connection is lost while waiting for a command to be sent from the server via an MQTT channel.
Reference implementation
We are providing the reference implementation for the following environment:
- Linux
- Intel Edison
- Ti CC3200
If you want to use the SDK in other environments, please implement the necessary APIs by yourself. As shown in the structure diagram, all OS dependent processes like Socket and Task (thread) generation are pluggable for each platform. You can deploy the SDK to any platforms by replacing these implementations.
If you are replacing the API implementations, please prepare the source code equivalent to kii_iot_environment_linux.c file in the thing-if-ThingSDK repository for your environment.
See Quick Start for more details on the SDK preparation.