iobroker.openknx 0.0.15 → 0.1.0

package/README.md

@@ -1,74 +1,110 @@
 ![Logo](admin/openknx.png)
 # ioBroker.openknx
-=================
 
 [![NPM version](http://img.shields.io/npm/v/iobroker.openknx.svg)](https://www.npmjs.com/package/iobroker.openknx)
 [![Downloads](https://img.shields.io/npm/dm/iobroker.openknx.svg)](https://www.npmjs.com/package/iobroker.openknx)
 
 [![NPM](https://nodei.co/npm/iobroker.openknx.png?downloads=true)](https://nodei.co/npm/iobroker.openknx/)
 
-This adapter serves as a communication interface between Iobroker Object tree and a IP Gateway on the KNX bus.  
-This adapter allows to generate the communication objects by importing of knxproj Files from ETS.  
-All generated Communication Objects are initially configured readable and writeable.
 
-# Installation of early versions
-This is an early untested version  
-Please make a good backup of all your data!  
-Please do not test in critical environments
+This adapter serves as communication interface between Iobroker and your KNX IP Gateway.
+The adapter allows to generate the iobroker communication objects automatically by importing an ETS group address xml export.  
+All generated communication objects are initially configured readable and writeable, values are fetched from the knx bus on adapter restart.
+
+# Installation
+This is an early untested version. Please make a good backup of all your data before installation! Please do not test in critical environments.
 
 install in shell
+
     cd /opt/iobroker/node_modules  
-    npm i iobroker.openknx@latestversion  
+    npm i iobroker.openknx  
     iobroker add openknx  
     npm i knx  
 
-updates:
-    npm i iobroker.openknx@latestversion  
+updates
+
+    npm i iobroker.openknx  
     iobroker upload openknx  
 
-# GA import
+# Adapter configuration
+![settings](docs/setting.png)
+Press "save & close" or "save" to restart the adapter and take over the changes.
+When starting, the adapter tries to read all GroupAdresses with have the autoread flag (default setting).
+This could take a while and can produce a higher load on your KNX-bus. This ensures that the adapter operates with up-to-date values from the start.
+Autoread is done on the first connection with the knx bus after an adapter start or restart, not on every knx reconnection.  
+After adapter installation, open the adapter configuration. Fill in:
+#### KNX Gateway IP
+IP of your KNX/Lan GW
+
+##### Port
+this is normally port 3671 of the KNX IP gateway.
+
+##### phys. EIB Adress
+Fill in physical address of the gateway in the format 1/1/1.
+
+##### Add only new Objects
+If checked, the import will skip overwriting existing communication objects.
+
+##### Override object path
+The adapter uses openknx.0 for first instance as default path for Iobroker objects.
+If your curent setup has a lot of references to existing knx objects to an existing folder, then you can specify its location, for example knx.0.
+This feature will be removed in future.
 
+#### GA XML import
+1. In ETS go to Group Addresses, select export group addresse and select XML export in latest format version
+2. upload your ETS Export XML in the adapter via the GA XML-Import dialog
+3. Import will immediatelly start after file selection and give a status report after completion.  
+After the successful import a message shows how much objects where recognized. More detailed information could be found in the log.
+
+#### Frames per sec
+This settings protects the KNX bus from data flooding by limiting data frames to a certain rate. Not sent frames are put into a fifo buffer.
+
+# howto use the adapter & basic concept
+todo
 
 # Compatibility
 This adapter has its own namespace 'openknx'.
-for existing applications, that are connected to knx signals of other knx adapters you can use the setting:
-Override object path
+for existing applications, that are connected to knx signals of other knx adapters you can use the setting:  
+Override object path  
 to e.g. knx.0. A new project import will then store the data in this object tree space.
 Objects are not compatible, remove them manually before the import and disable all other knx adapters.
 Leave setting empty to use the adapters own namespace.
 
 # log level
+Enable expert mode to enable switching between different log levels. Default loglevel is info.  
+![loglevel](docs/logelevel.png)
 
+# IOBroker Communication Object description
 
-# Adapter setting Interface Description
+GA import generates a communication object folder structure following the ga main-group/middle-group scheme. Each groupaddress is an oject with following automatically generated data.
 
     {
-    "_id": "path.and.name.to.object",       //derieved from the KNX structure
+    "_id": "path.and.name.to.object",                       //derieved from the KNX structure
     "type": "state",
-    "common": {
-        "desc": "Basetype: 1-bit value, Subtype: switch", //informative
-        "min": 0,                                         //
-        "max": 1,
-        "name": "Aussen Melder Licht schalten",           //informative description
-        "read": true,                                     //default this is set, if false incoming bus values are not updating the object
-        "role": "",                                       //tbd
-        "type": "boolean",                                //boolean, number, string, object
-        "unit": "",                                       //informative, derived from dpt
-        "write": true                                     //default true, if set change on object is triggering knx write, succ. write sets then ack flag to true
+    "common": {                                             //values here can be interpreted by iobroker
+        "desc": "Basetype: 1-bit value, Subtype: switch",   //informative, from dpt
+        "min": 0,                                           //derieved from dpt
+        "max": 1,                                           //derieved from dpt
+        "name": "Aussen Melder Licht schalten",             //informative description from ets export
+        "read": true,                                       //default set, if false incoming bus values are not updating the object
+        "role": "",                                         //tbd
+        "type": "boolean",                                  //boolean, number, string, object, derieved from dpt
+        "unit": "",                                         //derived from dpt
+        "write": true                                       //default true, if set change on object is triggering knx write, succ. write sets then ack flag to true
     },
-    "native": {
-        "address": "0/0/7",         //knx address
-        "answer_groupValueResponse": false, //default false, if set to true adapter responds with value on GroupValue_Read
-        "autoread": true,           //default true, adapter sends a GroupValue_read on start to sync its states
-        "bitlength": 1,             //size ob knx data
-        "dpt": "DPT1.001",          //DPT
-        "encoding": {               //informative
+    "native": {                                             //values here can be interpreted by openknx adapter
+        "address": "0/0/7",                                 //knx address
+        "answer_groupValueResponse": false,                 //default false, if set to true adapter responds with value on GroupValue_Read
+        "autoread": true,                                   //default true, adapter sends a GroupValue_read on start to sync its states
+        "bitlength": 1,                                     //size ob knx data, derived from dpt
+        "dpt": "DPT1.001",                                  //DPT
+        "encoding": {                                       //informative
         "0": "Off",
         "1": "On"
         },
-        "force_encoding": "",       
-        "signedness": "",
-        "valuetype": "basic"
+        "force_encoding": "",                               //informative
+        "signedness": "",                                   //informative
+        "valuetype": "basic"                                //composite means set via a specific javascript object
     },
     "from": "system.adapter.openknx.0",
     "user": "system.user.admin",
@@ -77,18 +113,57 @@ Leave setting empty to use the adapters own namespace.
 
 
 # Adapter communication Interface Description
-handeled DPTs 1-21,232,237,238  
-
-Unhandeled DPTs are written as raw buffers, the iterface is a hexadecimal number.
-Where number, see scaling.
+Handeled DPTs are: 1-21,232,237,238  
+Unhandeled DPTs are written as raw buffers, the interface is a sequencial string of hexadecimal numbers. For example write '0102feff' to send values 0x01 0x02 0xfe 0xff on the bus. 
+Where number datatype is used please note that interface values can be scaled.
+
+#### API call
+
+    setState(
+        id: string,                                     // object path
+        state: State | StateValue | SettableState,
+        ack: false,                                     //set to false and will be set to true by KNX stack on send confirmation
+        c: 'GroupValue_Read'                            //optional comment, set this value to trigger a bus read to this object, given StateValue is ignored
+    ): void;
+
+
+
+#### Description of all DPTs
+
+|KNX DPT        |javascript datatype                	        |special values	|value range |
+|---        |---        |---                                    |---|
+|DPT-1	    |boolean    |                                    |false, true|
+|DPT-2	    |object	    |{"priority":1 bit,"data":1 bit}	       |-|
+|DPT-3	    |object	    |{"decr_incr":1 bit,"data":2 bit}	|-|
+|DPT-18	    |object	    |{"save_recall":0,"scenenumber":0}	|
+|DPT-21	    |object	    |{"outofservice":0,"fault":0,"overridden":0,"inalarm":0,"alarmunack":0}	|-|
+|DPT-232	|object	    |{red:0..255, green:0.255, blue:0.255}	-|
+|DPT-237	|object	    |{"address":0,"addresstype":0,"readresponse":0,"lampfailure":0,"ballastfailure":0,"convertorerror":0}	|-|
+|DPT-4	    |string		||one character sent as 8-bit character|
+|DPT-16	    |string		||one character sent as 16-character string|
+|DPT-5	    |number		||8-bit unsigned value|
+|DPT-5.001	|number		||0..100 [%] scaled to 1-byte|
+|DPT-5.003	|number		||0..360 [°] scaled to 1-byte|
+|DPT-6	    |number		||8-bit signed -128..127|
+|DPT-7	    |number		||16-bit unsigned value|
+|DPT-8	    |number		||2-byte signed value |-32768..32767|
+|DPT-9	    |number		||2-byte floating point value|
+|DPT-14	    |number		||4-byte floating point value|
+|DPT-12	    |number		||4-byte unsigned value|
+|DPT-13	    |number		||4-byte signed value|
+|DPT-15	    |number		||4-byte|
+|DPT-17	    |number		||1-byte|
+|DPT-20	    |number		||1-byte|
+|DPT-238 	|number		|                         |1-byte|
+|DPT-10	    |number for Date Object		||-|
+|DPT-11	    |number for Date Object		||-|
+|DPT-19	    |number for Date Object		||-|
+|rest	    |string	    |00010203..	            |-|
 
-Description of handeled DPTs
-
-tbd
 
 Only time and date information is exchanged with KNX time based datatypes, e.g. DPT-19 has unsupported fields for signal quality  
 
-Object send and receive values are of type boolean (eg DPT1), number (scaled, or unscaled), string.  
+Object send and receive values are of type boolean DPT1), number (scaled, or unscaled), string.  
 DPT 2 'expects a object {"priority":0,"data":1}' receive provides a strinified object of same type.  
 Other joint DPTs have similar object notation.  
 DPT19 expects a Number from a Date Object, Iobroker can not handle objects, fields of KNX ko that cannot be derived from timestamp are not implemented eg. quality flags
@@ -98,69 +173,52 @@ Please have in mind that Javascript and KNX have very different base type for ti
 DPT10 is time (hh:mm:ss) plus "day of week". This concept is unavailable in JS, so you'll be getting/setting a regular Date Js object, but please remember you'll need to ignore the date, month and year. The exact same datagram that converts to "Mon, Jul 1st 12:34:56", will evaluate to a wildly different JS Date of "Mon, Jul 8th 12:34:56" one week later. Be warned! 
 DPT11 is date (dd/mm/yyyy): the same applies for DPT11, you'll need to ignore the time part.
 
+#### group value write
+send is triggered by writing a communication object.
+Communication object is triggered when a write frame is received on the bus.
 
-# Features
-* import groupaddresses in XML format
-* import knxprj (only tested with ets 5.7.4 file format) 
-
-# Adapterconfiguration
-After installing this adapter, open the adapter configuration. Fill in:
-
-##### KNX Gateway IP
-<IP of your KNX/Lan GW> with ipv4 format
-
-##### Port
-this is normally port 3671 of the gateway.
-
-##### phys. EIB Adress
-Fill in physical address of the gateway in the format 1/1/1.
-
-##### Add only new Objects
-
-##### Override object path
-The adapter uses openknx.0 for first instance as default path for Iobroker objects.
-If your existing installation has a lot of references to existing knx objects to an existing folder, then you can specify its location, for example knx.0.
-This feature will be removed in future.
-
-##### Upload configuration
-1st In the ETS go to Group Addresses, select Export Grou Adresses
-Select XML Output Format 
-2nd upload your ETS Export XML in the adapter via the GA XML-Import dialog
-
-After the successful import a message shows how much objects where recognized.
-Press "save & close" or "save" to restart the adapter and take over the changes.
-When starting, the adapter tries to read all GroupAdresses with have the autoread flag (default setting). This could take a while and can produce a higher load on your KNX-bus. This ensures that the adapter operates with up-to-date values from the start.
+#### group value read
+Sending can be triggered by writing a communicaton object with comment.
+Receiving, if configured will trigger a group value response (limitation: write) of the actual c.o. value, see below
 
-## Objects
-In Objects the group adress tree like in your ETS project.
+#### group value response
+Sending Not yet supported. Emulated if response setting is set and adapter writes a group value write.
+Receiving will update the value of the iobroker object in read is set to true.
 
-# Usage
-If the adapter startet successfully your datapoints will be available for communication interaction.
+# Features
+* fast import of groupaddresses in XML format
+* stable knx stack
+* interpretation of many DPTs
+* raw read and write of unsupported DPTs
+* support of group value read and group value write, group value write as response to group value request
+* Autoread
+* free open source
 
-## Datapoint Types
-Wide DPT (datapoint type) support (DPT1 - DPT21, DPT232, DPT237, DPT238 supported)
 
-# Special settings
 
 
 # Known Problems
-- raw value write where missing DPTs not fully implemented
-- cannot receive ga of unsupported dpt
-- sends write instead of response on GroupValue_Read
-- setting onlyAddNewObjects not working
-- knxprj file only tested from ETS 5.7.4
+- sends write instead of GroupValue_Response on GroupValue_Read
 - IOBroker object role definition missing
 
-# limitations
-- only three level group address are supported
+# Limitations
+- only three level group addresses are supported
 
 ## Changelog
+###
+* initial test release
+
+### 0.0.19
+* display warning on ga import file errors
+
+### 0.0.17
+* raw value handling, can now write and receive ga of unsupported dpt
+* setting onlyAddNewObjects fixed
+* adapter restart after import
+
 ### 0.0.14
-* initial raw value handling added
 * import ga xml
 
-### 0.0.12
-* initial version
 
 
 ## License

package/admin/index_m.html

@@ -19,8 +19,6 @@
     <link rel="stylesheet" type="text/css" href="style.css" />
     <script type="text/javascript" src="words.js"></script>
 
-    <script type="text/javascript" src="zip/zip.js"></script>
-    <script type="text/javascript" src="zip/inflate.js"></script>
 
     <style>
         #progress {
@@ -163,7 +161,7 @@
                             if (ValidateIPaddress(ip1)) {
                                 $('#gwip').val(ip1);
                             } else {
-                                alert("Adresse ist nicht gültig");
+                                alert("invalid address");
                             }
                         }
 
@@ -172,7 +170,7 @@
                             if (ValidatePortaddress(gwipport1)) {
                                 $('#gwipport').val(gwipport1);
                             } else {
-                                alert("Portnummer ist nicht gültig");
+                                alert("invalid portnumber");
                             }
                         }
 
@@ -181,7 +179,7 @@
                             if (ValidateEIBaddress(eibadr1)) {
                                 $('#eibadr').val(eibadr1);
                             } else {
-                                alert("Physikalische EIB Adresse ist nicht gültig");
+                                alert("physical EIB address not valid");
                             }
                         }
 
@@ -224,7 +222,6 @@
                 }
             });
 
-
             //start with no changed settings, disable save button
             onChange(false);
             // reinitialize all the Materialize labels on the page if you are dynamically adding inputs:
@@ -249,7 +246,6 @@
             callback(obj);
         }
 
-
         function fileHandler(event) {
             event.preventDefault();
 
@@ -259,18 +255,10 @@
                 console.warn('invalid file object');
                 return false;
             }
-            if (file.size > 100000000) {
-                showMessage('Filezise is too big');
-                $('#knxprojFile').replaceWith($(knxprojFile));
-                $('#knxprojFile').change(fileHandler);
-                return false;
-            }
 
             $('.file-field .btn').addClass('disabled');
             $('.file-field .file-path').prop('disabled', true);
 
-            zip.useWebWorkers = false;
-
             if (file.name.split('.').pop() == 'xml') {
                 var reader = new FileReader();
                 reader.addEventListener('load', function readFile(event) {
@@ -278,18 +266,14 @@
                     transmitXML();
 
                     function transmitXML() {
-                        //$('#progress').find('.determinate').css('width', Math.round((callback / maxCat) * 100) + '%');
-                        //if (callback < maxCat) {
-                        //    setTimeout(transmitXML, 100);
-                        //    return;
-                        //}
+
                         $('#knxprojFile').replaceWith($(knxprojFile));
                         $('#knxprojFile').change(fileHandler);
 
-                        showToast(null, _('Please wait while generating Objects.....it could take a while.'), null, 5000);
+                        showToast(null, _('Please wait while importing Objects...'), null, 5000);
                         $('#progress .determinate').removeClass('determinate').addClass('indeterminate');
                         $('#onlyAddNewObjects').addClass('disabled');
-                        sendTo(null, 'project', { xml: event.target.result }, function (result) {
+                        sendTo(null, 'import', { xml: event.target.result, onlyAddNewObjects: $('#onlyAddNewObjects').prop('checked') }, function (result) {
                             $('#onlyAddNewObjects').removeClass('disabled');
                             $('.file-field .btn').removeClass('disabled');
                             $('.file-field .file-path').prop('disabled', false);
@@ -299,7 +283,11 @@
                                 showMessage(_('Error: ') + (result ? result.error : _('Unknown')));
                             } else {
                                 showMessage(_('Extracted %s states', result.count));
-                                sendTo(null, 'reload', null);
+                                sendTo(null, 'reset', null);
+
+                                //todo enable save button
+                                $('.file-field .btn').addClass('enabled');
+                                $('.file-field .file-path').prop('enabled', true);
                             }
                         });
                     }
@@ -320,15 +308,12 @@
             // I will check only 2 first numbers of ipV4
             var i1 = ip1.split('.');
             var i2 = ip2.split('.');
-
             // If ipv6 or DNS name
             if (i1.length !== i2.length || i1.length !== 4) return 1;
-
             if (i1[0] !== i2[0]) return 0;
             if (i1[1] !== i2[1]) return 1;
             if (i1[2] !== i2[2]) return 2;
             if (i1[3] !== i2[3]) return 3;
-
             return 4;
         }
 
@@ -348,11 +333,9 @@
         }
 
 
-
         //todo ??
         $('.switch').find('input[type=checkbox]').on('change', function () {
             var status = $(this).prop('checked');
-
             $.ajax({
                 url: url,
                 type: 'post',
@@ -360,35 +343,6 @@
             })
         });
 
-
-        //todo ??
-        var modalInstance;
-        document.addEventListener('DOMContentLoaded', function () {
-            var modalelem = document.querySelector(".modal");
-            modalInstance = M.Modal.init(modalelem);
-        });
-
-        //todo ??
-        function openPasswordModal() {
-            //            document.getElementById("password").value = "";
-            modalInstance.open();
-        };
-
-        //todo ??
-        function getPassword() {
-            openPasswordModal(this);
-            //          passwordOKBtn.onclick = function() {
-            //              console.log(document.getElementById("password").value);
-            //              modalInstance.value = document.getElementById("password");
-            //              modalInstance.close();
-            //          }
-        }
-
-        function closePasswordModal() {
-            //console.log(document.getElementById("password").value);
-            modalInstance.close();
-        }
-
         function disableAllDialogs() {
             $('.c-tab').removeClass('tab-active');
             var x = document.getElementsByClassName("dialog");
@@ -404,12 +358,14 @@
             x.style.display = "block";
         }
 
+        /*
         function showDebugDialog() {
             disableAllDialogs();
             $('.dialog-debug').addClass('tab-active');
             var x = document.getElementById("debugDialog");
             x.style.display = "block";
         }
+        */
 
     </script>
 </head>
@@ -417,16 +373,17 @@
 <body>
     <!-- you have to put your config page in a div with id adapter-container -->
     <div class="m adapter-container">
+        <!--
         <nav>
             <div class="nav-wrapper">
                 <a href="#!" class="brand-logo"><img src="openknx.png" width="65" height="auto" alt="logo" /></a>
                 <ul class="right hide-on-med-and-down">
                     <li><a onclick="showConfigDialog()" class="dialog-config c-tab translate">Configuration</a></li>
-                    <!-- <li><a onclick="showDebugDialog()" class="dialog-debug c-tab translate">Debug</a></li>-->
+                    <li><a onclick="showDebugDialog()" class="dialog-debug c-tab translate">Debug</a></li>
                 </ul>
             </div>
         </nav>
-
+        -->
         <div id="passwordModal" class="modal" role="dialog">
             <div class="modal-dialog">
                 <div class="modal-content">

package/admin/words.js

@@ -168,9 +168,9 @@ systemDictionary = {
         "es": "Escuchar en todas las direcciones IP",
         "pl": "Posłuchaj na wszystkich IP"
     },
-    "Please wait while generating Objects.....it could take a while.": {
-        "en": "Please wait while generating Objects.....it could take a while.",
-        "de": "Bitte warten Sie, während Sie Objekte erzeugen ..... es könnte eine Weile dauern.",
+    "Please wait while generating Objects...": {
+        "en": "Please wait while generating Objects...",
+        "de": "Bitte warten Sie, während Sie Objekte erzeugen...",
         "ru": "Подождите, пока вы создадите объекты ..... это может занять некоторое время.",
         "pt": "Aguarde enquanto gera objetos ..... pode demorar um pouco.",
         "nl": "Even geduld met het genereren van objecten ... het kan even duren.",
@@ -181,7 +181,7 @@ systemDictionary = {
     },
     "Extracted %s states": {
         "en": "Extracted %s states",
-        "de": "Es wurde %s Objekte extrahiert",
+        "de": "Es wurden %s Objekte extrahiert",
         "ru": "Извлечено %s объектов",
         "pt": "Estados extraídos %s",
         "nl": "Geëxtrade %s toestanden",