# CoAP 协议网关

CoAP 网关实现了轻量级设备接入，专为资源受限设备设计，适配低功耗和低带宽的场景，支持基于 CoAP 的发布订阅机制。

## 工作模式

CoAP 网关提供两种工作模式：

- **无连接模式**
  - 遵循 [Publish-Subscribe Broker for CoAP](https://datatracker.ietf.org/doc/html/draft-ietf-core-coap-pubsub-09) 协议。
  - 客户端无需连接认证、会话、心跳维持。
  - 支持以下功能：
    - 消息发布
    - 订阅主题
- **连接模式**
  - 引入连接认证、会话维持、心跳机制等。
  - 客户端需先创建连接，获得会话令牌（Token），后续通信需在 Query String 中附带 Token 信息。
  - 支持以下功能：
    - 创建连接
    - 关闭连接
    - 会话保持（心跳，可选）
    - 认证

是否启用连接模式可在 CoAP 网关设置页面进行配置。

::: tip
连接模式仅增加连接管理相关接口。在此模式下，发布、订阅、取消订阅等操作仍然可用，但每次请求需携带 `ClientId` 和 `Token`。
:::

## 基本设置

点击 CoAP 网关**操作**列中的**设置**按钮即可对网关进行基本设置：

- **连接模式**：启用或禁用连接模式。默认为启用。
  - `true`：启用连接模式。在此模式下，客户端需要进行连接认证、会话维持，并使用会话令牌（Token）进行通信。适用于需要更严格连接管理的场景。
  - `false`：禁用连接模式，使用无连接模式。在无连接模式下，客户端不需要进行连接管理，仅进行消息的发布和订阅。

- **通知类型**：该设置决定了 CoAP 消息的通知类型，默认为 `qos`。
  - `qos`：质量服务等级（Quality of Service），通常用于控制消息的传递可靠性。
  
  - `con`：确认消息（Confirmable），表示消息发送后需要客户端确认。
  
  - `non`：非确认消息（Non-Confirmable），表示消息发送后不需要确认，适用于不重要或者可丢失的消息。
  
- **心跳间隔**：设置 CoAP 网关与客户端之间的心跳间隔。心跳消息用于检测客户端与网关的连接状态，确保连接处于活动状态。如果心跳超时，连接可能会被断开。可设置为任意秒数，默认值：`30秒`。

- **订阅 QoS**：设置订阅消息的服务质量等级（QoS）。默认为 CoAP 协议级别。

- **发布 QoS**：设置发布消息的服务质量等级（QoS）。默认为 CoAP 协议级别。

- **挂载点**：设置 CoAP 网关的挂载点。挂载点是 CoAP 协议的 URL 路径前缀，允许用户定义特定的 URL 路径结构，以便不同的应用或客户端可以根据不同的挂载点来进行数据交换和访问。

完成设置后，点击**更新**保存设置。

## 客户端

在 CoAP 页面的**客户端**标签页中可以查看连接到部署的客户端的基本信息。在**操作**列中，可以选择将某一客户端踢除。

### 客户端接入接口说明

具体内容，参考[客户端接入接口说明](./connection_interface.md)。

### 连接地址和端口

在部署概览页面可以查看连接地址和端口信息。

### 发布订阅

CoAP 网关基于 [Publish-Subscribe Broker for CoAP](https://datatracker.ietf.org/doc/html/draft-ietf-core-coap-pubsub-09) 实现发布订阅功能。权限管理通过[客户端授权](../deployments/authz_overview.md)统一管理。

### 客户端库

推荐以下客户端库用于开发和测试：

- [libcoap](https://github.com/obgm/libcoap)
- [californium](https://github.com/eclipse/californium)

## 认证管理

仅在连接模式下可用。 客户端 ID、用户名、密码由客户端的[创建连接](./connection_interface.md#创建连接)请求提供。

您可以在网关页面，点击 CoAP 网关**操作**列中的**接入认证**按钮进入到 CoAP 认证管理页面，在该页面中添加、编辑或删除认证信息。