@homebridge-plugins/homebridge-govee 11.30.1 → 11.31.0-beta.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
+## v11.31.0 (Pending Release)
+
+### Added
+
+- feat(lan): add a `lanScanSubnets` option to scan given subnets directly, so lan devices on a different subnet from homebridge can be found (#1323)
+
 ## v11.30.1 (2026-07-23)
 
 ### Changed

package/config.schema.json

@@ -96,6 +96,15 @@
           "functionBody": "return (!model.lanDisable);"
         }
       },
+      "lanScanSubnets": {
+        "title": "LAN Scan Subnets",
+        "type": "string",
+        "description": "Optional. Only needed if your Govee devices are on a different subnet/VLAN from Homebridge. LAN discovery normally uses multicast, which routers do not pass between subnets. Enter one or more subnets in CIDR form (e.g. 192.168.20.0/24), separated by commas, and the plugin will also scan those directly. Requires the devices to have LAN control enabled.",
+        "placeholder": "192.168.20.0/24",
+        "condition": {
+          "functionBody": "return (!model.lanDisable);"
+        }
+      },
       "openApiDisable": {
         "title": "Disable OpenAPI",
         "type": "boolean",
@@ -1513,6 +1522,7 @@
         "lanDisable",
         "lanRefreshTime",
         "lanScanInterval",
+        "lanScanSubnets",
         "openApiDisable",
         "openApiRefreshTime",
         "bleControlInterval",

package/lib/connection/lan.js

@@ -69,6 +69,11 @@ export default class {
     // Keeps track of all devices that are found on the network
     this.lanDevices = []
 
+    // Expand any configured subnets (for devices on a different subnet than
+    // Homebridge, which the multicast scan can't reach) into a flat list of
+    // host IPs to scan directly. Capped so a wide mask can't flood the network.
+    this.scanHosts = this.expandSubnets(this.config.lanScanSubnets)
+
     // Add any devices that have a custom IP address in the config
     Object.keys(platform.deviceConf).forEach((device) => {
       if (platform.deviceConf[device].customIPAddress) {
@@ -191,11 +196,51 @@ export default class {
     })
   }
 
+  // Expand a comma-derived list of CIDR subnets into individual host IPs.
+  // Returns an empty array when nothing is configured or a subnet is invalid.
+  // The total is capped (a /24 is 254 hosts) so a wide mask can't flood.
+  expandSubnets(subnets) {
+    if (!Array.isArray(subnets) || subnets.length === 0) {
+      return []
+    }
+    const maxHosts = 1024
+    const hosts = []
+    subnets.forEach((cidr) => {
+      const [base, prefixStr] = cidr.split('/')
+      const prefix = Number.parseInt(prefixStr, 10)
+      const octets = base.split('.').map(o => Number.parseInt(o, 10))
+      if (prefix < 8 || prefix > 32 || octets.some(o => Number.isNaN(o) || o < 0 || o > 255)) {
+        this.log.warn('[LAN] ignoring invalid scan subnet [%s].', cidr)
+        return
+      }
+      const baseInt = ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0
+      const hostBits = 32 - prefix
+      const size = 2 ** hostBits
+      // Skip the network and broadcast addresses for a normal subnet
+      const first = hostBits > 1 ? baseInt + 1 : baseInt
+      const last = hostBits > 1 ? baseInt + size - 2 : baseInt + size - 1
+      for (let ip = first; ip <= last && hosts.length < maxHosts; ip += 1) {
+        hosts.push(`${(ip >>> 24) & 255}.${(ip >>> 16) & 255}.${(ip >>> 8) & 255}.${ip & 255}`)
+      }
+    })
+    if (hosts.length > 0) {
+      this.log.debug('[LAN] will also scan %s host(s) across configured subnet(s).', hosts.length)
+    }
+    return hosts
+  }
+
   // Send a request that asks for all devices in the multicast group
   sendScanCommand() {
     const scanCommand = JSON.stringify({ msg: { cmd: commands.scan, data: { account_topic: 'reserve' } } })
     this.log.debug('[LAN] scanning for devices over LAN...')
     this.sender.send(scanCommand, scanCommandPort, multicastIp)
+
+    // Also scan any configured subnets directly. Multicast doesn't cross
+    // between subnets, so devices on a different subnet than Homebridge are
+    // reached by sending the scan straight to each host (they reply on 4002).
+    this.scanHosts.forEach((host) => {
+      this.sender.send(scanCommand, scanCommandPort, host)
+    })
   }
 
   // Get all available LAN devices

package/lib/platform.js

@@ -139,6 +139,23 @@ export default class {
             this.config[key] = val
           }
           break
+        case 'lanScanSubnets': {
+          // Comma-separated list of CIDR subnets to scan directly (for devices
+          // on a different subnet from Homebridge, which multicast can't reach)
+          if (typeof val !== 'string' || val.trim() === '') {
+            break
+          }
+          const subnets = val
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => /^\d{1,3}(?:\.\d{1,3}){3}\/\d{1,2}$/.test(s))
+          if (subnets.length === 0) {
+            logIgnore(key)
+          } else {
+            this.config[key] = subnets
+          }
+          break
+        }
         case 'awsDisable':
         case 'bleDisable':
         case 'colourSafeMode':

package/package.json

@@ -2,7 +2,7 @@
   "name": "@homebridge-plugins/homebridge-govee",
   "alias": "Govee",
   "type": "module",
-  "version": "11.30.1",
+  "version": "11.31.0-beta.0",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",