极物科技 | KNX人体感应 – 传感器UDP对接协议
前言
KNX 生态的强大在于“广”：全球数百家厂商的灯具、窗帘、暖通、传感设备都遵循同一套组地址模型，即插即用、互联互通。
在此基础上，极物主机将八类 KNX 设备统一抽象为一套简洁的 UDP 控制接口，第三方系统无需了解 KNX 报文细节即可完成对接。本文给出该接口在具体设备上的字段定义、报文示例与工程实施建议。
一句话概述：本文给出人体感应传感器对接极物主机的UDP JSON协议——人来/人走事件上报格式与自动化联动示例。
1. 协议总览
| 传输协议 | UDP |
| 端口 | 2151 |
| 数据格式 | JSON（UTF-8） |
| 通信模型 | 主机主动上报事件（传感器为纯输入设备） |
2. 保活报文
每5秒一次，与面板协议一致：
{
"frame_type": "keeplive"
}
3. 传感器事件上报
有人触发/离开时主机主动推送：
{
"frame_type": "update",
"frame_qn": 1,
"frame_driver": "gernel_input",
"driver_data": {
"name": "主卧传感器",
"object": "input",
"action": "on"
}
}
3.1 字段详解
| frame_type | update | 事件上报报文 |
| frame_qn | 数字 | 报文序列号 |
| frame_driver | gernel_input | 通用输入传感器驱动标识（固定值） |
| driver_data.name | 字符串 | 传感器名称，区分不同传感器的唯一依据 |
| driver_data.object | input | 事件主体，固定值 |
| driver_data.action | on / off | on=人来（触发），off=人离开（恢复） |
💡 与面板不同，传感器用name（设备名称）而非ID寻址——名称必须在主机配置中与传感器设备一一对应，建议命名包含房间位置。
4. 联动示例
4.1 灯光自动化（来人开灯、离开延时关灯）
LIGHT_DELAY = 300 # 离开后延时关灯秒数
def on_sensor_update(msg):
d = msg["driver_data"]
if d["name"] != "玄关传感器":
return
if d["action"] == "on":
send_relay("玄关灯", "on") # 开灯
else:
schedule_later(LIGHT_DELAY, lambda: send_relay("玄关灯", "off"))
延时期间再次触发on应取消挂起的关灯任务——"人还在屋里走动"不应被关灯。
4.2 安防布防联动
布防状态 + 传感器 action=on → 推送告警（勿直接开灯吓退取证）
撤防状态 + 传感器 action=on → 正常灯光自动化
4.3 与主机场景联动
传感器也可直接绑定主机场景（无需第三方开发）：人来自动触发"回家场景"，离开触发"离家场景"——在主机Web端即可配置。
5. 传感器选型与部署建议
| 感应类型 | 走廊/玄关用红外（PIR）；书房/卫生间用存在感应（毫米波） |
| 灵敏度 | 红外传感器避免正对空调出风口/窗帘，防误触发 |
| 名称规范 | [区域]-[传感器]，如"主卧-人体感应"，全网唯一 |
| 联动防抖 | 高频触发场景在第三方侧做2~5秒事件合并 |
6. 常见问题
| 收不到事件 | 传感器触发地址未绑定或name配置不符 |
| 频繁on/off抖动 | 红外灵敏度过高/安装位置不当，硬件侧调整 |
| 名称匹配失效 | name大小写与主机配置不一致 |
| 夜间误亮灯 | 加装光照阈值判断（传感器自带照度联动或主机侧判断时间窗） |
7. 相关文档
- 《极物科技 | KNX按键面板 – UDP对接协议规范》
- 《极物科技 | KNX场景 – 主机场景与APP免编程调试》
- 《极物科技 | KNX设备 – 状态上报与在线监控机制》
- 《极物科技 | KNX设备 – Web添加与管理指南》
文档说明与勘误
- 本文示例报文与配置均取自真机联调环境，其中设备名称、场景名、个体地址等均为演示数据，实际使用时请按工程命名规范替换。
- 文中端口号、报文类型与字段定义以成文时的固件版本为准；若与后续版本存在差异，请以主机 Web 端「系统配置 — 接口说明」页面展示的内容为准。
- 系列文档之间通过「相关文档」小节互相引用，建议按编号顺序阅读，先看协议规范再看工程实战。
- 如发现示例报文与现场不一致，欢迎在评论区留言指正，我们会持续核对并修订本文。
本文由极物福州研发团队整理。
