xknxproject 1.1.0

A library to gather information from ETS project files used for KNX

(X)KNX Project

Extracts KNX projects and asynchronously parses the underlying XML.

This project aims to provide a library that can be used to extract and parse KNX project files and read out useful information including the group addresses, devices and their descriptions and possibly more.

Documentation

Currently, xknxproject supports extracting (password protected) ETS5 and ETS6 files and can obtain the following information from your project:

• Areas, Lines, Devices and their individual address
• CommunicationObjectInstance references for their devices (GA assignments)
• Group Addresses and their DPT type if set
• The application programs communication objects and their respective flags and the DPT Type
• Location information of your devices (in which rooms they are)

Caution: Loading a middle-sized project with this tool takes about 1.5 seconds. For bigger projects this might as well be >3s.

Installation

In order to parse XML and to overcome the performance issues that parsing application programs with over 800k lines of XML has we use lxml. lxml requires libxml2 to be installed in the underlying system. You can read more on their documentation on this topic.

pip install xknxproject

Usage

    import asyncio
    from xknxproject.models import KNXProject
    from xknxproject import KNXProj


    async def main():
        """Extract and parse a KNX project file."""
        knxproj: KNXProj = KNXProj("path/to/your/file.knxproj", "optional_password")
        project: KNXProject = await knxproj.parse()

    asyncio.run_until_complete(main())

The KNXProject is a typed dictionary and can be used just like a dictionary, or, exported as JSON. You can find an example file (exported JSON) in our test suite under https://github.com/XKNX/xknxproject/tree/main/test/resources/stubs

The full type definition can be found here: https://github.com/XKNX/xknxproject/blob/main/xknxproject/models/knxproject.py