初期登録

ゲートウェイとエンドノードを利用するためには、ゲートウェイ、エンドノードと、それらを利用するオーナーの間で紐付け操作が必要です。この紐付け操作を初期登録（Onbording）と呼び、初期化処理の一部として実行する必要があります。

初期登録を行うことで、Thing Interaction Framework 上でコマンド送信やステートの登録などの機能が実行できるようになるとともに、Thing を操作できるユーザーやグループを明確にしてセキュリティを確保することができます。

初期登録では以下の構造を明確することにより、処理に必要な内部構造を初期化します。

  • ゲートウェイとそれを利用するオーナー（ユーザーやグループ）との関係

  • エンドノードとそれを利用するオーナー（ユーザーやグループ）との関係

  • ゲートウェイとエンドノードの関係

このページでは、初期登録の仕組みと、初期登録の実装で必要になる Thing Interaction Framework の機能について示します。

前提条件

ゲートウェイとエンドノード（コンバーター）では、それぞれ以下の情報を持っている想定とします。

  • ゲートウェイ

    工場出荷の段階、または、ゲートウェイエージェントのプロセスを起動する段階で、以下の情報がゲートウェイに設定されているものとします。

    • vendorThingID、ユーザー名、パスワード

      vendorThingID（ここでは gwVendorThingID とします）と、ゲートウェイのユーザー名/パスワード（gwUsername/gwPassword とします）が必要です。

      ゲートウェイのユーザー名は、モバイルアプリからローカル REST API にアクセスする際の認証の目的で使用します。また、パスワードはローカル REST API の認証に加え、Thing Interaction Framework 上でゲートウェイ関連のデータ保護の目的にも使用します。

    • ゲートウェイが使用するアプリケーションの情報

      アプリケーションの AppID とサーバー設定場所が設定されているものとします。

      なお、サードパーティー製のエンドノードを追加する場合に備えて、エンドノードとゲートウェイでアプリケーションを別々に作成することができます。そのため、エンドノード用のアプリケーションの AppID はゲートウェイの API のパラメータとして与える仕組みになっています。

  • エンドノード/コンバーター

    各エンドノードは、それをアプリケーション上で一意に認識するための vendorThingID を持っているものとします。エンドノード自身が vendorThingID を振り出すのが困難な場合、コンバーターが UUID などの一意な ID を振り出して、それを vendorThingID として利用するように実装しても問題ありません。

初期登録の手順

初期登録を行う際は、ゲートウェイアプリを開発する場合と、エンドノードアプリを開発する場合で手順が異なります。

ゲートウェイの初期登録

ゲートウェイを設置後、まずは、ゲートウェイ単体での初期登録を行います。

初期登録は図の手順で行います。図中の赤色の文字はモバイルアプリでの API を、緑色の文字はやりとりされるパラメーターを表します。図中の番号は以下の説明文に対応します。

  1. ゲートウェイのリリース後、ユーザーはモバイルアプリをダウンロードしてスマートフォンにインストールします。

  2. ユーザーはゲートウェイのハードウェアを設置し、ネットワークの接続設定を行います。これによってスマートフォンとゲートウェイが Wi-Fi 等の手段で通信できる状態になります。

  3. モバイルアプリではゲートウェイやエンドノードのオーナーとなるユーザーを作成してアクセストークンを入手します。ここでは、ownerAccessToken とします。

  4. モバイルアプリは、ローカル API 経由でゲートウェイにアクセスするため、ゲートウェイにログインします。このリクエストでは、ゲートウェイエージェントへのアクセストークンを入手するため、ゲートウェイが持つユーザー名 gwUsername とパスワード gwPassword によって認証します。

  5. モバイルアプリは、ゲートウェイに対して初期登録のリクエストを出します。

  6. ゲートウェイは、さらに Thing Interaction Framework に対して初期登録のリクエストを行います。この際、ゲートウェイの vendorThingID gwVendorThingID と、パスワード gwPassword を指定してゲートウェイのセキュリティを確保します。これにより、サーバーでゲートウェイの初期登録が行われます。

  7. 初期登録の結果として、Thing Interaction Framework からゲートウェイの thingID gwThingID が返ります（同時にゲートウェイのアクセストークンや MQTT の接続情報など、内部処理に必要なデータも返ります）。

  8. 5 の応答として、ゲートウェイはモバイルアプリに gwThingID を返します。

  9. モバイルアプリは、Thing Interaction Framework に対してモバイルアプリ側の初期登録のリクエストを行います。このとき、オーナーとなるユーザーのアクセストークン ownerAccessToken、ゲートウェイの thingID gwThingID、ゲートウェイのパスワード gwPassword を渡します。Thing Interaction Framework は、すでに実行されているゲートウェイ側のデータ構造に関連付けてオーナーユーザーなどのデータを初期化できます。

ここまでの操作によって、モバイルアプリとゲートウェイの間で紐付けが行われ、エンドノードを追加する準備ができたことになります。

なお、4 や 9 の処理のためにゲートウェイのユーザー名 gwUsername とパスワード gwPassword をモバイルアプリに入力しておく必要があります。入力方法はどのような形でも問題ありませんが、たとえばゲートウェイのケースに貼られたシールの情報を、モバイルアプリで入力するなどの方法が考えられます。

エンドノードの初期登録

ゲートウェイを初期登録した後、エンドノードの初期登録を行います。以下の手続きは、エンドノードを増設するたびに、それぞれ実行する必要があります。

  1. ユーザーはエンドノードの Thing を設置します。同時にゲートウェイにコンバーターをインストールしてエンドノードが接続できる状態にします。

  2. エンドノードは自動的に、または、ユーザーからの登録操作によってゲートウェイに接続します。このとき、パラメータとしてエンドノードが接続するアプリケーションの AppID appid とエンドノードの vendorThingID endVendorThingID を送信します。AppID を送信するのは、エンドノードのベンダーによってアプリケーションが異なる場合があるためです。
    接続されると、ゲートウェイエージェントは内部にエンドノードの vendorThingID を未登録一覧として保持しておくように実装されています。

  3. ユーザーがモバイルアプリからエンドノードの登録操作を行うと、モバイルアプリはゲートウェイのローカル REST API を通して、エンドノードの未登録一覧の取得機能を呼び出します。これは、ゲートウェイエージェントで初期登録がまだ完了していないエンドノードの一覧を取得する機能です。

  4. 3 の応答として、ゲートウェイはエンドノードの vendorThingID の一覧（ここでは 1 件の endVendorThingID）を返します。

  5. エンドユーザーに、返されたエンドノードの一覧から、今回初期登録を実行するエンドノードを 1 つ選択してもらいます。同時に、エンドノードのパスワードを決めてもらいます（endPassword と仮定します）。

  6. モバイルアプリからエンドノードの初期登録を実行します。パラメータには、ゲートウェイの初期登録ですでに取得しているオーナーのアクセストークン ownerAccessToken、選択したエンドノードの vendorThingID endVendorThingID、入力したパスワード endPassword、接続するゲートウェイの thingID gwThingID を指定します。

  7. 6 の応答として、Thing Interaction Framework は登録したエンドノードの thingID endThingID を返します。

  8. モバイルアプリは、ゲートウェイエージェントのローカル REST API によって取得した endThingID を通知して初期登録完了とします。この後、ゲートウェイエージェントは Thing Interaction Framework にアクセスしてエンドノードのアクセストークンを入手できます。

手順の 1 と 2 は、エンドノードアプリの ゲートウェイの初期登録 の手順の前に実行していても、問題ありません。