极物科技 | KNX设备 - 状态上报与在线监控机制
前言
KNX 生态的强大在于"广"：全球数百家厂商的灯具、窗帘、暖通、传感设备都遵循同一套组地址模型，即插即用、互联互通。
在此基础上，极物主机将八类 KNX 设备统一抽象为一套简洁的 UDP 控制接口，第三方系统无需了解 KNX 报文细节即可完成对接。本文给出该接口在具体设备上的字段定义、报文示例与工程实施建议。
一句话概述：本文回答"第三方系统如何可靠地掌握全部KNX设备的最新状态与在线情况"------状态上报的时机、全量同步的入口、在线判定的依据一次讲清。
1. 状态上报的四条时机
极物主机在以下四种情况向UDP客户端推送设备状态（update报文）：
| 时机 | 触发条件 | 特点 |
|---|---|---|
| 即时上报 | 总线状态变化（经防抖判定后） | 毫秒~秒级，最常用 |
| 周期同步 | 设备定时器周期点位（约100秒档） | 兜底，防止漏推 |
| 全量同步 | 新客户端接入（检测到新对端） | 客户端初始化零等待 |
| 控制回执 | 本机下发控制后的状态确认 | 控制闭环 |
text
状态源（总线Response/上报）
│ 防抖窗口
▼
设备模型更新 ──→ 立即推送update
│
└──→ 定时器周期点位再推一次（兜底）2. 新客户端接入全量同步
第三方系统（或重连的APP）接入任意设备端口后，主机识别到新的UDP对端地址，随即推送该端口全部设备的状态：
text
第三方 bind并首次发包（如keeplive）
→ 主机登记对端
→ 依次推送该端口所有设备的update报文
→ 之后进入正常事件推送节奏对接方最佳实践：客户端启动后先发一条keeplive"报到"，等待全量同步完成后（通常1秒内）再渲染界面，避免"空白界面→逐个蹦出来"的观感。
3. 在线判定机制
3.1 客户端→主机方向
主机以5秒保活判定第三方客户端在线，超时未收到keeplive则停止定向推送（重连后重新全量同步）。
3.2 设备→主机方向（总线设备在线）
总线设备没有独立"心跳"，在线状态由以下证据合成：
| 证据 | 说明 |
|---|---|
| 周期Read有Response | 约120秒一轮，有响应=在线 |
| 主动上报存在 | 传感器/执行器的事件报文 |
| 控制有回执变化 | 下发后状态地址有反馈 |
连续多个查询周期无任何响应 → 判定疑似离线（触达物理层排查）。
3.3 DALI网关方向
DALI网关与KNX驱动之间有独立UDP会话与保活（每5秒），网关侧的在线状态影响其下挂DALI设备的可见性。
4. 离线告警的工程实现建议
主机原生提供状态与在线数据，告警策略建议由第三方/主机联动侧实现：
python
class DeviceMonitor:
MISS_LIMIT = 3 # 连续未响应轮询次数阈值
def __init__(self):
self.miss = {}
def on_poll_result(self, name, responded):
if responded:
self.miss.pop(name, None)
return
self.miss[name] = self.miss.get(name, 0) + 1
if self.miss[name] == self.MISS_LIMIT:
notify(f"设备疑似离线：{name}") # 推送告警
# 恢复上报时清除计数并通知恢复告警分级建议：
| 级别 | 条件 | 动作 |
|---|---|---|
| 提示 | 单设备1个周期未响应 | 仅记录日志 |
| 警告 | 单设备连续3周期未响应 | 推送维保人员 |
| 严重 | 同一配电箱多设备同时离线 | 推送+检查电源/总线（大概率物理层故障） |
💡 "多设备同时离线"几乎总是物理层问题（电源过载、总线短路、网关掉线），单独设备离线多为该设备故障------分级规则天然区分了两种根因。
5. 状态一致性核对（验收动作）
text
① 随机抽10台设备，本地物理操作（按面板/拔负载）
② 观察第三方系统1~2秒内是否同步
③ 断开执行器电源再恢复，等待一个查询周期（约2分钟）
④ 核对状态是否自动恢复一致
⑤ 重启主机，验证开机集中Read后状态收敛五步全过，状态链路验收完成。
6. 常见问题
| 现象 | 排查 |
|---|---|
| 界面长时间不更新 | 客户端keeplive停发被主机判定离线，检查保活线程 |
| 全量同步没收到 | 接入时报文发错了端口，各设备类型端口不同 |
| 设备显示离线但能控制 | 控制地址正常、状态地址无响应，优先查状态地址绑定 |
| 告警风暴 | 阈值过灵敏或总线负载高导致响应慢，加大MISS_LIMIT |
7. 相关文档
- 《极物科技 | KNX协议 - 读/写/响应机制与状态同步》
- 《极物科技 | KNX报文追踪 - 功能总览与使用指南》
- 《极物科技 | KNX调试 - Web远程调试与现场排障实战》
- 《极物科技 | KNX系统 - 工程实施与部署运维指南》
文档说明与勘误
- 本文示例报文与配置均取自真机联调环境，其中设备名称、场景名、个体地址等均为演示数据，实际使用时请按工程命名规范替换。
- 文中端口号、报文类型与字段定义以成文时的固件版本为准；若与后续版本存在差异，请以主机 Web 端「系统配置 --- 接口说明」页面展示的内容为准。
- 系列文档之间通过「相关文档」小节互相引用，建议按编号顺序阅读，先看协议规范再看工程实战。
- 如发现示例报文与现场不一致，欢迎在评论区留言指正，我们会持续核对并修订本文。
本文由极物福州研发团队整理。