@homebridge-plugins/homebridge-govee 11.32.2-beta.17 → 11.32.2-beta.18

package/CHANGELOG.md

@@ -36,6 +36,7 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - refactor: choose a device handler from a table, so adding a device type no longer means editing the platform
 - refactor: move the settings parsing into its own file, away from the code that talks to devices
 - refactor: move the work of describing a device to its handler into its own file
+- refactor: move the rules for combining govee's device lists, and for letting go of a device that has gone, into their own file with tests
 
 ## v11.32.1 (2026-08-02)
 

package/lib/platform.js

@@ -18,6 +18,7 @@ import { applyUserConfig } from './utils/config-parser.js'
 import platformConsts from './utils/constants.js'
 import platformChars from './utils/custom-chars.js'
 import { applyDeviceContext } from './utils/device-context.js'
+import { cloudListsWereFetched, planDeviceSetup, planRedundantAccessories } from './utils/device-merge.js'
 import { resolveDeviceType } from './utils/dispatch.js'
 import eveChars from './utils/eve-chars.js'
 import {
@@ -342,192 +343,45 @@ export default class {
         throwOnTimeout: true,
       })
 
-      // Initialise the devices
-      let bleSyncNeeded = false
-      let httpSyncNeeded = false
-      let lanDevicesWereInitialised = false
-      let httpDevicesWereInitialised = false
-      let openApiDevicesWereInitialised = false
-
-      if (httpDevices && httpDevices.length > 0) {
-        // We have some devices from HTTP client
-        httpDevices.forEach((httpDevice) => {
-          // Format device id
-          if (!httpDevice.device.includes(':')) {
-            // Eg converts abcd1234abcd1234 to AB:CD:12:34:AB:CD:12:34
-            // For sensors with an add-on sensor like H5178
-            // Eg converts abcd1234abcd1234_1 to AB:CD:12:34:AB:CD:12:34_1
-            httpDevice.device = httpDevice.device.replace(DEVICE_ID_FORMAT_REGEX, '$&:').toUpperCase()
-          }
-
-          // Check it's not a user-ignored device
-          if (this.ignoredDevices.includes(httpDevice.device)) {
-            return
-          }
-
-          // Skip Govee app device groups as these are not real devices (#1309)
-          if (['BaseGroup', 'SameModeGroup'].includes(httpDevice.sku)) {
-            this.log.debug('[%s] %s.', httpDevice.deviceName, platformLang.devIsGroup)
-            return
-          }
-
-          // Check it's not a matter-ignored device, if the config has been set
-          if (platformConsts.matterModels.includes(httpDevice.sku) && this.config.ignoreMatter) {
-            return
-          }
-
-          // Sets the flag to see if we need to set up the BLE/HTTP syncs
-          if (platformConsts.models.sensorLeak.includes(httpDevice.sku)) {
-            httpSyncNeeded = true
-          }
-          if (platformConsts.models.sensorThermo.includes(httpDevice.sku)) {
-            bleSyncNeeded = true
-            httpSyncNeeded = true
-          }
-
-          // Find any matching device from the LAN client
-          const lanDevice = lanDevices.find(el => el.device === httpDevice.device)
-
-          // Find any matching device from the OpenAPI client to merge capabilities
-          const matchingOpenApiDevice = openApiDevices.find(el => el.device === httpDevice.device)
-          const openApiMerge = matchingOpenApiDevice
-            ? {
-                openApiInfo: matchingOpenApiDevice.openApiInfo,
-                properties: matchingOpenApiDevice.properties,
-                supportCmds: matchingOpenApiDevice.supportCmds,
-              }
-            : {}
-
-          if (lanDevice) {
-            // Device exists in LAN data so add the http info to the object and initialise
-            this.initialiseDevice({
-              ...lanDevice,
-              httpInfo: httpDevice,
-              model: httpDevice.sku,
-              deviceName: httpDevice.deviceName,
-              isLanDevice: true,
-              ...openApiMerge,
-            })
-            lanDevicesWereInitialised = true
-            lanDevice.initialised = true
-          } else {
-            // Device doesn't exist in LAN data, but try to initialise as could be other device type
-            this.initialiseDevice({
-              device: httpDevice.device,
-              deviceName: httpDevice.deviceName,
-              model: httpDevice.sku,
-              httpInfo: httpDevice,
-              ...openApiMerge,
-            })
-          }
-          httpDevicesWereInitialised = true
-        })
-      }
-
-      if (openApiDevices && openApiDevices.length > 0) {
-        openApiDevices.forEach((openApiDevice) => {
-          // Skip Govee app device groups as these are not real devices (#1309)
-          if (['BaseGroup', 'SameModeGroup'].includes(openApiDevice.model)) {
-            this.log.debug('[%s] %s.', openApiDevice.deviceName, platformLang.devIsGroup)
-            return
-          }
-
-          if (this.ignoredDevices.includes(openApiDevice.device)) {
-            return
-          }
-
-          if (platformConsts.matterModels.includes(openApiDevice.model) && this.config.ignoreMatter) {
-            return
-          }
-
-          if (httpDevices.some(httpDevice => httpDevice.device === openApiDevice.device)) {
-            return
-          }
-
-          const lanDevice = lanDevices.find(el => el.device === openApiDevice.device)
-
-          if (lanDevice) {
-            this.initialiseDevice({
-              ...lanDevice,
-              deviceName: openApiDevice.deviceName,
-              model: openApiDevice.model,
-              openApiInfo: openApiDevice.openApiInfo,
-              properties: openApiDevice.properties,
-              supportCmds: openApiDevice.supportCmds,
-              isLanDevice: true,
-            })
-            lanDevicesWereInitialised = true
-            lanDevice.initialised = true
-          } else {
-            this.initialiseDevice(openApiDevice)
-          }
-
-          openApiDevicesWereInitialised = true
-        })
-      }
+      // Work out what to set up. Govee describes the same device through up to
+      // three lists, and how they combine is decided away from here so it can
+      // be tested rather than hoped about
+      const plan = planDeviceSetup({
+        httpDevices,
+        lanDevices,
+        openApiDevices,
+        ignoredDevices: this.ignoredDevices,
+        ignoreMatter: this.config.ignoreMatter,
+        deviceConf: this.deviceConf,
+      })
 
-      // Some LAN devices may exist outside the HTTP client
-      const pendingLANDevices = lanDevices.filter(el => !el.initialised)
-      if (pendingLANDevices.length > 0) {
-        // No devices from HTTP client, but LAN devices exist
-        pendingLANDevices.forEach((lanDevice) => {
-          // Check it's not a user-ignored device
-          if (this.ignoredDevices.includes(lanDevice.device)) {
-            return
-          }
+      plan.skippedGroups.forEach(name => this.log.debug('[%s] %s.', name, platformLang.devIsGroup))
+      plan.devices.forEach(device => this.initialiseDevice(device))
 
-          // Check it's not a matter-ignored device, if the config has been set, since a
-          // device skipped by the http/openapi loops for this reason still has an
-          // unmatched lan record, which would otherwise be added here and then removed
-          // again by the cleanup below on every restart (#1315)
-          if (this.config.ignoreMatter && platformConsts.matterModels.includes(lanDevice.sku)) {
-            return
-          }
+      const {
+        bleSyncNeeded,
+        httpSyncNeeded,
+        httpDevicesWereInitialised,
+        openApiDevicesWereInitialised,
+        lanDevicesWereInitialised,
+      } = plan
 
-          // Initialise the device into Homebridge
-          // Since LAN does not provide a name, we will use the configured label or device id
-          this.initialiseDevice({
-            device: lanDevice.device,
-            deviceName: this.deviceConf?.[lanDevice.device]?.label || lanDevice.device.replaceAll(':', ''),
-            model: lanDevice.sku || 'HXXXX', // In case the model is not provided
-            isLanDevice: true,
-            isLanOnly: true,
-          })
-          lanDevicesWereInitialised = true
-        })
-      }
-
-      if (!lanDevicesWereInitialised && !httpDevicesWereInitialised && !openApiDevicesWereInitialised) {
-        // No devices either from HTTP client nor LAN client
+      if (!plan.anyInitialised) {
         throw new Error(platformLang.noDevs)
       }
 
-      // Check for redundant Homebridge accessories
-      // Only treat 'not found in Govee' as a reason to remove an accessory when the
-      // configured cloud clients actually returned their device lists this session,
-      // otherwise a failed fetch would remove the accessory and destroy any HomeKit
-      // scenes and automations it is part of (#1264)
-      const cloudListsFetched = (!this.config.username || !!this.httpClient)
-        && (!!this.config.openApiDisable || !this.config.apiKey || !!this.openApiClient)
-      devicesInHB.forEach((accessory) => {
-        // Remove the accessory if it is now being ignored, or if it is a matter model
-        // and the user has enabled ignoreMatter (otherwise the cached accessory lingers
-        // even though the device is skipped during setup) (#1287)
-        const isIgnored = this.ignoredDevices.includes(accessory.context.gvDeviceId)
-          || (this.config.ignoreMatter && platformConsts.matterModels.includes(accessory.context.gvModel))
-
-        // Also remove it if the device no longer exists in Govee, but never based on
-        // an incomplete cloud list, and never for LAN-only devices which may simply
-        // have missed a scan window (#1264)
-        const isMissing = !httpDevices.some(el => el.device === accessory.context.gvDeviceId)
-          && !lanDevices.some(el => el.device === accessory.context.gvDeviceId)
-          && !openApiDevices.some(el => el.device === accessory.context.gvDeviceId)
-        const isLanOnly = accessory.context.hasLanControl && !accessory.context.firmware
-
-        if (isIgnored || (isMissing && cloudListsFetched && !isLanOnly)) {
-          this.removeAccessory(accessory)
-        }
-      })
+      // Let go of any cached accessory that no longer belongs. Removing one
+      // destroys the HomeKit scenes and automations it is part of, so the rules
+      // for this live next to their tests
+      planRedundantAccessories({
+        accessories: [...devicesInHB.values()],
+        httpDevices,
+        lanDevices,
+        openApiDevices,
+        ignoredDevices: this.ignoredDevices,
+        ignoreMatter: this.config.ignoreMatter,
+        cloudListsFetched: cloudListsWereFetched(this.config, this),
+      }).forEach(accessory => this.removeAccessory(accessory))
 
       // Set up the ble client sync needed for thermo sensor devices
       if (bleSyncNeeded) {

package/lib/utils/device-merge.js

@@ -0,0 +1,251 @@
+import platformConsts from './constants.js'
+import platformLang from './lang-en.js'
+
+/**
+ * Works out which devices to set up, and which cached ones to let go of.
+ *
+ * Govee can describe the same device through three different lists - the
+ * account's own device list, the local network scan, and the public api - and
+ * each carries something the others do not. This decides how they combine.
+ *
+ * Nothing here talks to Homebridge. It returns a plan, and the platform carries
+ * it out, which is what lets the awkward cases below be tested rather than
+ * hoped about.
+ */
+
+const DEVICE_ID_FORMAT_REGEX = /([a-z0-9]{2})(?=[a-z0-9])/gi
+
+// The app lets people group devices together. Those groups come back looking
+// like devices, and are not (#1309)
+const GROUP_SKUS = ['BaseGroup', 'SameModeGroup']
+
+function isGroup(sku) {
+  return GROUP_SKUS.includes(sku)
+}
+
+/**
+ * Govee's own list gives ids without separators, and everything else uses them.
+ * An add-on sensor keeps its `_1` suffix.
+ */
+function formatDeviceId(id) {
+  return id.includes(':') ? id : id.replace(DEVICE_ID_FORMAT_REGEX, '$&:').toUpperCase()
+}
+
+/**
+ * Decide what to set up.
+ *
+ * @param {object} input the three device lists and the settings that filter them
+ * @param {Array} [input.httpDevices] what the account's device list returned
+ * @param {Array} [input.lanDevices] what the local network scan found
+ * @param {Array} [input.openApiDevices] what the public api returned
+ * @param {Array} [input.ignoredDevices] ids the owner asked to leave alone
+ * @param {boolean} [input.ignoreMatter] whether matter models are being skipped
+ * @param {object} [input.deviceConf] per-device settings, for names
+ * @returns {object} `devices` to hand to the platform in order, which periodic
+ *   syncs are needed, which lists produced something, and any app groups that
+ *   were skipped so the caller can log them
+ */
+export function planDeviceSetup({
+  httpDevices = [],
+  lanDevices = [],
+  openApiDevices = [],
+  ignoredDevices = [],
+  ignoreMatter = false,
+  deviceConf = {},
+}) {
+  const devices = []
+  const skippedGroups = []
+  let bleSyncNeeded = false
+  let httpSyncNeeded = false
+  // Which lists produced something, since each one decides whether its own
+  // periodic sync is worth starting
+  let httpDevicesWereInitialised = false
+  let openApiDevicesWereInitialised = false
+  let lanDevicesWereInitialised = false
+
+  const isIgnored = id => ignoredDevices.includes(id)
+  const isIgnoredMatter = model => ignoreMatter && platformConsts.matterModels.includes(model)
+
+  httpDevices.forEach((httpDevice) => {
+    // Kept in place, because the lists are compared by id further down and by
+    // the caller afterwards
+    httpDevice.device = formatDeviceId(httpDevice.device)
+
+    if (isIgnored(httpDevice.device)) {
+      return
+    }
+    if (isGroup(httpDevice.sku)) {
+      skippedGroups.push(httpDevice.deviceName)
+      return
+    }
+    if (isIgnoredMatter(httpDevice.sku)) {
+      return
+    }
+
+    // These two kinds of sensor are the reason the periodic syncs exist
+    if (platformConsts.models.sensorLeak.includes(httpDevice.sku)) {
+      httpSyncNeeded = true
+    }
+    if (platformConsts.models.sensorThermo.includes(httpDevice.sku)) {
+      bleSyncNeeded = true
+      httpSyncNeeded = true
+    }
+
+    const lanDevice = lanDevices.find(el => el.device === httpDevice.device)
+    const matchingOpenApi = openApiDevices.find(el => el.device === httpDevice.device)
+    const openApiMerge = matchingOpenApi
+      ? {
+          openApiInfo: matchingOpenApi.openApiInfo,
+          properties: matchingOpenApi.properties,
+          supportCmds: matchingOpenApi.supportCmds,
+        }
+      : {}
+
+    if (lanDevice) {
+      devices.push({
+        ...lanDevice,
+        httpInfo: httpDevice,
+        model: httpDevice.sku,
+        deviceName: httpDevice.deviceName,
+        isLanDevice: true,
+        ...openApiMerge,
+      })
+      lanDevicesWereInitialised = true
+      lanDevice.initialised = true
+    } else {
+      // Not on the local network, but it may still be reachable another way
+      devices.push({
+        device: httpDevice.device,
+        deviceName: httpDevice.deviceName,
+        model: httpDevice.sku,
+        httpInfo: httpDevice,
+        ...openApiMerge,
+      })
+    }
+    httpDevicesWereInitialised = true
+  })
+
+  openApiDevices.forEach((openApiDevice) => {
+    if (isGroup(openApiDevice.model)) {
+      skippedGroups.push(openApiDevice.deviceName)
+      return
+    }
+    if (isIgnored(openApiDevice.device) || isIgnoredMatter(openApiDevice.model)) {
+      return
+    }
+    // Already handled by the loop above
+    if (httpDevices.some(httpDevice => httpDevice.device === openApiDevice.device)) {
+      return
+    }
+
+    const lanDevice = lanDevices.find(el => el.device === openApiDevice.device)
+    if (lanDevice) {
+      devices.push({
+        ...lanDevice,
+        deviceName: openApiDevice.deviceName,
+        model: openApiDevice.model,
+        openApiInfo: openApiDevice.openApiInfo,
+        properties: openApiDevice.properties,
+        supportCmds: openApiDevice.supportCmds,
+        isLanDevice: true,
+      })
+      lanDevicesWereInitialised = true
+      lanDevice.initialised = true
+    } else {
+      devices.push(openApiDevice)
+    }
+    openApiDevicesWereInitialised = true
+  })
+
+  // Anything found on the network that neither list knew about
+  lanDevices.filter(el => !el.initialised).forEach((lanDevice) => {
+    if (isIgnored(lanDevice.device)) {
+      return
+    }
+    // A device the loops above skipped for this reason still has an unmatched
+    // network record. Without this it would be added here and removed again by
+    // the cleanup on every restart (#1315)
+    if (isIgnoredMatter(lanDevice.sku)) {
+      return
+    }
+
+    devices.push({
+      device: lanDevice.device,
+      // The network scan does not give a name, so use the owner's label
+      deviceName: deviceConf?.[lanDevice.device]?.label || lanDevice.device.replaceAll(':', ''),
+      model: lanDevice.sku || 'HXXXX',
+      isLanDevice: true,
+      isLanOnly: true,
+    })
+    lanDevicesWereInitialised = true
+  })
+
+  return {
+    devices,
+    bleSyncNeeded,
+    httpSyncNeeded,
+    skippedGroups,
+    httpDevicesWereInitialised,
+    openApiDevicesWereInitialised,
+    lanDevicesWereInitialised,
+    anyInitialised: httpDevicesWereInitialised || openApiDevicesWereInitialised || lanDevicesWereInitialised,
+  }
+}
+
+/**
+ * Decide which cached accessories no longer belong.
+ *
+ * ⚠️ The careful part. Removing an accessory destroys the HomeKit scenes and
+ * automations it is in, and that cannot be undone from here. So "Govee did not
+ * mention it" only counts when the cloud lists were actually fetched this time
+ * - a failed request must never look like a deleted device (#1264).
+ *
+ * @param {object} input the cached accessories and what was seen this session
+ * @param {Array} [input.accessories] the accessories Homebridge already has
+ * @param {Array} [input.httpDevices] what the account's device list returned
+ * @param {Array} [input.lanDevices] what the local network scan found
+ * @param {Array} [input.openApiDevices] what the public api returned
+ * @param {Array} [input.ignoredDevices] ids the owner asked to leave alone
+ * @param {boolean} [input.ignoreMatter] whether matter models are being skipped
+ * @param {boolean} [input.cloudListsFetched] whether the cloud lists can be
+ *   trusted to be complete this session
+ * @returns {Array} the accessories to remove
+ */
+export function planRedundantAccessories({
+  accessories = [],
+  httpDevices = [],
+  lanDevices = [],
+  openApiDevices = [],
+  ignoredDevices = [],
+  ignoreMatter = false,
+  cloudListsFetched = false,
+}) {
+  return accessories.filter((accessory) => {
+    const id = accessory.context.gvDeviceId
+
+    // Asked to be ignored, or a matter model while matter models are ignored -
+    // otherwise the cached tile lingers even though setup skipped it (#1287)
+    const isIgnored = ignoredDevices.includes(id)
+      || (ignoreMatter && platformConsts.matterModels.includes(accessory.context.gvModel))
+
+    const isMissing = !httpDevices.some(el => el.device === id)
+      && !lanDevices.some(el => el.device === id)
+      && !openApiDevices.some(el => el.device === id)
+
+    // A device only ever seen on the network may simply have missed a scan
+    const isLanOnly = accessory.context.hasLanControl && !accessory.context.firmware
+
+    return isIgnored || (isMissing && cloudListsFetched && !isLanOnly)
+  })
+}
+
+/**
+ * Whether the cloud lists can be trusted to be complete this session. A client
+ * that was configured but failed to connect means the answer is no.
+ */
+export function cloudListsWereFetched(config, clients) {
+  return (!config.username || !!clients.httpClient)
+    && (!!config.openApiDisable || !config.apiKey || !!clients.openApiClient)
+}
+
+export { formatDeviceId, platformLang }

package/package.json

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