• ドキュメント
• SORACOM Beam
• エントリポイントリファレンス

MQTT エントリポイント

MQTT で受けた通信を、MQTT または MQTTS で転送を行う設定です。

MQTT の Publish、Subscribe を転送先となる MQTT ブローカーに転送します。MQTT ブローカーからのメッセージの Publish もデバイスに対して転送します。

設定項目

SORACOM ユーザーコンソールの場合

• 設定名: 本設定の名前
• 転送先
  • プロトコル: 転送先への送信プロトコル (MQTT もしくは MQTTS から選択)
  • ホスト名: 転送先の FQDN
  • ポート番号: 転送先のポート番号
  • ユーザー名: 転送先ブローカーへ送信するユーザー名 (オプション) (*1)
  • パスワード: 転送先ブローカーへ送信するパスワード (オプション) (*1)
  • パススルー: ON にした場合、クライアントデバイスから送信されるユーザー名/パスワードを転送先にパススルーします。
  • 証明書: クライアント証明書を送信するかどうかのフラグ
  • 認証情報: 送信するクライアント証明書
• オプション
  • IMSI 付与: IMSI を送信するかどうかのフラグ (オンにするとトピックの末尾に、トピック名/IMSI という形式で IMSI が付与されます)。当 IMSI 付与は Publish に対応します。
  • トピック名にセッション情報を利用する: トピック名に存在するプレースホルダー ({{imsi}} / {{simId}} / {{imei}}) を各セッション情報で置換します。当プレースホルダーは Publish、Subscribe の両方に対応します。
    • {{imsi}} : IMSI で置き換えます。
    • {{simId}} : SIM ID で置き換えます。
    • {{imei}} : 通信モジュールの IMEI で置き換えます。IMEI は接続するキャリアやプランによっては取得できない場合があり、その場合は {{imei}} を unknown-imei に置換します。
  • プラットフォームバージョン: 201912 と 201509 が選択できます。201912 と 201509 の違いについては、プラットフォームバージョン 201509 と 201912 の違い を参照してください。

SORACOM CLI / SORACOM API の場合

soracom groups put-config (Group:putConfigurationParameters API) を使用します。

{namespace} は、SoracomBeam です。

ボディで指定するプロパティについては、以下の key と value のペアを配列で指定します。

"mqtt://beam.soracom.io:1883": { // 固定
  "name": "string", // 任意の名称
  "destination": "mqtts://mqtt.example.com/topicname", // MQTT接続先
  "enabled": true | false, // MQTT エントリポイントの有効無効
  "addSubscriberHeader": true | false, // topic にIMSI を足すか否か
  "username": "USERNAME", // ユーザ名(任意)
  "password": "PASSWORD", // パスワード(任意)
  "useClientCert": true | false, // TLSクライアント証明書を使用するか否か
  "clientCerts": { // 上記を有効にした場合は必須
    "default": { // 現状は証明書を 1 つだけ登録可能
      "key": "...", // 秘密鍵(PEM形式)
      "cert": "...", // 証明書(PEM形式)
      "ca": "...", // CA証明書(PEM形式)
    }
  },
  "useCaCert": true | false, // 独自のCA証明書を使用するか否か
  "caCert": "...", // CA証明書(PEM形式)
  "usePubnub": true | false, // 転送先がPubNubの場合Trueにする(任意、指定なしの場合 false)
  "useAzureIoT": true | false, // 転送先がAzureIoTの場合Trueにする(任意、指定なしの場合 false)
  "useGoogleIoT": true | false // 転送先がGoogleIoTの場合Trueにする(任意、指定なしの場合 false)
}

設定例

[
  {
    "key": "mqtt://beam.soracom.io:1883",
    "value": {
      "name": "AWS IoT",
      "destination": "mqtts://data.iot.ap-northeast-1.amazonaws.com:8883",
      "enabled": true,
      "addSubscriberHeader": false,
      "useClientCert": true,
      "clientCerts": {
        "default": {
          "key": "-----BEGIN RSA PRIVATE KEY-----\n...",
          "cert": "-----BEGIN CERTIFICATE-----\n...",
          "ca": "-----BEGIN CERTIFICATE-----\n..."
        }
      }
    }
  }
]

MQTT エントリポイント URL (ホストおよびポート)

beam.soracom.io:1883

実際の利用例

Publish

mosquitto を使ってデバイスから beam へ実際に Publish してみます。

デバイス側

$ mosquitto_pub -h beam.soracom.io -p 1883 -t test -m message -d
Client mosqpub/82534-MBP sending CONNECT
Client mosqpub/82534-MBP received CONNACK
Client mosqpub/82534-MBP sending PUBLISH (d0, q0, r0, m1, 'test', ... (7 bytes))
Client mosqpub/82534-MBP sending DISCONNECT

転送先の MQTT ブローカー

1482290763: New connection from 52.198.245.54 on port 8080.
1482290763: New client connected from 52.198.245.54 as mosqpub/82534-MBP (c1, k60).
1482290763: Sending CONNACK to mosqpub/82534-MBP (0, 0)
1482290767: Received PUBLISH from mosqpub/82534-MBP (d0, q0, r0, m0, 'test/4401031********', ... (7 bytes))
1482290767: Received DISCONNECT from mosqpub/82534-MBP
1482290767: Client mosqpub/82534-MBP disconnected.

この試験では IMSI 付与をオンにしているのでトピックの末尾に IMSI が付与されているのが確認できます。(ドキュメントに載せるため、後半 8 桁をマスクしています。)

Subscribe

mosquitto を使ってデバイスから beam へ実際に Subscribe し、転送先の MQTT ブローカーからメッセージを Publish してみます。

デバイスからの Subscribe

$ mosquitto_sub -h beam.soracom.io -p 1883 -t test -d
Client mosqsub/82586-MBP sending CONNECT
Client mosqsub/82586-MBP received CONNACK
Client mosqsub/82586-MBP sending SUBSCRIBE (Mid: 1, Topic: test, QoS: 0)
Client mosqsub/82586-MBP received SUBACK
Subscribed (mid: 1): 0

Subscribe を受ける転送先 MQTT ブローカー

1482291094: New connection from 52.198.245.54 on port 8080.
1482291094: New client connected from 52.198.245.54 as mosqsub/82586-MBP (c1, k60).
1482291094: Sending CONNACK to mosqsub/82586-MBP (0, 0)
1482291094: Received SUBSCRIBE from mosqsub/82586-MBP
1482291094:     test (QoS 0)
1482291094: mosqsub/82586-MBP 0 test
1482291094: Sending SUBACK to mosqsub/82586-MBP

MQTT ブローカーに別のクライアントからメッセージを Publish

1482291169: New connection from 127.0.0.1 on port 8080.
1482291169: New client connected from 127.0.0.1 as mosqpub/3516-ip-10-0-0- (c1, k60).
1482291169: Sending CONNACK to mosqpub/3516-ip-10-0-0- (0, 0)
1482291169: Received PUBLISH from mosqpub/3516-ip-10-0-0- (d0, q0, r0, m0, 'test', ... (7 bytes))
1482291169: Sending PUBLISH to mosqsub/82586-MBP (d0, q0, r0, m0, 'test', ... (7 bytes))
1482291169: Received DISCONNECT from mosqpub/3516-ip-10-0-0-
1482291169: Client mosqpub/3516-ip-10-0-0- disconnected.

Publish されたメッセージを Beam 経由でデバイスが受け取る様子

Client mosqsub/82586-MBP received PUBLISH (d0, q0, r0, m0, 'test', ... (7 bytes))
message

MQTT エントリポイントに関する制限事項と注意事項

MQTT エントリポイントには以下の制限事項や注意事項があります。

• MQTT 接続時 (connect コマンド) のオプションについて
  • connect の keepalive に設定できる値は、0 または 5 以上 から 1200 以下の整数です。それ以外の値を設定した場合、connect リクエストに NOT_AUTHORIZED コードを返却します。
  • Beam では session の状態の保存を行っていませんが、MQTT ブローカーには clean session のパラメータをそのまま転送します。
• Publish 時
  • 接続先の MQTT ブローカーがサポートしていない QoS を指定した場合、コネクションが切断されたりエラーになったりする場合があります。
• 無通信時の切断について
  • keepalive に 0 以外の値が設定されているとき、SORACOM Beam は keepalive の 1.5 倍の時間、通信がない場合に TCP コネクションを切断します。
  • keepalive が 0 に設定されている場合、SORACOM Beam は 30 分間通信がない場合に TCP コネクションを切断します。
• MQTT 接続中にセルラー通信のセッションが切断された場合、SORACOM Beam との TCP セッションは不通になりますが、SORACOM Beam ではそれを検知できません。
  • 端末側で常時接続するユースケースの場合は、keepalive を有効化するか、クライアント側でセルラー通信のセッション断を検知して再接続する仕組みの導入を強く推奨します。
    keepalive に 5 以上 1200 以下の整数を指定すると、keepalive が有効となり、セッション断を検知できます。keepalive を有効化するとクライアントが指定された間隔で PINGREQ パケットを送出します。
  • セルラー通信の切断は、SORACOM ユーザーコンソールまたは SORACOM API で IoT SIM のセッション切断の操作を行うことで再現できます。
• Azure IoT Hub、Google IoT Core、PubNub、Watson IoT Platform については、認証情報を設定することでそれぞれに合わせた形式でリクエストを転送します。詳しくは、Getting Started の以下のページを参照してください。
  • Azure IoT Hub と接続する
  • Azure IoT Hub と X.509 証明書で認証した接続をする
  • Google IoT Core と接続する
  • IBM Watson IoT Platform と接続する
• Beam 設定で種別を「Azure IoT Hub」または「Google Cloud IoT Core」 にして接続する場合は、トークンの有効期限が 1 時間で失効します。Azure の場合は X.509 証明書で認証した接続 の利用も検討してください。

プラットフォームバージョン 201509 と 201912 の違い

MQTT エントリポイントの動作はプラットフォームバージョンによって異なります。 プラットフォームバージョンには 201912 (推奨) と 201509 (サポート終了予定) の 2 つがあります。

プラットフォームバージョン 201912 は、接続先ブローカーとの互換性・信頼性が向上しています。新たに MQTT エントリポイントを利用する場合は、201912 を選択してください。

課金対象メッセージ

デバイスと Beam、Beam と MQTT ブローカーの間でメッセージをやり取りしたときに、それぞれを個別に 1 リクエストとカウントし、リクエスト数に応じて課金されます (*1)。たとえば、クライアントからメッセージを 1 通 PUBLISH した場合、2 リクエストとカウントされます。

MQTT のバージョンおよび仕様に関する違い

転送先に接続するプロトコル

MQTT エントリポイントのプラットフォームバージョン変更時の注意事項

たとえば、以下のようなケースで、201912 へ変更後に接続エラーが発生することが報告されています。

クライアントが接続時に MQTT バージョンの指定をしていない場合 (特に Azure IoT Hub、Google IoT Core を利用している場合)

プラットフォームバージョン 201509 においては、クライアントが指定している MQTT バージョンに関わらず、ソラコムプラットフォームが MQTT バージョン 3.1.1 を使用して MQTT ブローカーに接続していました。

プラットフォームバージョン 201912 においては、アーキテクチャの変更によって、常にクライアントが指定する MQTT バージョンを使用して接続するように変更されました。そのため、クライアントが MQTT ブローカーが対応していない MQTT バージョン (3.1) を指定して接続した場合、接続エラーが発生します。また、デフォルトの MQTT バージョンが 3.1 になっている MQTT クライアントやデバイスが複数確認されています。

なお、MQTT バージョンの変更方法については MQTT クライアントやデバイスの取扱説明書を参照してください。

転送先に接続するプロトコルに MQTT を指定した状態で証明書を利用していた場合

プラットフォームバージョン 201509 においては、証明書 (key と cert) を利用している場合、転送先に接続するプロトコルの設定に関わらず MQTTS プロトコルで転送先に接続されます。

プラットフォームバージョン 201912 においては、証明書の利用有無に関わらず、転送先に指定されたプロトコルで接続します。

転送先のプロトコルが正しく設定されているかを事前に確認ください。