48 极物科技 | knxd - knxtool命令行调试工具全解

极物科技 | knxd - knxtool命令行调试工具全解

前言

KNX 作为国际标准（ISO/IEC 14543-3）拥有完全开放的协议规范与蓬勃的开源生态，knxd 正是这一开放性的最好注脚------一台普通 Linux 设备即可变身 KNX 路由器。

极物科技的产品同样构建在开放标准之上：自研 KNX 主机的极物 OS 原生支持 KNXnet/IP 路由与隧道双通道，与 knxd、ETS 等主流工具链无缝互通；配套鸿蒙、苹果、安卓三端原生 APP，深度接入 Apple HomeKit 与小度生态，支持主机远程调试------工程调试不受任何私有协议锁定。

一句话概述：本文回答"不用ETS、不写代码，如何用几条命令直接驱动KNX总线"，把knxtool这个口袋调试台讲透。

本文聚焦于 knxtool 命令行调试工具，涵盖写入/读取/监听/总线监控四大类命令、组地址十六进制换算、脚本化批量测试与典型调试案例。

1. knxtool 是什么

knxtool 是 knxd 自带的命令行工具集（安装 knxd-tools 包即得），每条命令对应一类总线操作：

bash 复制代码

knxtool <子命令> <接口URL> [参数]

接口URL的写法：

写法	含义
`local:`	本机Unix Socket（最常用）
`ip:127.0.0.1`	本机/远端knxd（组播方式）
`tunnel:192.168.1.20`	隧道方式连远端网关

💡 一次性建议：调试期全程 local:，避免占用网关隧道通道。

2. 写入类命令

2.1 groupswrite------写1bit（开关量）

bash 复制代码

# 打开 1/1/1（bit=1）
knxtool groupswrite local: 1/1/1 1

# 关闭 1/1/1（bit=0）
knxtool groupswrite local: 1/1/1 0

适用：继电器开关、模式切换、场景号触发（配合场景激活值）。

2.2 groupwrite------写多字节

bash 复制代码

# 写1字节：调光 1/2/5 亮度50%（0x32）
knxtool groupwrite local: 1/2/5 32

# 写2字节：温度设定 1/3/7 为 21.5℃（DPT 9.001，需按浮点编码换算）
knxtool groupwrite local: 1/3/7 0x0AB6

注意：参数是十六进制原始数据 ，不是十进制工程值------50%要写 32（hex），而不是50（dec）。DPT 9.x的温度等浮点值还需按KNX编码规则换算（详见《KNX协议 - APCI指令与数据点类型DPT详解》）。

2.3 groupwrite的编码速查

DPT	工程值 → 报文值（hex）
1.001 开关	1/0
5.001 亮度0-100%	工程值×255/100，四舍五入
5.003 角度0-360°	工程值×255/360
9.001 温度	(值+273)×0.01 → 2字节移码（0x0Axx区段）

3. 读取类命令

3.1 groupread------发起读请求

bash 复制代码

knxtool groupread local: 1/1/101

向组地址发送GroupValueRead，总线上支持该地址的设备会以GroupValueResponse应答。注意：命令本身不显示应答，应答需要配合监听命令观察（见4.1）。

3.2 groupcache......为什么没有应答显示

读请求发出后，应答帧是异步到达的。标准姿势是两个终端配合：

text 复制代码

终端A：knxtool grouplisten local: 1/1/101     # 持续监听
终端B：knxtool groupread  local: 1/1/101      # 发起读取
终端A打印：Write from 1.1.5 to 1/1/101: 01    # 这就是应答值

4. 监听类命令

4.1 grouplisten------组地址监听

bash 复制代码

# 监听指定组地址
knxtool grouplisten local: 1/1/101

# 监听全部组地址（按组地址过滤的快捷方式）
knxtool groupsocketlisten local:

输出示例：

text 复制代码

Write from 1.1.5 to 1/1/1: 01
Write from 1.1.5 to 1/2/5: 20
Read from 1.1.2 to 1/1/101:
Response from 1.1.5 to 1/1/101: 01

4.2 vbusmonitor1------总线监视

bash 复制代码

knxtool vbusmonitor1 local:

输出的是链路层视角的原始帧（含个体地址源/目的、帧类型、ACK状态），比组地址监听多出以下能力：

看到发送方个体地址（谁在说话）；
看到ACK/NACK（链路层是否成功）；
看到寻址模式（组播/单播/广播）。

适合排查"报文到底有没有上总线"这类底层问题。

5. 脚本化批量测试

knxtool的输出可直接管道处理，天然适合自动化：

5.1 全屋灯循环测试

bash 复制代码

#!/bin/bash
# 逐路点亮再熄灭，验证每一路继电器
for ga in 1/1/1 1/1/2 1/1/3 1/1/4 1/1/5; do
    knxtool groupswrite local: $ga 1
    sleep 2
    knxtool groupswrite local: $ga 0
    sleep 1
done

5.2 总线流量录制

bash 复制代码

# 录制10分钟总线流量做离线分析
timeout 600 knxtool groupsocketlisten local: > buslog-$(date +%H%M).txt

5.3 压力测试

bash 复制代码

# 高频读写混合压测，观察丢帧
for i in $(seq 1 200); do
    knxtool groupswrite local: 1/1/1 $((i % 2)) &
done
wait

6. 典型调试案例

案例：某调光灯不受控

bash 复制代码

# 第1步：确认写入帧到达总线
knxtool grouplisten local: 1/2/5 &
knxtool groupwrite local: 1/2/5 80    # 写50%
# → 监听显示 Write to 1/2/5: 80，帧已上总线 ✔

# 第2步：发起状态读取
knxtool groupread local: 1/2/105
# → 无Response，说明执行器侧未配置状态对象或地址错误 ✘

# 第3步：换个体地址视角定位设备
knxtool vbusmonitor1 local:
# → 发现写入帧被某个体地址NACK，锁定为该执行器链路层拒绝

三步把问题从"灯不亮"收敛到"执行器配置错误"。

7. 注意事项

十六进制陷阱：groupwrite参数是hex，写"50"实际是0x50=80%；
grouplisten与groupsocketlisten区别：前者只能看单地址，后者全总线，长时间挂机用后者+grep过滤；
别在生产高峰跑压测：总线重发风暴会拖慢全楼设备；
写场景号记得对齐：用knxtool触发主机场景时，写入值=场景激活值-1（见《KNX场景 - 主机场景与APP免编程调试》）；
隧道通道占用：用tunnel:接口的每个knxtool进程占用一个网关通道，用完即退，勿常驻。

8. 相关文档

《极物科技 | knxd - 部署与配置完全指南》
《极物科技 | knxd - TCP与Unix Socket接口对接》
《极物科技 | knxd - Wireshark抓包与总线监控》
《极物科技 | KNX协议 - APCI指令与数据点类型DPT详解》
《极物科技 | KNX报文追踪 - 总线监控与问题定位》

关于极物科技（ZEEWO）

极物科技（Zeewo）致力于为用户提供智能控制系统及硬件产品。我们以总线系统为技术底座，以**"稳定、可靠、快速响应"**为产品底线，是国内少有的拥有 KNX、DALI 全套软硬件自主研发能力的厂商之一。

我们的核心能力：

系统架构：自研极物 OS，支持多协议无界融合（KNX/DALI/CAN/RS485/IP）。
核心硬件：带双路 DALI 的 KNX 主机、超薄全金属定制面板、各类智选传感器及网关。
生态互联：深度融入 Apple HomeKit、Matter、小度、HomeAssistant 及纯血鸿蒙生态。
调试交付：独家支持 ETS 导出 XML 直接导入进行 APP 免编程调试，支持远程 WEB 运维。

我们的市场覆盖：

服务网点已覆盖全国核心城市（含长三角、珠三角、成渝等），并以高品质的方案深耕家居生活、酒店民宿、企业办公、疗愈康养、餐馆会所等多个细分领域。

(如果您在开发或落地中遇到技术问题，欢迎通过官网或后台私信与我交流探讨)