Skip to content

CoAP ゲートウェイ ​

EMQX の CoAP ゲートウェイは、Publish-Subscribe Broker for the CoAP プロトコルに準拠し、標準的なパブリッシュ、サブスクライブ、およびメッセージ受信を実現します。

以下は、接続モードおよびコネクションレスモードでサポートされる機能一覧です。

機能コネクションレスモード接続モード
メッセージパブリッシュ√√
トピックサブスクライブ√√
トピックのサブスクライブ解除×√
接続の作成×√
接続のクローズ×√
ハートビート×√
認証×√

CoAP ゲートウェイの有効化 ​

EMQX 5 では、CoAP ゲートウェイはダッシュボード、REST API、および設定ファイル base.hocon を通じて設定および有効化できます。本節では、ダッシュボードを使った設定手順を例に説明します。

EMQX ダッシュボードの左ナビゲーションメニューで Extensions -> Gateways をクリックします。Gateway ページにはサポートされているすべてのゲートウェイが一覧表示されます。CoAP を探し、Actions 列の Setup をクリックすると、Initialize CoAP ページに遷移します。

TIP

EMQX をクラスターで運用している場合、ダッシュボードや REST API で行った設定はクラスター全体に影響します。特定のノードのみ設定を変更したい場合は、base.hocon で設定してください。

EMQX CoAP ゲートウェイはコネクションレスモードと接続モードの両方をサポートします。コネクションレスモードではメッセージはワンオフの送信として扱われ、センサーの読み取りやシンプルなコマンド送信などの短時間のやり取りに適しています。接続モードでは、クライアントがデータ転送開始前にブローカーと接続を確立します。

Connection Requested の設定で、接続モード(true)またはコネクションレスモード(false)を選択できます。デフォルトは false です。

接続モードを確認したら、設定を続けます。特にカスタマイズが不要な場合は、以下の3ステップで CoAP ゲートウェイを有効化できます。

  1. Basic Configuration タブで Next をクリックし、すべてのデフォルト設定を受け入れます。
  2. 続いて表示される Listeners タブでは、EMQX がポート 5683 で UDP リスナーを事前設定しています。ここでも Next をクリックして設定を確認します。
  3. 最後に Enable ボタンをクリックして CoAP ゲートウェイを有効化します。

ゲートウェイの有効化が完了すると、Gateways ページに戻り、CoAP ゲートウェイのステータスが Enabled と表示されます。

CoAPゲートウェイ有効化

上記の設定は REST API でも行えます。

例:

bash
curl -X 'PUT' 'http://127.0.0.1:18083/api/v5/gateways/coap' \
  -u <your-application-key>:<your-security-key> \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "coap",
  "enable": true,
  "mountpoint": "coap/",
  "connection_required": false,
  "listeners": [
    {
      "type": "udp",
      "name": "default",
      "bind": "5683",
      "max_conn_rate": 1000,
      "max_connections": 1024000
    }
  ]
}'

詳細な REST API の説明は REST API - Gateway を参照してください。

カスタマイズが必要な場合やリスナーの追加、認証ルールの追加を行いたい場合は、CoAP ゲートウェイのカスタマイズ セクションをお読みください。

CoAP ゲートウェイは UDP および DTLS タイプのリスナーのみをサポートしています。設定可能なパラメータの完全なリストは Gateway Configuration - Listeners を参照してください。

CoAP クライアントとの連携 ​

クライアントライブラリ ​

CoAP ゲートウェイを構築したら、CoAP クライアントツールを使って接続をテストし、正常に動作することを確認できます。以下は推奨される CoAP クライアントツールの例です。

パブリッシュ/サブスクライブ ​

CoAP ゲートウェイは Publish-Subscribe Broker for the CoAP 標準で定義された URI パスとメソッドを使用します。

詳細なパラメータは メッセージパブリッシュ、トピックサブスクライブ、トピックのサブスクライブ解除 を参照してください。

EMQX 6.3.3 以降、CoAP ゲートウェイは認可前にデコードされたトピックの検証を行います。パブリッシュリクエストは有効な MQTT トピック名を使用し、サブスクライブまたはサブスクライブ解除リクエストは有効な MQTT トピックフィルターを使用する必要があります。

ブロック単位転送(Block-Wise Transfer) ​

CoAP ゲートウェイは、単一のデータグラムに収まらない大きなペイロードに対して CoAP Block-Wise Transfer をサポートしています。ゲートウェイは送信ペイロードをブロックに分割し、受信ブロックを再構成してから完全なペイロードを処理します。ピアが blockwise.max_block_size より大きなブロックサイズを提案した場合、EMQX は設定された最大値まで転送サイズを交渉します。

Block-Wise 転送は REST API または設定ファイルで設定可能です。

Block-Wise の設定項目は以下の通りです。EMQX 6.3.3 以降、blockwise.max_concurrent_exchanges と blockwise.max_total_size は各クライアントセッションが保持する Block-Wise 状態の制限に適用されます。

設定項目型デフォルト説明
blockwise.enableBooleantrueBlock-Wise 転送を有効にするかどうか。
blockwise.max_block_sizeブロックサイズ1024最大ブロックサイズ(バイト単位)。利用可能な値は 16, 32, 64, 128, 256, 512, 1024。
blockwise.max_body_sizeバイトサイズ"4MB"再構成後のペイロード最大サイズ。0 より大きい必要があります。これを超えるペイロードは EMQX により拒否されます。
blockwise.max_concurrent_exchanges整数161 クライアントセッションが保持できる最大 Block-Wise 交換数。0 より大きい必要があります。制限に達すると新規 Block1 アップロードは 4.29 Too Many Requests を受け、送信中の Observe 通知はキューに入ります。
blockwise.max_total_sizeバイトサイズ"16MB"1 クライアントセッションが保持できる Block-Wise 交換の合計ペイロード最大サイズ。0 より大きい必要があります。制限に達すると新規 Block1 アップロードは 4.13 Request Entity Too Large を受けます。ペイロードが収まる場合、送信中の Observe 通知はキューに入ります。
blockwise.exchange_lifetime期間"247s"EMQX が一時的な Block-Wise 交換状態を保持する期間。0 より大きい必要があります。状態が期限切れになると、EMQX は対応するセッション容量を解放します。

交換数と保持ペイロードサイズの制限は各クライアントセッションごとに独立して適用されます。リスナー全体で共有される制限ではありません。キューに入った Observe 通知は容量が空くと送信を再開し、保持 Block-Wise 状態の期限切れによる容量解放も含みます。

EMQX 6.3.3 以降、blockwise.max_body_size、blockwise.max_total_size、blockwise.exchange_lifetime は 0 より大きい必要があります。REST API は非正の値を拒否し、保存済みのゲートウェイ設定は変更しません。

CoAP ゲートウェイのカスタマイズ ​

デフォルト設定に加え、EMQX はさまざまな設定オプションを提供し、特定のビジネス要件に柔軟に対応できます。本節では Gateways ページで利用可能な各フィールドの詳細を説明します。スクリーンショット下の説明もご参照ください。

image-20230420152920254
  • Connection Required: コネクションレスモードか接続モードかを設定します。デフォルトは false(コネクションレス)。選択肢は false(コネクションレス)、true(接続モード)です。

  • Notification Message Type: 配信する CoAP メッセージのタイプを設定します。デフォルトは qos。選択肢は以下の通りです。

    • qos: CoAP 通知のアック要否は受信したメッセージの QoS レベルに依存します。
      • QoS 0 の場合、クライアントからのアックは不要
      • QoS 1/2 の場合、クライアントからのアックが必要
    • con: CoAP 通知はクライアントからのアックが必要
    • non: CoAP 通知はクライアントからのアックは不要
  • Heartbeat: Connection Required が true の場合のみ必要。接続維持のための最小ハートビート間隔を設定します。デフォルトは 30 秒。

  • Enable Statistics: ゲートウェイによる統計収集と報告を許可するか設定します。デフォルトは true。選択肢は true、false。

  • Subscriber QoS: サブスクライブリクエストのデフォルト QoS レベルを設定します。デフォルトは coap。選択肢は以下の通りです。

    • coap: Notification Message Type の設定に従い QoS レベルを決定
      • アック不要の場合は QoS 0
      • アック必要の場合は QoS 1
    • qos0, qos1, qos2
  • Publish QoS: パブリッシュリクエストのデフォルト QoS レベルを設定します。デフォルトは coap。選択肢は coap、qos0、qos1、qos2。

  • MountPoint: パブリッシュやサブスクライブ時にすべてのトピックの前に付加される文字列を設定します。異なるプロトコル間でのメッセージルーティングの分離を実現できます。例: CoAP。

    注意: このトピックプレフィックスはゲートウェイが管理します。CoAP クライアントはパブリッシュやサブスクライブ時に明示的にこのプレフィックスを付加する必要はありません。

リスナーの追加 ​

デフォルトで、名前が default の UDP リスナーがポート 5683 で設定されており、最大 1,024,000 の同時接続をサポートしています。Settings をクリックするとより詳細な設定が可能で、Delete でリスナーを削除、Add Listener で新規リスナーを追加できます。

coap-advanced-conf

Add Listener をクリックすると Add Listener ページが開き、以下の設定を行えます。

基本設定

  • Name: リスナーの一意識別子を設定します。
  • Type: プロトコルタイプを選択します。CoAP では udp または dtls のいずれかです。
  • Bind: リスナーが接続を受け付けるポート番号を設定します。
  • MountPoint(任意): パブリッシュやサブスクライブ時にすべてのトピックの前に付加される文字列を設定します。

リスナー設定

  • Max Connections: リスナーが処理可能な最大同時接続数を設定します。デフォルトは 1024000。
  • Max Connection Rate: リスナーが1秒あたりに受け入れ可能な新規接続の最大レートを設定します。デフォルトは 1000。

UDP 設定

  • ActiveN: ソケットの {active, N} オプションを設定します。これはソケットが積極的に処理できる受信パケット数です。詳細は Erlang Documentation - setopts/2 を参照してください。
  • Buffer: 受信および送信パケットを格納するバッファのサイズを KB 単位で設定します。
  • Receive Buffer: 受信バッファのサイズを KB 単位で設定します。
  • Send Buffer: 送信バッファのサイズを KB 単位で設定します。
  • SO_REUSEADDR: ポート番号のローカル再利用を許可するか設定します。

DTLS 設定(DTLS リスナーのみ)

TLS Verify の有効化はトグルスイッチで設定可能ですが、その前に関連する TLS Cert、TLS Key、および CA Cert の情報をファイル内容の入力または Select File ボタンでアップロードして設定する必要があります。詳細は Enable SSL/TLS Connections を参照してください。

認証の設定 ​

クライアント ID、ユーザー名、パスワードはクライアントの Create Connection リクエストで提供されます。CoAP ゲートウェイは以下の認証方式をサポートします。

ここではダッシュボードを例に認証設定方法を説明します。

Gateways ページで CoAP を探し、Actions 列の Setup をクリックし、Authentication タブに入ります。

Create Authentication をクリックし、Mechanism に Password-Based または JWT を選択し、必要に応じて Backend を選択します。

認証方式の詳細な設定方法は本節冒頭のリンク先を参照してください。

ダッシュボードのほか、REST API でも認証設定が可能です。例えば、CoAP ゲートウェイ用に組み込みデータベース認証を作成するには以下のコードを使用します。

bash
curl -X 'POST' \
  'http://127.0.0.1:18083/api/v5/gateway/coap/authentication' \
  -u <your-application-key>:<your-security-key> \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "built_in_database",
  "mechanism": "password_based",
  "password_hash_algorithm": {
    "name": "sha256",
    "salt_position": "suffix"
  },
  "user_id_type": "username"
}'

TIP

MQTT プロトコルとは異なり、ゲートウェイは認証方式の作成のみをサポートし、認証方式のリスト(または認証チェーン)はサポートしていません。認証方式が有効でない場合、すべての CoAP クライアントのログインが許可されます。

リファレンス: CoAP クライアントガイド ​

Create Connection ​

Connection Mode のみ利用可能です。

このインターフェースは CoAP ゲートウェイへのクライアント接続を作成するために使用します。CoAP ゲートウェイの認証が有効な場合、このリクエストで提供された clientid、username、password を検証し、不正ユーザーを防止します。

リクエストパラメータ:

  • メソッド: POST
  • URI: mqtt/connection{?QueryString*}。QueryString は以下の通り:
    • clientid: 必須パラメータ、UTF-8 文字列。ゲートウェイはこの文字列を接続の一意識別子として使用します。
    • username: 任意パラメータ、UTF-8 文字列。接続認証に使用。
    • password: 任意パラメータ、UTF-8 文字列。接続認証に使用。
  • ペイロード: 空

レスポンス:

  • ステータスコード:
    • 2.01: 接続作成成功。接続用のトークン文字列がメッセージボディに返されます。
    • 4.00: 不正なリクエスト。詳細なエラー情報がメッセージボディに返されます。
    • 4.01: 認可失敗。リクエスト形式は正しいが認可に失敗しました。
  • ペイロード: ステータスコードが 2.01 の場合は Token、それ以外は ErrorMessage。
    • Token: 後続リクエストで使用するトークン文字列。
    • ErrorMessage: エラー説明メッセージ。

例として libcoap を使った接続作成リクエスト:

bash
# clientid 123、username と password に admin/public を指定して接続リクエストを送信。
# 返却されたトークンは 3404490787
coap-client -m post -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&username=admin&password=public"

3404490787

TIP

接続が正常に作成された後、ダッシュボード、REST API、CLI を使って CoAP ゲートウェイのクライアント一覧を確認できます。

Close Connection ​

Connection Mode のみ利用可能です。

このインターフェースは CoAP 接続をクローズするために使用します。

リクエストパラメータ:

  • メソッド: DELETE
  • URI: mqtt/connection{?QueryString*}。QueryString は以下の通り:
    • clientid: 必須パラメータ、UTF-8 文字列。ゲートウェイはこの文字列を接続の一意識別子として使用します。
    • token: 必須パラメータ。Create Connection リクエストで返されたトークン文字列を使用。
  • ペイロード: 空

レスポンス:

  • ステータスコード:
    • 2.01: 接続クローズ成功。
    • 4.00: 不正なリクエスト。詳細なエラー情報がメッセージボディに返されます。
    • 4.01: 認可失敗。リクエスト形式は正しいが認可に失敗しました。
  • ペイロード: ステータスコードが 2.01 の場合は Token、それ以外は ErrorMessage。

例:

bash
coap-client -m delete -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&token=3404490787"

Heartbeat ​

Connection Mode のみ利用可能です。

このインターフェースは CoAP クライアントとゲートウェイ間の接続維持に使用します。ハートビートが期限切れになると、ゲートウェイはセッションとサブスクリプションを削除し、そのクライアントのすべてのリソースを解放します。

リクエストパラメータ:

  • メソッド: PUT
  • URI: mqtt/connection{?QueryString*}。QueryString は以下の通り:
    • clientid: 必須パラメータ、UTF-8 文字列。ゲートウェイはこの文字列を接続の一意識別子として使用します。
    • token: 必須パラメータ。Create Connection リクエストで返されたトークン文字列を使用。
  • ペイロード: 空

レスポンス:

  • ステータスコード:
    • 2.01: 接続クローズ成功。
    • 4.00: 不正なリクエスト。詳細なエラー情報がメッセージボディに返されます。
    • 4.01: 認可失敗。リクエスト形式は正しいが認可に失敗しました。
  • ペイロード: ステータスコードが 2.01 の場合は Token、それ以外は ErrorMessage。

例:

bash
coap-client -m put -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&token=3404490787"

TIP

ハートビート間隔は CoAP ゲートウェイの heartbeat オプションで決まり、デフォルトは 30 秒です。

メッセージパブリッシュ ​

このインターフェースは CoAP クライアントが指定したトピックにメッセージを送信するために使用します。Connection Mode が有効な場合は追加の識別情報を含める必要があります。

リクエストパラメータ:

  • メソッド: POST

  • URI: ps/{+topic}{?QueryString*}

    • {+topic} はパブリッシュ先の MQTT トピック名です。例: coap/test にパブリッシュする場合は URI ps/coap/test を使用します。デコード後の値は有効な MQTT トピック名であり、ワイルドカード文字 + または # を含んではいけません。
    • {?QueryString} はリクエストパラメータ:
      • clientid: Connection Mode では必須、Connectionless Mode では任意。
      • token: Connection Mode のみ必須。
      • retain(任意): メッセージをリテインドメッセージとしてパブリッシュするか。ブール値で、デフォルトは false。
      • qos: メッセージの QoS。メッセージの QoS レベルを示し、MQTT クライアントの受信方法にのみ影響します。値は 0、1、2 のいずれか。
      • expiry: メッセージの有効期限(秒単位)。デフォルトは 0(期限なし)。
  • ペイロード: メッセージペイロード

レスポンス:

  • ステータスコード:
    • 2.04: パブリッシュ成功
    • 4.00: 不正なリクエスト。トピック名が無効な場合、メッセージボディは invalid topic。
    • 4.01: 認可失敗。リクエスト形式は正しいが認可に失敗しました。
  • ペイロード: ステータスコードが 2.04 の場合は空、その他は ErrorMessage。

例: コネクションレスモードでメッセージをパブリッシュ

bash
coap-client -m post -e "Hi, this is libcoap" "coap://127.0.0.1/ps/coap/test"

または、接続モードで clientid と token を付与してパブリッシュ

bash
coap-client -m post -e "Hi, this is libcoap" "coap://127.0.0.1/ps/coap/test?clientid=123&token=3404490787"

トピックサブスクライブ ​

このインターフェースは CoAP クライアントがトピックをサブスクライブするために使用します。Connection Mode が有効な場合は追加の識別情報を含める必要があります。

リクエストパラメータ:

  • メソッド: GET

  • オプション: Observe を 0 に設定

  • CoAP トークン: Observe 関係を識別するために空でないトークンを使用

  • URI: ps/{+topic}{?QueryString*}

    • {+topic} はサブスクライブする MQTT トピックフィルターです。例: coap/test にサブスクライブする場合は URI ps/coap/test を使用します。デコード後の値は有効な MQTT トピックフィルターである必要があります。例として a/#/b、a+/b、#a は無効なトピックフィルターです。
    • {?QueryString} はリクエストパラメータ:
      • clientid: Connection Mode では必須、Connectionless Mode では任意。
      • token: Connection Mode のみ必須。
      • qos: サブスクライブ QoS。ゲートウェイが CoAP クライアントにメッセージを配信する際に使用する MessageType(CON または NON)を示します。値は以下の通り。
        • 0: NON メッセージで配信
        • 1 または 2: CON メッセージで配信
  • ペイロード: 空

レスポンス:

  • ステータスコード:
    • 2.05: サブスクライブ成功
    • 4.00: 不正なリクエスト。トピックフィルターが無効な場合、メッセージボディは invalid topic。
    • 4.01: 認可失敗。リクエスト形式は正しいが認可に失敗しました。
  • ペイロード: ステータスコードが 2.05 の場合は空、その他は ErrorMessage。

例: コネクションレスモードで coap/test をサブスクライブ

bash
coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://127.0.0.1/ps/coap/test"

または、接続モードで clientid と token を付与してサブスクライブ

bash
coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://127.0.0.1/ps/coap/test?clientid=123&token=3404490787"

-T "obstoken" で設定した CoAP トークンは Observe 関係を識別します。URI クエリパラメータの token は接続モードでの認証に使用され、これとは別のものです。

トピックのサブスクライブ解除 ​

このインターフェースは CoAP クライアントがトピックのサブスクライブを解除するために使用します。

Observe 関係を明示的に解除するには、同じリソースに対して Observe: 1 と元の Observe トークンを付けて GET リクエストを送信します。

現状の実装では、サブスクライブ解除操作は Connection Mode のみで利用可能です。

リクエストパラメータ:

  • メソッド: GET

  • オプション: Observe を 1 に設定

  • CoAP トークン: 元の Observe リクエストで使用したトークンを使用

  • URI: ps/{+topic}{?QueryString*}

    • {+topic} はサブスクライブ解除する MQTT トピックフィルターです。例: coap/test のサブスクライブを解除する場合は URI ps/coap/test を使用します。デコード後の値は有効な MQTT トピックフィルターである必要があります。
    • {?QueryString} はリクエストパラメータ:
      • clientid: Connection Mode では必須、Connectionless Mode では任意。
      • token: Connection Mode のみ必須。
  • ペイロード: 空

レスポンス:

  • ステータスコード:
    • 2.07: サブスクライブ解除成功
    • 4.00: 不正なリクエスト。トピックフィルターが無効な場合、メッセージボディは invalid topic。
    • 4.01: 認可失敗。リクエスト形式は正しいが認可に失敗しました。
  • ペイロード: ステータスコードが 2.07 の場合は空、その他は ErrorMessage。

例: 接続モードで coap/test のサブスクライブを解除

bash
coap-client -m get -O 6,0x01 -T "obstoken" "coap://127.0.0.1/ps/coap/test?clientid=123&token=3404490787"

プロトコル仕様との違い ​

EMQX 6.3 リリースでは、クライアントが Reset メッセージで確認可能(CON)Observe 通知を拒否した場合や、すべての再送試行がアックなしでタイムアウトした場合、EMQX は以下の処理を行います。

  • 失敗した通知を破棄する。
  • その通知に関連するトランスポートおよび Block2 状態をクリーンアップする。
  • Observe 関係およびブローカーのサブスクリプションは保持する。

そのため、後続のリソース変更は保持された関係を通じて引き続き配信される可能性があります。関係を保持することは失敗した通知の再配信を保証しません。これらの失敗は関係自体をキャンセルしません。通常のクライアントセッションのクリーンアップが適用されます。

この動作は互換性のために維持されています。RFC 7641 セクション 4.5 (RFC 7641 section 4.5) とは異なり、Reset メッセージ受信後または最終再送タイムアウト後にサーバーがオブザーバーを削除することを要求していません。

短縮パラメータ名 ​

メッセージサイズ削減のため、CoAP ゲートウェイは短縮パラメータ名をサポートしています。例えば、clientid=barx は c=bar と書けます。サポートされる短縮パラメータ名は以下の通りです。

パラメータ名短縮名
clientidc
usernameu
passwordp
tokent
qosq
retainr