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

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

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

このガイドでは、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_IDEX_APP_KEYEX_APP_SITE

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

    また EX_APP_SITE は、開発者ポータルにて指定したサーバー設定場所に対応して以下の URL を指定するか、サーバー設定場所に対応する値("JP""US""CN3""SG"、または "EU")を指定してください。

    • アメリカ合衆国:https://api.kii.com/
    • 日本:https://api-jp.kii.com/
    • 中国:https://api-cn3.kii.com/
    • シンガポール:https://api-sg.kii.com/
    • ヨーロッパ:https://api-eu.kii.com/
  • &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 のレイアウトポジションです。STANDALONEGATEWAYENDNODE のいずれかの値を取ります。詳しくは ゲートウェイとエンドノード をご覧ください。
  • THING_PROPERTIES:Thing 情報を JSON で指定できます。Kii Cloud SDK を併用する場合に利用する項目のため、ここでは空の JSON を指定します。

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