CoAP 服务端

CoAP 服务端把数据转发组内的变量发布为固定 URI 资源。客户端可发现资源、读取 JSON 或文本、执行受控 PUT / POST、使用条件请求和 Block1 / Block2，以及通过 Observe 接收变化通知。

公共配置见数据转发。需要读取其他 CoAP 设备的资源时，选择 CoAP 主站。

创建资源服务

1. 进入“开发配置 → 数据转发”，设置转发组变量范围，确认源变量在线且已初始化。
2. 新增目标，选择“CoAP 服务端”，通道类型选择 UDP，设置本地绑定地址，例如 0.0.0.0:5683。
3. 设置完整正文上限、数据报上限及 Observe 容量。初次验证时保持“允许写入”为否。
4. 打开“目标变量属性”，为变量设置唯一绝对路径，例如 /sensors/temperature，并选择 JSON 或文本表示。
5. 保存并启用目标，进入“调试 → 操作 → 映射点表”核对资源路径、值和访问权限。

只有组内已配置路径的变量才会发布；未映射成员计入统计。重复路径或非法路径使建模失败，源变量离线或未初始化时不会返回伪造的默认值。

目标参数

参数	说明
本地绑定地址	默认 0.0.0.0:5683，使用 UDP；端口应由一个目标独占。
允许写入	默认否；须与变量级权限和源变量 RPC 写能力共同开启。
最大正文大小	默认 65507 字节，范围 16～65507，限制完整表示和分块上传的累计正文。
最大数据报字节数	默认 65507，范围 64～65507，包含头、Token、选项和正文；可按网络 MTU 降低并使用分块。
请求超时毫秒	默认 5000，范围 100～120000，包括源变量回写等待。
最大观察关系数	默认 128，范围 1～1024。
观察租约秒数	默认 300，范围 30～86400。客户端须在到期前重新注册以续期。

本插件提供明文 coap:// UDP，不提供 DTLS、OSCORE、CoAP over TCP 或 HTTP 代理。不要开启通道 SSL；应在受控网络中部署，并通过网络访问控制限制能够发起写命令的客户端。

保存时会校验通道、正文上限和数据报预算；导入配置在启动前也会执行同样校验。无效参数应先修正，目标不会用错误配置占用监听端口。

变量参数

参数	说明
资源路径	以 / 开头，例如 /sensors/temperature，最多 1024 字符，区分大小写；不能包含查询、片段、百分号转义、空路径段、. 或 ..。
使用 JSON 格式	默认是，Content-Format 50，保留数值、布尔、字符串、数组或对象的 JSON 类型；文本模式使用 UTF-8 和 Content-Format 0，源变量必须为字符串。
允许变量写入	默认否；与目标级允许写入共同生效。

/.well-known/core 为保留发现入口，不能映射变量。客户端访问固定资源时不应附带查询参数；发现入口支持 href 筛选。

多段资源路径应逐段传输，例如 /sensors/value 对应 sensors 和 value 两个 Uri-Path 选项。把斜杠转义到单个段中的 /sensors%2Fvalue 会返回 4.00，不会读取或修改 /sensors/value。

发现目录同样支持条件读取：If-Match 不匹配返回 4.12，ETag 匹配返回无正文的 2.03 Valid。目录使用 Block2 分块时，后续块必须保留首块的 href 查询，使用同一目录表示和 ETag；更换筛选条件后应从首块重新读取，直接续读会返回 4.08。GET 不应携带请求正文、If-None-Match 或 Block1。

读取、回写与 Observe

1. 使用 GET coap://网关IP:5683/.well-known/core 获取 link-format 资源目录。
2. GET 资源路径并核对 Content-Format。客户端可用 Accept 指定格式；不匹配时返回 4.06。
3. 在点表中点击“网络探测”，再点击“网络读取”，验证当前资源的真实 UDP 读取结果。
4. 在安全测试点开启双层写权限和源变量 RPC，填写 JSON 值，点击“网络写入并读回”，确认后核对结果。文本资源在调试框中仍填写 JSON 字符串，例如 "running"。
5. 外部客户端 PUT / POST 时设置与资源一致的 Content-Format；固定资源不允许 DELETE，也不通过 POST 新建路径。
6. 需要避免覆盖并发更新时，先读取 ETag，再用 If-Match 写入；条件不满足返回 4.12。固定资源已存在，If-None-Match 写入也返回 4.12。
7. GET 携带 Observe 0 注册观察；客户端处理确认通知并发送 ACK，Observe 1 或 RST 可取消。应在配置的租约到期前重新注册。

文本资源允许空字符串。在目标调试框中填写 ""，外部客户端则发送 Content-Format 0、零字节正文的 PUT / POST；成功后 GET 返回同一格式的空表示。JSON 资源的空正文会返回 4.00；JSON 空字符串应发送 ""，其正文包含两个双引号字节。

大正文使用 Block1 上传及 Block2 下载，累计正文仍受上限约束。服务端为未完成下载保留稳定表示，避免不同版本的块拼接。块传输状态 30 秒到期，同时最多保留 32 个上传及 32 个下载；客户端应及时完成传输。Observe 支持分块通知；未确认的通知按退避间隔重试，连续超时后移除关系。

同一客户端并发上传同一资源时，应为每次 Block1 上传使用不同的 Request-Tag，并在该次上传的所有块中保持标签列表一致。空标签与未携带标签属于不同上传，Token 不能代替上传标签；不发送 Request-Tag 的客户端应顺序完成上传。只有完整正文接收并校验成功后才回写源变量，多个成功写入的最终值由完成顺序决定。

合法数据报内的单包正文超过正文上限时返回 4.13，不会调用源变量回写。Block2 下载开始后，即使源值变化或临时离线，后续块仍在状态有效期内使用首块的表示及 ETag；携带 If-Match 时也按该表示校验。下载完成后重新 GET 获取当前源值。

映射修改或目标重启会清空未完成传输和观察关系。客户端应重新发现、读取并注册观察；不要继续使用旧的块序号。

排障

现象	处理方法
超时或离线	检查 UDP 绑定 IP、端口占用、防火墙、目标使能与组状态。
4.02 Bad Option	检查未知关键选项、重复单值选项和固定资源上的查询参数。
4.04 Not Found	检查路径大小写、组范围和目标变量路径配置。
4.05 Method Not Allowed	检查方法及双层写权限；固定资源不允许 DELETE。
4.08 Request Entity Incomplete	块顺序不完整或状态到期，重新从首块传输。
4.13 Request Entity Too Large	缩小完整正文；分块不能绕过累计上限。
4.15 Unsupported Content-Format	核对 JSON 50 或文本 0，不要把普通数字当作文本资源的 JSON 字符串。
5.00 Internal Server Error	检查源变量品质、初始化状态及 RPC 执行结果。
Observe 停止或 5.03	检查租约续订、ACK、观察容量与传输状态；完成旧下载后重新注册。