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

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

前言

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

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

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

1. 服务端口与连接说明

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

服务	端口号	说明
创明窗帘接口	2058	对应创明 RS485 窗帘服务

连接说明：

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

2. 报文帧结构总览

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

字段	类型	必选	说明
frame_type	String	是	报文类型（request/keeplive/update）
frame_qn	Number	是	报文序列号，服务端自动累加
frame_driver	String	是	驱动标识，固定为 `gernel_curtain`
driver_data	Object	是	实际控制参数，由窗帘模块定义
device_info	Object	否	发送方设备信息（如 sn）
frame_result	String	是	报文结果，固定为 `ok`

完整示例：

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 字段说明

字段	类型	说明
name	String	窗帘设备名称（如"客厅窗帘"）
action	String	动作类型（stop/travel/angle）
value	Number	动作参数值（行程0_{100，角度0}100）

4. 保活报文

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

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

json 复制代码

{
  "frame_type": "keeplive"
}

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

json 复制代码

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

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

保活策略：

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

5. 控制报文详解

5.1 停止控制

停止窗帘当前运行。

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

json 复制代码

{
  "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%）。

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

json 复制代码

{
  "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。

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

json 复制代码

{
  "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. 状态更新报文

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

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

json 复制代码

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

driver_data 字段说明：

字段	类型	说明
travel	Number	当前行程位置（0~100，百分比）
angle	Number	当前叶片角度（0~100，百分比）
online	Number	在线状态（1=在线，0=离线）
name	String	窗帘设备名称

更新策略：

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

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

7. UDP 通信可靠性建议

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

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

8. 常用指令速查表

8.1 控制指令

功能	action	value	说明
停止	`stop`	无	停止当前运行
行程控制	`travel`	0~100	百分比位置
角度控制	`angle`	0~100	叶片角度

8.2 系统指令

功能	frame_type	说明
保活	`keeplive`	连接保活
状态推送	`update`	服务端主动推送

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. 注意事项

设备名称唯一 ：name 字段必须与系统中配置的窗帘名称完全匹配，否则无法识别
行程范围 ：travel 的 value 范围为 0~100，超出范围将被限制
角度范围 ：angle 的 value 范围为 0~100，香格里拉帘内部自动除以2
客户端保活：所有客户端必须周期性发送保活报文，超过保活超时未发送的客户端将被服务端断开
串口独占：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 运维。

我们的市场覆盖：

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

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