xknx / knx-frontend

Home Assistant Panel for managing the KNX integration

XKNX - An asynchronous KNX library written in Python

Documentation

See documentation at: https://xknx.io/

Help

We need your help for testing and improving XKNX. For questions, feature requests, bug reports either open an issue, join the XKNX chat on Discord or write an email.

Development

You will need at least Python 3.10 in order to use XKNX.

Setting up your local environment:

1. Install requirements: pip install -r requirements/testing.txt
2. Install pre-commit hook: pre-commit install

Testing

To run all tests, linters, formatters and type checker call tox

Running only unit tests is possible with pytest Running specific unit tests can be invoked by: pytest -vv test/management_tests/procedures_test.py -k test_nm_individual_address_serial_number_write_fail

Home-Assistant

XKNX is the underlying library for the KNX integration in Home Assistant.

Example

"""Example for switching a light on and off."""
import asyncio

from xknx import XKNX
from xknx.devices import Light


async def main():
    """Connect to KNX/IP bus, switch on light, wait 2 seconds and switch it off again."""
    async with XKNX() as xknx:
        light = Light(
            xknx,
            name='TestLight',
            group_address_switch='1/0/9',
        )
        xknx.devices.async_add(light)

        await light.set_on()
        await asyncio.sleep(2)
        await light.set_off()

asyncio.run(main())

Attributions

Many thanks to Weinzierl Engineering GmbH and MDT technologies GmbH for providing us each an IP Secure Router to support testing and development of xknx.

knx-frontend's Issues

Add some explanation to the panel

It would be helpful if there would be some explanation what this panel does. E.g. I had configured everything manually and I don't have a clue what happens when importing the ETS project file. I don't want to mess up this setup. So some explanation in the panel would be helpful to give users a hint about what it does in detail.

Group Address Overview

Hi,

today I had the challenge that I wanted to change something in HomeAssistant while away from home and I needed the address of a group. It would be so nice if it would be possible to get a List of alle group Adresses, so that I could lookup a new group address without opening my ETS.

"Description" field in entity creation view

It would be nice to be able to show the "Description" field of an KNX device from the ETS in the device listing on the right when creating a new KNX entity in the UI.

Add type checker to CI

... and make it pass 😉

Add support for logging

It would be useful to be able to see long term history in group monitor. There should be a preference for retention period and a cut-off value for realtime browsing, for when your sort the group monitor according to criteria other than time.

In addition to group monitor there could be object view like Schneider Wiser for KNX, where you can browse/filter group addresses and can see the last value seen on bus for that group address and when it was seen.

You're doing magnificent work with the integration.

Readd callbacks when KNX integration reloads

Add GC actions for validation, releasing etc.

Create python package to parse ETS project ZIP file

Add linters etc. for frontend and backend

Root route leads to empty page

/knx/ (without overview or monitor) leads to an empty page.
/knx without trailing slash redirects to overview.

Upload failed

When I upload my KNX project on home assistant I get the following error: Uploaded file is too large.
My file is 3,7 mB and is a lot smaller than some other projects I've worked on.

Create Data Table as Bus Monitor

Needs custom websocket commands
Needs a telegram_received_cb in the custom integration that listens to the telegrams and stores them somewhere

No-op chevrons in tab menu

There are non functional (and not needed) chevrons in the tab menu.

On desktop mode when clicked it disappears, on Safari responsive mode simulating an iphone they just do nothing.

Add websocket commands to custom integration

Overview: Cards scrolling over header and menu

Group Monitor: auto-scroll

It would be nice if the group monitor table would auto-scroll when new rows are added and last scroll position was at bottom of the table.

Group monitor: display time

we currently display time in group moitor in millisecond precision with dates starting with year.
Since the table is cleared on every reload, I guess its fine to only display time without date. Maybe add date if the monitor is active over midnight for the older rows. The column could be narrower then.

Unable to update to version 2024.7.25.204106

my version:
XKNX Version
2.12.2
KNX-Frontend Version
2024.1.20.105944

what I have done:

➜ ~ python3 -m venv /path/to/venv
. /path/to/venv/bin/activate
(venv) ➜ ~ ls
addon_configs addons backup config homeassistant media share ssl
(venv) ➜ ~ sudo pip3 install --upgrade knx-frontend
Requirement already satisfied: knx-frontend in /path/to/venv/lib/python3.12/site-packages (2024.7.25.204106)

[notice] A new release of pip is available: 24.0 -> 24.2
[notice] To update, run: pip install --upgrade pip
(venv) ➜ ~ pip install --upgrade pip
Looking in indexes: https://pypi.org/simple, https://wheels.home-assistant.io/musllinux-index/
Requirement already satisfied: pip in /path/to/venv/lib/python3.12/site-packages (24.0)
Collecting pip
Downloading https://wheels.home-assistant.io/musllinux-index/pip-24.2-py3-none-any.whl (1.8 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.8/1.8 MB 5.5 MB/s eta 0:00:00
Installing collected packages: pip
Attempting uninstall: pip
Found existing installation: pip 24.0
Uninstalling pip-24.0:
Successfully uninstalled pip-24.0
Successfully installed pip-24.2
(venv) ➜ ~ sudo pip3 install --upgrade knx-frontend
Requirement already satisfied: knx-frontend in /path/to/venv/lib/python3.12/site-packages (2024.7.25.204106)
(venv) ➜ ~ deactivate

seems ok but version in my KNX-frontend page is still the old one.

what is wrong?

Find proper way to store panel module properties

is_dev_build function is error prone since we use it as not is_dev_build() - which is still False if one forgets the parentheses - like it happend to me with the last dependency update
https://github.com/home-assistant/core/blob/9e666ae0c0c93137586103c1be71a327786a34a9/homeassistant/components/knx/websocket.py#L37
It is not a problem when not running a dev build, so I guess we can just leave it for now, but we should fix it with the next dependency bump or find a better way to deal with these functions. Maybe have a Panel class in __init__.py that holds some attributes used in HA so a single import is enough.

Create entity without writing yaml..

it is possible?

Panel sometimes not loading

After update to current dev (2023.4.0b4) the panel sometimes just doesn't load in Safari. Chrome seems fine.
It loads after some page reloads 🤷

[Error] Unhandled Promise Rejection: Error: The following properties on element knx-frontend will not trigger updates as expected because they are set using class fields: hass. Native class fields and some compiled output will overwrite ...
	performUpdate (reactive-element.js:774)
	(anonyme Funktion) (reactive-element.js:705)
	asyncFunctionResume
	(anonyme Funktion)
	promiseReactionJobWithoutPromise
	promiseReactionJob

maybe related: nielsfaber/alarmo@0919965

Project file upload: File too large

Trying to upload my project file gives the following error:

Uploaded file is too large

My project file is 46MB in size. I'm using HAOS 10.2 on a KVM VM and HA 2023.6.1 and there is enough free space.

Group Monitor show log but i can't see entity

24 light, 9 cover, 20 sensor, group monitor on knx see all but i can't manage the entiry in HA.

KNX page on HA:

group monitor:

I've Add the KNX Integration, configurated it on automatic simply sending the ip address of my knx device. I've also GoogleHome that work with light and cover, so I think that KNX configuration allow to view the entity, but i can't see except in the group monitor.

Install instructions

Hello. I'm a huge fan of XKNX and I'd love to run the HA Frontend as well.

I'm not a HA expert, but I'm struggling to get up and running.

I've installed knx-frontend via HACS and I added...

knx-frontend:

...to my configuration.yaml, restarted, and reset frontend cache. But, when I click on the new tab in the sidebar, it doesn't load.

Any tips or guidance would be super helpful.

Group monitor: Mobile compatibility

Bus monitor isn't compatible with narrow screens.

I guess we could only display

• time
• destination
• payload

and omit the other colums.

Project data gone after update

After updating to the latest HA version the names which previously were picked up from the ETS file have disappeared.
The interface still shows the file name and ETS version but apparently the addon does not read them anymore.

Group Monitor using the wrong attribute to identify the source

Instead of the name of the device as configured in the knxproj with ETS, it is using the name of the application.

Example 1

Source: 1.1.9
Source: GIRA Giersiepen Dimming actuator, 4-gang Standard
Destination: 1/2/21
Destination: B1 Hal spots SwTm

It should be

Source: 1.1.9
Source: Dimactuator B
Destination: 1/2/21
Destination: B1 Hal spots SwTm

Example 2

Source: 1.1.32
Source: GIRA Giersiepen Push button sensor 3 Plus 2-gang
Destination: 1/4/36
Destination: D Woonkamer D Actuele Tempratuur

It should be

Source: 1.1.32
Source: TS-9 RTR Woonkamer (this is the value entered for "Name" of device 1.1.32)
Destination: 1/4/36
Destination: D Woonkamer D Actuele Tempratuur

It it is picking up the correct Group Name in the Destination column from the knxproj file.
However, instead of the Device name in the source column, it shows the name of the application that is installed on the device.
We can still identify the device because the device number is also shown, but it is inconvenient if you named everything the project file.

Delete

`

Clear Schema when create entity page is discarded

eg. when using "back" button

To reproduce:

• Open create light entity form
• Assign eg. color temperature GA
• "Back" to entity platform select menu
• Open create switch entity form
• -> color temperature GA is still in schema and validation fails

"Back" Button

When we move to a "Configuration" panel, we should have a "back" navigation button.

I think hass-tabs-subpage and hass-tabs-subpage-data-table would provide those out of the box.

See home-assistant/core#96855

KNX Project file "Upload failed" - "Unknown error"

The KNX project file some how doesn't work for me.

1. I can browse & select a KNX project file and enter the password
2. The processing starts (= wheel starts turning)
3. The processing passes the password check (if enter a wrong password I get an "Invalid password" pop-up message faster approx. 10 seconds)
4. After approx. 30seconds I get an "Upload failed" pop-up with the message "Unknown error".

What could be the issue?

Log Details

Logger: homeassistant.components.websocket_api.http.connection
Source: components/knx/project.py:108
Integration: Home Assistant WebSocket API (documentation, issues)
First occurred: 22:57:16 (1 occurrences)
Last logged: 22:57:16

[548110576848] Error handling message: Unknown error (unknown_error) admin from 192.168.107.201 (Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36)
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/components/websocket_api/decorators.py", line 26, in _handle_async_response
    await func(hass, connection, msg)
  File "/usr/src/homeassistant/homeassistant/components/knx/websocket.py", line 100, in ws_project_file_process
    await knx.project.process_project_file(
  File "/usr/src/homeassistant/homeassistant/components/knx/project.py", line 110, in process_project_file
    project = await self.hass.async_add_executor_job(_parse_project)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/concurrent/futures/thread.py", line 58, in run
    result = self.fn(*self.args, **self.kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/src/homeassistant/homeassistant/components/knx/project.py", line 108, in _parse_project
    return xknxproj.parse()
           ^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/xknxproject/xknxproj.py", line 41, in parse
    project = XMLParser(knx_project_content).parse(self.language)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/xknxproject/xml/parser.py", line 63, in parse
    group_address_links = [
                          ^
  File "/usr/local/lib/python3.11/site-packages/xknxproject/xml/parser.py", line 64, in <listcomp>
    _ga_id_to_address[link] for link in com_object.links
    ~~~~~~~~~~~~~~~~~^^^^^^
KeyError: 'GA-2980'

Context

• All HA updates are installed

• I have a approx. 10 KNX entities set up manually in a KNX.yaml file which work fine

• The connection type is 'Tunnel UDP'

• KNX-bus connection works, e.g. the group monitor works

• XKNX Version 2.10.0

• KNX-Frontend Version 2023.5.31.141540

• Connected to bus Yes

• Individual address 1.0.1

• The KNX project file was exported from ETS 5.7.7 (Build 1428; latest 5.x version)

• Reimporting the KNX project file into the ETS (and opening it) works fine

Create new entity based on KNX GA

It would be super helpful to be able to see a list of all GA (#76) and then have a possibility to create a new entity based on the Group Address.

Is this something that is in scope of this project?

Feature Request: Show corresponding HA entity in KNX group monitor

Would be nice to not only see the group address, but also the HA entity name if one exists.

Rename "Bus monitor" to "Group monitor"

Since we only support Data link layer connections we should call our monitor "Group monitor" instead of "Bus monitor" to use same naming as ETS.

KNX Group Monitorn History Data

Is it possible to have a longer history in the KNX group monitor view?
Is this data stored in a DB and can bei accessed somehow?

Manually created entities not shown in KNX-Frontend

I have several manually created KNX entitiy in the configuration.yaml is it possible to display them in the knx-frontend under Entities (maybe as separate group "manually created" or is there a simple way to migrate them?

Group Monitor: Add "More Info" dialog

The group monitor telegram rows should be clickable to open a "More info" dialog.

This would be handy for mobile where we can't really show all information.

This dialog could have

• an "X" icon on top to close it (and click outside on desktop)
• a "Next" and "Previous" Button" at bottem to traverse the list of telegrams
• details about DPT
• relations of the address in HA entities (tracked in #79 )

Add i18n

HA users are from all around the world and thus we should add i18n support to have support for multiple languages.

We could use crowdin for that potentially.

Find a way to test the custom integration with pytest

Upload failed: uploaded file is too large

Hi,
trying to upload a project file of 4,5MB size, I got "Upload failed: File is too large".
is there a limit on the KNX project size?

Add proper header and tab navigation to the custom UI

project tab

I uploaded my project from ets but cannot see the project tab

Confirmation dialog for deleting project data

We should show a confirmation dialog when deleting project data.

Device list with restart button

I just needed to restart a device and thought it would have been more convenient if there would be a list of KNX devices in HA with the possibility to restart without firing up the ETS

Ability to send telegram

I believe it would be useful if user could send KNX telegram to KNX interface from Home Assistant.

Hash the resulting file

To avoid caching issues in HA we need to cache the frontend artifact before releasing.

Group Monitor: DataTable header and row disjointed

They scroll independently.

Add config flow for easier setup

Ad a Pause button in KNX Group Monitor

The group monitor is a very interesting feature, but you would need to be able to pause the refresh to be able to analyze it.

Currently the only way to do this is to use a filter for example on the time in order to no longer have any new messages in the list.

If we could then have the possibility of showing/hiding columns or reorganizing them that would be fantastic.

Overview: more information

Add some more information to "Overview" section

• knx-frontend version
• links to xknx, xnxproject and knx-frontend repos / issue trackers
• tint the "Delete Project data" button red
• Add some information text about the project upload - describing what it does and what it is (currently) used for. Something like

Names and information about group addresses, devices, used group objects, topology and building structure is extracted. This information will be used in the KNX Group Monitor. The project itself and the optional password are not stored by Home Assistant.

Mmaybe also rename "Overview" to something more descriptive - Project upload doesn't really fit into "Overview", but is the most prominent thing there currently. Maybe just "Info"