63 极物科技 | KNX窗帘电机 - 行程与角度控制对接

极物科技 | KNX窗帘电机 – 行程与角度控制对接

前言

KNX 生态的强大在于“广”：全球数百家厂商的灯具、窗帘、暖通、传感设备都遵循同一套组地址模型，即插即用、互联互通。

在此基础上，极物主机将八类 KNX 设备统一抽象为一套简洁的 UDP 控制接口，第三方系统无需了解 KNX 报文细节即可完成对接。本文给出该接口在具体设备上的字段定义、报文示例与工程实施建议。

一句话概述：本文给出KNX窗帘电机（含百叶帘/香格里拉帘）对接极物主机的完整UDP协议——行程、角度、停止三类控制与状态上报。

1. 协议总览

2. 保活报文

每5秒一次：

{
"frame_type": "keeplive"
}

3. 状态上报报文

窗帘行程/角度变化时主机主动推送：

{
"frame_type": "update",
"frame_qn": 4,
"frame_driver": "gernel_curtain",
"driver_data": {
"travel": 100,
"angle": 0,
"name": "客厅窗帘"
}
}

⚠️ name匹配机制：主机以name字段匹配窗帘，第三方系统与主机两侧的名称必须完全一致（含大小写），否则状态对不上号。

4. 控制报文

4.1 行程控制

{
"frame_type": "request",
"frame_qn": 1,
"frame_driver": "gernel_curtain",
"driver_data": {
"name": "客厅窗帘",
"action": "travel",
"value": 100
}
}

4.2 角度控制

{
"frame_type": "request",
"frame_qn": 2,
"frame_driver": "gernel_curtain",
"driver_data": {
"name": "客厅窗帘",
"action": "angle",
"value": 50
}
}

4.3 停止

{
"frame_type": "request",
"frame_qn": 3,
"frame_driver": "gernel_curtain",
"driver_data": {
"name": "客厅窗帘",
"action": "stop",
"value": 0
}
}

4.4 action速查

5. 组地址绑定要点

窗帘设备的功能地址最丰富，按需绑定：

普通开合帘只绑行程类即可，主机控制界面自动隐藏角度控件。

6. 百叶帘角度映射说明

KNX侧角度常见两种编码，主机统一映射为0~100百分比：

DPT 5.003（0~360°）：主机内部按 angle% × 360° 换算
DPT 5.001（0~100%）：直接透传

工程标定建议：交付前用0/50/100三个点位实测叶片状态，确认"0=收拢、100=全展开"方向与业主要求一致；方向反了在驱动器侧调换行程上下限即可，不必改协议侧。

7. 常见问题

8. 相关文档

• 《极物科技 | KNX按键面板 – UDP对接协议规范》
• 《极物科技 | KNX设备 – Web添加与管理指南》
• 《极物科技 | KNX协议 – APCI指令与数据点类型解析》
• 《极物科技 | KNX方案 – 别墅大宅全屋智能实战》

文档说明与勘误

• 本文示例报文与配置均取自真机联调环境，其中设备名称、场景名、个体地址等均为演示数据，实际使用时请按工程命名规范替换。
• 文中端口号、报文类型与字段定义以成文时的固件版本为准；若与后续版本存在差异，请以主机 Web 端「系统配置 — 接口说明」页面展示的内容为准。
• 系列文档之间通过「相关文档」小节互相引用，建议按编号顺序阅读，先看协议规范再看工程实战。
• 如发现示例报文与现场不一致，欢迎在评论区留言指正，我们会持续核对并修订本文。

本文由极物福州研发团队整理。