arduino-esp32 OpenThread 实战：用 Native API 搭建 Thread 领导节点与双传输 CoAP 温室网关（greenhouse_server）

arduino-esp32 OpenThread 实战用 Native API 搭建 Thread 领导节点与双传输 CoAP 温室网关greenhouse_server【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32本篇以 arduino-esp32 仓库中 OpenThread 库的CoAP_Greenhouse示例之服务端 greenhouse_server 为主体完整讲解如何用 ESP32H2/C6/C5组建一个 Thread 网络Leader Commissioner、开启 PSKd 加入者窗口并在同一块板子上同时运行明文 CoAP5683只读遥测与 CoAPS/DTLS5684认证执行器指令两套资源服务。读完本文你可以独立烧录、调试这对服务端/客户端 demo理解OThread、OThreadCoAPServer、OThreadCoAPSecureServer三套 Native API 的真实调用关系并能把双传输架构移植到自己的 Thread 应用里。一、greenhouse_server 在整个 demo 中的角色CoAP_Greenhouse是 OpenThread 库 Native CoAP 示例组 中的一个完整工程演示典型 IoT 分工开放遥测走明文 CoAP认证执行器指令走 CoAPS。服务端greenhouse_server.ino承担四件事摘自 服务端 README用硬编码DataSet组建名为ESP_OT_CoAP_Greenhouse的 Thread 网络申请Commissioner角色为 PSKdJ01NME打开加入者Joiner窗口在端口5683上运行明文 CoAP 服务提供只读遥测资源greenhouse/temp、greenhouse/light在端口5684上运行CoAPS 服务DTLS提供认证执行器指令valve/water、fan/speed在loop()中模拟温度和光照的缓慢漂移。它与 greenhouse_client 互为配对客户端是 Joiner 控制器NON 轮询遥测、CON 下发执行器指令。组总览中给出的双传输架构示意如下┌─────────────────────────────────────┐ greenhouse_client │ PlainClient (5683) │ │ NON GET greenhouse/temp │ │ NON GET greenhouse/light │ │ SecureClient (5684) │ │ CON PUT valve/water │ │ CON PUT fan/speed │ └─────────────────┬───────────────────┘ │ Thread mesh ┌──────────────────────▼──────────────────────────┐ greenhouse_server│ OThreadCoAPServer — telemetry (read) │ │ OThreadCoAPSecureServer — actuators (write) │ └─────────────────────────────────────────────────┘二、支持的目标芯片来自 greenhouse_server READMESoCThreadStatusESP32-H2yesSupportedESP32-C6yesSupportedESP32-C5yesSupported三、必需的 IDF 特性sdkconfig要让greenhouse_server完整跑起来固件中需要以下特性原文档表格含用途说明FeatureWhyCONFIG_OPENTHREAD_ENABLEDyBuild the OpenThread stack.CONFIG_SOC_IEEE802154_SUPPORTEDyEnsure the SoC has the 802.15.4 radio.CONFIG_OPENTHREAD_COMMISSIONERyEnable Commissioner APIs for Joiner admission.OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE1CoAPS actuator server on 5684.MBEDTLS_KEY_EXCHANGE_PSK_ENABLEDPSK cipher suite for the demo.其中前三项与 CI 校验文件 ci.yml 的requires完全一致说明这三项是该 sketch 在验证环境中的硬性前提CoAPS 相关两项则只影响 5684 端口的执行器功能。3.1 为什么 CoAPS 需要特殊构建CoAPS requires OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE1。运行时会用OThreadCoAP::secureApiEnabled()判断固件里是否编译了安全 API其声明见 OThreadCoAP.h注释写明返回 true 当且仅当构建时设置了OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE。若为 falsegreenhouse_server会降级为只跑明文遥测——5683 的遥测不依赖 CoAPS 构建标志但 5684 的执行器 PUT 依赖。标准 Arduino IDE 构建可能不含 CoAPS 安全 API。按 组总览 README 的Enabling CoAPS一节应把 sketch 作为Arduino 组件的 ESP-IDF 工程见 Arduino as an ESP-IDF component 文档重新构建把 sketch 拷入工程main/目录.ino改名.cpp执行idf.py set-target soc后进入idf.py menuconfig启用下列选项menuconfigSettingComponent config → OpenThreadOpenThreadComponent config → OpenThread → Thread Core FeaturesEnable Commissionergreenhouse_serverComponent config → OpenThread → Thread Core FeaturesEnable Joinergreenhouse_clientComponent config → mbedTLS → TLS Key Exchange MethodsEnable pre-shared-key ciphersuitesComponent config → mbedTLS → TLS Key Exchange MethodsEnable PSK based ciphersuite modesComponent config → OpenThread → Thread Extensioned FeaturesUse a header file defined by customer注意OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE不是直接的 menuconfig 开关使用自定义 OpenThread 头文件时需在头文件内定义#define OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE 1并将该头文件路径配置在Thread Extensioned Features → OpenThread Custom Header Config保存后idf.py build flash monitor。四、代码剖析从组建网络到双端口监听以下按 greenhouse_server.ino 的实际执行顺序展开README 给出的骨架代码与之一致// 1) Form network and petition Commissioner. OThread.commitDataSet(ds); OThread.networkInterfaceUp(); OThread.start(); OThread.startCommissioner(); OThread.addJoiner(J01NME, JOINER_WINDOW_SEC); // 2) Plain CoAP telemetry (5683). OThreadCoAPServer.on(greenhouse/temp, OT_COAP_METHOD_GET, onGreenhouseTemp); OThreadCoAPServer.on(greenhouse/light, OT_COAP_METHOD_GET, onGreenhouseLight); OThreadCoAPServer.begin(); // 3) CoAPS actuators (5684). OThreadCoAPSecureServer.setPSK(COAP_PSK, sizeof(COAP_PSK), esp-coap-demo); OThreadCoAPSecureServer.on(valve/water, OT_COAP_METHOD_PUT, onValveWater); OThreadCoAPSecureServer.on(fan/speed, OT_COAP_METHOD_PUT, onFanSpeed); OThreadCoAPSecureServer.begin(); // 4) loop(): simulate temp/light drift; fan cools greenhouse4.1 组建网络DataSet 离线路径startNetwork()中先构造DataSet调用ds.initNew()、ds.setNetworkName(ESP_OT_CoAP_Greenhouse)、ds.setChannel(CHANNEL)、ds.setPanId(PAN_ID)、ds.setNetworkKey(NETKEY)然后OThread.commitDataSet(ds)、OThread.networkInterfaceUp()、OThread.start()。从 OThread.h 的注释看DataSet正是配置好参数后交给OpenThread::commitDataSet()提交的离线offline组网路径——无需扫描已有网络节点凭本地数据集直接成为 Leader。随后waitForAttach()轮询OThread.otGetDeviceRole() OT_ROLE_CHILD最长等待ATTACH_TIMEOUT_MS30000 ms超时则OThread.stop()后 2 秒重试。组网成功后执行if (OThread.startCommissioner() OT_ERROR_NONE) { OThread.addJoiner(PSKD, JOINER_WINDOW_SEC); Serial.printf(Commissioner ready (PSKd \%s\)\n, PSKD); }从 OThread.h 的签名可看到默认值startCommissioner(uint32_t timeoutMs 30000)、addJoiner(const char *pskd, uint32_t timeoutSec 120, const otExtAddress *eui64 nullptr)。本 demo 显式传入JOINER_WINDOW_SEC 60010 分钟加入窗口并允许任意 EUI-64未绑定特定设备。这一步是后续客户端加入失败类问题的关键窗口关闭后Joiner 就无法再附网。4.2 明文 CoAP 服务器5683OThreadCoAPServer.on(path, methodMask, handler, context)按 URI 路径注册处理器method 是位掩码OThreadCoAP.h 中OT_COAP_METHOD_GET (1 0)、OT_COAP_METHOD_PUT (1 2)。两个遥测 handler 的公共行为是方法不符即回OT_COAP_RESP_METHOD_NA405合法 GET 回OT_COAP_RESP_OK205payload 为温度字符串String(state-tempC, 1)保留 1 位小数或 lux 整数字符串通过logRequestKind()打印[CON]或[NON]及req.remoteIP().toString()得到对端 IPv6 地址。从 OThreadCoAP.h 的类注释可知几条重要约束处理器在OpenThread worker task中运行匹配请求到来即被调用无需loop()轮询因此keep handlers short每设备只允许一个明文 CoAP 服务器默认 5683 上的一次 UDP 绑定应使用库内全局单例OThreadCoAPServer或OThreadCoAP::plainServer()不要自己构造明文OThreadCoAPServer与OThreadCoAPSecureServer5684可以在同一设备上并存——这正是 CoAP_Greenhouse 的设计依据若 handler 返回时未调用response.send()且请求是单播 CON 或 GET服务端会自动补发 2.05无 payload以免确认方客户端无限等待但打算返回 4.xx/5.xx 错误的 handler 必须自己send()否则失败会被静默上报为成功OThreadCoAP.h。4.3 CoAPS 执行器服务器5684执行器 handleronValveWater、onFanSpeed的校验逻辑是if (req.method() ! OT_COAP_REQ_PUT) { resp.setCode(OT_COAP_RESP_METHOD_NA); resp.send(); return; } if (!parsePercent(req.payloadString(), percent)) { resp.setCode(OT_COAP_RESP_BAD_REQUEST); resp.setPayload(0-100); resp.send(); return; } state-valvePercent percent; resp.setCode(OT_COAP_RESP_CHANGED); // 204即 payload 必须是 0–100 的整数非法时回 400 并附 0-100 提示合法则回OT_COAP_RESP_CHANGED204并把该值回显为 payload。setPSK(COAP_PSK, sizeof(COAP_PSK), COAP_PSK_ID)设置 16 字节预共享密钥PSK 标识字符串为esp-coap-demo对端client必须使用同一 PSK 才能完成 DTLS 握手。setup()中用if (OThreadCoAP::secureApiEnabled())分支处理固件里没有 CoAPS的情况打印CoAPS is not enabled in this build. Secure actuators will not run.后让明文遥测继续工作而不是停机。另外从 OThreadCoAP.h 的注释看OThreadCoAPSecureServer.begin()在同一设备上存在活动的OThreadCoAPSecureClient会话时会失败OpenThread 每实例共享一个 CoAPS 栈与凭据这也是CoAPS 服务器放一个节点、CoAPS 客户端放另一个节点这一建议的源码依据。4.4 loop()模拟环境漂移s_state.tempC ((float)random(-5, 6)) / 10.0f; s_state.tempC - (float)s_state.fanSpeed / 200.0f; // 风扇有降温效果 // temp 钳位在 [18, 32]lightLux 随机漂移并钳位在 [2000, 20000] delay(1000);风扇转速会真实地以fanSpeed / 200每秒拉低模拟温度使遥测—控制闭环在演示中可见。五、资源表ResourcesPathTransportMethodsResponsegreenhouse/tempPlain 5683GETTemperature string (°C)greenhouse/lightPlain 5683GETLight level (lux)valve/waterCoAPS 5684PUTBody 0–100 →204 Changedfan/speedCoAPS 5684PUTBody 0–100 →204 ChangedHandler 会记录[CON]或[NON]以及远端 IP。组总览补充了客户端侧的可靠性约定遥测用NON无确认、省开销执行器命令用CON可靠客户端每 8 秒轮询一次遥测、首读成功后每 24 秒下发一次 CON 控制指令。六、运行顺序与预期串口输出启动顺序要求先烧录greenhouse_server等待Commissioner ready (PSKd J01NME)、5683 明文 CoAP 与 5684 CoAPS 就绪提示再烧录/复位 greenhouse_client服务器每次复位后都应复位客户端使其重新加入。成功时的预期串口输出原文档 CoAP Greenhouse — server Forming Thread network... Waiting for attach.. Attached as Leader. Starting Commissioner... Commissioner ready (PSKd J01NME) Starting CoAP servers... Ready. Plain CoAP on port 5683: GET greenhouse/temp, greenhouse/light CoAPS on port 5684: PUT valve/water, fan/speed (PSK id esp-coap-demo) Mesh-local: fdde:ad00:beef:0:.... [NON] GET greenhouse/temp from fdde:ad00:beef:0:.... [CoAPS CON] PUT fan/speed from fdde:ad00:beef:0:.... Fan - 75% Valve - 60%fdde:ad00:beef:前缀正来自PAN_ID 0xBEE5的 Mesh-local 地址派生。若固件未含 CoAPS输出为 CoAP Greenhouse — server ... Ready. Plain CoAP on port 5683: GET greenhouse/temp, greenhouse/light CoAPS is not enabled in this build. Secure actuators will not run. Plain CoAP telemetry continues. Mesh-local: fdde:ad00:beef:0:....七、可调参数Customization所有可调项集中在.ino文件头部对照 greenhouse_server.ino 的实际定义ConstantPurposePSKDJoiner secret accepted by the Commissioner.demo 值J01NMEJOINER_WINDOW_SECHow longaddJoiner()stays valid (default 600 s)。CHANNEL802.15.4 channel (default 15)。PAN_ID16-bit PAN ID (default0xBEE5)。NETKEY128-bit network key。COAP_PSK16-byte CoAPS pre-shared key — must match client。COAP_PSK_IDPSK identity string (defaultesp-coap-demo)。明文遥测固定端口5683执行器固定 CoAPS 端口5684。修改网络参数时注意 client 侧需同步PSKD、CHANNEL_HINT15等值否则客户端无法附网。八、故障排查TroubleshootingStartup order先烧greenhouse_server等 Commissioner ready 且两个服务都在监听再烧 greenhouse_client。原文档的完整症状表SymptomLikely causeCoAPS is not enabled in this buildCoAPS is missing from the firmware. Rebuild as an ESP-IDF project with Arduino as a component见上文 3.1 节 menuconfig 步骤。Server continues with plain telemetry only.CoAPS server start failedCoAPS enabled in build butOThreadCoAPSecureServer.begin()failed (PSK, port, or attach)。Plain CoAP server start failedOpenThread not attached。Client join failsCommissioner window closed — reset server or extendJOINER_WINDOW_SEC。Client plain GET works, CoAPS PUT failsPSK mismatch or CoAPS not built on client。Client worked, then stops after server resetReset client to re-join。结合 OThreadCoAP.h 的约束CoAPS server start failed还有一种可能原因同节点上已存在活动的 CoAPS client 会话begin()会因此返回 false。九、配套示例与延伸阅读CoAP Greenhouse — group overview — 资源表、双传输架构、How to Run 与 menuconfig 配置CoAP Greenhouse — greenhouse_client — Joiner 自动化客户端其 CI 依赖CONFIG_OPENTHREAD_JOINERy见 client ci.ymlCoAP Secure — secure_server — 纯 CoAPS 的更精简服务端Native CoAP examples 总览 — 全部 Native CoAP demo 与端口约定5683 明文 / 5684 安全库 API 参考OThread.h组网/Commissioner/Joiner、OThreadCoAP.hCoAP/CoAPS 客户端与服务端。十、License该示例遵循 Apache License 2.0与仓库整体一致见 LICENSE.md。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考