iobroker.openknx 0.2.2 → 0.2.5

package/README.md

@@ -31,10 +31,6 @@ IP of your KNX IP gateway.
 ### Port
 this is normally port 3671 of the KNX IP gateway.
 
-### phys. KNX Adress
-Fill in physical address of the KNX IP gateway in the format 1/1/1.
-Two level group addresses can be transformed manually if needed.
-
 ### Local IPv4 network interface
 The interface that is connected to the KNX IP gateway.
 
@@ -42,7 +38,9 @@ The interface that is connected to the KNX IP gateway.
 Searches via a standardized protocol all available KNX IP Gateways on the given network interface.
 
 ### Frames delay [ms]
-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. If you experience disconnects from your KNX IP Gateway  in the log then increase this number.
+This settings protects the KNX bus from data flooding by limiting data frames to a certain rate.
+Not sent frames are delay until the delay time since last send on bus is elapsed. If more send requests are waiting, send order is random.
+If you experience disconnects from your KNX IP Gateway  in the log then increase this number.
 
 ### Add only new Objects
 If checked, the import will skip overwriting existing communication objects.
@@ -147,36 +145,38 @@ IoBroker state roles (https://github.com/ioBroker/ioBroker/blob/master/doc/STATE
 
 Autoread is set to false where it is clear from the DPT that this is a trigger signal. This applies to scene numbers.
 
-    {
-    "_id": "path.and.name.to.object",                       //derieved from the KNX structure
+```json
+{
+    "_id": "path.and.name.to.object",                       // derieved from the KNX structure
     "type": "state",
-    "common": {                                             //values here can be interpreted by iobroker
-        "desc": "Basetype: 1-bit value, Subtype: switch",   //informative, 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": state,                                      //default state, derieved from DPT
-        "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
+    "common": {                                             // values here can be interpreted by iobroker
+        "desc": "Basetype: 1-bit value, Subtype: switch",   // informative, 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": "state",                                    // default state, derieved from DPT
+        "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": {                                             //values here can be interpreted by openknx adapter
-        "address": "0/1/2",                                 //knx group address
-        "answer_groupValueResponse": false,                 //default false, if set to true adapter responds with value on GroupValue_Read
-        "autoread": true,                                   //default true for non trigger signals , 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
+    "native": {                                             // values here can be interpreted by openknx adapter
+        "address": "0/1/2",                                 // knx group address
+        "answer_groupValueResponse": false,                 // default false, if set to true adapter responds with value on GroupValue_Read
+        "autoread": true,                                   // default true for non trigger signals , 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": "",                               //informative
-        "signedness": "",                                   //informative
-        "valuetype": "basic"                                //composite means set via a specific javascript object
+        "force_encoding": "",                               // informative
+        "signedness": "",                                   // informative
+        "valuetype": "basic"                                // composite means set via a specific javascript object
     },
     "from": "system.adapter.openknx.0",
     "user": "system.user.admin",
     "ts": 1638913951639
-    }
+}
+```
 
 # Adapter communication Interface Description
 Handeled DPTs are: 1-21,232,237,238  
@@ -186,27 +186,31 @@ Where number datatype is used please note that interface values can be scaled.
 ### API call
 IoBroker defines States as communication interface.
 
-    setState(
-    @param {string}                                 id of the object with path
-    @param {object|string|number|boolean}           state simple value or object with attribues.
-    {
-    val:    value,
-    ack:    true|false,                             optional, should be false by convention
-    ts:     timestampMS,                            optional, default - now
-    q:      qualityAsNumber,                        optional, set it to value 0x10 to trigger a bus read to this object, given StateValue is ignored
-    from:   origin,                                 optional, default - this adapter
-    c:      comment,                                optional, set it to value GroupValue_Read to trigger a bus read to this object, given StateValue is ignored
-    expire: expireInSeconds                         optional, default - 0
-    lc:     timestampMS                             optional, default - calculated value
-    }
-    @param {boolean} [ack]                          optional, should be false by convention
-    @param {object} [options]                       optional, user context
-    @param {ioBroker.SetStateCallback} [callback]   optional, return error and id
+```javascript
+setState(
+    '',                                             // @param {string}                                id of the object with path
+    {                                               // @param {object|string|number|boolean}          state simple value or object with attribues.
+	val:    value,
+	ack:    true|false,                         // optional, should be false by convention
+	ts:     timestampMS,                        // optional, default - now
+	q:      qualityAsNumber,                    // optional, set it to value 0x10 to trigger a bus read to this object, given StateValue is ignored
+	from:   origin,                             // optional, default - this adapter
+	c:      comment,                            // optional, set it to value GroupValue_Read to trigger a bus read to this object, given StateValue is ignored
+	expire: expireInSeconds                     // optional, default - 0
+	lc:     timestampMS                         // optional, default - calculated value
+    },
+    false,                                          // @param {boolean} [ack]                         optional, should be false by convention
+    {},                                             // @param {object} [options]                      optional, user context
+    (err, id) => {}                                 // @param {ioBroker.SetStateCallback} [callback]  optional, return error and id
+);
+```
 
 example to trigger a GroupValue_Read:
 
-    setState(myState, {val: false, ack: false, c:'GroupValue_Read'});
-    setState(myState, {val: false, ack: false, q:0x10});
+```javascript
+setState(myState, {val: false, ack: false, c:'GroupValue_Read'});
+setState(myState, {val: false, ack: false, q:0x10});
+```
 
 GroupValue_Read comment does not work for javascript adapter. Use qualityAsNumber value 0x10 instead.
 
@@ -306,8 +310,14 @@ Data is sent to Iobroker Sentry server hosted in Germany. If you have allowed io
 - only IPv4 supported
 
 ## Changelog
+## 0.2.5 (2022-06-22)
+* feature: option remove existing KNX objects that are not in import file
+
+## 0.2.4 (2022-05-27)
+* feature: cleanly disconnect on shutdown, upgrade to knx lib 2.5.2
+
 ### 0.2.2 (2022-05-26)
-* feature: writing to bus l_data.con creates a ack on the iobroker object if successful (the knx conf flag unset)
+* feature: writing to bus l_data.con creates a ack on the iobroker object if successful (the knx conf flag unset) #133
 * bugfix: remove manual Physical KNX address dialog, use 0.0.0 instead
 * bugfix: remove error log when answering to GroupValueRead: #183
 * bugfix: improve warning logs on intended and unintended disconnects

package/admin/index_m.html

@@ -64,6 +64,7 @@
                 this.getIsAdapterAlive(function (isAlive) {
                     if (isAlive && !window.isProcessingRequest) {
                         $("#onlyAddNewObjects").removeClass("disabled");
+                        $("#removeUnusedObjects").removeClass("disabled");
                         $("#setAckOnWrite").removeClass("disabled");
                         $(".file-field .btn").removeClass("disabled");
                         $(".file-field .file-path").prop("disabled", false);
@@ -79,6 +80,7 @@
             if (settings.gwipport === undefined) settings.gwipport = 3671;
             if (settings.minimumDelay === undefined) settings.minimumDelay = 50;
             if (settings.onlyAddNewObjects === undefined) settings.onlyAddNewObjects = false;
+            if (settings.removeUnusedObjects === undefined) settings.removeUnusedObjects = false;
             if (settings.localInterface === undefined) settings.localInterface = "";
             if (settings.setAckOnWrite === undefined) settings.setAckOnWrite = false;
 
@@ -218,7 +220,7 @@
                     $("#etsFile").change(processXmlFile);
                     showToast(null, _("Import started..."), null, 3000);
                     $("#progress").show();
-                    sendTo(null, "import", { xml: event.target.result, onlyAddNewObjects: $("#onlyAddNewObjects").prop("checked") }, function (result) {
+                    sendTo(null, "import", { xml: event.target.result, onlyAddNewObjects: $("#onlyAddNewObjects").prop("checked"), removeUnusedObjects: $("#removeUnusedObjects").prop("checked") }, function (result) {
                         $("#progress").hide();
                         if (!result || result.error) {
                             let message = "Unknown error"
@@ -372,7 +374,11 @@
                     <div class="row">
                         <div class="col s12 input-field">
                             <input class="value" id="onlyAddNewObjects" type="checkbox" />
-                            <label class="translate" for="onlyAddNewObjects">add only new Objects</label>
+                            <label class="translate" for="onlyAddNewObjects">store only additionally found GAs</label>
+                        </div>
+                        <div class="col s12 input-field">
+                            <input class="value" id="removeUnusedObjects" type="checkbox" />
+                            <label class="translate" for="removeUnusedObjects">remove existing KNX objects that are not in import file</label>
                         </div>
 
                         <div class="col s12 m12 l6 file-field input-field">

package/io-package.json

@@ -1,9 +1,9 @@
 {
     "common": {
         "name": "openknx",
-        "version": "0.2.2",
+        "version": "0.2.5",
         "news": {
-            "0.2.2": {
+            "0.2.5": {
                 "en": "see https://www.npmjs.com/package/iobroker.openknx",
                 "de": "https://www.npmjs.com/package/iobroker.openknx"
             }

package/lib/knx/.gitignore

@@ -0,0 +1,2 @@
+.tags*
+node_modules

package/lib/knx/.npmignore

@@ -0,0 +1,2 @@
+.tags*
+node_modules

package/lib/knx/README-API.md

@@ -136,3 +136,21 @@ 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'))
 ```
+
+### Disconnect
+
+In order to cleanly disconnect, you must send the Disconnect-Request and give the KNX-IP-Stack enough time to receive the Disconnect-Response back from the IP Gateway. Most IP-Gateways will have a timeout and clean stale connection up, even if you do not disconect cleanly, but depending on the limits on the number of parallel active connections, this will limit your ability to re-connect until the timeout has passed.
+
+For NodeJS cleaning up when the script exits, this requires something like [async-exit-hook](https://www.npmjs.com/package/async-exit-hook):
+
+```js
+const exitHook = require('async-exit-hook');
+
+exitHook(cb => {
+  console.log('Disconnecting from KNX…');
+  connection.Disconnect(() => {
+    console.log('Disconnected from KNX');
+    cb();
+  });
+});
+```

package/lib/knx/index.d.ts

@@ -17,7 +17,7 @@ type ConnectionSpec = {
     debug?: boolean,
     manualConnect?: true,
     minimumDelay?: number,
-    handlers: HandlersSpec,
+    handlers?: HandlersSpec,
 }
 
 type KnxDeviceAddress = string
@@ -42,17 +42,39 @@ interface DatapointEvent {
 }
 
 declare module 'knx' {
-    export interface IConnection extends events.EventEmitter {
+    type MachinaEventsCallback = (...args: any[]) => void
+
+    interface MachinaEventsReturn {
+        eventName: string
+        callback: MachinaEventsCallback
+        off: () => void
+    }
+
+    class MachinaEvents {
+        emit(eventName: string): void
+        on(eventName: string, callback: MachinaEventsCallback): MachinaEventsReturn
+        off(eventName?: string, callback?: MachinaEventsCallback): void
+    }
+
+    interface MachinaEventsReturn {
+        eventName: string
+        callback: MachinaEventsCallback
+        off: () => void
+    }
+
+    export interface IConnection extends MachinaEvents {
         debug: boolean
-        Disconnect(): void
+        Connect(): void
+        Disconnect(cb?: Function): void
         read( ga: KnxGroupAddress, cb?: (value: Buffer) => void ): void
         write( ga: KnxGroupAddress, value: Buffer, dpt: DPT, cb?: () => void): void
     }
 
-    export class Connection extends events.EventEmitter implements IConnection {
+    export class Connection extends MachinaEvents implements IConnection {
         public debug: boolean
         constructor( conf: ConnectionSpec )
-        Disconnect(): void
+        Connect(): void
+        Disconnect(cb?: Function): void
         read( ga: KnxGroupAddress, cb?: (value: Buffer) => void ): void
         write( ga: KnxGroupAddress, value: Buffer, dpt: DPT, cb?: () => void): void
         writeRaw( ga: KnxGroupAddress, value: Buffer, bitlength?: number, cb?: () => void): void