added a timeout to discovery, extended documentation

Author: AlCalzone

README.md

@@ -7,22 +7,24 @@ Library to talk to IKEA Trådfri Gateways without external binaries
 *Requires NodeJS >= 6.x*
 
 ## Example usage
-### Discover Tradfri Gateway
 
-You can discover one (currently its not possible to discover multiple gateways) Tradfri Gateways.
-
-```TS
+### Discover a Gateway
+```js
 import { discoverGateway } from "node-tradfri-client";
 
-discoverGateway().then(result => console.log(result));
+// later:
+const result = await discoverGateway();
 ```
 
-If the search is successful it will return
-
-```
-{ name: 'gw-a0cc2bf8535d',
- version: '1.3.14',
- addresses: [ '10.0.0.94', 'fe80::a2cc:2bff:fef8:535d' ] }
+The `result` variable has the following properties:
+```js
+{
+    name: 'gw-abcdef012345',
+    version: '1.3.14',
+    addresses: [ 
+        // array of strings with IP addresses
+    ]
+}
 ```
 
 
@@ -99,12 +101,44 @@ tradfri.destroy();
 
 ## Detailed usage
 
+### Import the necessary methods
 ```TS
 const tradfriLib = require("node-tradfri-client");
+// for normal usage:
 const TradfriClient = tradfriLib.TradfriClient;
+// for discovery:
+const discoverGateway = tradfriLib.discoverGateway;
+
 // or with the new import syntax
-import { TradfriClient /*, more imports */ } from "node-tradfri-client";
+import { discoverGateway, TradfriClient /*, more imports */ } from "node-tradfri-client";
+```
+
+### Auto-detect your gateway
+You can automatically discover a Trådfri gateway on the local network with the `discoverGateway` method. Discovery will return the first gateway found, finding multiple ones is not possible yet.
 
+The method has the following signatures:
+```TS
+const discovered = await discoverGateway();
+const discovered = await discoverGateway(timeout: number);
+const discovered = await discoverGateway(false);
+```
+The timeout parameter is the time in milliseconds (default 10000) the discovery will run before returning `null` to indicate that no gateway was found. By passing a negative value or `false` you can instruct the discovery to run *forever*.
+
+The return value is of the type `DiscoveredGateway` which looks as follows:
+```ts
+{
+    // hostname of the gateway, has the form "gw-abcdef012345"
+    name: string,
+    // firmware version of the gateway
+    version: string,
+    // array of IP addresses the gateway responds to
+    addresses: string[],
+}
+```
+
+
+### Create a client instance
+```TS
 // one of the following
 const tradfri = new TradfriClient(hostname: string);
 const tradfri = new TradfriClient(hostname: string, customLogger: LoggerFunction);

build/lib/discovery.d.ts

@@ -3,4 +3,9 @@ export interface DiscoveredGateway {
     version: string;
     addresses: string[];
 }
-export declare function discoverGateway(): Promise<DiscoveredGateway>;
+/**
+ * Auto-discover a tradfri gateway on the network.
+ * @param timeout (optional) Time in milliseconds to wait for a response. Default 10000.
+ * Pass false or a negative number to explicitly wait forever.
+ */
+export declare function discoverGateway(timeout?: number | false): Promise<DiscoveredGateway>;

build/lib/discovery.js

@@ -1,21 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const bonjourPackage = require("bonjour");
-const bonjour = bonjourPackage();
-function discoverGateway() {
+let bonjour;
+/**
+ * Auto-discover a tradfri gateway on the network.
+ * @param timeout (optional) Time in milliseconds to wait for a response. Default 10000.
+ * Pass false or a negative number to explicitly wait forever.
+ */
+function discoverGateway(timeout = 10000) {
+    if (bonjour == null)
+        bonjour = bonjourPackage();
+    let timer;
     return new Promise((resolve, reject) => {
         const mdnsBrowser = bonjour.findOne({ type: "coap", protocol: "udp" }, (service) => {
-            if (!service || !service.txt || !service.name.startsWith("gw-")) {
+            if (!service || !service.txt || !service.name.startsWith("gw-"))
                 return;
-            }
+            if (timer != null)
+                clearTimeout(timer);
             const foundDevice = {
                 name: service.name,
                 version: service.txt.version,
                 addresses: service.addresses,
             };
-            mdnsBrowser.stop();
             resolve(foundDevice);
         });
+        if (typeof timeout === "number" && timeout > 0) {
+            timer = setTimeout(() => {
+                if (mdnsBrowser != null)
+                    mdnsBrowser.stop();
+                resolve(null);
+            }, timeout);
+        }
         mdnsBrowser.start();
     });
 }

src/lib/discovery.ts

@@ -1,21 +1,28 @@
 import * as bonjourPackage from "bonjour";
+let bonjour: bonjourPackage.Bonjour;
 
 export interface DiscoveredGateway {
 	name: string;
 	version: string;
 	addresses: string[];
 }
 
-export function discoverGateway(): Promise<DiscoveredGateway> {
-  const bonjour = bonjourPackage();
+/**
+ * Auto-discover a tradfri gateway on the network.
+ * @param timeout (optional) Time in milliseconds to wait for a response. Default 10000. 
+ * Pass false or a negative number to explicitly wait forever.
+ */
+export function discoverGateway(timeout: number | false = 10000): Promise<DiscoveredGateway> {
+	if (bonjour == null) bonjour = bonjourPackage();
+	let timer: NodeJS.Timer;
 
 	return new Promise((resolve, reject) => {
 		const mdnsBrowser = bonjour.findOne(
 			{ type: "coap", protocol: "udp" },
 			(service: any) => {
-				if (!service || !service.txt || !service.name.startsWith("gw-")) {
-					return;
-				}
+				if (!service || !service.txt || !service.name.startsWith("gw-")) return;
+
+				if (timer != null) clearTimeout(timer);
 				const foundDevice = {
 					name: service.name,
 					version: service.txt.version,
@@ -24,6 +31,14 @@ export function discoverGateway(): Promise<DiscoveredGateway> {
 				resolve(foundDevice);
 			},
 		);
+
+		if (typeof timeout === "number" && timeout > 0) {
+			timer = setTimeout(() => {
+				if (mdnsBrowser != null) mdnsBrowser.stop();
+				resolve(null);
+			}, timeout);
+		}
+		
 		mdnsBrowser.start();
 	});
 }