极物科技 | KNX设备 - Web添加与管理指南
前言
KNX 是全球唯一的开放式楼宇自动化国际标准（ISO/IEC 14543-3），历经三十余年生态沉淀，全球数百家厂商、上万种设备在同一总线上互联互通；其双绞线总线与去中心化架构不依赖任何中央节点，以"稳定、可靠、快速响应"著称，是别墅大宅与商用空间智能控制的首选底座。
极物科技是国内少有的拥有 KNX、DALI 全套软硬件自主研发能力的厂商：自研 KNX 主机内置双路 DALI，配套鸿蒙、苹果、安卓三端原生 APP，深度接入 Apple HomeKit 与小度生态，更支持主机远程调试与远程 WEB 运维；从 ETS 工程 XML 一键导入到 APP 免编程调试，让国际标准的强大能力以极简方式落地。
一句话概述：本文回答"XML导入之外，如何手工添加和管理KNX设备"，帮助工程人员补录设备、调整组地址并规范设备命名。
本文聚焦于 极物主机KNX设备的Web添加与管理，涵盖八类设备的手动添加流程、组地址绑定规则、设备列表管理、参数修改与删除操作，以及设备命名规范建议。
1. 设备模型总览
极物主机将总线上的KNX设备抽象为八类设备模型，每类模型由若干功能地址组成：
| 设备类型 | 功能地址项 | 典型总线设备 |
|---|---|---|
| 按键面板 | 按键、事件、背光灯、状态灯 | 总线面板、智能开关面板 |
| 人体感应传感器 | 触发地址 | 人体红外、存在感应 |
| 继电器灯具 | 控制地址、状态地址 | 继电器模块、开关模块 |
| 窗帘电机 | 行程控制/查询/开关、角度控制/查询、停止、升降 | 窗帘驱动器、百叶驱动器 |
| 环境设备 | 开关/模式/风速/设定温度（各含控制+查询）、环境温度 | 空调网关、地暖温控、新风 |
| 调光灯 | 亮度控制、开关、状态 | 调光执行器 |
| 彩色灯 | RGB/色温控制与状态 | LED调光调色驱动 |
| DALI双色温灯 | 亮度+色温（经DALI网关） | DALI DT8 灯具 |
💡 每台设备由设备名称唯一标识，控制报文通过name字段寻址；每台设备归属一台KNX网关，报文从对应网关收发。
2. 手动添加设备
2.1 添加流程
- 进入Web管理界面设备管理页，选择设备类型页签；
- 点击"添加设备"；
- 填写设备名称、选择归属网关；
- 按功能项绑定组地址；
- 启用设备并保存。
2.2 继电器灯具示例
| 配置项 | 值 | 说明 |
|---|---|---|
| 设备名称 | 客厅灯 | 全局唯一 |
| 归属网关 | knx-gateway-1 | 报文收发通道 |
| 控制地址 | 1/1/1 | 开关指令写入的组地址 |
| 状态地址 | 1/1/101 | 状态反馈读取的组地址 |
| 启用 | 是 | 关闭后设备不参与收发 |
控制与状态的分工：控制地址只写不读（下发开关指令），状态地址只读不写（总线设备回读应答）。两者分离是KNX工程的标准做法------即使执行器重启，主机也能通过状态地址回读恢复真实状态。
每台继电器设备在主机内部的模型大致如下（脱敏示意）：
c
/* 继电器灯具的设备模型（脱敏示意） */
typedef struct relay_light_s {
char name[128]; /* 设备名称：全局唯一，控制报文的寻址依据 */
char gateway[128]; /* 归属网关：报文从哪台网关收发 */
uint16_t id; /* 数字ID：同类设备内递增 */
char enable[8]; /* 启用/停用：停用后不参与收发 */
uint32_t ticker; /* 定时器节拍：驱动周期状态查询 */
uint8_t status; /* 缓存的当前状态 */
uint16_t ga_control; /* 控制组地址：只写 */
uint16_t ga_status; /* 状态组地址：只读 */
struct list_head list; /* 挂入全局设备链表 */
} relay_light_t;💡 从这个模型能直观看到两条主线：
name/id对上"对外寻址"，ga_control/ga_status对上"总线上的一对组地址"------Web页面上填写的每一项配置，最终都落到这几个字段上。
2.3 窗帘电机示例
窗帘设备的功能地址最丰富：
| 功能项 | 说明 |
|---|---|
| 行程控制 | 写入0~100百分比定位 |
| 行程查询 | 读取当前行程位置 |
| 行程开关 | 开/关/停基本控制 |
| 角度控制 | 百叶叶片角度0~100 |
| 角度查询 | 读取当前角度 |
| 停止 | 立即停止运行 |
| 升降 | 升降启动控制 |
普通帘只需绑定行程类地址；百叶帘/香格里拉帘需补齐角度类地址。
2.4 环境设备示例
空调类环境设备最多可绑定9个功能地址（4组控制+查询加环境温度查询）。支持部分绑定：
- 纯空调：绑定开关/模式/风速/设定温度全套；
- 纯地暖：只绑定开关+设定温度（或模式）；
- 新风：绑定开关+风速。
主机按实际绑定的功能项生成控制界面，未绑定的功能自动隐藏，兼容不同暖通设备的差异化能力。
3. 设备列表管理
3.1 列表功能
设备列表页支持：
- 查看设备状态（在线/离线、当前值）；
- 修改设备名称与组地址绑定；
- 启用/停用设备；
- 删除设备。
列表查询返回的数据结构（示意）：
json
{
"frame_driver": "gernel_relay_light",
"frame_type": "update",
"relay_light_list": [
{
"name": "客厅灯",
"id": 1,
"enable": "on",
"status": 1,
"address_s": "1/1/1",
"address_status_s": "1/1/101",
"knx_router_name": "knx-gateway-1"
},
{
"name": "客厅-沙发背景-筒灯-01",
"id": 2,
"enable": "on",
"status": 0,
"address_s": "1/1/2",
"address_status_s": "1/1/102",
"knx_router_name": "knx-gateway-1"
}
]
}字段与Web页面一一对应：address_s 是控制组地址、address_status_s 是状态组地址、knx_router_name 是归属网关------第三方系统也可以直接消费这份列表做设备台账同步。
3.2 设备ID机制
每台设备在添加时自动分配数字ID ，该ID在同一类设备内递增且全局唯一。对外接口中，面板类设备使用 dev_id 寻址，其余设备使用 name 寻址。ID在导入XML时按解析顺序重新编排。
⚠️ 注意：删除设备后其ID不会立即复用，新增设备继续递增编号，避免历史控制报文误命中。
4. 设备命名规范建议
设备名称是控制报文的寻址依据，命名质量直接决定工程的可维护性。推荐命名模板：
text
[区域]-[位置]-[类型]-[序号]
示例：
客厅-沙发背景-筒灯-01
主卧-窗帘-纱帘
二楼-书房-空调命名原则：
| 原则 | 说明 |
|---|---|
| 全局唯一 | 同类设备名称重复会导致报文命中错误设备 |
| 区域前缀 | 便于列表检索与批量定位 |
| 面向业主 | APP界面直接显示该名称，使用业主熟悉的语言 |
| 避免特殊字符 | 不建议使用 #、/ 等与协议解析相关的字符 |
| 预留扩展 | 同类设备保持序号连续，后期增补不冲突 |
5. 设备与场景的关系
设备添加完成后即可被场景引用：
- KNX原生场景：总线设备自身的场景号，由面板/执行器实现；
- 主机场景：在极物主机上编排多设备动作，触发方式包括APP、面板按键、传感器联动、定时等。
场景编排与APP免编程调试的完整流程见《极物科技 | KNX场景 - 主机场景与APP免编程调试》。
6. 注意事项
- 组地址冲突：同一组地址绑定到多台设备时，报文会同时分发给所有绑定设备，请确保组地址按"一址一责"规划。
- 状态地址优先：凡执行器支持状态反馈的，务必绑定状态地址，否则主机只能"盲发"指令，无法感知真实状态。
- 删除前解绑场景：删除设备前先检查场景引用，避免场景中残留失效设备。
- 启停代替删除：调试期的临时设备建议停用而非删除，保留配置便于恢复。
- 导入与手工并用：XML导入会重置设备列表，手工补录的设备请在导入后重新检查，必要时先导出备份配置。
7. 相关文档
- 《极物科技 | KNX智能控制系统 - 快速接入指南》
- 《极物科技 | KNX工程 - ETS导出XML一键导入指南》
- 《极物科技 | KNX继电器模块 - 对接与控制》
- 《极物科技 | KNX窗帘电机 - 行程与角度控制对接》
- 《极物科技 | KNX未知设备 - 自动识别与管理机制》
关于极物科技（ZEEWO）
极物科技（Zeewo）致力于为用户提供智能控制系统及硬件产品。我们以总线系统为技术底座，以**"稳定、可靠、快速响应"**为产品底线，是国内少有的拥有 KNX、DALI 全套软硬件自主研发能力的厂商之一。
我们的核心能力：
- 系统架构：自研极物 OS，支持多协议无界融合（KNX/DALI/CAN/RS485/IP）。
- 核心硬件：带双路 DALI 的 KNX 主机、超薄全金属定制面板、各类智选传感器及网关。
- 生态互联：深度融入 Apple HomeKit、Matter、小度、HomeAssistant 及纯血鸿蒙生态。
- 调试交付：独家支持 ETS 导出 XML 直接导入进行 APP 免编程调试，支持远程 WEB 运维。
我们的市场覆盖：
服务网点已覆盖全国核心城市（含长三角、珠三角、成渝等），并以高品质的方案深耕家居生活、酒店民宿、企业办公、疗愈康养、餐馆会所等多个细分领域。
(如果您在开发或落地中遇到技术问题，欢迎通过官网或后台私信与我交流探讨)