2.8.17 Azure向けMQTT設定支援ツール

1. 概要

本ツールは、MQTTセキュアプロトコル変換機能の転送先として Azure IoT Hub をご利用するにあたり、必要な設定作業の一部を自動化することができます。

以下の3つの設定作業を本ツールから実施することができます。

  • IoT Connect Gateway の SIM のAzureデバイスIDを更新する。
  • IoT Connect Gateway に 認証情報を追加する。
  • Azure IoT Hub にデバイスを追加する。

本ツールを以下のリンク先からダウンロードしてご利用ください。

https://github.com/nttcom/icgw-tools

2. 目的

SIMに関するデータは IoT Connect Mobile® Type S 及び IoT Connect Gateway のご契約時に自動で同期されますが、IoT Connect Gateway のMQTTプロトコル変換機能を実際にご利用頂くためには、ご利用クラウドおよび IoT Connect Gateway のそれぞれに対して設定する必要があります。

小規模な環境の場合は、比較的少ない設定でご利用できますが、大規模な環境で大量のデバイスをご利用する場合は、デバイスの数に応じて設定作業が増えていきます。MQTTプロトコル変換機能の転送先として Azure IoT Hub をご利用される場合は、 IoT Connect Gateway では、SIM毎の azureDeviceId の設定、グループ単位での認証情報の登録が必要です。また、ご利用クラウドでは、デバイス登録を実施する必要があります。

本ツールをご利用することにより、上記の設定作業の一部を自動化することで、円滑に Azure IoT Hub を転送先とした IoT Connect Gateway のMQTTプロトコル変換機能をご利用できます。

3. コマンド一覧

MQTT設定支援ツールは3つの操作に対応しています。

  • IoT Connect Gateway のSIM情報にazureDeviceIdを更新する。

    $ python main.py update-sims example.yaml
    
  • IoT Connect Gateway に認証情報を追加する。

    • 認証情報の名前に、YYYYmmddhhmm 形式の接尾子が追加されます。
      • (例) auth_20220101123450 (年月日時分)
    $ python main.py add-authentications example.yaml
    
  • Azure IoT Hubにデバイスを追加する。

    • 既にデバイスが存在する場合は設定を上書きします。
    $ python main.py add-devices example.yaml
    

4. 推奨環境

本ツールは下記の環境で動作確認を行っています。

  • OSバージョン
    • Mac OS X: 12.6.1
  • ソフトウェアバージョン
    • python: 3.8.13
    • pip: 22.0.4
    • cmake: 3.23.2
    • git: 2.36.1
    • openssl LibreSSL: 2.8.3

5. 共通設定

  • MQTT設定支援ツールに必要な環境構築を行います。
  • Pythonの仮想環境 (pyenv や poetryなど) をご利用されている場合は、適宜ご自身の環境に合わせて実行してください。

環境構築

  1. 設定支援ツールをダウンロードします

    git clone https://github.com/nttcom/icgw-tools
    
  2. 設定支援ツールのフォルダーへ移動します

    cd icgw-tools/mqtt-setup-support
    
  3. 依存ライブラリをインストールします

    pip install -r requirements.txt
    

環境変数ファイル(.env)の作成

  • SDP用の環境変数ファイルを作成します

  • ファイル名は .env とし、MQTT設定支援ツールと同じフォルダー上で作成します

    # For SDP Settings
    SDP_API_HOST="api.ntt.com/iot-c-icgw"
    SDP_API_TENANT_ID="<SIMが所属するテナントIDを指定>"
    SDP_API_KEY="<SDP APIのAPIキーを指定>"
    SDP_API_SECRET="<SDP APIのAPIシークレットを指定>"
    

6. Azure IoT Hub ご利用時の設定

IoT Connect Gateway の設定確認

  • IoT Connect Gateway
  • ポータル上で、設定対象のSIMが存在するかを確認します。
../../_images/icgw-mqtt-support-00.png
  • 下図のように【azureデバイスID】が既に設定されている場合は上書きされますのでご注意ください。
../../_images/icgw-mqtt-support-10.png

ご利用クラウドの設定

  • Azure IoT Hub を作成します
    • 【ネットワーク】や【管理】などの項目は必要に応じて適宜設定してください。
../../_images/icgw-mqtt-support-11.png
  • Azure IoT Hub の共有ポリシーからプライマリ(セカンダリ)接続文字列を取得します

    • 【IoT Hub > 共有アクセスポリシー > iothubowner】を選択し、プライマリ、もしくはセカンダリ接続文字列をメモ帳などに控えておきます。この値は【設定ファイルの作成】時に使用します。

      • iothubowner 以外のポリシーを使用したい場合は、【レジストリ読み取り】および【レジストリ書き込み】権限を割り当てたポリシーを作成して、プライマリ(セカンダリ)接続文字列を取得してください。
      ../../_images/icgw-mqtt-support-12.png

設定ファイルの作成

  • 任意のファイル名でYAML形式の設定ファイルを作成します。
  • optionsへ指定した primary_key および secondary_key は、本ツールを用いて追加する全デバイスへ登録されます。
  • primary_keyセカンダリキー は予め作成する必要があります。
    • 下記などのコマンドを用いることで primary_keysecondary_key を作成できます。
      • date +%s | sha256sum | base64 | head -c 32
  • primary_keysecondary_key はそれぞれ指定する必要があります。
  • 本例で使用している主キーおよびセカンダリキーは本番環境で使用しないでください。
    • 前述のコマンドを用いた、主キーもしくはセカンダリキーの新規作成を推奨しています。
# サンプル設定
# 下記設定を編集してご利用ください
azureSettings:
  connectionString: "<YOUR_CONNECTION_STRING>"
  options:
  - name: type
    value: SAS
  - name: primary_key
    value: "<YOUR_PRIMARY_KEY_FOR_DEVICE>"
  - name: secondary_key
    value: "<YOUR_SECONDARY_KEY_FOR_DEVICE>"
  devices:
  - imsi: "999990000000001"
    deviceId: device1
  - imsi: "999990000000002"
    deviceId: device2
  authentications:
  - name: "for-example-devices"
    sharedAccessKey: "<YOUR_SHARED_ACCESS_KEY>"
    deviceId: "example-device-01"
    description: "example description"
  • connectionString
    • Azure IoT Hub のプライマリ(セカンダリ)接続文字列を指定します
  • options
    • name: type
      • value: SAS を指定します
    • name: primary_key
      • value: 主キーを指定します
    • name: secondary_key
      • value: セカンダリキーを指定します
  • devices (※ 複数指定可)
    • imsi
      • ご利用中SIMの IMSI を指定します
    • deviceId
      • azureDeviceIdの名前を指定します
        • Azure IoTHub で作成するデバイス名としても利用します
  • authentications (※ 複数指定可)
    • name: 認証情報の 任意の名前 を指定します
    • sharedAccessKey: optionsへ指定した主キーもしくはセカンダリキーを指定します
    • deviceId: devicesに指定した deviceId のいずれかを指定します
    • description: 任意の説明 を指定します

実行例および実行結果の確認

  1. IoT Connect Gateway のSIM情報へ azureDeviceId を追加します

    $ python main.py update-sims azure.yaml
    
  2. SIM詳細画面でazureDeviceIdが更新されていることを確認します

../../_images/icgw-mqtt-support-10.png
  1. IoT Connect Gateway へ認証情報を追加します

    $ python main.py add-authentications azure.yaml
    
  2. IoT Connect Gateway の認証情報一覧画面で認証情報が追加されていることを確認します

  • 【クラウドサービス接続 > 認証】一覧ページで下記画像のように新たな認証情報が追加されます。
../../_images/icgw-mqtt-support-13.png
  • 【クラウドサービス接続 > 認証 > 認証情報名】でより詳細な情報を確認できます。
../../_images/icgw-mqtt-support-14.png
  1. Azure IoT Hubへデバイスを追加する

    $ python main.py add-devices azure.yaml
    
  2. Azure IoT Hubのデバイス一覧画面でデバイスが追加されていることを確認します

../../_images/icgw-mqtt-support-15.png