龙小智 KNX —「网关点位」操作说明
龙小智 KNX 桌面端（Tauri）/ 局域网 Web 的「网关点位」模块操作说明，含网关管理、点位管理、历史查询三个二级页面的完整操作流程与常见问题。
一、推荐操作顺序（首次使用）
- 网关管理：新建 KNX 网关 → 填写 IP 或选「路由」→ 连接
- 点位管理：新建点位或 KNX 导入（ESF/XML） → 配置 DPT、只读/可写、历史存储
- 历史查询：确认点位已开启历史 → 选网关与时间 → 查询 / 导出 CSV
KNX 总线未连接时，点位页的 下发、总线读 会被禁用；请先在网关页完成连接。
二、网关管理
作用：管理现场设备连接（KNX、Modbus、串口 HEX、LXZ 内部虚拟点），并控制 KNX 单隧道 的连/断。
2.1 页面结构
- 顶部按钮（桌面端）：
+ KNX 网关/+ 串口 HEX/+ Modbus TCP/+ Modbus RTU/+ LXZ 内部 - 搜索与筛选：按名称、地址搜索；可按 IP / 路由筛选 KNX
- 当前总线：显示所选网关连接态；连接（所选网关） / 断开
- 网关列表：点选一行（单选）后操作
2.2 支持的网关类型
| 类型 | 用途 | 连接说明 |
|---|---|---|
| KNX（IP / 路由） | KNX 组地址读写 | IP 模式填网关 IP、端口（默认 3671）；路由模式走组播，无需填 IP。全局仅一条 KNX 隧道，连新 KNX 会自动断开旧 KNX |
| 串口 HEX | 第三方 UDP→串口场景 | 选 COM 口、波特率；点位侧配置 HEX 帧，写 1 触发 |
| Modbus TCP/RTU | 寄存器轮询 | 填 IP/COM、从站号、轮询间隔；点位用 tags JSON 配寄存器 |
| LXZ 内部 | 虚拟逻辑点 | 无需连接；供联动、脚本、HMI 读写 bool/number/string |
Modbus 可与 KNX 同时在线，互不影响。
2.3 常用操作
新建 KNX 网关（桌面端）
- 点击 + KNX 网关
- 填写 名称（必填）、连接类型（IP 或 路由）
- IP 模式：填写 IP、端口
- 可选：描述、超时、重试等高级项
- 保存
连接 / 断开
- 在列表中 点选一行 → 上方 连接（所选网关）
- 或行内快捷 连接 按钮
- 断开：断开当前 KNX 隧道（Modbus 轮询另有暂停逻辑）
连接成功后，点位管理页总线条应显示 已连接。
编辑 / 删除
- 编辑：行内「编辑」（桌面端）
- 删除：仅当该网关下 无点位 时可删；否则需先在「点位管理」移除或迁移点位
浏览器模式限制
- 可 连接 KNX、查看列表
- 新建 / 编辑 / 删除 网关请在 桌面端 操作
2.4 状态说明
- 连接状态：已连接 / 未连接 / 连接中 等（catalog 模式以 core 上报为准）
- 子点位通讯更新：该网关下只读点位最近一次总线采样时间（北京）
- 现场网关连断后，LXZ 内部会同步
{网关名}_status镜像点（0/1）
三、点位管理
作用：维护组地址（及 Modbus/串口/LXZ 点），查看缓存值，对 KNX 点位 总线读 / 下发，配置 历史存储 策略。
3.1 页面结构
- 总线状态条：当前 KNX 是否已连接（未连接时下发/总线读禁用）
- 筛选网关：下拉只看某一网关下点位
- 点位表：组地址、名称、DPT、网关、读值与历史策略、只读、最新值、总线时间、操作
- + 新建点位、KNX 导入（ESF/XML）
- 表底 翻页（20 / 50 / 100）；组地址 升序/降序
3.2 新建点位
- 点击 + 新建点位
- 必填：网关、组地址（同网关下不可重复）
- 选 DPT（与现场组地址数据类型一致）
- 填写 名称（可选，便于历史/HMI 识别）
- 只读：勾选则禁止下发，仅监测/读取
- 读值与历史（存储策略，三选一）：
- 关：不自动读、不记历史
- 定时 N 分钟/小时：按间隔读总线并 记历史
- 仅变化记历史：值变化时写入历史（可配合只读监测）
- 保存
修改存储策略后需 保存 才会生效；历史查询前请确认已选「记历史」类策略。
3.3 KNX 批量导入（ESF / XML）
- 点击 KNX 导入（ESF/XML）
- 先选 目标网关（仅 KNX 现场网关，不含 Modbus/串口/LXZ）
- 选择 ESF/XML 文件（ETS 导出等）
- 查看解析摘要 → 确认导入
- 冲突组地址可勾选 覆盖 后再次确认
导入后可在表中逐条补 DPT、历史策略、只读属性。
3.4 表格操作
| 操作 | 说明 |
|---|---|
| 总线读 | 从 KNX 总线读当前值（需总线已连接）；与打开页面无关，不会全表自动读 |
| 下发 | 可写点位：弹窗按 DPT 写值（开关/数值/场景等） |
| 编辑 | 修改名称、DPT、网关、只读、存储策略 |
| 删除 | 删除该点位 |
最新值 / 总线时间：来自数据库缓存与监测；只读点由后台持续写库，进入本页 不会 触发全表总线读。
3.5 批量与快捷键
- Ctrl/Cmd + 点击：多选
- Shift + 点击：按当前排序连续选
- Esc：清除选择
- 选中后：批量修改只读、批量删除
- 右键行：快捷批量菜单
3.6 各类型点位差异
- KNX：组地址 + DPT；依赖网关 KNX 连接
- Modbus：
tags内 JSON 配置寄存器；后台轮询更新值 - 串口 HEX：配置下发帧；写
1即发帧 - LXZ 内部：bool/number/string；无总线，供逻辑/HMI
3.7 常见问题
| 现象 | 处理 |
|---|---|
| 下发/总线读灰色 | 到 网关管理 连接 KNX |
| 同组地址无法保存 | 换组地址或换网关 |
| 历史查不到 | 编辑点位 → 开启「定时记历史」或「变化记历史」→ 保存 → 等待采样 |
| ESF 无法选某网关 | 该网关非 KNX 类型，请选 KNX 现场网关 |
四、历史查询
作用：查看已开启 历史存储 的点位在一段时间内的采样记录。
4.1 前提
- 点位在「点位管理」中配置了 记历史（定时读并记历史 / 仅变化记历史）
- 采样已发生（变化存储需值变化；定时存储需到达间隔且有点位值）
4.2 查询条件
| 条件 | 说明 |
|---|---|
| 网关 | 选择目标网关；default 表示未绑定网关的点位 |
| 点位 | 可选「全部点位」或指定一条 |
| 快捷时间 | 最近 1 小时 / 1 天 / 3 天 / 7 天 |
| 自定义起止 | 勾选「使用起止时间查询」，填 北京时间 起止（可先用「自定义 1h」填充） |
点击 查询。单次最多返回 5000 条，按时间 新→旧。
4.3 结果表格
| 列 | 含义 |
|---|---|
| 采集时间(北京) | 写入历史库的时刻 |
| 网关 | 当前 网关名称（改名后会显示新名） |
| 点位 | 点位名称 |
| 组地址 / DPT | 便于核对现场 |
| 值 | 当时采样值文本 |
4.4 导出
- 导出 CSV：含时间、网关名、点位名、组地址、DPT、值、id（UTF-8 BOM，Excel 可直接打开）
- 重置：恢复默认网关与「最近 1 天」
4.5 常见问题
| 现象 | 处理 |
|---|---|
| 暂无数据 | 确认存储策略、时间范围、点位是否属于所选网关 |
| 时间对不上 | 本页与表格均为 北京时间；自定义范围请勾选「使用起止时间」 |
| 网关名仍是旧的 | 刷新查询；历史行展示的是查询时 当前 网关名 |
五、三个页面协作示例
场景：新接入一条 KNX 线路，要做照明反馈与历史曲线
- 网关管理：新建「展厅 KNX」→ IP
192.168.1.20→ 连接 - 点位管理：ESF 导入组地址 → 反馈点设 只读 + 仅变化记历史 → 控制点 可写
- 运行一段时间或手动 总线读 触发变化
- 历史查询：网关选「展厅 KNX」→ 点位选某反馈点 → 最近 1 天 → 查询 → 导出 CSV
六、权限与角色
管理员在 用户 / 权限 中为角色勾选：
gw_gateways— 网关管理gw_points— 点位管理（含下发，视只读设置）gw_history— 历史查询（只读）
仅 查看 权限的用户无法新建/编辑/删除/下发（以实际角色配置为准）。
七、相关文档
- 组态视图（HMI）：
.cursor/skills/lxz-knx-hmi-views/SKILL.md - 多协议网关细节：
.cursor/skills/lxz-knx-multi-protocol-gateways/SKILL.md - 局域网 Web 访问：
.cursor/skills/lxz-knx-lan-web-access/SKILL.md
文档版本与软件基线：0.1.0（随安装包 龙小智 KNX_0.1.0_x64-setup.exe 对齐）。