iobroker.openknx 0.0.16 → 0.0.17

package/README.md

@@ -168,24 +168,23 @@ If the adapter startet successfully your datapoints will be available for commun
 
 ## Datapoint Types
 Wide DPT (datapoint type) support (DPT1 - DPT21, DPT232, DPT237, DPT238 supported)
+Values of unhandeled DPTs can be written and read out in raw format.
 
 # 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
 - IOBroker object role definition missing
 
 # limitations
-- only three level group address are supported
+- three level group address are only supported
 
 ## Changelog
-### 0.0.16
-* raw value handling
+### 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
 * import ga xml

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/io-package.json

@@ -1,7 +1,7 @@
 {
   "common": {
         "name": "openknx",
-        "version": "0.0.16",
+        "version": "0.0.17",
         "news": {
             "0.0.1": {
                 "en": "initial release",

package/lib/knx/AUTHORS

@@ -0,0 +1,3 @@
+Elias Karakoulakis <elias.karakoulakis@gmail.com>
+Mattias Holmlund <mattias@holmlund.se>
+Timo Müller <timomueller1993@gmail.com>

package/lib/knx/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2016 Elias Karakoulakis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/knx/README-API.md

@@ -0,0 +1,138 @@
+## Connect to your KNX IP router
+
+By default *you only need to specify a 'handlers' object* containing your functions to handle KNX events. All the other options have defaults that can be overridden according to your needs.
+
+
+```js
+var connection = new knx.Connection( {
+  // ip address and port of the KNX router or interface
+  ipAddr: '127.0.0.1', ipPort: 3671,
+  // in case you need to specify the multicast interface (say if you have more than one)
+  interface: 'eth0',
+  // the KNX physical address we'd like to use
+  physAddr: '15.15.15',
+  // set the log level for messsages printed on the console. This can be 'error', 'warn', 'info' (default), 'debug', or 'trace'.
+  loglevel: 'info',
+  // do not automatically connect, but use connection.Connect() to establish connection
+  manualConnect: true,  
+  // use tunneling with multicast (router) - this is NOT supported by all routers! See README-resilience.md
+  forceTunneling: true,
+  // wait at least 10 millisec between each datagram
+  minimumDelay: 10,
+  // enable this option to suppress the acknowledge flag with outgoing L_Data.req requests. LoxOne needs this
+  suppress_ack_ldatareq: false,
+  // 14/03/2020 In tunneling mode, echoes the sent message by emitting a new emitEvent, so other object with same group address, can receive the sent message. Default is false.
+  localEchoInTunneling:false,
+  // define your event handlers here:
+  handlers: {
+    // wait for connection establishment before sending anything!
+    connected: function() {
+      console.log('Hurray, I can talk KNX!');
+      // WRITE an arbitrary boolean request to a DPT1 group address
+      connection.write("1/0/0", 1);
+      // you also WRITE to an explicit datapoint type, eg. DPT9.001 is temperature Celcius
+      connection.write("2/1/0", 22.5, "DPT9.001");
+      // you can also issue a READ request and pass a callback to capture the response
+      connection.read("1/0/1", (src, responsevalue) => { ... });
+    },
+    // get notified for all KNX events:
+    event: function(evt, src, dest, value) { console.log(
+        "event: %s, src: %j, dest: %j, value: %j",
+        evt, src, dest, value
+      );
+    },
+    // get notified on connection errors
+    error: function(connstatus) {
+      console.log("**** ERROR: %j", connstatus);
+    }
+  }
+});
+```
+
+**Important**: connection.write() will only accept *raw APDU payloads* and a DPT.
+This practically means that for *reading and writing to anything other than a binary
+switch* (eg. for dimmer controls) you'll need to declare one or more *datapoints*.
+
+### Declare datapoints based on their DPT
+
+Datapoints correlate an *endpoint* (identifed by a group address such as '1/2/3')
+with a *DPT* (DataPoint Type), so that *serialization* of values to and from KNX
+works correctly (eg. temperatures as 16bit floats), and values are being translated
+to Javascript objects and back.
+
+```js
+// declare a simple binary control datapoint
+var binary_control = new knx.Datapoint({ga: '1/0/1', dpt: 'DPT1.001'});
+// bind it to the active connection
+binary_control.bind(connection);
+// write a new value to the bus
+binary_control.write(true); // or false!
+// send a read request, and fire the callback upon response
+binary_control.read( function (response) {
+    console.log("KNX response: %j", response);
+  };
+// or declare a dimmer control
+var dimmer_control = new knx.Datapoint({ga: '1/2/33', dpt: 'DPT3.007'});
+// declare a binary STATUS datapoint, which will automatically read off its value
+var binary_status = new knx.Datapoint({ga: '1/0/1', dpt: 'DPT1.001', autoread: true});
+```
+
+Datapoints need to be bound to a connection. This can be done either at their
+creation, *or* using their `bind()` call. Its important to highlight that before
+you start defining datapoints (and devices as we'll see later), your code
+*needs to ensure that the connection has been established*, usually by declaring them in the 'connected' handler:
+
+```js
+var connection = knx.Connection({
+  handlers: {
+    connected: function() {
+      console.log('----------');
+      console.log('Connected!');
+      console.log('----------');
+      var dp = new knx.Datapoint({ga: '1/1/1'}, connection);
+      // Now send off a couple of requests:
+      dp.read((src, value) => {
+        console.log("**** RESPONSE %j reports current value: %j", src, value);
+      });
+      dp.write(1);
+    }
+  }
+});
+```
+
+### Declare your devices
+
+You can define a device (basically a set of GA's that are related to a
+physical KNX device eg. a binary switch) so that you have higher level of control:
+
+```js
+var light = new knx.Devices.BinarySwitch({ga: '1/1/8', status_ga: '1/1/108'}, connection);
+console.log("The current light status is %j", light.status.current_value);
+light.control.on('change', function(oldvalue, newvalue) {
+  console.log("**** LIGHT control changed from: %j to: %j", oldvalue, newvalue);
+});
+light.status.on('change', function(oldvalue, newvalue) {
+  console.log("**** LIGHT status changed from: %j to: %j", oldvalue, newvalue);
+});
+light.switchOn(); // or switchOff();
+```
+
+This effectively creates a pair of datapoints typically associated with a binary
+switch, one for controlling it and another for getting a status feedback (eg via
+manual operation)
+
+### Write raw buffers
+
+If you encode the values by yourself, you can write raw buffers with `writeRaw(groupaddress: string, buffer: Buffer, bitlength?: Number, callback?: () => void)`.
+
+The third (optional) parameter `bitlength` is necessary for datapoint types
+where the bitlength does not equal the buffers bytelength * 8.
+This is the case for dpt 1 (bitlength 1), 2 (bitlength 2) and 3 (bitlength 4).
+For other dpts the paramter can be omitted.
+
+```js
+// Write raw buffer to a groupaddress with dpt 1 (e.g light on = value true = Buffer<01>) with a bitlength of 1
+connection.writeRaw('1/0/0', Buffer.from('01', 'hex'), 1)
+// Write raw buffer to a groupaddress with dpt 9 (e.g temperature 18.4 °C = Buffer<0730>) without bitlength
+connection.writeRaw('1/0/0', Buffer.from('0730', 'hex'))
+```

package/lib/knx/README-datapoints.md

@@ -0,0 +1,62 @@
+## Datapoint Types
+
+|DPT   	  | Description       | Value type  	| Example  	| Notes |
+|---	    |---	                  |---	|---	|---	|
+|DPT1   	| 1-bit control  	      | Boolean/Numeric	|  true/"true"/1 false/"false"/0 | |
+|DPT2   	| 1-bit control w/prio  | Object  	| {priority: 0, data: 1}  	|   |
+|DPT3   	| 4-bit dimming/blinds  | Object  	| {decr_incr: 1, data: 0}  	|   data: 3-bit (0..7)|
+|DPT4   	| 8-bit character  	|   String	| "a"  	|   1st char must be ASCII	|
+|DPT5   	| 8-bit unsigned int  | Numeric | 127  	|  0..255 	|
+|DPT6   	| 8-bit signed int  	| Numeric | -12  	|  -128..127 	|
+|DPT7   	| 16-bit unsigned int  | Numeric  |   	|  0..65535 	|
+|DPT8   	| 16-bit signed integer | Numeric |   	|  -32768..32767 |
+|DPT9   	| 16-bit floating point | Numeric |   	|   	|
+|DPT10   	| 24-bit time + day of week 	|   Date	|  new Date() |   only the time part is used, see note |
+|DPT11   	| 24-bit date 	|   Date	|  new Date() |   only the date part is used, see note |
+|DPT12   	| 32-bit unsigned int | Numeric |   	|   	|
+|DPT13   	| 32-bit signed int   | Numeric |   	|   	|
+|DPT14   	| 32-bit floating point | Numeric |   	|  incomplete: subtypes |
+|DPT15   	| 32-bit access control |  |   	|   incomplete|
+|DPT16   	| ASCII string 	|  String |   	|   	|
+|DPT17   	| Scene number 	|   	|   	|  incomplete|
+|DPT18   	| Scene control 	|   	|   	|   incomplete|
+|DPT19   	| 8-byte Date and Time 	|  Date | new Date() |   	|
+|DPT20-255 | feel free to contribute! 	|   |  |   	|
+
+
+When you add new DPT's, please ensure that you add the corresponding unit test
+under the `test/dptlib` subdirectory. The unit tests come with a small helper
+library that provides the boilerplate code to marshal and unlarshal your test cases.
+
+Take for example the unit test for DPT5, which carries a single-byte payload.
+Some of its subtypes (eg. 5.001 for percentages and 5.003 for angle degrees)
+need to be scaled up or down, whereas other subtypes *must not* be scaled at all:
+
+```js
+// DPT5 without subtype: no scaling
+commontest.do('DPT5', [
+  { apdu_data: [0x00], jsval: 0},
+  { apdu_data: [0x40], jsval: 64},
+  { apdu_data: [0x41], jsval: 65},
+  { apdu_data: [0x80], jsval: 128},
+  { apdu_data: [0xff], jsval: 255}
+]);
+// 5.001 percentage (0=0..ff=100%)
+commontest.do('DPT5.001', [
+  { apdu_data: [0x00], jsval: 0 },
+  { apdu_data: [0x80], jsval: 50},
+  { apdu_data: [0xff], jsval: 100}
+]);
+// 5.003 angle (degrees 0=0, ff=360)
+commontest.do('DPT5.003', [
+  { apdu_data:  [0x00], jsval: 0 },
+  { apdu_data:  [0x80], jsval: 181 },
+  { apdu_data:  [0xff], jsval: 360 }
+]);
+```
+
+## Date and time DPTs (DPT10, DPT11)
+Please have in mind that Javascript and KNX have very different base type for time and date.
+
+- 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*.

package/lib/knx/README-events.md

@@ -0,0 +1,50 @@
+## Events
+
+There's a ton of information being emitted by the library, so you can get full disclosure as to what's going on under the hood.
+
+### Connection events
+
+```js
+// Generic groupwrite event: device with 'src' physical address wrote to 'dest' group address
+connection.on('GroupValue_Write', function (src, dest, value) { ... });
+// Generic groupread event: device with physical address 'src', is asking on the KNX
+// bus the current value of group address 'dest'
+connection.on('GroupValue_Read', function (src, dest) { ... });
+// response event: device with physical address 'src', is responding to a
+// read request that the current value of group address 'dest' is 'value'
+connection.on('GroupValue_Response', function (src, dest, value) { ... });
+
+// Specific group address event: device with 'src' physical address
+// .. wrote to group address
+connection.on('GroupValue_Write_1/2/3', function (src, value) { ... });
+// .. or responded about current value
+connection.on('GroupValue_Response_1/2/3', function (src, value) { ... });
+
+// there's also the generic catch-all event which passes the event type
+// as its 1st argument, along with all the other info
+connection.on('event', function (evt, src, dest, value) { ... });)
+// the generic catch-all event can also be used with group addresses
+connection.on('event_1/2/3', function (evt, src, dest, value) { ... });)
+```
+
+Here's the full list of events emitted by the connection:
+```
+["GroupValue_Read", "GroupValue_Response", "GroupValue_Write",
+"PhysicalAddress_Write",  "PhysicalAddress_Read", "PhysicalAddress_Response",
+"ADC_Read", "ADC_Response", "Memory_Read", "Memory_Response", "Memory_Write",
+"UserMemory", "DeviceDescriptor_Read", "DeviceDescriptor_Response",
+"Restart", "OTHER"]
+```
+
+Other connection events:
+```js
+// an outgoing tunnelling request didn't get any acknowledgement
+connection.on('unacknowledged', function (datagram) { ... });)
+```
+
+### Datapoint events
+
+```js
+// a datapoint has had its value changed
+datapoint.on('change', function(oldvalue, newvalue){...});
+```

package/lib/knx/README-knxd.md

@@ -0,0 +1,5 @@
+**Please note**: if you use `eibd` or `knxd` as your IP router, and you have it running on the **same** box as your NodeJS app, then eibd/knxd will DROP multicast packets coming from the same source IP address. This is meant to prevent endless loops: if by error knxd is configured also as a client (that will join the same multicast group), then a multicast storm will flood your LAN. I'm sure you've experienced something similar if you take a microphone connected to an amplifier and put it near the speakers (ECHO!)
+
+`Layer 0 [11:server/Server     7.133] Dropped(017): 06 10 05 30 00 11 29 00 BC D0 11 64 29 0F 01 00 80`
+
+The trick here (although not entirely within the specs) is to use the loopback interface, so if you define the KNX connection address/port to `127.0.0.1:3671` then this will bypass the source address check (and happily route your packets down your USB or TPUART interface).

package/lib/knx/README-resilience.md

@@ -0,0 +1,38 @@
+## And why should I bother?
+
+The main cause for writing my own KNX protocol stack is that I couldn't find a *robust* access layer that properly handles state management.
+Connections tend to fail all the time; consider flakey Wi-Fi, RRR's (Recalcitrant Rebooting Routers), bad karma, it happens all the time. A KNX access layer should be *resilient* and be able to recover if needed.
+
+Also, although seemingly innocent, the consecutive calls to *read()* and then *write()* on the same group address will either *confuse* your KNX IP router, or *return incoherent results*.
+KNXnet/IP uses **UDP** sockets, which is not ideal from a programmer's perspective. Packets can come and go in any order; very few libraries offer the robustness to reconcile state and ensure a **steady and reliable connection**.
+
+This library is, to the best of my knowledge, the only one that can handle the *serialisation* of tunneling requests in a way that your program will have a *robust and reliable* KNX connection. Try toggling your Wi-Fi or disconnect your Ethernet cable while you're connected; the library will detect this and reconnect when network access is restored :)
+
+```
+27 Oct 15:44:24 - [info] Started flows
+27 Oct 15:44:24 - [info] [knx-controller:9ab91ab8.547938] KNX: successfully connected to 224.0.23.12:3671
+27 Oct 15:44:24 - [info] [knx-controller:9ab91ab8.547938] GroupValue_Read {"srcphy":"15.15.15","dstgad":"0/0/15"}
+...
+27 Oct 15:44:54 - [info] [knx-controller:9ab91ab8.547938] KNX Connection Error: timed out waiting for CONNECTIONSTATE_RESPONSE
+27 Oct 15:45:36 - [info] [knx-controller:9ab91ab8.547938] KNX: successfully connected to 224.0.23.12:3671
+27 Oct 15:45:36 - [info] [knx-in:input] GroupValue_Read {"srcphy":"15.15.15","dstgad":"0/0/15"}
+```
+
+
+## A note on resilience
+
+There are basically *two* ways to talk to KNX via UDP/IP:
+
+- **Tunneling** is effectively UDP **unicast** with connection state (essentially mimicking TCP), thus we get to make a CONNECT_REQUEST to establish a session id with the router or interface. This enables us to periodically check on the connection's health (with CONNECTIONSTATE_REQUESTs) and handle retries, acknowledgements etc. The disadvantage here is that KNXnet/IP lacks a service discovery mechanism, thus you need to specify the router/interface endpoint IP address and port.
+
+- **Routing** is a plain UDP multicast transport *without any connection or reliability semantics whatsoever* - which makes it much harder to detect dropped packets eg due to congested networks. The multicast approach works well on wired high-speed (eg Ethernet) segments that are dedicated to KNX traffic only. As we all know, KNX/TP1 has a bandwidth that is several orders of magnitude slower than a LAN, but this isn't necessarily the case when you connect over a VPN! *In reality, your network is definately going to drop some packets*. The advantage of multicast though is that it needs no configuration, as long as the IP router is configured to the default KNX multicast address (224.0.23.12)
+
+- Finally, this library allows a **hybrid** approach, that's taking the best of the two methods above: You can use **multicast** transport with a **tunnelling** connection to ensure reliable communication. *Unfortunately this deviates from the official KNXnet/IP spec*, and is therefore not compatible with some IP routers. You can enable this "hybrid mode" by enabling the `forceTunneling` option when constructing a new Connection object as follows:
+
+```js
+var connection = new knx.Connection( {
+  // use tunneling with multicast - this is NOT supported by all routers!
+  forceTunneling: true,
+...
+});
+```

package/lib/knx/README.md

@@ -0,0 +1,54 @@
+## KNXnet/IP for Node.JS
+
+**New:** [Join the Gitter.im chatroom!](https://gitter.im/knx-js/Lobby)
+
+A feature-complete [KNXnet/IP protocol stack](https://www.knx.org/en-us/knx/technology/developing/devices/ip-devices/index.php) in pure Javascript, capable of talking multicast (routing) and unicast (tunneling). Adding KNX to your Node.JS applications is now finally easy as pie.
+
+* Wide DPT (datapoint type) support (DPT1 - DPT20 supported)
+* Extensible Device support (binary lights, dimmers, ...)
+* You won't need to install a specialised eibd daemon with its arcane dependencies  and most importantly,
+* If you got an IP router and a network that supports IP multicast, you can start talking to KNX within seconds!
+
+## Installation
+
+Make sure your machine has Node.JS (version 4.x or greater) and do:
+
+`npm install knx`
+
+## Usage
+
+At last, here's a **reliable** KNX connection that simply works without any configs. To get a basic KNX monitor, you just need to run this in Node:
+
+```js
+var knx = require('knx');
+var connection = knx.Connection({
+ handlers: {
+  connected: function() {
+    console.log('Connected!');
+  },
+  event: function (evt, src, dest, value) {
+  console.log("%s **** KNX EVENT: %j, src: %j, dest: %j, value: %j",
+    new Date().toISOString().replace(/T/, ' ').replace(/\..+/, ''),
+    evt, src, dest, value);
+  }
+ }
+});
+```
+
+Ahhh, KNX telegrams, what a joy:
+
+```
+> 2016-09-24 05:34:07 **** KNX EVENT: "GroupValue_Write", src: "1.1.100", dest: "5/0/8", value: 1
+2016-09-24 05:34:09 **** KNX EVENT: "GroupValue_Write", src: "1.1.100", dest: "5/1/15", value: 0
+2016-09-24 05:34:09 **** KNX EVENT: "GroupValue_Write", src: "1.1.100", dest: "5/0/8", value: 0
+2016-09-24 05:34:17 **** KNX EVENT: "GroupValue_Write", src: "1.1.100", dest: "5/1/15", value: 0
+2016-09-24 05:34:17 **** KNX EVENT: "GroupValue_Write", src: "1.1.100", dest: "5/0/8", value: 1
+```
+
+## Development documentation
+
+- [Basic API usage](../master/README-API.md)
+- [List of supported datapoints](../master/README-datapoints.md)
+- [List of supported events](../master/README-events.md)
+- [eibd/knxd compatibility](../master/README-knxd.md)
+- [On resilience](../master/README-resilience.md)

package/lib/knx/bitbucket-pipelines.yml

@@ -0,0 +1,7 @@
+image: node:current
+pipelines:
+  default:
+    - step:
+        script: # Modify the commands below to build your repository.
+          - npm install
+          - npm test