KNX ETS5 / ETS6 使用指南
从安装到导出 CSV 对接 EasyPro —— ETS5 与 ETS6 全流程对比
ETS（Engineering Tool Software）是 KNX 系统的官方工程配置软件，用于设计拓扑、配置设备参数、分配组地址、编程下载与诊断。本指南把ETS5（经典稳定版）与ETS6（新一代跨平台版）的完整工程流程并排对比，最终目标是导出组地址 CSV 并导入 EasyPro 平台，与 KNX 驱动功能设计 中的 importPointApi 闭环。
本页目前使用示意图占位图（灰底虚线框），便于先搭好文档骨架与图文位置。真实 ETS 截图请按 assets/knx-ets/ 下的命名（如 ets5-home.svg）替换为同名 PNG/SVG 即可自动显示。
ETS（Engineering Tool Software）是 KNX 协会（KNX Association）发布的官方工程配置软件，是 KNX 工程师进行系统设计、参数配置、组地址分配、编程下载、诊断调试的唯一标准工具。所有 KNX 设备出厂时都附带可在 ETS 中导入的产品数据库。
简单说：要让一个 KNX 系统工作起来——哪些设备挂在哪、谁能控制谁、按键按一下控制哪盏灯——这些逻辑关系都是在 ETS 里设计并下载到设备里的。
目前并存两个主流大版本：ETS5（长期稳定、Windows 平台）与 ETS6（新一代、跨平台、新 UI）。两者完成的工程任务一致，但在授权模型、运行平台、界面交互上有明显差异。
| 对比维度 | ETS5 | ETS6 |
|---|---|---|
| 发布定位 | 经典稳定版（长期广泛使用） | 新一代主力版（持续演进） |
| 操作系统 | 仅 Windows | Windows / macOS（跨平台） |
| 授权方式 | License Key（加密狗/软件证书） | KNX 账号在线登录授权 |
| 界面风格 | 传统桌面三栏式 | 现代化扁平界面、工作流引导更强 |
| 产品数据库格式 | .vd5 / .knxprod | .knxprod（向下兼容 .vd5） |
| 导出 CSV | 支持（组地址导出） | 支持（组地址导出） |
| 与 EasyPro 对接 | 两者导出的组地址 CSV 均可被 importPointApi 解析（UTF-16LE 编码） | |
新项目若团队跨平台（含 Mac）或希望用最新界面，首选 ETS6；若现场老设备多、调试机为 Windows 且追求最大兼容性，ETS5 仍非常稳妥。两者的工程文件（.knxproj / .knxproj）在新版可互相迁移。
ETS 由 KNX 协会官方分发，需从官网（my.knx.org）下载。下载前通常需注册 KNX 账号。两个版本的安装包各自独立，可在同一台机器上共存以便迁移老工程。
从 KNX 官网下载 ETS5 安装包（.exe）。仅支持 Windows 7/10/11。
- 系统：仅 Windows
- 格式：
.exe安装程序 - 需 .NET Framework 运行时
登录 KNX 账号后，在 my.knx.org 下载对应平台的 ETS6 安装包。
- 系统：Windows / macOS
- 格式：Win
.exe/ Mac.dmg - 跨平台部署能力更强
两者安装流程相似（接受协议 → 选择路径 → 等待 → 完成），但 ETS6 首次启动会引导登录 KNX 账号。
- 运行
.exe→ 接受许可协议 - 选择安装路径与组件
- 安装 .NET 依赖（若缺失）
- 完成 → 桌面生成快捷方式
- Win 运行
.exe/ Mac 挂载.dmg - 拖拽到 Applications（Mac）
- 首次启动引导登录 KNX 账号
- 在线激活授权
① 安装目录需可写；② Windows 上若已装旧版 ETS，建议先卸载或装到不同目录避免冲突；③ Mac 上若提示"无法验证开发者"，在系统设置 → 隐私与安全性中允许打开。
ETS 的授权（License）决定了你能用的功能范围（如可下载的设备数）。这是 ETS5 与 ETS6 最大的使用差异。
ETS5 采用离线 License Key：可以是软件证书，也可以是硬件加密狗。在「Help → License Manager」中输入或插入加密狗激活。
- 离线可用，加密狗即插即用
- 适合无外网的现场调试机
- 更换电脑需迁移 License
ETS6 采用在线账号授权：启动时登录 KNX 账号（my.knx.org 注册），授权自动绑定到账号，在线激活。
- 账号即授权，换机登录即可
- 首次激活需联网
- 支持离线宽限期（短期断网可用）
授权完成后进入主界面。两者都遵循工程 → 拓扑 → 组地址 → 链接的核心工作区划分，但 ETS6 的导航更现代化。
左侧工程树 + 中部工作区 + 右侧属性面板，菜单栏功能入口密集。
启动页引导工程操作，工作流分区更清晰，配色更扁平。
ETS 提供 Lite / Entry / Lite Plus / Professional 等授权等级。未授权时可使用 Lite 模式（限少量设备）进行学习与小型工程，导出 CSV 等基础功能可用。
所有 KNX 配置都从「新建工程」开始。一个工程（Project）对应一个独立的楼宇/项目，包含拓扑、组地址、设备、链接等全部信息。
- 菜单 File → New Project
- 填写工程名、编号、客户信息
- 选择介质（默认 Twisted Pair / TP）
- 启动页 New Project 引导
- 同填工程名、编号、客户
- 向导式步骤，更直观
KNX 采用域（Area）→ 线（Line）→ 设备的拓扑结构。每个域最多 15 条线，每条线最多 64 设备（含线耦合器）。工程新建后会自动生成「域 0 / 线 0」作为主干线。
Backbone 主干线"] --- L0["线 Line 0
主干线"] A --- L1["线 Line 1
支线"] A --- L2["线 Line 2
支线"] L1 --- D1["设备 x.y.z"] L1 --- D2["设备 x.y.z"] L2 --- D3["设备 x.y.z"] style A fill:#e8f0fe,stroke:#007aff,stroke-width:2px,color:#1c1c1e style L0 fill:#f0f0f5,stroke:#5856d6,color:#1c1c1e style L1 fill:#fff4e8,stroke:#ff9500,color:#1c1c1e style L2 fill:#fff4e8,stroke:#ff9500,color:#1c1c1e
这里的域/线结构对应 EasyPro KNX 驱动实例的 KNXBranch 属性（如 1.1 = 1 区 1 线），用于约束合法物理地址范围。详见 KNX 驱动 · 实例属性。
KNX 设备不是即插即用的——必须先把它对应的「产品数据库」导入 ETS，才能在工程中添加该设备并配置其参数。数据库由设备厂商提供，描述了设备的参数、通信对象、DPT等信息。
| 格式 | 使用版本 | 说明 |
|---|---|---|
.knxprod | ETS5 / ETS6 | 新版统一格式，推荐 |
.vd5 | ETS5 为主 | 旧版格式，ETS6 可兼容导入 |
.vd4 | ETS4 | 已淘汰，需厂商提供新版 |
- 菜单 Catalogs → Import Product
- 选择
.knxprod/.vd5文件 - 导入后进入产品目录
- Catalogs 区 Import 引导
- 支持拖拽
.knxprod - 自动校验签名与版本
① 设备数据库必须与 ETS 版本匹配，过老的 .vd4 在 ETS6 可能无法导入；② 同一设备型号有不同硬件版本（HW Revision），数据库选错会导致参数项不一致；③ 厂商更新数据库后，需重新导入并核对工程。
组地址是 KNX 的核心寻址机制，采用 x/y/z 三级格式（如 1/1/3）。它代表一个功能逻辑而非物理设备——这是理解 KNX 与 Modbus 等轮询总线最大的区别。
| 组地址 | 典型含义 | 主类型 |
|---|---|---|
1/1/1 | 会议室灯光开关 | 主组 1 = 照明 |
1/1/2 | 会议室灯光调光值 | 主组 1 = 照明 |
2/1/1 | 窗帘开关 | 主组 2 = 遮阳 |
3/2/1 | 当前温度 | 主组 3 = 暖通 |
主组（第一段 x）按功能域划分（照明/遮阳/暖通/计量…），中间组（y）按子区域，末端（z）为具体功能。一致的命名规范会让后续平台导入与运维更清晰。
每个组地址必须指定一个 DPT（Datapoint Type），定义值的格式与含义。这与 EasyPro KNX 驱动的 DPT 注册表严格对应——组地址的 DPT 决定了报文字节如何被平台解析。
| DPT | 名称 | 平台类型 | 示例 |
|---|---|---|---|
1.001 | switch 开关 | boolean | 开/关 |
1.010 | start 启动 | boolean | 启/停 |
5.001 | 百分比 | int | 0-100% |
9.001 | 温度 | float | 22.5°C |
13.001 | 有功电能 | int | 12345 Wh |
14.xxx | 4 字节浮点 | float | 任意 IEEE754 |
组地址在 ETS 里设置的 DPT，必须与平台点位的 dataType 一致，否则报文会被按错误类型解析（如温度点配成 5.001 会得到乱码值）。详见 KNX 驱动 · 数据点类型。
- 左侧树选 Group Addresses
- 右键 → New / 批量建
- 双击设置 DPT、名称
- Groups 工作区
- 支持批量模板创建
- DPT 选择更图形化
从已导入的产品目录中，把具体型号的设备拖入拓扑的对应线（Line）下，设备会自动获得一个物理地址（可手动修改）。每个设备展开后有参数（Parameters）和通信对象（Communication Objects）两类配置。
- 双击设备 → Parameters 配参数
- Group Addresses 视图拖拽链接
- 或用 Screening 自动建议
- 设备工作区配置参数
- 链接面板可视化拖拽
- 实时校验 DPT 匹配
链接 = 把设备的通信对象绑定到组地址。例如把灯具执行器的「开关」对象链接到组地址 1/1/1，把墙面面板的「按键」对象也链接到 1/1/1，于是面板按键就能控制该灯具。链接完成后，整个逻辑闭环才成立。
按键对象"] -.->|"链接"| GA["组地址 1/1/1
DPT 1.001"] GA -.->|"链接"| L["灯具执行器
开关对象"] style P fill:#e8f8f0,stroke:#34c759,color:#1c1c1e style GA fill:#e8f0fe,stroke:#007aff,stroke-width:2px,color:#1c1c1e style L fill:#fff4e8,stroke:#ff9500,color:#1c1c1e
平台订阅 1/1/1 即可同时感知面板动作与灯具状态——这就是 KNX 「组地址即频道」的解耦优势。
每个设备需要一个物理地址 x.y.z（域.线.设备号），用于设备寻址与诊断。物理地址通常在设备出厂后首次接入总线时通过「物理地址分配」写入，默认值是 15.15.255。
- 设备按编程按钮（PROG）
- ETS 选 Set Physical Address
- 点击设备 → 写入地址
- 同样的 PROG 按钮流程
- 引导式分配向导
- 支持批量顺序分配
这是让配置真正生效的关键步骤：把工程里设计的参数与组地址链接下载到设备。下载分两种：
| 下载方式 | 内容 | 耗时 | 场景 |
|---|---|---|---|
| 部分下载（Partial） | 仅变化的参数/链接 | 快 | 调试期频繁修改 |
| 完全下载（Full） | 设备全部应用 + 组地址表 | 慢 | 首次配置 / 大改后 |
| 物理地址下载 | 仅写物理地址 | 极快 | 初次寻址 |
- 工具栏 Download（部分/完全）
- 选接口 → 选设备 → 下载
- 进度与错误日志实时显示
- 同样的部分/完全下载
- 向导式接口选择
- 下载结果更醒目的状态反馈
① KNX USB 接口或 IP 接口已连接且被 ETS 识别；② 设备已在总线供电；③ 设备的 PROG 按钮按下（红灯亮）——首次写物理地址或部分下载单台设备时尤其需要；④ 同一线建议避免同时多客户端下载以免总线冲突。
下载完成后，用总线监控实时观察总线上的报文流，验证设备是否按预期收发组地址报文，是调试阶段最重要的工具。
- Diagnostics 视图 → Bus Monitor
- 实时报文列表（时间/源/目标/值）
- 可过滤组地址
- 诊断面板统一入口
- 报文可视化更清晰
- 支持报文回放与统计
确认所有组地址报文正常后，工程即可投入运行。下一步就是把组地址导出为 CSV，导入 EasyPro 平台，让平台接管监控与控制。
这是 ETS 工程与 EasyPro 平台对接的桥梁，也是本指南的核心目的。ETS 工程里设计好的群组地址（Group Address）列表——包括地址、名称、数据点类型（DPT）——可以整体导出为 CSV 文件；平台 KNX 驱动的 importPointApi 接收该 CSV 后，会自动解析并批量创建点位，免去逐条手建。
简单说：你在 ETS 里怎么设计的组地址，平台就原样建出对应的点位。所以导出前请确保工程内的组地址已设计完整、DPT 已正确设置。
对接平台需要的是 Group Addresses 导出（组地址列表），不是拓扑导出、不是项目导出（.knxproj）、不是设备参数导出。三者格式完全不同，导错会导致平台解析失败。
- 左侧工程树选 Group Addresses 视图
- 右键根节点 → Export
- 保存类型选
CSV - 选择保存路径，命名
- 点击保存完成导出
- 进入 Groups 工作区
- 菜单或工具栏 Export
- 格式选
CSV - 确认导出范围（全部组地址）
- 保存到本地
EasyPro 的 importPointApi 要求 CSV 为 UTF-16LE 编码（ETS 默认即此编码）。若用文本编辑器「另存为 UTF-8」，会导致中文组地址名乱码、BOM 丢失或整表解析失败。导出后请勿手动转码。
ETS 导出的群组地址 CSV 是一个带表头的制表符（Tab）分隔的文本表格（虽扩展名为 .csv，但实际分隔符是 Tab，不是逗号）。每行描述一个组地址。典型内容如下（已简化，省略部分列）：
"Group address" "Name" "Central" "Unfiltered" "Description" "DatapointType" "DatapointTypeDescription" "1/1/1" "会议室-灯光开关" "false" "false" "主控开关" "1.001" "switch" "1/1/2" "会议室-调光值" "false" "false" "0-100%" "5.001" "percentage" "2/1/1" "办公室-窗帘" "false" "false" "电动窗帘" "1.001" "switch" "3/2/1" "走廊-当前温度" "false" "false" "回风温度" "9.001" "temperature (°C)" # 字段之间是 Tab（制表符）分隔，不是逗号；首行为表头
用 Excel / WPS 打开（选择「分隔符号 → Tab」），或用支持 UTF-16LE 的编辑器（如 VSCode 选择「UTF-16 LE」编码）打开。普通记事本打开若显示乱码，多半是编码识别问题，不影响平台导入。
CSV 每一列对应组地址的一项属性。下表列出对接平台最关心的核心字段，以及它们如何决定平台点位的建立：
| CSV 字段 | 含义 | 示例 | 平台用途 |
|---|---|---|---|
Group address | 组地址 x/y/z | 1/1/1 | → 平台点位的 groupAddress（核心寻址） |
Name | 组地址名称 | 会议室-灯光开关 | → 点位名称 / 通道名称 |
DatapointType | 数据点类型 DPT 编号 | 1.001 | → 点位的 dataType，决定报文解析方式 |
DatapointTypeDescription | DPT 文字描述 | switch | 辅助识别，便于核对 |
Description | 组地址备注 | 主控开关 | 说明性信息，不影响建点 |
Central / Unfiltered | 标志位 | false | ETS 内部属性，平台一般忽略 |
平台解析报文完全依赖 DatapointType。若该列缺失或为空，平台无法确定值类型，点位即使建出来也会解析失败。导出前务必确保每个组地址都已设置 DPT（在 ETS 组地址属性里选择）。
了解映射关系，有助于排查导入后点位行为不符预期的问题。下表把 ETS CSV 字段与 EasyPro KNX 驱动点位属性逐一对应（详见 KNX 驱动 · 点位属性）：
| ETS CSV 字段 | 平台点位属性 | 说明 |
|---|---|---|
Group address | groupAddress | 组地址直接写入，报文订阅/下发都靠它 |
Name | channelName | 作为通道名导入 |
DatapointType | dataType | DPT 编号，如 1.001 |
| 由 DPT 派生 | sysType | bool/int/float/text，由 DPT 的 sysType 自动决定 |
| 导入时自动生成 | channelType | 形如 CR----，字母决定读写 R/W 权限 |
| 导入时自动生成 | symbol | r只读 / w只写 / rw读写 |
| 设备物理地址（另由拓扑导出或手填） | physicalAddress | 设备级寻址 x.y.z，组地址 CSV 中通常不含 |
组地址 CSV 描述的是功能逻辑，不携带设备物理地址。平台点位的 physicalAddress 需通过其他方式补充（手填或从拓扑/设备列表导入）。这不影响组地址报文的订阅与解析，只影响设备级诊断。
| 项 | ETS 导出默认 | 能否改动 |
|---|---|---|
| 字符编码 | UTF-16LE（带 BOM） | 勿改。改 UTF-8 会导致中文乱码、平台解析失败 |
| 字段分隔符 | Tab 制表符 | 勿改为逗号。逗号分隔的 CSV 平台无法识别 |
| 文本限定符 | 双引号 " | 字段含特殊字符时自动加，保持默认即可 |
| 换行符 | CRLF（Windows） | 默认即可 |
① 用 Excel 打开后直接另存为 CSV——Excel 会把它转成 UTF-8 + 逗号分隔，破坏格式，平台无法识别。如需查看，请用「打开」而非「另存」；如需修改，应在 ETS 内修改后重新导出。② 用 WPS/记事本编辑后保存，可能改变编码。导出后尽量保持原文件不动。
拿到符合要求的 CSV 后，在 EasyPro 平台调用 KNX 驱动的导入接口，即可自动批量建点。整个流程与 KNX 驱动文档的 ETS 导入章节闭环：
导入后的点位属性（组地址、DPT、channelType 等）及 4 个 HTTP API 详解，见 KNX 驱动功能设计 · ETS CSV 导入 与 Web 接口。导入报错的排查见下方 FAQ Q4。
.knxprod 推荐，.vd4 在 ETS6 可能不支持）；② 检查数据库文件是否完整（未损坏）；③ 从设备厂商官网重新下载最新版数据库；④ ETS6 会校验数据库签名，未签名或被篡改的库会被拒。x/y/z 格式；④ DatapointType 列不能为空，否则无法确定值类型；⑤ 部分 DPT 若不在平台 DPT 注册表中会解析失败，先用 saveOrUpdateKnxPointTypeApi 补充；⑥ 详见 KNX 驱动 FAQ。.knxproj）跨平台兼容，Mac 和 Windows 之间可互相打开编辑。注意：移动工程时建议同时打包引用的产品数据库，避免目标机器未导入对应库导致设备信息丢失。