KNX-Bus-Dump is a popular building automation protocol and is used to interconnect sensors, actuators and other components of a smart building together. Our KNX Bus Dump tool uses the Calimero java library, which we contributed to for the sake of this tool, to record the telegrams sent over a KNX bus. Particularly, our tool accesses the KNX bus through a TPUART connection but can be changed to use different connection mediums. The telegrams are dumped into a Wireshark-compatible hex dump file. Timestamps are provided and normalized to UTC time with nanosecond precision to perform data analysis and provide a timeline of the telegrams. The hex dump file can be imported into Wireshark, which can be configured to dissect the KNX telegrams with Wireshark’s cEMI dissector.
Our tool can be used for protocol analysis of KNX sensors, actuators and other KNX devices. For example, we used the tool to understand our KNX devices and found irregular KNX telegrams. The tool is also ideal for security analysis of KNX devices given that it exposes all details of the involved protocol and data sent over the KNX bus.
Tcpdump and Wireshark cannot be used to dump telegrams sent over a KNX bus since we are dealing with native KNX telegrams, not TCP/IP packets. Wireshark and tcpdump can dump KNXnet/IP packets, which are TCP/IP packets. KNXnet/IP is a protocol for sending commands and data to a KNX bus over a TCP/IP network.
This tool is designed to work with the Calimero Java library and is compatible with a Raspberry Pi 3 or 4 and a Raspberry Pi HAT for the TPUART connection.
Here are some guides to getting the environment setup:
- KNX Raspberry PiHAT Usage Walkthrough
- Raspberry Pi and Calimero Suite Setup
Note: The next steps will assume that you setup your environment according to these guides.
- Place the KNXBusDump.java file into the introduction/src/main/java/ folder of the Calimero Project suite.
- Change into the introduction folder.
- To run the program, you can simply run:
./gradlew run -Pcalimero.serial.tpuart.maxInterByteDelay=60000 -DmainClass=KNXBusDump
- Now, you wait for some messages to be transmitted on the bus and the dumped telegrams will be in the KNXBusDump-Telegrams.txt file.
- Cancel the tool using Ctrl-C and the file is now ready to be imported into Wireshark to be analyzed.
In Wireshark, you have the ability to import packets from a hex dump and specify a dissector to analyze the packet.
- Upon starting Wireshark, wait for the initial loading to finish. Then click File -> Import From Hex Dump…
- In order to properly parse this out, we need to give it a regular expression (regex) with some tags.
- Choose the hex dump file as the source.
- Under the new dialog, change to the Regular Expression tab and paste the regex into the box.
- Ensure that the data encoding is Plain hex 200*16
- In the Timestamp format textbox, we need to specify the pattern that is generated by the tool.
- Under the Encapsulation section, change Encapsulation Type to Wireshark Upper PDU Export.
- Check ExportPDU to specify the cemi dissector.
- Now you’re able to import the file and analyze the telegram.
Corresponding Hex Dump File
- The cemi dissector starts at the message code (MC) portion of the telegram. It does not take into consideration the medium type.
- The reason why the TPCI is highlighted in red is because of a design choice. The dissector will see that the packet is an Unnumbered Data Packet (UDP) which means that the sequence number, according to the KNX standard, is usually set to 0. However, sometimes some devices will set this to a non-zero value. In this case, it was set to 1. The dissector will then check if the sequence number is zero. In this case it is not, thus the error message for the sequence number expecting to be 0.