iot-protocols

iot-protocols

用途

此技能提供用于与 Zigbee、Z-Wave、LoRaWAN、CoAP、Matter 和 Thread 等 IoT 协议交互的工具，使 IoT 应用能够连接设备、交换数据并管理网络。

适用场景

在构建需要低功耗网状网络（例如用于智能家居的 Zigbee）、远距离通信（例如用于偏远地区传感器的 LoRaWAN）或轻量级协议（例如面向受限设备的 CoAP）的 IoT 系统时，使用此技能。适用于智能家居自动化、工业 IoT 监控，或通过 Matter 实现互操作的生态系统等场景。

主要功能

• 使用特定协议建立与设备的连接：例如，用于网状网络的 Zigbee，或基于 IPv6 的低功耗无线协议 Thread。
• 发送/接收数据载荷：例如，通过 CoAP 查询传感器数据，或控制 Z-Wave 设备。
• 配置网络设置：例如，设置 LoRaWAN 网关或 Matter Fabric 桥接器。
• 处理协议特定功能：例如，使用 Zigbee 的绑定功能配对设备，或使用 LoRaWAN 的自适应数据速率。
• 实现跨协议互操作：例如，将 Matter 设备与 Thread 网络桥接，实现无缝集成。

使用模式

要完成任务，请先通过设置环境变量 export IOT_API_KEY=your_api_key 进行身份验证。使用 openclaw iot init 命令初始化会话，然后使用特定协议对应的子命令。比如，要连接设备，请指定协议和设备 ID；执行数据操作时，请使用查询标志。在脚本中始终加入错误检查。模式：openclaw iot <subcommand> --protocol <protocol> --device-id <id>。对于复杂配置，请使用 JSON 配置文件；例如，创建名为 config.json 的文件，内容为 { "protocol": "zigbee", "networkKey": "hex_key" }，并通过 --config config.json 传入。

常用命令/API

快速交互可使用 OpenClaw CLI，以编程方式访问则可使用 REST API。身份验证需要 $IOT_API_KEY 请求头。

• CLI 命令：列出协议
  openclaw iot list --protocol zigbee
  此命令会输出可用的 Zigbee 设备；添加 --verbose 可查看详细的网络信息。

• CLI 命令：连接设备
  openclaw iot connect --protocol lorawan --device-id 456 --region EU868
  使用此命令建立 LoRaWAN 连接；请指定区域标志以设置频段。

• API 端点：通过 CoAP 发送数据
  POST /api/iot/send
  请求体：{ "protocol": "coap", "endpoint": "/sensors/temp", "payload": "{\"temp\": 25}" }
  添加请求头：Authorization: Bearer $IOT_API_KEY

• API 端点：查询 Z-Wave 状态
  GET /api/iot/status?protocol=z-wave&device-id=789
  响应：类似 { "status": "online", "nodes": 5 } 的 JSON 对象；可在代码中使用简单的 fetch 处理：
  fetch('/api/iot/status', { headers: { 'Authorization': process.env.IOT_API_KEY } }) .then(response => response.json())

• 配置格式：要集成 Matter，请使用 YAML 文件：
  matter-config.yaml: protocol: matter, fabricId: 12345, nodeId: 678
  使用以下命令加载：openclaw iot load-config --file matter-config.yaml

集成说明

在工作流中引用 iot 集群，即可将此技能与其他 OpenClaw 工具集成。对于外部系统，请导出 $IOT_API_KEY 并在 API 调用中使用。要与数据库技能结合使用，可通过管道传递输出：例如，openclaw iot get --protocol coap | openclaw db insert。集成 Thread 时，请确保网络协议栈兼容 IPv6。例如，在 Node.js 应用中，导入 OpenClaw SDK 并调用：
const openclaw = require('openclaw-sdk'); openclaw.iot.connect({ protocol: 'thread', deviceId: '101' });
请始终验证输入；对于 Zigbee，请在连接前检查网状拓扑。

错误处理

通过检查 CLI 退出代码或 API 响应状态来处理错误。常见错误包括身份验证失败（HTTP 401）或协议不匹配（例如，无效的 Zigbee 网络密钥）。在代码中使用 try-catch：
try { await openclaw.iot.connect({ protocol: 'z-wave', deviceId: '202' }); } catch (error) { console.error(error.message); // e.g., "Device not found" }
对于 CLI，解析输出：如果 openclaw iot connect 返回非零值，请检查 stderr 中是否有类似 "Protocol not supported" 的消息。对于暂时性错误（例如，LoRaWAN 信号丢失），使用指数退避进行重试。

具体使用示例

1. 设置 Zigbee 网状网络： 首先，导出密钥：export IOT_API_KEY=abc123。然后，初始化：openclaw iot init --protocol zigbee。连接设备：openclaw iot connect --protocol zigbee --device-id 303 --pan-id 0x1a62。发送命令以切换灯的状态：openclaw iot send --protocol zigbee --endpoint /lights/1 --payload '{"state": "on"}'。这样即可建立用于家庭自动化的网状网络。

2. 查询 LoRaWAN 传感器的数据： 通过环境变量进行身份验证，然后运行：openclaw iot connect --protocol lorawan --device-id 404 --app-eui 70B3D57EF0000000。获取数据：openclaw iot get --protocol lorawan --payload-type temp。在代码中：
   openclaw.iot.get({ protocol: 'lorawan', deviceId: '404' }).then(data => console.log(data));
   这适用于监控远程环境传感器。

图关系

• 相关：iot-cluster（用于更广泛的 IoT 管理）、networking-skills（用于与协议无关的网络）。
• 依赖：security-skills（用于 Zigbee 等协议中的加密）。
• 通过 iot 标签连接，可在 OpenClaw 的图中进行跨技能查询。