A KNX installation is only as reliable as the documentation behind it. When a system works flawlessly on day one, it is easy to overlook the paperwork, but the moment a client calls with a fault, an upgrade request, or a handover to a new installer, that documentation becomes the most valuable asset in the project. A complete KNX as-built documentation package protects everyone involved: the installer, the building owner, and any future integrator who picks up the project years down the line.
Getting this right is not just about compliance or professionalism. It is about making sure that every group address, every device parameter, and every network setting can be understood and reproduced without needing to reverse-engineer a live system. The following sections break down exactly what a solid KNX documentation package should contain and how to keep it useful long after the installation is complete.
Core documents every KNX package must include
A complete KNX installation documentation package starts with a well-organised set of core files that cover the project from every angle. At minimum, this means the ETS project file, a topology overview, a device list with physical addresses, and the group address export. Together, these give any qualified installer enough information to understand the system without needing the original integrator present.
Beyond the ETS file itself, it is worth including a human-readable summary of the installation. Not every stakeholder, including facility managers or building owners, will open ETS, so a clearly formatted PDF or spreadsheet that lists devices, their locations, and their functions adds real practical value. Think of it as the translation layer between the technical project and the people who live or work in the building.
How to structure your group address list for clarity
The group address list is often the first place a new installer looks when troubleshooting, so its structure can make or break the usability of the entire documentation. A logical naming convention, typically organised by building area, function type, and data point, makes it far easier to locate a specific address under pressure.
A three-level structure works well for most projects: the first level covers the functional area (lighting, HVAC, shading), the second level identifies the room or zone, and the third level specifies the exact data point (switch, dimming value, feedback). Whatever convention is chosen, it should be applied consistently across the entire KNX project documentation and never changed mid-project without updating all references. A brief legend at the top of the document explaining the naming logic saves considerable time for anyone working with the file later.
Network and IP layer documentation for KNX systems
Modern KNX systems rarely exist in isolation. With KNX IP routers, interfaces, and controllers connecting the bus to the local network, the IP layer is now an essential part of any KNX system integrator‘s documentation responsibility. This means recording static IP addresses, subnet masks, VLAN assignments, and any routing configurations relevant to KNX traffic.
It is also important to document which devices act as IP backbone line couplers and how the KNX topology maps onto the network infrastructure. If the installation includes a controller, such as the xxter controller, its IP address, connection settings, and any integrations with third-party protocols like Modbus or BACnet should be captured here as well. Without this layer, a network change by an IT team can silently break KNX functionality in ways that are difficult to diagnose. You can manage your xxter controller settings online to keep configuration records current and accessible.
Handover checklist: what installers often forget
Even experienced installers can leave gaps in a handover package. The technical files are usually present, but several supporting items tend to get overlooked in the final rush to complete a project.
- Login credentials for all KNX IP devices, routers, and controllers (stored securely, not in plain text)
- Firmware versions of all programmable devices at the time of handover
- A record of any scene configurations, timer programs, or logic functions programmed outside ETS
- Contact details for the installing company and any subcontractors involved in specialist systems
Handing over a system without this information leaves the building owner dependent on the original installer for even minor changes. A thorough checklist completed before sign-off is the simplest way to avoid that situation and to demonstrate a professional standard of service. If you need support during a handover, you can contact the xxter team directly for guidance.
Keeping documentation accurate after system changes
Documentation that was accurate at handover can quickly become misleading after modifications. Every time a group address is added, a device is replaced, or a new function is programmed, the as-built package needs to be updated to reflect the current state of the system. This is one of the most commonly neglected aspects of long-term KNX project management.
A practical approach is to treat documentation updates as part of every service visit, no matter how small the change. Keeping a change log within the documentation folder, noting the date, the nature of the change, and who made it, creates a useful audit trail. For larger installations, version-controlled storage (a shared folder with dated archives) ensures that previous states can be recovered if a change causes unexpected behaviour. The goal is always to ensure that the documentation reflects the live system, not the system as it was originally installed.
How xxter supports KNX professionals with documentation and integration
For KNX system integrators, managing documentation is just one part of delivering a complete installation. xxter makes the broader job easier by providing a controller platform that centralises KNX control, IP integration, and third-party protocol support in a single, well-documented device.
- The xxter controller KNX and protocol support includes Modbus, BACnet, Art-Net DMX, and Philips Hue, reducing the number of separate systems that need individual documentation
- The free xxter app works across iOS, Android, Windows, and Apple Watch with no subscription fees or licence costs
- The Pairot bridge for Apple HomeKit integration adds Amazon Alexa and Google Assistant compatibility to any KNX installation without additional programming complexity
- xxter’s Smart Energy Manager integrates directly into the KNX ecosystem, giving installers a documented, controllable energy management layer alongside the rest of the building automation
If you are looking to streamline your KNX installations and deliver projects that are easier to document, hand over, and maintain, explore what xxter has to offer at xxter.com.
Ofte stillede spørgsmål
What file formats should I use when saving and sharing KNX as-built documentation?
For long-term accessibility, it is best to export and store documentation in both its native format and a universally readable alternative. Keep the ETS project file (.knxproj) as the primary technical record, but always accompany it with PDF exports of your group address list, topology diagram, and device summary so that non-ETS users can access the information without specialist software. For spreadsheets and change logs, open formats like .xlsx or .csv ensure compatibility across different tools and organisations over time.
How should I securely store and hand over login credentials for KNX IP devices and controllers?
Plain-text credentials in a documentation folder are a security risk, especially for commercial buildings with multiple stakeholders. A better approach is to use a dedicated password manager (such as Bitwarden or 1Password for Teams) and share access securely with the building owner or facility manager at handover. If a physical record is required, store it in a sealed envelope in a secure location on-site and note its location within the documentation package rather than embedding the credentials directly in shared files.
What is the best way to handle documentation when taking over a KNX project from another installer with incomplete records?
Start by performing a full ETS scan of the installation to recover physical addresses and group address assignments from the live bus, which can reveal much of what was originally programmed. Cross-reference this with any partial documentation available and physically inspect each device to confirm its location, type, and firmware version. Once you have rebuilt a working picture of the system, treat it as a new as-built document from that point forward, noting in the change log that it was reconstructed from a live scan rather than inherited from original records.
How granular should my topology diagram be, and what should it always include at a minimum?
At a minimum, your topology diagram should show every KNX line, all line and area couplers, the IP backbone, and the physical location or panel reference for each segment. For larger installations, it is worth going one level deeper and indicating the approximate number of devices per line and any lines that are close to their device limit, as this becomes critical information during future expansions. Including the diagram as both a vector-editable file (such as .vsdx or a CAD format) and a PDF export ensures it can be updated without starting from scratch.
Is there a recommended way to document KNX logic functions and scenes that are programmed outside of ETS?
Yes, and this is one of the most commonly overlooked gaps in handover packages. For any logic, scenes, or timer programs configured in a controller or visualisation platform outside ETS, create a dedicated document that describes each function in plain language: what triggers it, what it controls, and any conditions or exceptions that apply. A simple table format works well, with columns for function name, trigger, affected group addresses, and any relevant notes. This makes it possible for a future installer to replicate or modify the behaviour without needing access to the original configuration interface.
How often should KNX documentation be reviewed and updated in an active building?
Documentation should be updated immediately after every change, no matter how minor, rather than batched into periodic reviews. In practice, treating the documentation update as the final step of every service visit, before leaving the site, is the most reliable habit to build. For buildings that undergo frequent changes, scheduling a quarterly documentation audit to verify that the files match the live system can catch any gaps that slipped through during busy periods.
Can good documentation actually reduce the time spent on future service calls?
Absolutely, and this is one of the strongest practical arguments for investing time in thorough documentation upfront. A well-structured group address list and accurate topology diagram can reduce fault diagnosis time from hours to minutes by allowing an installer to identify the affected line, device, and data point without interrogating the live system from scratch. Over the lifetime of a building automation system, the cumulative time saved across multiple service visits far outweighs the effort spent creating and maintaining accurate records.