62 极物科技 | KNX继电器模块 - 对接与控制

tags:

极物
极物智能
极物科技
KNX协议
KNX继电器
UDP协议
智能照明
楼宇自动化
description: 本文是KNX继电器模块对接协议规范：端口2152、状态上报与控制报文JSON格式、name寻址机制、多路继电器管理与回读状态一致性保障方案。

极物科技 | KNX继电器模块 - 对接与控制

前言

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

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

一句话概述：本文给出继电器类灯具（灯带、筒灯、插座等开关负载）对接极物主机的完整UDP协议与状态一致性方案。

text

1. 协议总览

项目	值
传输协议	UDP
端口	2152
数据格式	JSON（UTF-8）
通信模型	主机上报状态（update）+ 第三方下发控制（request），name寻址

2. 保活报文

每5秒一次：

json 复制代码

{
    "frame_type": "keeplive"
}

3. 状态上报报文

继电器状态变化（面板按键/APP/主机自动化的结果）时，主机主动推送：

json 复制代码

{
    "frame_type": "update",
    "frame_qn": 8,
    "frame_driver": "gernel_relay_light",
    "driver_data": {
        "action": "on",
        "object": "relay_light",
        "name": "继电器-1"
    }
}

字段	值	说明
frame_driver	`gernel_relay_light`	继电器灯具驱动标识（固定值）
driver_data.name	字符串	灯具名称，区分不同负载的唯一标识
driver_data.action	`on` / `off`	开/关
driver_data.object	`relay_light`	对象类型，固定值

4. 控制报文

第三方向主机下发：

json 复制代码

{
    "driver_data": {
        "name": "继电器-1",
        "action": "off",
        "object": "relay_light"
    },
    "frame_type": "request",
    "frame_qn": 112233,
    "frame_driver": "gernel_relay_light",
    "device_info": {
        "sn": "11111"
    },
    "frame_result": "ok"
}

开/关切换只需改action字段，name务必与主机配置中的灯具名称完全一致。

5. 多路继电器的管理实践

一个12路继电器模块通常对应12个独立灯具（12组组地址对）。推荐配置策略：

text 复制代码

模块：12路继电器（配电箱内）
 ├─ 1路 客厅-主灯      控制地址1/1/1   状态地址1/1/101
 ├─ 2路 客厅-灯带      控制地址1/1/2   状态地址1/1/102
 ├─ 3路 客厅-筒灯      控制地址1/1/3   状态地址1/1/103
 └─ ...

一路一灯一name：即使多个回路总是一起动作，也建议独立命名，后期可单控；
统一开关交给场景（一次触发多路），而不是把多路绑到同一组地址；
名称建议带区域前缀，第三方系统检索方便。

6. 状态一致性保障

继电器的状态来源有三个，优先级如下：

text 复制代码

① 总线回读（状态地址的Response/主动上报）  ← 权威
② 主机周期状态查询（约120秒一轮Read）
③ 本机控制指令的乐观更新（发送即认为成功，待②③校准）

第三方系统只需订阅update报文即可获得最终一致的状态视图；若发现长时间无update，可用控制指令加回读校验（结合报文追踪确认Read/Response链路）。

7. 对接示例

python 复制代码

def send_relay(name, action):
    sock.sendto(json.dumps({
        "frame_type": "request", "frame_qn": next_seq(),
        "frame_driver": "gernel_relay_light",
        "driver_data": {"name": name, "action": action,
                        "object": "relay_light"},
        "device_info": {"sn": "11111"}, "frame_result": "ok"
    }).encode(), (HOST, 2152))

# 一键全关
for lamp in ["客厅-主灯", "客厅-灯带", "客厅-筒灯"]:
    send_relay(lamp, "off")

8. 常见问题

现象	排查
控制无反应	name不匹配（大小写/空格）；设备被停用
状态不回	未绑定状态地址；执行器不支持回读
开关反向	ETS中该对象DPT配置为反向逻辑
部分路控不动	该路组地址未导入/绑定，检查未知设备列表

9. 相关文档

《极物科技 | KNX按键面板 - UDP对接协议规范》
《极物科技 | KNX调光灯 - 亮度控制对接》
《极物科技 | KNX协议 - 读/写/响应机制与状态同步》
《极物科技 | KNX未知设备 - 自动识别与管理机制》

文档说明与勘误

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

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