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 ゲートウェイを有効化できます。

Basic Configuration タブで Next をクリックし、すべてのデフォルト設定を受け入れます。
次に Listeners タブに遷移し、EMQX はポート 5683 で UDP リスナーを事前設定しています。再度 Next をクリックして設定を確定します。
最後に Enable ボタンをクリックし、CoAP ゲートウェイを有効化します。

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

上記の設定は 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 パスとメソッドを使用します。

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

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

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

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 をクリックするとリスナー追加ページが開き、以下の設定が可能です。

基本設定

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 クライアントガイド

コネクション作成

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 ゲートウェイのクライアント一覧を確認できます。

コネクション終了

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"

ハートビート

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} はパブリッシュメッセージのトピックです。例: coap/test にパブリッシュする場合、URI は ps/coap/test となります。
- {?QueryString} はリクエストパラメータ:
  - clientid: Connection Mode では必須、Connectionless Mode では任意。
  - token: Connection Mode のみ必須。
  - retain（任意）: リテインメッセージとしてパブリッシュするかどうか。ブール値で、デフォルトは false。
  - qos: メッセージの QoS。MQTT クライアントがメッセージを受信する際の QoS レベルを示す。0、1、2 の列挙値。
  - expiry: メッセージの有効期限（秒単位）。デフォルトは 0（期限なし）。
ペイロード: メッセージペイロード

レスポンス:

ステータスコード:
- 2.04: パブリッシュ成功
- 4.00: 不正なリクエスト。詳細なエラー情報がメッセージ本文に返されます。
- 4.01: 認可失敗。リクエスト形式は正しいが認可に失敗。
ペイロード: ステータスコードが 2.04 の場合は空、その他は ErrorMessage。

例：Connectionless Mode でメッセージをパブリッシュ

bash

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

または Connection Mode で 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} はサブスクライブするトピック。例: coap/test をサブスクライブする場合、URI は ps/coap/test。
- {?QueryString} はリクエストパラメータ:
  - clientid: Connection Mode では必須、Connectionless Mode では任意。
  - token: Connection Mode のみ必須。
  - qos: サブスクライブ QoS。ゲートウェイが CoAP クライアントにメッセージを配信する際の MessageType（CON または NON）を示します。列挙値:
    - 0: NON メッセージで配信
    - 1 または 2: CON メッセージで配信
ペイロード: 空

レスポンス:

ステータスコード:
- 2.05: サブスクライブ成功
- 4.00: 不正なリクエスト。詳細なエラー情報がメッセージ本文に返されます。
- 4.01: 認可失敗。リクエスト形式は正しいが認可に失敗。
ペイロード: ステータスコードが 2.05 の場合は空、その他は ErrorMessage。

例：Connectionless Mode で coap/test をサブスクライブ

bash

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

または Connection Mode で 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（Connection Mode の認証用）とは別物です。

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

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

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

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

リクエストパラメータ:

メソッド: GET
オプション: Observe を 1 に設定。
CoAP トークン: 元の Observe リクエストで使用したトークンを使用。
URI: ps/{+topic}{?QueryString*}
- {+topic} はサブスクライブ解除するトピック。例: coap/test の場合、URI は ps/coap/test。
- {?QueryString} はリクエストパラメータ:
  - clientid: Connection Mode では必須、Connectionless Mode では任意。
  - token: Connection Mode のみ必須。
ペイロード: 空

レスポンス:

ステータスコード:
- 2.07: サブスクライブ解除成功
- 4.00: 不正なリクエスト。詳細なエラー情報がメッセージ本文に返されます。
- 4.01: 認可失敗。リクエスト形式は正しいが認可に失敗。
ペイロード: ステータスコードが 2.07 の場合は空、その他は ErrorMessage。

例：Connection Mode で 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 の仕様とは異なり、同仕様では Reset メッセージ受信後または最終再送のタイムアウト後にサーバーがオブザーバーを削除することを要求しています。

短縮パラメータ名

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

パラメータ名	短縮名
`clientid`	`c`
`username`	`u`
`password`	`p`
`token`	`t`
`qos`	`q`
`retain`	`r`

スキーマレジストリ

LLM ベースの MQTT データ処理

サブスクリプションフィルター

メッセージキュー

MQTT ストリーム

MQTT over QUIC

クラスターリンク

MQTT ベースのファイル転送

マルチプロトコルゲートウェイ

JT/T 808 ゲートウェイ

GB/T 32960 ゲートウェイ

A2A over MQTT

MCP over MQTT

SDK

MCP ブリッジ

RTCサービス

Volcengine RTC

シナリオ

GPT-Realtime

EMQX クラスタリング

CoAP ゲートウェイ

CoAP ゲートウェイの有効化

CoAP クライアントとの連携

クライアントライブラリ

パブリッシュ／サブスクライブ

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

リスナーの追加

認証の設定

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

コネクション作成

コネクション終了

ハートビート

メッセージパブリッシュ

トピックサブスクライブ

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

プロトコル仕様との違い

短縮パラメータ名

JT/T 808 ゲートウェイ

GB/T 32960 ゲートウェイ

Volcengine RTC

シナリオ

GPT-Realtime

CoAP ゲートウェイ ​

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

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

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

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

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

リスナーの追加 ​

認証の設定 ​

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

コネクション作成 ​

コネクション終了 ​

ハートビート ​

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

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

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

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

短縮パラメータ名 ​

CoAP ゲートウェイ

CoAP ゲートウェイの有効化

CoAP クライアントとの連携

クライアントライブラリ

パブリッシュ／サブスクライブ

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

リスナーの追加

認証の設定

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

コネクション作成

コネクション終了

ハートビート

メッセージパブリッシュ

トピックサブスクライブ

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

プロトコル仕様との違い

短縮パラメータ名