- Description
- Requirements
- Features
- Installation
- Adapter configuration
- GA-Tool
- Planned features
- Changelog
en: This adapter allows importing of knxproj Files from ETS. It generates the translation between KNX-group addresses and ioBroker and puts the devices into rooms (esp. for MobileUI).
ru: Установка и базовая настройка адаптера
It connects to standard KNX/LAN Gateways.
Attention: with changing to KNX-Adapter Version 2.x the licensing has been changed. You can get a new license from https://iobroker.net
You also should update iobroker js-controller AND admin to the latest version.
Before beginning: Every DPT of com.Objects should be set in your ETS project. Every device should be sorted into your facility structure.
- node Version >= 14.15.4
- admin Version >= 5.2.0
- js-controller Version >=3.3.20
Without this requirement, the adapter is not installable or will work not properly.
For less than 500 data points, there is no need for registration or adding a license key. If you have more than 500 data points, you need a license. You can choose between yearly and permanent license.
To use this adapter in ioBroker, you need to accept the source code license of the adapter. The source code of this adapter is available under the CC-NC-BY license.
Additionally, you need a license to use the adapter. The license editions are available on https://iobroker.net/www/pricing
- importing
knxprojfile - generating ETS-like object structure
- finding and combining act-channel and state-channel (heuristic)
- updating all states on start
- no cloud or internet needed
- emitting a READ to the KNX-Bus, while writing on state-object
- edit and modify GA objects with GA-Tools
- edit and modify state-act relations with GA-Tools
- NEW: allow a non-KNX State direct link (vice-verse)
- NEW: adapter responses to GroupValueRead to a directLink connected object
- NEW: import of passwort protected project files (thanks to aKzenT)
###Installation This adapter is only installable with npm. Installation via GitHub does not work.
##Adapter configuration After installing this adapter, open the adapter configuration.
###Install the License The first step is to apply the license. If you have not installed a license, then 500 Data points are applied.
- (1) shows your System ID, you need this to get a license
- (2) click here to apply your license
If you already have created a new license under https://iobroker.net, then you can paste it in (2), OR you can acquire it directly online by clicking on (1)
If you have clicked on (1), enter your iobroker.net account login.
If your data have been correct, you will see all your licenses you got. Choose the one you want to use.
If this was successful, save it.
That's all. Click on the button to save on the bottom of this page.
- KNX-Gateway IP: IPv4 of KNX-LAN Gateway.
- KNX-Gateway port: Default is Port 3671.
- physical address: Physical address of iobroker knx instance. Important: this is not the physical address of the LAN Gateway! and May not end in 0
- KNX packages per second: this limits the package rate. If KNX Lan Gateway reconnects too much or is temporarily not accessible, then reduce this rate.
- local iobroker IP: select the IP / Interface on which the adapter will be bound
- loglevel: normally is level "Info", for debugging increase the level.
- only import new Data points: this is enabled by default. In the case of disabling, new GA's will be generated AND existing GA's will be recreated.
- button upload file: drag-and-drop is available here or on click the file chooser dialog. Here you can upload your ETS Export in
knxprojformat. After successful import, a dialog shows the number of imported objects. Now press "save & close" and the adapter should start. While starting the adapter reads all group addresses with read-Flag and write-Flag. This might take a while and can produce a high load on your KNX-bus. But the values in your vis are updated after the start. Uploading a password secured file is not yet available. - Host-ID: this is a special ID of iobroker host. This ID is necessary for generating and validating the license
- GA-Tools: toolbox for fast-changing GA's
Here is under knx.0 the group address tree like in your ETS project. For modifying the properties, use GA-Tool.
If the adapter starts successfully, your data points will be available for everything you like to do.
All DPTs according to "System Specifications, Interworking, Datapointtypes" from KNX Association are available. That means there are two types of information you can get:
- a Value or a String
- comma-separated values or an array of values (for the moment I don't know what's the better way to handle)
For example, a DPT5.001 is encoded as unsigned Integer with 8-Bit. This gives a single Value. The DPT3.007 (Control Dimming) is encoded as 1Bit(Boolean)+3Bit(unsigned Int). These results, e.g., in a value like "0,5", where "0" means "decrease" and "5" means number of intervals.
-
reading of all communicationobjectreferences (COR): combining of groupadressreference ID'd with DPT of corresponding COR (if exists).
-
generation of group address structure (GAS): generating the GAS based on GAR IDs and setting DPT (if not done yet)
-
finding state an act addresses: in ets-exports are no information about state and act addresses.The adapter parses all GA's of "status" or "state". If there are 2 GA's with a similarity more than 90%, then one address will be actor and the other one the state. There is also a check if the DPT's are similar. That's why it's not easy to find a pair if GA naming is not consistent.
-
Flag check in the device configuration: the flags are handled as follows:
KNX KNX KNX ioBroker ioBroker Read Write Transmit Read Write Explanation - - - - - the value will be updated by GroupValueRead x - - x x sending any value on this state trigger a GroupValueRead - x - - x write the value to KNX with GroupValueWrite - - x x - the state value will be updated by GroupValueResponse x - x x x sending any value on this state trigger a GroupValueRead -
Creation of datapoint peers (DPP): A DPP will be created if GA, GAR and DPT are valid. These are the DPP the adapter is working with. If DPT is missing in a GA, because it couldn't be found, then the DPP will not be created. It can be done with GA-Tool.
-
At adapter start: All GA's marked with "Read" Flag are checked at start. This can affect the higher bus traffic. In the end are all states up to date.
- clean ETS programming and more important clean ETS programming and most important clean ETS programming
- Assign the DPTs!!
- uniform labeling of the GA names (e.B "EG Wohnen Decke Licht schalten" and "EG Wohnen Decke Licht schalten status" )
- Avoidance of special characters ",./;&%$§[]" (may cause problems with the generation of gas)
- Check if the KNX/LAN GW is reachable. If it is not, the adapter tries to connect continuously.
- Correctly select physical address (important when using line couplers). !!! ATTENTION: the physical address entered here is NOT the address of the LAN Gateway and must not end in 0 !!!
- The port of the LAN interface is usually 3671
- Due to the possibility of status query, one thing must be noted: It must be ensured that no more than 40 requests per second are generated by the ioBroker, because these can then be physically generated can no longer be passed on to the gateway by the adapter.
The GA-Tool makes it easy to change properties of GA's.
- shows the GA tree and selected GA
- in the property section, the name of selected GA
- set iobroker flags
- set GA DPT
- recognized act GA
- recognized state GA
- show the state-act relation
- if relation exists, then it can be removed
If no relation exists, then can be created a new one by clicking (2) for selected GA (1). In the dialog (3) can the peer be selected
If there are more GA's to change properties, use multiselect. This feature works only for GA's with no relation.
- selected GA's
- properties to change
- there is no change possible
Since Adapter Version 2.0.6 it is possible to link a non KNX ioBroker state directly to a GA. This
can be used to apply time, date, any states or info to KNX. (a small hint: you can link any of your
IOT components directly to a GA in KNX (f.e. link a homematic button to a KNX GA or link a KNX button sensor to
your sonos player)). The states can be read with a GroupValueRead, and if the state changes, it will be
automatically updated on KNX. Also, if you change on KNX, it will update the linked non KNX iot device.
- select the GA to connect to
- show the selected GA
- this GA must have write attribute
- choose a valid data point type (if they don't match, it will not work)
- it is not allowed to have an act-state relation
- button to select a non KNX object to link with
- select the non-KNX object you want to link
- hit OK if you're done
Now is KNX-GA (1) directly linked with non-KNX iobroker (2). With (3) you can delete this relation.
- esf-import
- GA-Mon bus monitoring tool
- fixed GUI errors, starting redesign GA-Tools
- updated the adapter import schema for ETS 6.3.0
- nodejs >= 20 is required
- Update license related data and fix package version
- updated the adapter import schema for ETS 6.2.2
- fixed UTF-8 error
- updated the adapter import schema for ETS 6.2.1
- nodejs >= 18 is required
- updated the adapter import schema for ETS 6.2.0
- small bug-fixes
- updated the adapter import schema for ETS 6.1.1
- corrected wrong GW Port after adapter upgrade
- allow self-defined values for min and max
- some small other fixes
- added import specification, solved problems in GaTools
- fixed license handling
- fixed license handling with js-controller Version > 5
- added ETS V6.1.0 import
- required node version >= 16.13.1
- fixed send-delay
- small changes
- added ETSv6.0.6 import
- major changes in Adapter Config UI
- fixed change of port settings for LAN-GW
- added ETSv6.0.5 import
- fixed import error with extrem large KNX catalogue files
- fixed unrecognized connection breaks
- added ETSv6.0.4 (override 6.0.3)
- small bugfixes
- added ETSv5.7.7 import
- fixed "unknown value" bug
- some other small fixes
- fixed handling of undefined DP
- updated the data point types
- fix warning with incompatible DPT in future
- the biggest issue of all: I get shocked because of the war in Ukraine. My thoughts are with the people of Ukraine, I am infinitely sorry for what is happening to them and their country. It is an inhuman shame.
- can't fix it, but I appeal to everyone: Be neighbors and not enemies. Respect the other and do not fight yourselves.
- fixed password handling for projects from upgraded ETS
- import of ETS6.0.2 projects ETS6.0.1 not possible
- bugfixes
- import password protected project files
- bug fixes
- fixed bug with unackn write
- fixed bug in linkedState
- fixed bug with unable to write on KNX
- fixed problem on ETSv6 import
- many small bugfixes
- implemented GA-Tools directLink feature
- fixed problem on ETSv4 import
- corrected some messages
- corrected DPT14.x min and max range
- fixed DPT9.xxx calculation
- implemented date-and-time DPT19.00x
- fixed confusing "no license error"
- small bugfixes
- fixed counting 1st Datapoint
- automaticly remove old V1 license", preventing confusion after upgrade from V1 to V2
- fixed problem with license acceptance
- Breaking change! => new license is neccessary V1 Licenses will not work => V1 business Licenses can changed to V2
- complete refactoring of knx-admin
- added Tool for handling GA in knx-admin
- fixed many bugs (in knx-stack, on importing ETS Projects, reconnect and timeouts)
- added new datapoint types
- added import till ETS V6
- changed license management
- New admin GUI
- import of ETS v5.7.5 projects
- fixed act and state handling
- added some new datapoint types
- fix facility and room recognition and device allocation
- Fixed problem with missing index_m.html
- fixed bug on GroupValue_Response event
- corrected connection to Gira GW
- fixed some import errors for ETS 5.7.x
- fixed bug on GroupValue_Response event
- fixed import error
- fixed some bugs on import
- show warning if import-file ist password protected
- update for ETS 5.7.3 import
- some bugs fixed
- fixed permanent reconnects, if no traffic on knx-bus
- changes on importer for detecting project-id
- fixed bug while writing to bus
- added units to states
- fixed "read/write of undefined" error
- updated importer for ETS V5.7.2, some changes in KNX-stack state-machine
- some fixes on ETS5.7.2 importer
- small changes in knx-stack statemachine
- added (again) phys address to admin config dialog
- fixed bug in deviceTree generation
- new Importer for ETS5.7.2 knxproj files
- extended accepted Data point types
- new adapter configuration menu
- implemented a switch for the user to decide to use "true" and "false" or "0" or "1" for binary values
- fixed bug in GroupValue_Read
- implemented a selector for local network interface for KNX to Gateway communication
- extended State Object for later features
- fixed some small other bugs
- fixed bug in handling KNX-data packages, which occurs periodical reconnects
- fixed bug in KNX-project file upload procedure
- reverted to true/false handling for DPT1.x
- fixed upload issue with ETS5.6.x project files
- switched values for "boolean" from 1 and 0 to true false
- fixed recognition of role set for DPT1.x to switch
- fixed DPT16.xxx writing to KNX-Bus with values < 14Byte
- Better state processing
- Add configurable package rate
- corrected Bug in "import only new objects"
- change ChID on reconnect
- on Startup read wait for response of State channel or timeout
- elimination of special signs while importing
- small bug-fixes
- reduced and sorted log output
- small bug-fixes
- NEW Feature: request State/Val of stateObject from KNX-Bus
- fixed DPT1 correcting value problem
- fixed reconnect problem
- other small optimizations and fixes
- closing local port in case of undefined connection state
- added advanced debug-level via adapter-config
- many fixes
- changed to state-wise processing
- fixed "disconnect-request"
- changed connection handling with knxd
- many small fixes
- modified package queue
- fixed ACK if sending to KNX-Bus
- many small fixes
- fixed Adapter-lock while uploading projects
- fixed connection problem
- corrected package counter
- fixed empty objects, related to DPT1 (error message [object Object] unknown Input value)
- fixed path variable
- fixed bug with GA's containing a "/" in the name (on proj-import)
- start implementing crosswise property update on corresponding DPT (on proj-import)
- schema update for room enumeration coming up with ETS 5.6
- kleine Fehler beseitigt
- fixed certificate error
- substitution of used KNX-stack with own from scratch build stack
- implemented full scale of DPT according to "System Specifications, Interworking, Datapointtypes" from KNX Association
- hardening connection handling for tunneling connections
- upgrade Adapter-configuration Interface to be ready with Admin3
- removed "Delay Slider" because of the new knx-stack
- many other small changes
- fixed post-comma values to scale-value of DPT
- implemented "add" mode for knx project upload (existing Objects stay as they are, only new Objects where added)
- some small bug-fixes
- insert slider to set a sendDelay for slow KNX/LAN Gateways to prevent connection loss
- project loader rebuild, dpt13-fix
- added act channel update of corresponding state
- fix bug in state-vis update
- optimized knxproj upload
- implemented device-config parsing from knxproj
- better choice of state/val of DP objects
- fixed DPT1 switch problem
- (chefkoch009) more DPT's are supported
- faster Startup
- implemented generation of room list with device dependencies
- (chefkoch009) added necessary dependencies
- (chefkoch009) Support standard KNX/LAN Gateways.
- (chefkoch009) Support of project export
- (chefkoch009) redesign
- (vegetto) include vis widget
- (bluefox) fix errors with grunt
- (bluefox) initial release
This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers.
For more details and for information how to disable the error reporting see Sentry-Plugin Documentation!
Sentry reporting is used starting with js-controller 3.0.
The developer is not able to get any further special information about the system/config/user/environment. In case no license is found, the adapter version and host ID are also reported.
- bluefox
- foxriver76
The CC-NC-BY License (CC-NC-BY)
Copyright (c) 2016-2024 K.Ringmann [email protected]
THE WORK IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.
BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS.
Read full license text in LICENSE