初期化コードの実装

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

初期登録には、モバイルアプリから紐付ける方法と、Thing とモバイルアプリ両方から紐付ける方法の 2 通りがあります。いずれの方法でも同じ結果が得られますが、双方で共有すべき情報が異なります。

ここでは、以下のどちらか一方の手順を実行します。

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

モバイルアプリから紐付ける場合

モバイルアプリから紐付ける方法を選択した場合、この手順を実行します。

この方式では、モバイルアプリ上で Thing Interaction Framework への紐付けリクエストをまとめて実施します。

機能ガイドの 初期登録 に示すとおり、この方法では初期登録の実装がシンプルになりますが、モバイルアプリと Thing との間で Bluetooth などでの通信手段を確保する必要があります。

ステップ 1：モバイルアプリからの初期登録

モバイルアプリからの初期登録を行うため、初期登録に必要な情報を Thing からモバイルアプリに渡します。具体的には Thing の vendorThingID と thingPassword を通知します。

モバイルアプリに通知を行う方法は任意です。転送方法の例は、こちら をご覧ください。

モバイルアプリでは、Thing から転送された情報を元に、Android または iOS のコードに従って初期登録を実行します。モバイルアプリ側の実装の詳細は、こちら（Android, iOS）をご参照ください。

ステップ 2：Thing 側の初期化

モバイルアプリ側の初期登録で得られた thingID と thingAccessToken を Thing に転送します。転送の仕方は任意です。たとえば Bluetooth などを使ってセキュアに Thing へ転送します。

転送完了後、Thing 側で以下のコードを実行して 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_with_onboarded_thing(&kii_thing_if, EX_APP_ID, EX_APP_KEY,
             EX_APP_SITE, thing_id, thing_access_token,
             &command_handler_resource, &state_updater_resource, NULL);
if (result == KII_FALSE) {
  /* Handle the error. */
}

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

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

  • &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" を指定してください。

  • thing_id、thing_access_token

    モバイルアプリ側で取得した thingID と Thing のアクセストークンの文字列を表す char 型のポインタです（モバイルアプリより Bluetooth 等で Thing に転送された値を使用します）

    モバイルアプリ側での thing_id、thing_access_token の取得方法はこちら（Android, iOS）をご覧ください。

  • &command_handler_resource

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

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


  • &state_updater_resource

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

    メンバー 意味
    buffer ステートの送信のため、SDK 内部で使用するバッファです。必要なサイズはステートの JSON 表現に依存します。今回、スキーマのサンプル（Android, iOS）で使用している程度の複雑さであれば、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 との間のやりとりを行うには十分ですが、スキーマ定義（Android, iOS）で複雑なパラメータを指定した場合、リソース不足を引き起こす可能性があります。この場合は、KII_JSON_FIXED_TOKEN_NUM の値の調整やリソース確保用のコールバック関数の実装および指定が必要になります。

モバイルアプリから紐付ける方法を選択した場合、必要な初期化処理は以上で完了です（初期登録はモバイルアプリ側ですでに行われているため、Thing 上での初期登録処理は不要です）。

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

Thing とモバイルアプリ両方から紐付ける場合

Thing とモバイルアプリ両方から紐付ける方法を選択した場合、この手順を実行します。

この方式では、まず Thing から Thing Interaction Framework への紐付けリクエストを行い、次にモバイルアプリからの紐付けリクエストを行います。

実際には、モバイルアプリからの紐付け処理（下記のステップ 3）を先に実行しても問題ありませんが、両方の初期登録が完了するまでコマンドの送受信やステートのやりとりは実行できません。

機能ガイドの 初期登録 に示すとおり、この方法では、モバイルアプリと Thing の両方で Thing Interaction Framework にアクセスして初期登録を行う必要がありますが、モバイルアプリと 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 の各パラメータの意味は init_kii_thing_if_with_onboarded_thing 関数と同じです（init_kii_thing_if では一部存在しないパラメータがあります）。詳細は こちら をご覧ください。

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

Thing からの初期登録を行い、モバイルアプリとの紐付けを行います。

/* Define the thing credentials and onboarding options. */
#define VENDOR_THING_ID "nbvadgjhcbn"
#define THING_PASSWORD "123456"
#define THING_TYPE "AirConditioner"
#define THING_PROPERTIES "{}"

kii_bool_t result;

/* Onboard the thing. */
result = onboard_with_vendor_thing_id(&kii_thing_if,
      VENDOR_THING_ID, THING_PASSWORD, THING_TYPE, THING_PROPERTIES);
if (result == KII_FALSE) {
  /* Handle the error. */
}

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

  • &kii_thing_if：事前に init_kii_thing_if 関数で初期化したものを指定します。
  • VENDOR_THING_ID：ベンダーが定義した Thing の ID です。詳細は こちら をご覧ください。
  • THING_PASSWORD：Thing のパスワードです。Thing Interaction Framework 上に登録された Thing の領域をセキュアにするため、Thing ごとに異なるパスワードを設定するのが基本です。
  • THING_TYPE：Thing タイプです。スキーマ定義（Android, iOS）で指定したものと同じものを指定します。
  • THING_PROPERTIES：Thing 情報を JSON で指定できます。Kii Cloud SDK を併用する場合に利用する項目のため、ここでは空の JSON を指定します。

なお、今回紹介した API は vendorThingID を使って初期登録を行いますが、モバイルアプリ側で先に初期登録を行い、得られた thingID を使って初期登録を行うための API も用意されています。詳細は Thing-IF SDK Documentation の onboard_with_thing_id をご覧ください。

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

ステップ 3：モバイルアプリからの初期登録

次にモバイルアプリからの初期登録を行い、モバイルアプリからのコマンド送信やステートの取得ができるようにします。

この際、vendorThingID（またはステップ 2 で取得した thingID）と thingPassword をモバイルアプリに通知する必要があります。転送方法の例は、こちら をご覧ください。

モバイルアプリ側の実装の詳細は、こちら（Android、iOS、JavaScript）をご参照ください。