iobroker.openknx 0.2.3 → 0.2.4

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.
@@ -306,8 +304,11 @@ Data is sent to Iobroker Sentry server hosted in Germany. If you have allowed io
 - only IPv4 supported
 
 ## Changelog
-### 0.2.3 (2022-05-26)
-* feature: writing to bus l_data.con creates a ack on the iobroker object if successful (the knx conf flag unset)
+## 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) #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/lib/knx/.gitignore

@@ -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