The bus records itself while you are away.
The KNX box is a Raspberry Pi that writes down every telegram around the clock and opens its own Wi-Fi. You set it up with the app: scan the QR code, done. No Home Assistant, no internet, no browser.
Prepare it once, then just scan.
Image and label are made once at your desk. On site it then takes a cable, power and the app.
- Prepare
- Write the image to an SD card (Raspberry Pi Imager, “Use custom”) and start the box once. It puts its QR code on the SD card as
knx-box-app.png: print it and stick it on the box. - Connect
- Network cable to the switch at the gateway, then power. After about a minute the box is ready.
- Scan
- In the app, “Add KNX box” and scan the label. The app joins the box’s Wi-Fi, pairs, sets the clock and looks for the gateway. If there is exactly one, it is set right away and the box records.
- Without app
- It works without the app too: the second QR code (
knx-box-wlan.png) joins the box’s Wi-Fi, then openknx-box.localin a browser with the box password.
What the app puts on the box for you.
Everything the box needs to know comes from the app. There is nothing to copy.
- Gateway
- The box finds it on its cable; if there are several, you pick one in the app.
- ETS project
- Import it in the app and it goes onto the box too. Then the box knows names, datapoint types and the time master.
- Keyring
- For KNX Secure the same: the box records secured telegrams readably.
- History
- The app shows it straight from the box, day by day, with replay and export.
- Storage
- On a USB SSD named
KNXBOXDATA, otherwise on the SD card. At five telegrams a second about 43 MB a day, raw.
Starts by itself, never stops.
As soon as a gateway is set, the box records. There is nothing to start and nothing to forget.
- Always on
- One tunnel stays open, every telegram goes into a daily file, even with no device connected.
- Clock
- Without internet: the box sets its clock from the iPhone or iPad that connects, or from the KNX time master on the line (DPT 19.001, 10.001 + 11.001).
- Until then
- The box already records and puts the time right afterwards. Or it waits, if you switch on “Record only once the time is right”.
- Power cut
- After the restart the box reconnects and carries on; at most the last seconds are lost.
- Retention
- Seven days by default, up to ten years.
- Pause
- Frees the tunnel, for example when ETS needs the gateway’s only slot.
IP today, straight on the bus tomorrow.
Today the box sits on a network cable to the KNX IP interface or IP router. In future it is meant to sit right on the line too: with a bus terminal, no IP gateway at all.
- IP (today)
- KNXnet/IP tunnelling or routing, KNX IP Secure included. The box takes one tunnel slot on the gateway.
- TP (planned)
- A bus terminal on the line and a TP-UART module over USB (such as busware TUL). No gateway needed, no tunnel slot taken.
- Bus monitor
- Over TP the box also sees what a tunnel never shows: acknowledgements (ACK, NAK, BUSY) and repeats.
- Address
- To listen, the box needs no individual address and no ETS programming.
- Status
- In progress, see the issue on GitHub.
What goes into the case.
- Computer
- Raspberry Pi 5 with 2 or 4 GB; a Pi 4 works too
- Clock
- Recommended: the RTC battery for the Pi 5 or a DS3231 module for the Pi 4. Then the time is right even before the first iPhone.
- Power
- 27 W power supply (USB-C); weaker ones crash under load
- Storage
- USB SSD or NVMe, 128 GB last for years
- The rest
- A case with a fan, a network cable, a label for the QR code; in future a bus terminal with a TP-UART module
A preview, to be honest.
The image is built automatically and runs in the test setup. Nobody has tried it on real hardware on a real site yet. Reports are very welcome.
- App
- You set up the box with the app, which arrives in the coming weeks. Until then it works without the app in the browser (see Setup).
- Gateway
- A gateway with a fixed address straight on the box’s cable does not work yet; that needs the switch.
- Wi-Fi
- The app joins by itself on iPhone, iPad and Android 10 or later; otherwise once in Settings.
- Alarms
- Without internet there are no notifications to your phone.
- Feedback
- Bugs and experiences are welcome as an issue on GitHub.
Common questions about the box
Do I need a PC?
Only once at your desk: to write the image and print the QR code. On site the app is enough.
Do I need Home Assistant?
No. The box runs the same software as the Home Assistant add-on, just as a device of its own. If you have Home Assistant, the add-on is the better choice.
Does the box take up a tunnel on the gateway?
Over IP yes, exactly one, around the clock. Every iPhone and iPad in the box’s Wi-Fi shares that tunnel. If ETS needs the only free slot, pause the box. With the bus terminal (planned) this goes away.
Do devices in the box's Wi-Fi reach the customer's network?
No. The firewall keeps the box’s Wi-Fi apart from the network on the cable. Only INTERNET_SHARING=yes in knx-box.txt lets devices in the Wi-Fi out.
What if someone walks off with the box?
Whoever has the label can pair. Change the box password in the app under Box settings; after that the label no longer pairs new devices. That is also where you revoke devices you no longer need.
May I record the bus in a lived-in house?
A bus recording shows when someone is home. Agree on it with the residents and keep the retention as short as you can.