feat: added more granular control for the discovery process

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to `@homebridge/hap-client` will be documented in this file. This project tries to adhere to [Semantic Versioning](http://semver.org/).
 
+## v3.4.0 (2026-02-24)
+
+### Changed
+
+- more granular control for the discovery process
+
 ## v3.3.0 (2026-02-14)
 
 ### Changed

README.md

@@ -27,6 +27,33 @@ this.hapClient = new HapClient({
 this.monitor = await this.hapClient.monitorCharacteristics(services?: ServiceType[]);  // Creates event monitors for all event capabable Homebridge services.  If a list of services is, this list is used rather than all
 ```
 
+The discovery timeout can be configured by setting the `discoveryTimeout` property in the `config` object.
+```
+const { HapClient } = require('@homebridge/hap-client');
+
+this.hapClient = new HapClient({
+  config: { debug: true, discoveryTimeout: 5000 },
+  pin: config.username,
+  logger: this.log,
+});
+
+// the discovery process will auto-start now with the timout of 5 seconds
+```
+
+It's possible to control the discovery process manually, by settings the `autoStartDiscovery` property to `false` and then calling `this.hapClient.startDiscovery(discoveryTimeout?: number)` when ready. If no timeout is provided to the function, the `discoveryTimeout` property will be used from the `config` object, and if that is not provided either, the default discovery timeout (60 seconds) will be used.
+```
+const { HapClient } = require('@homebridge/hap-client');
+
+this.hapClient = new HapClient({
+  config: { debug: true, autoStartDiscovery: false, discoveryTimeout: 10000 },
+  pin: config.username,
+  logger: this.log,
+});
+
+await this.hapClient.startDiscovery(); // use the timeout provided in the config, 10000 ms
+await this.hapClient.startDiscovery(5000); // use the argument as timeout, 5000 ms
+```
+
 ## hap-client Events
 
 ```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebridge/hap-client",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "A client for HAP-NodeJS.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/index.ts

@@ -21,12 +21,17 @@ export class HapClient extends EventEmitter {
   private browser: Browser
   private discoveryInProgress = false
 
+  private readonly defaultDiscoveryTimeout: number = 60000
+  private readonly defaultAutoStartDiscovery: boolean = true
+
   private logger: any
   private pin: string
   private debugEnabled: boolean = false
   private config: {
     debug?: boolean
     instanceBlacklist?: string[]
+    discoveryTimeout: number
+    autoStartDiscovery: boolean
   }
 
   private instances: HapInstance[] = []
@@ -47,8 +52,14 @@ export class HapClient extends EventEmitter {
     this.pin = opts.pin
     this.logger = opts.logger || console // Fallback to console if no logger is provided
     this.debugEnabled = !!opts.config.debug
-    this.config = opts.config
-    this.startDiscovery()
+    this.config = {
+      ...opts.config,
+      discoveryTimeout: opts.config.discoveryTimeout ?? this.defaultDiscoveryTimeout,
+      autoStartDiscovery: opts.config.autoStartDiscovery ?? this.defaultAutoStartDiscovery,
+    }
+    if (this.config.autoStartDiscovery) {
+      this.startDiscovery()
+    }
   }
 
   /**
@@ -114,9 +125,11 @@ export class HapClient extends EventEmitter {
     }
   }
 
-  private async startDiscovery() {
+  public async startDiscovery(discoveryTimeout?: number) {
     this.discoveryInProgress = true
 
+    const timeout = discoveryTimeout ?? this.config.discoveryTimeout
+
     this.browser = this.bonjour.find({
       type: 'hap',
     })
@@ -131,7 +144,7 @@ export class HapClient extends EventEmitter {
       this.debug(`[HapClient] Discovery :: Ended`)
       this.discoveryInProgress = false
       this.emit('discovery-ended')
-    }, 60000)
+    }, timeout)
 
     // service found
     this.browser.on('up', async (device: Service) => {