SDK の初期化と Thing の初期登録

SDK の初期化コードを実装するには、モバイルアプリと Thing との紐付け方法を決めておく必要があります。この紐付け操作を 初期登録（Onboarding） と呼びます。

サービス全体での初期登録の流れや手順の決定方法の詳細は、機能ガイドの Thing の初期登録をご覧ください。

このガイドでは、Thing から初期登録を行う方法を説明します。

ステップ 1：Thing-IF SDK の初期化
ステップ 2：Thing の初期登録

ステップ 1：Thing-IF SDK の初期化

まず、Thing-IF 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(&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. */
}

最終的に、init_kii_thing_if 関数を呼び出すと初期化が完了します。関数が成功すると、KII_TRUE を返します。

init_kii_thing_if の各パラメータの意味は以下のとおりです。

&kii_thing_if

SDK が利用する情報を格納するための kii_thing_if_t 構造体のポインタです。これは API からの出力パラメータですので、呼び出し元では領域のみを確保します。

後続の関数では、初期化後の kii_thing_if_t 構造体を渡します。Thing のプログラムが動作している間、初期化した kii_thing_if_t 構造体を保持し続ける必要があります。
EX_APP_ID、EX_APP_KEY、EX_APP_SITE

EX_APP_ID と EX_APP_KEY の項目は、開発者ポータルにて取得した AppID と任意の値を設定してください（アプリケーションの作成を参照してください）。

また EX_APP_SITE は、https://api-jp.kii.com/ か "JP" を指定してください。

&command_handler_resource

コマンドの受信と、コマンドリザルトの送信を行うための情報を格納した構造体です。このパラメータは API への入力のため、呼び出し元で以下のメンバーを準備します。

メンバー	意味
buffer	コマンドリザルトの送信のため、SDK 内部で使用するバッファです。通常は 4096 バイト程度を用意すれば問題ありません。小さすぎるとコマンドリザルトの送信が失敗します。
buffer_size	`buffer` に用意したサイズをバイト単位で指定します。
mqtt_buffer	Thing Interaction Framework からのプッシュ通知の受け取り（コマンド受信）のため、SDK 内部で使用するバッファです。コマンドを MQTT のデータとして受け取る際に使用します。必要なサイズはコマンドの JSON 表現に依存します。今回、トレイトのサンプルで使用している程度の複雑さであれば、2048 バイト程度を用意すれば問題ありません。小さすぎると、MQTT のプッシュ通知によるコマンドの受信に失敗します。
mqtt_buffer_size	`mqtt_buffer` に用意したサイズをバイト単位で指定します。
action_handler	アクションハンドラーへの関数ポインタを指定します。実装方法はコマンドの実行をご覧ください。
state_handler	コマンドの実行完了時に呼び出す、ステートハンドラーへの関数ポインタを指定します。実装方法はステートの登録と確認をご覧ください。

&state_updater_resource

一定間隔でのステートの送信を行うための情報を格納した構造体です。このパラメータは API への入力のため、呼び出し元で以下のメンバーを準備します。

メンバー	意味
buffer	ステートの送信のため、SDK 内部で使用するバッファです。必要なサイズはステートの JSON 表現に依存します。今回、トレイトのサンプルで使用している程度の複雑さであれば、4096 バイト程度を用意すれば問題ありません。小さすぎると、ステートの送信に失敗します。
buffer_size	`buffer` に用意したサイズをバイト単位で指定します。
period	ステートの送信間隔を秒で指定します。1 分間隔で更新したい場合は 60 を指定します。
state_handler	一定間隔でのステート更新を行う際に呼び出す、ステートハンドラーへの関数ポインタを指定します。実装方法はステートの登録と確認をご覧ください。

NULL

必要に応じて、kii_json ライブラリでバッファを確保するためのコールバック関数を指定します。これは、JSON の解析を行う際に、トークン用のバッファを割り当てるコールバック関数です。今回はコールバック関数を指定しないため NULL としています。詳細はこちらをご覧ください。

KII_JSON_FIXED_TOKEN_NUM マクロにサイズを指定してコンパイルした場合は NULL を指定できます。リファレンス実装では 256 を指定しており、256 個のトークンまで解析できます。この値は SDK と Thing Interaction Framework との間のやりとりを行うには十分ですが、トレイト定義で複雑なパラメータを指定した場合、リソース不足を引き起こす可能性があります。この場合は、KII_JSON_FIXED_TOKEN_NUM の値の調整やリソース確保用のコールバック関数の実装および指定が必要になります。

初期化処理の完了後は、SDK 側からコールバック関数が呼び出されるのを待機することになります。コールバック関数は、初期化したタスク（スレッド）とは別のタスクから呼び出されるため、初期化完了後はスリープ状態にするか、Thing Interaction Framework 外のコードを実行することができます。

ステップ 2：Thing の初期登録

続いて Thing の初期登録を行います。

/* 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);
  */
}

ここでは以下の値を設定しています。

&kii_thing_if：ステップ 1 において init_kii_thing_if 関数で初期化したものを指定します。
VENDOR_THING_ID：ベンダーが定義した Thing の ID です。詳細はこちらをご覧ください。
THING_PASSWORD：Thing のパスワードです。Thing Interaction Framework 上に登録された Thing の領域をセキュアにするため、Thing ごとに異なるパスワードを設定するのが基本です。
THING_TYPE：Thing タイプです。Thing 機能の登録で登録した Thing タイプを指定します。
FIRMWARE_VERSION: Thing のファームウェアバージョンです。Thing 機能の登録で登録したファームウェアバージョンを登録します。
LAYOUT_POSITION: Thing のレイアウトポジションです。STANDALONE、GATEWAY、ENDNODE のいずれかの値を取ります。詳しくはゲートウェイとエンドノードをご覧ください。
THING_PROPERTIES：Thing 情報を JSON で指定できます。Kii Cloud SDK を併用する場合に利用する項目のため、ここでは空の JSON を指定します。

これらの処理の完了後は、SDK 側からコールバック関数が呼び出されるのを待機することになります。コールバック関数は、初期化したタスク（スレッド）とは別のタスクから呼び出されるため、初期化完了後はスリープ状態にするか、Thing Interaction Framework 外のコードを実行することができます。