iobroker.knx 1.0.44 → 2.0.2

package/README.md

@@ -6,52 +6,107 @@
 
 [![NPM](https://nodei.co/npm/iobroker.knx.png?downloads=true)](https://nodei.co/npm/iobroker.knx/)
 
+#### Table of content
+
+* [Description](#description)
+* [Features](#features)
+* [Adapter configuration](#adapter-configuration)
+    * [Install the License](#install-the-license)
+    * [Configuration Interface](#configuration-interface)
+    * [Objects](#objects)
+    * [Usage](#usage)
+    * [Data point Types (DPT)](#data-point-types-dpt)
+    * [How the import works](#how-the-import-works)
+    * [Avoidance of problems](#avoidance-of-problems)
+* [GA-Tool](#ga-tool)
+* [Planned features](#planned-features)
+* [Changelog](#changelog)
+
 ## Description
+
 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: [Установка и базовая настройка адаптера](docs/ru/README.md)
+
 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](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.
 
+
+## License requirements
+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
+
+
 ## Features:
+
 * importing `knxproj` file
 * generating ETS-like object structure
 * finding and combining act-channel and state-channel (heuristic)
 * updating all states on start
 * emitting a READ to the KNX-Bus, while writing on state-object
-* sorting channels to rooms
+* edit and modify GA objects with GA-Tools
+* edit and modify state-act relations with GA-Tools
 
-## Adapter configuration
-After installing this adapter, open the adapter configuration. Fill in:
+##Adapter configuration
+After installing this adapter, open the adapter configuration.
 
-### KNX Gateway IP
-<IP of your KNX/Lan GW> with IPv4 format
+###Install the License
+The first step is to apply the license. If you have not installed a license, then 500 Datapoints are applied.
 
-### Port
-This is normally port 3671.
+* (1) shows your System ID, you need this to get a license
+* (2) click here to apply your license
 
-### phys. EIB Address
-Fill in free phys. address corresponding to your KNX-architecture, **BUT NOT the address of your KNX Gateway!** May not end in 0 !!!
+![knxV2-first-start-mod](docs/pictures/knxV2-first-start-mod.jpg)
 
-### debug-Level
-Extends the output level of the adapter for debugging purposes.
+If you already have created a new license under [https://iobroker.net](https://iobroker.net/), then you can paste it in (2), OR you can
+aquire it directly online by clicking on (1)
 
-### Upload knxproj
-here you can upload your ETS Export in `knxproj` format.
+![knxV2-2-1-Install-License-mod](docs/pictures/knxV2-2-1-Install-License-mod.jpg)
 
-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. This might take a while and can produce a high load on your KNX-bus. But the values in your vis are updated after start.
+If you have clicked on (1) enter your iobroker.net account login.
 
-### Objects
-Here is under knx.0 the group address tree like in your ETS project.
+![knxV2-2-2-Install-License-online-mod](docs/pictures/knxV2-2-2-Install-License-online-mod.jpg)
+
+If your data have been correct, you will see all your licenses you got. Choose the one you want to use.
+
+![knxV2-2-3-Install-License-online-mod](docs/pictures/knxV2-2-3-Install-License-online-mod.jpg)
+
+If this was succesfull, save it.
+
+![knxV2-2-4-Install-License-online-mod](docs/pictures/knxV2-2-4-Install-License-online-mod.jpg)
 
-### Enumerations
-If you have a building structure in your ETS with the corresponding devices, it will be shown here. Under "members" are the names of group addresses listed from the devices with send-Flag in this Group.
+Thats all. Click on the button to save on the bottom of this page.
+
+### Configuration Interface
+![knxV2-2-5-Install-License-online-applied-mod](docs/pictures/knxV2-2-5-Install-License-online-applied-mod.jpg)
+
+1. KNX-Gateway IP: IPv4 of KNX-LAN Gateway.
+2. KNX-Gateway port: Default is Port 3671.
+3. physical address: Physical address of iobroker knx instance **! important: this is not the phys. address of the LAN Gateway !** and May not end in 0
+4. KNX packages per second: this limits the package rate. If KNX Lan Gateway reconnects to much or is temporarly not accessable, then reduce this rate.
+5. local iobroker IP: select the IP / Interface on which the adapter will be bound
+6. loglevel: normaly is level "Info", for debugging increase the level.
+7. only import new Datapoints: this is enabled by default. In case of disabling new GA's will be generatet AND existing GA's will be recreated.
+8. button upload file: drag'n drop is available here or on click the filechooser dialog. Here you can upload your ETS Export in `knxproj` format.
+    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 start.
+    Uploading a password secured file is not yet available.
+9. Host-ID: this is a special ID of iobroker host. This ID is neccessary for generating and validating the license
+10. GA-Tools: toolbox for fast changing GA's
+
+### Objects
+Here is under knx.0 the group address tree like in your ETS project. For modifying the properties, use GA-Tool.
 
 ### Usage
 If the adapter starts successfully, your data points will be available for everything you like to do.
 
-### Data point Types
+### Data point Types (DPT)
 All DPTs according to "System Specifications, Interworking, Datapointtypes" from KNX Association are available. That means there are 2 types of information you can get:
 1) a Value or a String
 2) comma-separated values or an array of values (for the moment I don't know what's the better way to handle)
@@ -59,116 +114,173 @@ All DPTs according to "System Specifications, Interworking, Datapointtypes" from
 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).
 This results e.g. in a value like "0,5", where "0" means "decrease" and "5" means number of intervals.
 
+### How the import works
+1. reading of all communicationobjectreferences (COR):
+    combining of groupadressreference ID'd with DPT of corresponding COR (if exists).
+2. generation of groupaddress structure(GAS):
+    generating the GAS based on GAR IDs and setting DPT (if not done yet)
+3. finding state an act addresses:
+    in ets-exports are no informations 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 act and the other one the state. There is also a check if the DPT's are similar. Thats why its not easy to find a peer, if GA naming is
+    not consistent.
+4. Flag check in deviceconfiguration:
+   the flags are handled as follows:
+
+    | KNX   |  |  | 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|
+
+6. Creation of datapoint peers (DPP):
+    A DPP will be created if GA, GAR and DPT are valid. This 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.
+7. at adapter start:
+    all GA's marked with "Read" Flag are checked at start. This can affect a higher bus traffic. In the end
+    are all states up to date.
+
+###Avoidance of problems
+* 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.
+
+## GA-Tool
+The GA-Tool makes it easy to change properties of GA's.
+
+![knxV2-3-6-GATools-mod](/docs/pictures/knxV2-3-6-GATools-mod.jpg)
+
+1. shows the GA tree and selected GA
+2. in the property section the name of selected GA
+3. set iobroker flags
+4. set GA DPT
+5. recognized act GA
+6. recognized state GA
+
+![knxV2-3-2-GATools-mod](/docs/pictures/knxV2-3-2-GATools-mod.jpg)
+
+1. show the state-act relation
+2. if relation exists then it can removed
+
+If no relation exist, then can be created a new one by clicking (2) for selected GA (1).
+In the dialog (3) can the peer selected
+
+![knxV2-3-5-GATools-mod](/docs/pictures/knxV2-3-5-GATools-mod.jpg)
+
+If there are more GA's to change properties, use multiselect. This feature works only for GA's with no relation.
+
+![knxV2-3-4-GATools-mod](/docs/pictures/knxV2-3-4-GATools-mod.jpg)
+
+1. selected GA's
+2. properties to change
+3. there is no change possible
 
-## Wie werden die Datenpunkte generiert (Deutsch)
-### 1) Auslesen aller Kommunikationsobjektreferenzen (im folgenden KOR)
-Dabei werden den Gruppenaddressreferenz (im folgenden GAR) IDs der jeweilige DPT der KOR zugeordnet, wenn er vorhanden ist. Ausserdem bekommt der erste Eintrag die Attribute write=yes und read=no. Alle darauf folgenden GAR ID's bekommen nur den DPT zugeordnet
-
-### 2) Erzeugen der Gruppenadressstruktur (im folgenden GAS)
-Hier wird die GAS anhand der GAR IDs erzeugt und ebenfalls die DPTs zugeordnet, falls dies unter 1) noch nicht geschehen ist.
-
-### 3) Herausfinden der Schalt- und Statusaddressen
-In dem ETS-Export sind die Schalt- und Statusadressen nicht hinterlegt. Somit führe ich eine Ähnlichkeitsprüfung aller Gruppenadressnamen durch mit der Auswertung auf status und state.
- Wird ein Pärchen gefunden, dessen Ähnlichkeit mehr als 90% beträgt, dann wird angenommen, dass die GA1 die Schaltadresse und GA2 die Statusadresse ist. Dabei erhält GA1 das write=true und read=false und GA2 das write=false und read=true.
- Außerdem werden die DPT abgeglichen aus der jeweilig korrespondierenden GA. Aus diesem Grund ist es schwierig, Pärchen zu finden, wenn die Gruppenadressbeschriftungen nicht konsistent sind.
-
-Weiterhin werden die Flags in den Gerätekonfigurationen betrachtet. Dabei werden die Flags wie folgt umgesetzt:
-
-| KNX   |  |  | iobroker |  |  |
-|-------|-----------|------------|----------|----------|-------------------------------------------------|
-| Lesen | Schreiben | Übertragen | Lesen    | Schreiben| Erklärung                                       |
-|   -   |    -      |    -      |   -     |    -    | der wert wird über GroupValueResponse aktualiesiert |
-|   x   |    -      |    -      |   x     |    x    | ein Trigger darauf löst GroupValueRead aus|
-|   -   |    x      |    -      |   -     |    x    | Schreibt den angegeben Wert mit GroupValueWrite auf den KNX-Bus|
-|   -   |    -      |    x      |   x     |    -    | der Wert wird über GroupValueResponse aktualisiert |
-|   x   |    -      |    x      |   x     |    x    | ein Trigger darauf löst GroupValueRead aus|
-
-###  4)Erzeugen der Datenpunktpaare (im folgenden DPP)
-Ein DPP wird erzeugt, wenn die GA, GAR und der DPT valid sind. Mit diesen DPP arbeitet der Adapter. Fehlen also der DPT in einer GA, weil er auf keiner der o. A. Wege gefunden werden konnte, so wird für diese GA kein DPP erzeugt und sie ist im Weiteren nicht nutzbar.
+## Planned features
 
-Im Idealfall werden somit für einen Schaltkanal 2 DPP erzeugt. Das erste ist das Schalten. In diesem ist die GAR ID des Status DPP hinterlegt. Das zweite ist dann das Status DPP ohne weitere Referenz.
+* esf-import
+* GA-Mon bus monitoring tool
 
+<!--
+	Placeholder for the next version (at the beginning of the line):
+	### __WORK IN PROGRESS__
+-->
 
-## Beim Start des Adapters
-Alle mit dem Lesen-Flag markierten DPP werden beim Start abgefragt. Dies verursacht u.U. eine höhere Buslast und dauert einen Moment. Im Anschluss sind aber alle aktuellen Werte verfügbar.
+## Changelog
+### 2.0.1
 
-## (hidden) Features:
-Durch senden eines Wertes auf eine Statusadresse werden die Kommunikationsobjekte innerhalb dieser Gruppenadresse per GroupValueRead abgefragt.
+* fixed problem with license acceptance
 
-### Vermeidung von Problemen
-1) saubere ETS Programmierung und saubere ETS Programmierung und saubere ETS Programmierung
+### 2.0.0 (2021-11-15) **Major release**
 
-*   zuweisen der DPTs!!
-*   einheitliche Beschriftung der GA-Namen (z.B "EG Wohnen Decke Licht schalten" und "EG Wohnen Decke Licht schalten status" )
-*   Vermeidung von Sonderzeichen ",./;\&%$§[]" (kann zu Problemen bei der Erzeugung der GAS führen)
+* 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
 
-2) Prüfen ob das KNX/LAN GW erreichbar ist. Wenn es das nicht ist, versucht der Adapter sich kontinuierlich zu verbinden.
+### 1.0.46 (2021-03-23)
 
-3) Physikalische Adresse richtig wählen ( wichtig beim Einsatz von Linienkopplern ). !!! ACHTUNG: die hier eingetragene physikalische Adresse ist NICHT die Adresse des LAN Gateways und darf nicht auf 0 enden !!!
+* New admin GUI
 
-4) Der Port der LAN Schnittstelle ist i.d.R. 3671
+### 1.0.45 (2021_03_22)
 
-5) Durch die Möglichkeit der Statusabfrage ist eines zu beachten: Es ist sicherzustellen, dass nicht mehr als 40 Anfragen pro Sekunde vom ioBroker generiert werden, denn diese können dann physikalisch
-   bedingt nicht mehr durch den Adapter an das Gateway weitergereicht werden.
+* import of ETS v5.7.5 projects
 
-## Planned features
-* adding addresses to object-description (id)
-* selective import of knx-project
-* require node Version >8.9.4!
-
-## Changelog
 ### 1.0.44 (2021_01_22)
+
 * fixed act and state handling
 * added some new datapoint types
 * fix facility and room recognition and device allocation
 
 ### 1.0.42 (2020_09_03)
+
 * Fixed problem with missing index_m.html
 
 ### 1.0.41
+
 * fixed bug on GroupValue_Response event
 * corrected connection to Gira GW
 
 ### 1.0.40
+
 * fixed some import errors for ETS 5.7.x
 * fixed bug on GroupValue_Response event
 
 ### 1.0.39
+
 * fixed import error
 
 ### 1.0.38
+
 * fixed some bugs on import
 * show warning if import-file ist password protected
 
 ### 1.0.37 (2010-01-31)
+
 * update for ETS 5.7.3 import
 
 ### 1.0.36 (2019-10-16)
-* some bugs fixed 
+
+* some bugs fixed
 
 ### 1.0.35 (2019-09-15)
+
 * fixed permanent reconnects, if no traffic on knx-bus
 
 ### 1.0.34 (2019-09-15)
+
 * changes on importer for detecting project-id
 
 ### 1.0.33 (2019-09-12)
+
 * fixed bug while writing to bus
 * added units to states
 * fixed "read/write of undefined" error
 
 ### 1.0.32 (2019-09-03)
+
 * updated importer for ETS V5.7.2, some changes in KNX-stack state-machine
 
 ### 1.0.31
+
 * some fixes on ETS5.7.2 importer
 * small changes in knx-stack statemachine
 * added (again) phys address to admin config dialog
-
-### 1.0.31
 * fixed bug in deviceTree generation
 
 ### 1.0.30
+
 * new Importer for ETS5.7.2 knxproj files
 * extended accepted Data point types
 * new adapter configuration menu
@@ -179,80 +291,98 @@ Durch senden eines Wertes auf eine Statusadresse werden die Kommunikationsobjekt
 * fixed some small other bugs
 
 ### 1.0.20
+
 * fixed bug in handling KNX-data packages, which occurs periodical reconnects
 * fixed bug in KNX-project file upload procedure
 
 ### 1.0.19
+
 * reverted to true/false handling for DPT1.x
 
 ### 1.0.18
+
 * 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
 
 ### 1.0.17 (2018-08-16)
+
 * Better state processing
 * Add configurable package rate
 * corrected Bug in "import only new objects"
 
 ### 1.0.15 (2018-07-18)
+
 * change ChID on reconnect
 * on Startup read wait for response of State channel or timeout
 
 ### 1.0.13 (2018-07-04)
+
 * elimination of special signs while importing
 * small bug-fixes
 
 ### 1.0.12 (2018-06-19)
+
 * reduced and sorted log output
 * small bug-fixes
 * NEW Feature: request State/Val of stateObject from KNX-Bus
 
 ### 1.0.11 (2018-05-27)
+
 * fixed DPT1 correcting value problem
 * fixed reconnect problem
 * other small optimizations and fixes
 
 ### 1.0.10 (2018-05-04)
+
 * closing local port in case of undefined connection state
 * added advanced debug-level via adapter-config
 * many fixes
 
 ### 1.0.9 (2018-04-29)
+
 * changed to state-wise processing
 * fixed "disconnect-request"
 * changed connection handling with knxd
 * many small fixes
 
 ### 1.0.8 (2018-04-04)
+
 * modified package queue
 * fixed ACK if sending to KNX-Bus
 * many small fixes
 
 ### 1.0.7 (2018-03-16)
+
 * fixed Adapter-lock while uploading projects
 
 ### 1.0.6 (2018-03-11)
+
 * fixed connection problem
 * corrected package counter
 
 ### 1.0.5 (2018-03-01)
-* fixed empty objects, related to DPT1 (error message [object Object] unknown Input value)
+
+* 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)
 
 ### 1.0.4 (2018-02-27)
+
 * schema update for room enumeration coming up with ETS 5.6
 
 ### 1.0.2 (2018-02-27)
+
 * kleine Fehler beseitigt
 
 ### 1.0.1 (2018-02-26)
+
 * fixed certificate error
 
 ### 1.0.0 (2018-02-25)
+
 * 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
@@ -263,50 +393,63 @@ Durch senden eines Wertes auf eine Statusadresse werden die Kommunikationsobjekt
 * implemented "add" mode for knxproject upload (existing Objects stay as they are, only new Objects where added)
 
 ### 0.8.6 (2017-06-17)
+
 * some small bug-fixes
 * insert slider to set a sendDelay for slow KNX/LAN Gateways to prevent connection loss
 
 ### 0.8.5 (2017-06-05)
+
 * project loader rebuild, dpt13-fix
 
 ### 0.8.3 (2017-04-24)
+
 * added act channel update of corresponding state
 * fix bug in state-vis update
 * optimized knxproj upload
 
 ### 0.8.2 (2017-02-26)
+
 * implemented device-config parsing from knxproj
 * better choice of state/val of DP objects
 
 ### 0.8.1 (2017-02-06)
+
 * fixed DPT1 switch problem
 
 ### 0.8.0 (2017-02-xx) comming soon
 
 ### 0.7.3 (2016-12-22)
+
 * (chefkoch009) more DPT's are supported
 * faster Startup
 * implemented generation of room list with device dependencies
 
 ### 0.7.2 (2016-11-20)
+
 * (chefkoch009) added necessary dependencies
 
 ### 0.7.1 (2016-11-19)
+
 * (chefkoch009) Support standard KNX/LAN Gateways.
 
 ### 0.7.0 (2016-10-13)
+
 * (chefkoch009) Support of project export
 
 ### 0.6.0 (2016-07-20)
+
 * (chefkoch009) redesign
 
 ### 0.5.0
-  (vegetto) include vis widget
+
+*  (vegetto) include vis widget
 
 #### 0.4.0
+
 * (bluefox) fix errors with grunt
 
 #### 0.2.0
+
 * (bluefox) initial release
 
 ## License

package/admin/asset-manifest.json

@@ -0,0 +1,23 @@
+{
+  "files": {
+    "main.css": "./static/css/main.e2d673ee.chunk.css",
+    "main.js": "./static/js/main.2721c643.chunk.js",
+    "main.js.map": "./static/js/main.2721c643.chunk.js.map",
+    "runtime-main.js": "./static/js/runtime-main.ec74a465.js",
+    "runtime-main.js.map": "./static/js/runtime-main.ec74a465.js.map",
+    "static/css/2.67ef5efb.chunk.css": "./static/css/2.67ef5efb.chunk.css",
+    "static/js/2.8ce0c6f9.chunk.js": "./static/js/2.8ce0c6f9.chunk.js",
+    "static/js/2.8ce0c6f9.chunk.js.map": "./static/js/2.8ce0c6f9.chunk.js.map",
+    "index.html": "./index.html",
+    "static/css/2.67ef5efb.chunk.css.map": "./static/css/2.67ef5efb.chunk.css.map",
+    "static/css/main.e2d673ee.chunk.css.map": "./static/css/main.e2d673ee.chunk.css.map",
+    "static/js/2.8ce0c6f9.chunk.js.LICENSE.txt": "./static/js/2.8ce0c6f9.chunk.js.LICENSE.txt"
+  },
+  "entrypoints": [
+    "static/js/runtime-main.ec74a465.js",
+    "static/css/2.67ef5efb.chunk.css",
+    "static/js/2.8ce0c6f9.chunk.js",
+    "static/css/main.e2d673ee.chunk.css",
+    "static/js/main.2721c643.chunk.js"
+  ]
+}