06 极物科技 | 创明RS485窗帘 - UDP 通讯协议规范

极物科技 | 创明RS485窗帘 - UDP 通讯协议规范

前言

极物科技致力于智能控制系统及硬件研发，以"极物OS+多协议融合"打破生态壁垒。

一句话概述：本文提供极物主机创明窗帘服务的完整 UDP 通讯协议规范，供需要进行二次开发或系统对接的技术伙伴参考。

本文聚焦于 极物主机创明窗帘的 UDP 通讯协议规范，详细解析服务端口与保活机制、报文帧结构、控制报文格式（行程/角度/基础控制）、地址机制及状态更新报文，为二次开发和第三方中控对接提供完整的协议参考。

1. 服务端口与连接说明

极物主机创明窗帘服务提供 UDP 接口，用于将底层 RS485 协议转换为标准 UDP JSON 报文，方便第三方系统或主机进行对接。

连接说明：

• 客户端通过 UDP 协议向主机对应端口发送 JSON 报文
• 一个端口支持多个客户端同时连接
• 服务地址：极物主机 IP（默认监听 0.0.0.0）

2. 报文帧结构总览

所有控制报文遵循统一的 JSON 帧结构：

完整示例：

{
  "driver_data": {
    "name": "客厅窗帘",
    "action": "travel",
    "value": 50
  },
  "frame_type": "request",
  "frame_qn": 112233,
  "frame_driver": "gernel_curtain",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

3. driver_data 字段说明

4. 保活报文

保活报文用于确认客户端与服务端的连接状态。服务端对每个客户端维护独立的保活计时，超过设定超时时间未收到该客户端的保活报文，将主动关闭该客户端连接。

客户端 → 服务端（保活请求）：

{
  "frame_type": "keeplive"
}

服务端 → 客户端（保活响应）：

{
  "frame_type": "keeplive",
  "frame_qn": 1,
  "frame_driver": "curtain-chuanming"
}

收到相同的 frame_type: "keeplive" 即表示连接正常。

保活策略：

• 建议每 5 秒发送一次保活报文
• 客户端若在保活超时时间内未收到保活报文的返回值，应主动断开并重新建立连接
• 服务端支持多客户端连接，因此各客户端必须独立发送保活报文

5. 控制报文详解

5.1 停止控制

停止窗帘当前运行。

客户端 → 服务端（停止控制）：

{
  "driver_data": {
    "name": "客厅窗帘",
    "action": "stop"
  },
  "frame_type": "request",
  "frame_qn": "112233",
  "frame_driver": "curtain-chuanming",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

⚠️ 注意：控制指令无响应报文，请通过状态更新报文确认执行结果。

5.2 行程控制

控制窗帘到指定百分比位置，范围为 0~100（对应 0%~100%）。

客户端 → 服务端（行程控制）：

{
  "driver_data": {
    "name": "客厅窗帘",
    "action": "travel",
    "value": 50
  },
  "frame_type": "request",
  "frame_qn": "112234",
  "frame_driver": "curtain-chuanming",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

参数说明：

• value：0~100，对应窗帘行程百分比
• 0 表示完全关闭，100 表示完全打开
• 50 表示半开状态

⚠️ 注意：控制指令无响应报文，请通过状态更新报文确认执行结果。

5.3 角度控制

控制百叶帘/香格里拉帘的叶片角度，范围为 0~100。

客户端 → 服务端（角度控制）：

{
  "driver_data": {
    "name": "客厅百叶帘",
    "action": "angle",
    "value": 30
  },
  "frame_type": "request",
  "frame_qn": "112235",
  "frame_driver": "curtain-chuanming",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

参数说明：

• value：0~100，对应叶片角度百分比
• 百叶帘：0~100 直接映射到电机协议值
• 香格里拉帘：0~100 自动转换为 0~50（内部除以2）

⚠️ 注意：控制指令无响应报文，请通过状态更新报文确认执行结果。

6. 状态更新报文

窗帘服务会主动向所有已连接的客户端推送窗帘状态，报文格式如下：

服务端 → 客户端（状态推送）：

{
  "frame_type": "update",
  "frame_qn": 274,
  "frame_driver": "gernel_curtain",
  "driver_data": {
    "travel": 50,
    "angle": 30,
    "online": 1,
    "name": "客厅窗帘"
  }
}

driver_data 字段说明：

更新策略：

1. 数据有变化时立即发送一次
2. 新客户端接入时发送一次所有窗帘信息

⚠️ 注意：控制类指令执行后无确认报文，请通过 update 推送或主动查询确认窗帘实际执行结果。

7. UDP 通信可靠性建议

本服务对控制指令不返回确认报文（控制后可通过状态推送或主动查询确认执行结果）。由于 UDP 协议不保证报文可靠到达，建议第三方系统遵循以下策略：

1. 序列号管理：frame_qn 字段建议每次发送累加，用于报文去重与追踪
2. 控制确认：控制指令下发后，通过订阅状态更新报文或主动查询来确认窗帘实际执行结果
3. 非阻塞接收：接收 socket 需设置超时，避免阻塞
4. 保活检测：定期发送保活报文，检测连接状态，断线后自动重连

8. 常用指令速查表

8.1 控制指令

8.2 系统指令

9. 典型应用示例

9.1 控制窗帘到 50% 位置

• name：客厅窗帘
• action：travel
• value：50

9.2 停止窗帘运行

• name：客厅窗帘
• action：stop

9.3 设置百叶帘角度 30%

• name：客厅百叶帘
• action：angle
• value：30

9.4 设置香格里拉帘角度 50%

• name：卧室香格里拉帘
• action：angle
• value：50（内部自动转换为 25 下发到电机）

10. 注意事项

1. 设备名称唯一：name 字段必须与系统中配置的窗帘名称完全匹配，否则无法识别
2. 行程范围：travel 的 value 范围为 0~100，超出范围将被限制
3. 角度范围：angle 的 value 范围为 0~100，香格里拉帘内部自动除以2
4. 客户端保活：所有客户端必须周期性发送保活报文，超过保活超时未发送的客户端将被服务端断开
5. 串口独占：RS485串口必须保证只有一个程序在使用某个485接口，严禁多个程序同时使用同一个RS485串口，否则会导致收发数据错乱、通讯失败。此处的"多个程序"指不同功能的程序，例如杜亚窗帘程序和创明窗帘程序不能同时使用同一个RS485串口，即使它们控制的是不同品牌的设备。

11. 相关文档

• 《极物科技 | 创明RS485窗帘 - 快速接入指南》
• 《极物科技 | 创明RS485窗帘 - 通讯协议规范》
• 《极物科技 | 创明RS485窗帘 - 功能接口与调试指南》

关于极物科技（ZEEWO）

极物科技（Zeewo）致力于为用户提供智能控制系统及硬件产品。我们以总线系统为技术底座，以**“稳定、可靠、快速响应”**为产品底线，是国内少有的拥有 KNX、DALI 全套软硬件自主研发能力的厂商之一。

我们的核心能力：

• 系统架构：自研极物 OS，支持多协议无界融合（KNX/DALI/CAN/RS485/IP）。
• 核心硬件：带双路 DALI 的 KNX 主机、超薄全金属定制面板、各类智选传感器及网关。
• 生态互联：深度融入 Apple HomeKit、Matter、小度、HomeAssistant 及纯血鸿蒙生态。
• 调试交付：独家支持 ETS 导出 XML 直接导入进行 APP 免编程调试，支持远程 WEB 运维。

我们的市场覆盖：
服务网点已覆盖全国核心城市（含长三角、珠三角、成渝等），并以高品质的方案深耕家居生活、酒店民宿、企业办公、疗愈康养、餐馆会所等多个细分领域。

(如果您在开发或落地中遇到技术问题，欢迎通过官网或后台私信与我交流探讨)