CoAP 主站

CoAP 主站通过 UDP 通道读取和写入资源，支持 CoRE 目录、GET、PUT、POST、受控 DELETE、条件请求、Block1/Block2 与 Observe。插件名称为“CoAP 主站”，类型标识为 CoapMaster。公共操作见采集配置。当前资源使用明文 coap://，不配置 coaps://、DTLS、TCP/TLS 或 OSCORE。

建立通道与配置变量

进入“开发配置 → 采集配置”，创建 UDP 通道，设置本地绑定及远程服务端，通常端口 5683。添加 CoAP 主站设备并启用。变量地址填写绝对资源 URI，例如 coap://192.0.2.10:5683/sensors/room?unit=celsius；主机解析结果和端口必须匹配所属通道远端。

参数	说明
Exchange 超时毫秒	100–120000，默认 30000；整个交换和分块共用总期限。
初始 ACK 超时毫秒	100–30000，默认 2000；等待超时后按规则重传。
CON 最大重传次数	0–8，默认 4；重传保持原 Message ID 与 Token。
最大 payload 字节数	16–65507，默认 65507；限制整份请求和重组响应。
最大数据报字节数	64–65507，默认 65507；限制包含头、Token、URI 选项和正文的完整数据报。与完整资源正文上限分别配置。
首选块大小字节数	16–1024 的二次幂，默认 1024；只支持小块的设备可设为 16、32 或 64。服务端可在 Block1/Block2 中进一步缩小块。
启用 Observe 订阅	开启资源观察，保留周期读取回退。
最大 Observe 资源数	1–256，默认 64，按唯一资源计数。
写入方法	变量写默认 PUT，可按实际资源合同选择。

JSON 数值选择对应数字类型，布尔选择 Boolean，完整 JSON 选择 Object；纯文本选择 String。周期采集与特殊方法应指向同一资源和格式，不根据 URI 后缀猜测类型。

周期读取、自动 Observe 和调试批读按响应的 Content-Format 解析 JSON 或纯文本。明确声明 text/plain 0 的零字节表示会更新为空字符串；JSON 50 或未声明格式的空正文不作为有效变量值。向文本资源清空内容时，在专属写入页选择 Text、Content-Format 0，将正文留空；普通变量写入使用 JSON 表示，不能代替文本写入。

使用地址字段编辑器

1. 在设备的“实时变量”页新增或编辑变量，点击“变量地址”右侧的“字段编辑”。
2. 填写资源主机、端口、路径与可选查询字符串。查询不含开头的 ?；保留设备要求的空段及百分号转义，不把查询拼进主机字段。
3. 点击“确认并回填”，核对完整 coap:// URI 与通道远端一致，再点击变量窗口的“确定”。
4. 重新打开字段编辑器，确认路径、查询与端口保存正确；取消字段窗口不会保存该窗口中的修改。

检查实时变量

保持当前设备，在采集工作区顶部切换到“实时变量”标签，核对每个资源的地址、当前值、在线状态和错误信息。采集时间应随成功采集推进；Observe 更新会同时反映在关联变量中。改变源端值后，应检查当前值和变化时间，单独看到关系“已确认”不足以证明持续收到新值。

失败资源单独显示错误，其他资源继续采集。分块表示只有完整校验后才提交变量；出现块丢失、正文超限或格式变化时，不使用部分正文覆盖当前值。

专属调试操作

选中设备，打开顶部“协议调试”。第一个页签“核心状态”显示连接、超时、报文与分块预算；其右侧依次提供“特殊方法”和协议操作。

使用工作区顶部“刷新”更新状态。资源目录、Observe 关系、通知和错误分别分页，默认每页 20 项；自动刷新保留当前页。页面中的每页数量不改变 CoAP 的 Block1/Block2 块大小或完整数据报预算。

1. 资源发现输入当前主机地址，读取 /.well-known/core，核对 URI、资源类型和内容格式。
2. 在读取页填写绝对资源 URI 和 Accept。常用格式：0 为 text/plain，42 为 application/octet-stream，50 为 application/json。
3. 条件请求的 If-Match 使用 Base64 ETag，If-None-Match 表示资源不存在条件。条件不满足时检查 4.12，而非当作网络离线。
4. 批量读取每行一个 URI，最多 32 项，逐项查看错误。
5. 写入页选择 PUT/POST/DELETE 和正文编码 JSON/Text/Base64、Content-Format、Accept。核对资源并确认后发送，再 GET 读回。DELETE 仅用于明确允许删除的测试资源。
6. Observe 页建立关系，检查最近值、序号、Max-Age 和状态；从源端改变值，确认新通知。完成后注销关系。

分块、分批和小型设备

周期采集按资源逐点执行，不把不同 URI 合并到一个 CoAP 请求；调试批量读取最多 32 个 URI，也会逐项保留成功或失败。请求正文和响应表示都受“最大 payload 字节数”限制，超过限制在发送或重组前拒绝。Block1 上传和 Block2 下载按首选块大小分块，服务端返回更小的 SZX 后，后续块按新大小继续；Observe 的分块通知必须重组为完整表示后才更新变量。

每次 Block1 上传自动携带独立的 Request-Tag，同一次上传的所有块保持同一标签。对端支持相应并发容量时，同一通道向同一 URI 发起的多个上传可分别重组完整正文；最终资源值由完成顺序决定。请求标签也计入完整数据报预算，不需要手工配置。

块大小还受完整数据报预算限制。上传会计算实际 URI、Token、条件选项、块序号和正文的编码长度，必要时自动缩小块；下载会为标准响应元数据预留空间。例如短 URI 的完整报文预算为 64 字节时，下载使用 16 字节块。一份资源可以跨多个数据报，但累计正文仍不得超过“最大 payload 字节数”。需要 Block1 上传时，URI 与选项过长、连最小块都无法发送，应缩短资源地址或按设备能力提高数据报预算；单纯提高完整正文上限不能解决该问题。

GET、Observe 注册和注销会在完整报文预算允许时携带 Block2 option。若长 URI 已占满可用空间，而普通请求仍能装入预算，直接发送不含 Block2 的单包请求；服务端返回完整表示时正常结束，主动返回首块时则按实际块大小和序号续读。所有后续请求仍须满足同一数据报预算，无法容纳时明确失败。

若小型设备对首次 Block2 请求明确返回 4.02 Bad Option，该操作只重试一次并去掉 Block2，Observe 保持原 Token。其他 4.xx/5.xx、块序号跳变、ETag 或 Content-Format 不一致不会被吞掉。不支持分块的设备需要让请求与响应都能装入一个数据报；降低首选块大小适用于支持小块的设备，不能让设备获得原本没有的 Block1/Block2 能力。

检查长 URI 的单包读取时，在读取页核对返回值、blocksTransferred=1 和 block2=null。下面的读取在 64 字节完整数据报预算下返回 23.5；该 URI 不需要为可选 Block2 提高预算：

Observe 也可在相同预算下注册和注销。注册后核对已确认关系与初值，完成后选择该资源注销，确认临时关系移除：

使用读取页检查小块传输时，核对结果的 payloadLength、blocksTransferred 和正文。完整数据报预算为 64 字节、首选块为 1024 时，驱动仍会按预算选择 16 字节下载块；8193 字节资源需要 513 块，最后一块仅 1 字节。应等全部块完成后再使用结果，累计正文上限也必须容纳该资源。

向下滚动查看完整结果，确认最后一块 more=false、块大小 16、传输块数 513、正文长度 8193：

Observe 表同时显示已确认关系和最近通知，修改源值后核对序号与值的变化：

空 ACK 仅表示请求已接收；读取或写入必须等待有效响应。大正文自动按 Block1/Block2 处理，只有 ETag、格式与块顺序一致的完整表示才更新变量。取消操作后已发送的远端副作用不能撤回，应读回检查。

变量值映射支持 text/plain 与 application/json。对于格式 42 等二进制表示，专属调试保留完整 Base64、字节数和分块元数据，应按设备合同解释，不能当作 JSON 数值采集。

特殊方法

打开“协议调试”，选择“核心状态”右侧的“特殊方法”，再选择方法并编辑参数。

方法	用途
DiscoverResourcesAsync	endpointAddress 和 maximumLinks，读取有界 CoRE 目录。
ReadResourceRequestAsync	address、accept、ifMatchBase64、ifNoneMatch，执行条件 GET。
ReadResourcesAsync	addressesJson 为 URI 字符串数组。
RequestResourceAsync	指定 method、payload、payloadEncoding、contentFormat、accept 和条件字段。
ObserveResourceAsync、CancelObserveResourceAsync	按资源 URI 建立和注销关系；复用当前设备配置和 UDP 通道。

JSON 参数按方法参数顺序填写数组，可省略使用默认值的尾部参数，也可使用“字段编辑”。例如执行 ReadResourceRequestAsync：

["coap://192.0.2.10:5683/value",50]

不使用 If-Match 时省略其尾部参数，或填写空字符串 ""；不要将不可空的字符串参数填成 null。

故障处理

现象	检查与处理
URI 不匹配通道	核对远端 IP/DNS 解析和端口；不要借一个通道访问不同服务端。
4.04、4.05、4.15	分别检查资源路径、允许方法和 Content-Format/Accept。
4.12	重新读取当前 ETag，确认业务条件后再写；不要无条件覆盖。
超时或重传耗尽	核对端口、防火墙、CON 期限和服务负载。
4.02、分块或 ETag 错误	仅首个 Block2 4.02 Bad Option 会无 Block2 重试一次；其余错误直接返回。检查块大小、最大 payload、块序号以及源端 ETag/Content-Format，驱动不会使用部分正文。
Observe 过期或无通知	检查 Max-Age、源端 Observe 支持和订阅状态；设备运行时会重确认，失败继续周期读取。