MQTT コネクションの確立

MQTT プロトコルを使ってサーバーとやりとりするには、MQTT プロトコルによるコネクションを確立する必要があります。コネクションを取得する流れは、こちら のシーケンス図をご覧ください。

コネクションを確立するにはデフォルトの MQTT ブローカーに接続して、API の実行に使用するための接続情報を取得後、取得した MQTT ブローカーに接続します。API が実行できるのは、デフォルトのブローカーではなく新しく接続した方の MQTT ブローカーです。これらは、外部ライブラリー を使って実装できます。

コネクションを確立するには、以下の処理を順に行います。

デフォルト MQTT ブローカーへの接続

まずはデフォルト MQTT ブローカーに接続します。

  • ホスト名：mqtt-jp.kii.com
  • ポート番号：1883（TCP 接続）、8883（SSL/TLS 接続）、12470（WebSocket 接続）、12473（WebSocket SSL/TLS 接続）

通常、Thing からは、ポート番号 8883 を使用し、SSL/TLS で接続します。WebSocket は Web アプリからの用途を想定しています。

この MQTT ブローカーに以下の条件で接続します。

MQTT の接続パラメーター 指定する値
ユーザー名 type=oauth2&client_id={APP_ID}
パスワード client_secret={APP_KEY}
クライアント ID anonymous

接続時、多くの MQTT ライブラリーでは自動的に CONNECT コマンドの送信と CONNACK コマンドの受信が行われます。

PUBLISH コマンドの送信

デフォルト MQTT ブローカーへの接続後、初期登録 を実行するため、PUBLISH コマンドを送信します。以下の内容で PUBLISH コマンドを送信すると、API の実行に使用する Thing が Thing Interaction Framework に初期登録されます。

  • MQTT トピック名

    p/anonymous/thing-if/apps/{APP_ID}/onboardings

  • ペイロード

    ペイロードには下記のようなテキスト形式のデータを指定します。{VENDOR_THING_ID} と {THING_PASSWORD} には、初期登録で使用する Thing の vendorThingID とパスワードを指定します。

    POST
Content-type: application/vnd.kii.OnboardingWithVendorThingIDByThing+json

{
  "vendorThingID" : "{VENDOR_THING_ID}",
  "thingPassword" : "{THING_PASSWORD}"
}

    このフォーマットは、MQTT プロトコルを HTTPS プロトコルにマッピングするためのもので、Kii Cloud に特有の形式です。フォーマットの詳細は API の実行 をご覧ください。

PUBLISH コマンドの受信

初期登録の結果は、サーバー側からの PUBLISH コマンドとして受信できます。

PUBLISH コマンドで受信される MQTT トピック名は、送信時に指定したものと同じものです。

PUBLISH コマンドは様々な目的で受信するため、サーバー側からの PUBLISH コマンドを受け取った際には、必ず MQTT トピック名をチェックするように実装してください。また、未知の MQTT トピック名を持つ PUBLISH コマンドは、将来の拡張のため無視するように実装してください。

  • MQTT トピック名

    p/anonymous/thing-if/apps/{APP_ID}/onboardings

  • ペイロード

    ペイロードから、以下のようなテキストを受信できます。初期登録の実行結果と、API を処理できる MQTT ブローカーへの接続情報が含まれています。

    200
Accept-Ranges:bytes
Age:0
Cache-Control:max-age=0, no-cache, no-store
Content-Type:application/json
Date:Fri, 27 May 2016 05:44:17 GMT
Connection:keep-alive

{
  "accessToken" : "{ACCESS_TOKEN}",
  "thingID" : "{THING_ID}",
  "mqttEndpoint" : {
    "installationID" : "{INSTALLATION_ID}",
    "username" : "{USERNAME}",
    "password" : "{PASSWORD}",
    "mqttTopic" : "{MQTT_TOPIC}",
    "host" : "{BROKER_HOST}",
    "portTCP" : {PORT_TCP},
    "portSSL" : {PORT_SSL},
    "portWS" : {PORT_WS},
    "portWSS" : {PORT_WSS},
    "ttl" : {MQTT_TTL}
  }
}

この情報を受信した後は、デフォルト MQTT ブローカーへの接続を切断することができます。

デフォルト MQTT ブローカーでの接続では、初期登録以外の操作を実行することはできません。

MQTT ブローカーへの接続

次に、実際に API 呼び出しを受け付けるブローカーに接続します。初期登録の結果得られた MQTT ブローカーへの接続情報を使って、新しい MQTT コネクションを確立します。

接続には以下の情報を利用します。

接続に必要な情報 設定する値
接続先ホスト名 初期登録のレスポンス の "host"
接続先ポート番号 初期登録のレスポンス の "portTCP" （TCP 接続）または "portSSL" （SSL/TLS 接続）
WebSocket 接続用ポート番号 初期登録のレスポンス の "portWS"（TCP 接続）または "portWSS"（SSL/TLS 接続）
CONNECT コマンドの Keep alive timer アプリの実装に合わせて送信（キープアライブタイマー 参照）
CONNECT コマンドの Client identifier 初期登録のレスポンス の "mqttTopic"
CONNECT コマンドの Username 初期登録のレスポンス の "username"
CONNECT コマンドの Password 初期登録のレスポンス の "password"

さらに、通常は 初期登録のレスポンス の "mqttTopic" を SUBSCRIBE コマンドで講読しておきます。これは、プッシュ通知で利用する MQTT トピックで、モバイルアプリからの コマンド の受信を PUBLISH コマンドとして受け取ることができます。プッシュ通知で PUBLISH コマンドを受信した際の実装方法は コマンドの受信 をご覧ください。

キープアライブタイマー

MQTT では、コネクションが切れていないことを確認するために キープアライブタイマー による死活監視の方法が定められています。

MQTT プロトコルでは、CONNECT コマンドで送信した Keep alive timer 値の 1.5 倍の時間以内に、クライアントから何らかのメッセージを送信しないと、コネクションは自動的に切断されます。この時間内にクライアントからのメッセージ送信がない場合、PINGREQ コマンドを送信する必要があります。実装方法は使用する MQTT ライブラリーのドキュメントを参照してください。

MQTT クライアントの実装後は、送信コマンドがない状態でしばらく放置し、その後、コネクションが切れないことを確認しておくことをお勧めします。コネクションが一定時間で切れる場合、PINGREQ コマンドが送信されていない可能性があります。