CoAP 协议网关
CoAP 网关以 Publish-Subscribe Broker for the CoAP 为标准,实现了发布、订阅、和消息接收功能。
快速开始
EMQX 5.0 可以通过 Dashboard 配置并启用 CoAP 网关。
也可以通过 REST API 或 base.hocon 来启用,例如:
TIP
通过配置文件来配置网关,需要在每个节点上手动同步配置文件;而通过 Dashboard 或者 REST API 管理则会自动同步至整个集群。
CoAP 网关支持 UDP、DTLS 类型的监听器,其完整可配置的参数列表可以参考 EMQX 企业版配置手册中的网关配置 - 监听器。
工作模式
CoAP 网关支持 2 种工作模式:
无连接模式:该模式完全遵循 Publish-Subscribe Broker for the CoAP 协议,在该模式下不需要连接创建会话、心跳维持等操作,仅支持:- 消息发布
- 订阅主题
- 认证
连接模式:该模式下定义了连接认证、会话、和心跳维持等概念。客户端在发布订阅前需要先创建连接,成功连接后客户端将获得会话令牌(Token),在后续的通信中都需要在 Query String 加入令牌信息。它实现了如下功能:- 创建连接
- 关闭连接
- 会话保持 (心跳, 可选的)
- 认证
是否开启 连接模式 由 connection_required 参数决定,例如
# base.hocon
gateway.coap {
## true: 开启连接模式
## false: 关闭连接模式
connection_required = true
}TIP
连接模式 仅新增了连接管理相关接口。该模式下仍可以执行发布/订阅、取消订阅等操作,但每次请求需要携带 ClientId 和 Token。
认证
客户端 ID、用户名、密码由客户端的创建连接请求提供,CoAP 网关支持以下认证器类型:
例如,通过 REST API 或 base.hocon 为 CoAP 网关创建一个内置数据库认证:
与 MQTT 协议不同,网关仅支持创建一个认证器,而不是认证器列表(或认证链)。当不启用任何认证器时,表示所有的 CoAP 客户端都具有接入的权限。
其他类型的认证器的配置格式参考:安全 - 认证器
发布订阅
CoAP 网关基于 Publish-Subscribe Broker for the CoAP 协议中定义的请求路径和请求方法 实现了发布订阅的接口。
网关内无独立的发布订阅的权限控制,其对主题的权限控制需要统一在 授权(Authorization) 中管理。
从 EMQX 6.3.3 开始,CoAP 网关会在授权前验证解码后的主题。发布请求必须使用有效的 MQTT 主题名,订阅或取消订阅请求必须使用有效的 MQTT 主题过滤器。
Block-Wise 传输
CoAP 网关支持 CoAP Block-Wise Transfer,用于传输无法装入单个数据报的负载。网关会将待发送的负载拆分为多个块,并在处理收到的负载前完成分块重组。如果对端提出的有效分块大小超过 blockwise.max_block_size,EMQX 会将分块大小协商为配置的最大值。
可通过 REST API 或配置文件配置 Block-Wise 传输。
Block-Wise 传输相关配置项说明如下。从 EMQX 6.3.3 开始,blockwise.max_concurrent_exchanges 和 blockwise.max_total_size 用于限制每个客户端会话保留的 Block-Wise 状态。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
blockwise.enable | Boolean | true | 是否启用 Block-Wise 传输。 |
blockwise.max_block_size | Block Size | 1024 | 最大分块大小,单位为字节。可选值为 16、32、64、128、256、512 和 1024。 |
blockwise.max_body_size | Byte Size | "4MB" | 重组后负载的最大大小。该值必须大于 0。EMQX 会拒绝超过此限制的负载。 |
blockwise.max_concurrent_exchanges | Integer | 16 | 每个客户端会话可保留的最大 Block-Wise 交换数。该值必须大于 0。达到限制后,新的 Block1 上传会收到 4.29 Too Many Requests,待发送的 Observe 通知则进入队列等待。 |
blockwise.max_total_size | Byte Size | "16MB" | 每个客户端会话中 Block-Wise 交换可保留的最大负载总大小。该值必须大于 0。达到限制后,新的 Block1 上传会收到 4.13 Request Entity Too Large。如果其他交换释放容量后可容纳其负载,待发送的 Observe 通知会进入队列等待。 |
blockwise.exchange_lifetime | Duration | "247s" | EMQX 保留临时 Block-Wise 交换状态的时长。该值必须大于 0。状态过期后会释放对应的会话容量。 |
交换数和保留负载大小限制分别应用于每个客户端会话,不限制监听器上所有会话的资源总量。排队的 Observe 通知会在容量可用后继续发送,例如已保留的 Block-Wise 状态过期且 EMQX 释放相应容量时。
从 EMQX 6.3.3 开始,blockwise.max_body_size、blockwise.max_total_size 和 blockwise.exchange_lifetime 必须大于 0。REST API 会拒绝非正数值,且不会更改已保存的网关配置。
用户层接口
详细配置说明参考:网关配置 - CoAP 网关
详细 REST API 接口参考:REST API - 网关
客户端库
附录:客户端接入接口说明
创建连接
仅在 连接模式 下可用。
该接口用于向 CoAP 网关创建客户端连接。当开启 CoAP 网关的认证功能后,网关会对该请求中的 clientid, username, password 进行验证,以防止非法用户登录系统。
请求参数表:
- 方法(Method):
POST - 请求路径(URI):
mqtt/connection{?QueryString*},其中QueryString可用参数为clientid:必填参数;UTF8 字符串,网关以该字符串作为该连接的唯一标识。username:可选参数,UTF8 字符串,用于连接认证。password:可选参数,UTF8 字符串,用于连接认证。
- 消息体(Payload):为空。
返回结果:
- 返回码(Return Code):
2.01:连接创建成功,并在消息体中返回本次连接的 Token 字符串。4.00:错误的请求格式,并在消息体中返回具体的错误信息。4.01:请求格式正确,但登录鉴权失败。并在消息体中返回具体的错误信息。
- 消息体(Payload):当返回码为
2.01时,消息体为Token,否则为ErrorMessageToken:用于后续请求使用的令牌字符串。ErrorMessage: 错误说明,例如Login Failed: not_authorized
以 libcoap 为例:
# 使用 clientid 为 123, 用户名密码为 admin/public 发起创建连接请求,
# 返回 Token 为 3404490787
coap-client -m post -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&username=admin&password=public"
3404490787TIP
连接创建成功后,可以使用 Dashboard,REST API 或 CLI 检查 CoAP 网关的客户端列表中是否已存在该客户端。
断开连接
仅在 连接模式 下可用。
该接口用于关闭 CoAP 客户端连接。
请求参数表:
- 方法(Method):
DELETE - 请求路径(URI):
mqtt/connection{?QueryString*},其中QueryString可用参数为clientid:必填参数;UTF8 字符串,网关以该字符串作为该连接的唯一标识。token:必填参数;使用由创建连接方法返回的 Token 字符串
- 消息体(Payload):为空。
返回结果:
- 返回码(Return Code):
2.01:关闭连接成功。4.00:错误的请求格式,并在消息体中返回具体的错误信息。4.01:请求格式正确,但登录鉴权失败。并在消息体中返回具体的错误信息。
- 消息体(Payload):当返回码为
2.01时,消息体为空;否则为具体的错误消息
例如:
coap-client -m delete -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&token=3404490787"心跳
仅在 连接模式 下可用。
该接口用于维持 CoAP 客户端与网关的连接。当心跳超期后,网关会删除该客户端的会话、订阅关系,并释放所有的资源。
请求参数表:
- 方法(Method):
PUT - 请求路径(URI):
mqtt/connection{?QueryString*},其中QueryString可用参数为clientid:必填参数;UTF8 字符串,网关以该字符串作为该连接的唯一标识。token:必填参数;使用由创建连接方法返回的 Token 字符串
- 消息体(Payload):为空。
返回结果:
- 返回码(Return Code):
2.01:更新成功。4.00:错误的请求格式,并在消息体中返回具体的错误信息。4.01:请求格式正确,但登录鉴权失败。并在消息体中返回具体的错误信息。
- 消息体(Payload):当返回码为
2.01时,消息体为空;否则为具体的错误消息
例如:
coap-client -m put -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&token=3404490787"TIP
心跳间隔时间由 CoAP 网关的 heartbeat 配置决定,默认为 30 秒
消息发布
该接口用于 CoAP 客户端为指定主题发送消息。在 连接模式 下需要额外携带身份信息。
请求参数表:
- 方法(Method):
POST - 请求路径(URI):
ps/{+topic}{?QueryString*},其中:{+topic}为发布消息使用的 MQTT 主题名。例如,向coap/test发布消息时,请求路径为ps/coap/test。解码后的值必须是有效的 MQTT 主题名,不能包含通配符+或#。{?QueryString*}为请求参数clientid:连接模式下为必填参数,无连接模式下为可选参数。token: 仅用于连接模式,必填参数;retain:是否作为保留消息进行发布;布尔类型,可选参数,默认为false。qos:消息 QoS,用于标识该消息的 QoS 等级,仅影响 MQTT 客户端如何接收该消息;枚举类型,可选值为0、1、2expiry:消息超期时间,单位秒;默认为0表示永不超期
- 消息体(Payload):消息内容
返回结果:
- 返回码(Return Code):
2.04:发送成功。4.00:请求无效。如果主题名无效,消息体为invalid topic。4.01:请求格式正确,但鉴权失败。并在消息体中返回具体的错误信息。
- 消息体(Payload):当返回码为
2.04时,消息体为空;否则为具体的错误消息
例如,无连接模式 下为 coap/test 发送一条消息:
coap-client -m post -e "Hi, this is libcoap" "coap://127.0.0.1/ps/coap/test"连接模式 下则需要携带 clientid 和 token
coap-client -m post -e "Hi, this is libcoap" "coap://127.0.0.1/ps/coap/test?clientid=123&token=3404490787"订阅主题
该接口用于 CoAP 客户端订阅指定主题。在 连接模式 下需要额外携带身份信息。
请求参数表:
方法(Method):
GET选项值(Options):需设置
Observe为0。CoAP Token:使用非空 Token 标识 Observe 关系。
请求路径(URI):
ps/{+topic}{?QueryString*},其中:{+topic}为订阅使用的 MQTT 主题过滤器。例如,订阅coap/test时,请求路径为ps/coap/test。解码后的值必须是有效的 MQTT 主题过滤器。例如,a/#/b、a+/b和#a均为无效主题过滤器。{?QueryString*}为请求参数clientid:连接模式下为必填参数,无连接模式下为可选参数。token: 仅用于连接模式,必填参数;qos:订阅 QoS,用于指示网关以那种消息类型(CON或NON)来投递后续接收的该消息;枚举类型,可选值为:0,1,2:设置为qos0,qos1或qos2。如果设置为qos0表示该主题上的消息会以 NON 消息进行投递;qos1,qos2表示该主题上的消息会以 CON 消息进行投递。
消息体(Payload):空
返回结果:
- 返回码(Return Code):
2.05:订阅成功。4.00:请求无效。如果主题过滤器无效,消息体为invalid topic。4.01:请求格式正确,但鉴权失败。并在消息体中返回具体的错误信息。
- 消息体(Payload):当返回码为
2.05时,消息体为空;否则为具体的错误消息
例如,无连接模式 下订阅主题 coap/test :
coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://127.0.0.1/ps/coap/test"连接模式 下则需要携带 clientid 和 token:
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 Token 用于标识 Observe 关系。它与 URI 查询参数 token 不同,后者用于在 连接模式 下验证请求身份。
取消订阅
该接口用于 CoAP 客户端取消订阅指定主题。要显式取消 Observe 关系,请向原资源发送 GET 请求,设置 Observe: 1,并使用建立该关系时的 Observe Token。 目前,取消订阅操作仅在 连接模式 下可用。
请求参数表:
- 方法(Method):
GET - 选项值(Options):需设置
Observe为1。 - CoAP Token:使用原 Observe 请求中的 Token。
- 请求路径(URI):
ps/{+topic}{?QueryString*},其中:{+topic}为取消订阅使用的 MQTT 主题过滤器。例如,取消订阅coap/test时,请求路径为ps/coap/test。解码后的值必须是有效的 MQTT 主题过滤器。{?QueryString*}为请求参数clientid:连接模式下为必填参数,无连接模式下为可选参数。token: 仅用于连接模式,必填参数;
- 消息体(Payload):空
返回结果:
- 返回码(Return Code):
2.07:取消订阅成功。4.00:请求无效。如果主题过滤器无效,消息体为invalid topic。4.01:请求格式正确,但鉴权失败。并在消息体中返回具体的错误信息。
- 消息体(Payload):当返回码为
2.07时,消息体为空;否则为具体的错误消息
例如,连接模式 下取消订阅主题 coap/test :
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 关系及其对应的 Broker 订阅。
因此,后续资源变化仍可能通过保留的 Observe 关系发送通知。保留关系不保证失败的通知会再次投递。这两类失败本身不会取消 Observe 关系;正常的客户端会话清理仍然适用。
为保持兼容性,EMQX 保留此行为。它与 RFC 7641 第 4.5 节 的要求不同:RFC 要求服务器在收到 Reset 消息或最后一次重传超时后移除观察者。
短参数名称
为节省报文大小,CoAP 网关支持短参数名称。例如,参数 clientid=barx 可以写作 c=bar。所有支持的短 参数名称见下表:
| 参数名称 | 短参数名称 |
|---|---|
clientid | c |
username | u |
password | p |
token | t |
qos | q |
retain | r |