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

package/CHANGELOG.md

@@ -35,6 +35,8 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - feat: give a diffuser model that has not been worked out yet the same starting handler the other appliances have, so it works for on and off
 - 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

@@ -17,7 +17,8 @@ import { buildCommand } from './utils/command-builder.js'
 import { applyUserConfig } from './utils/config-parser.js'
 import platformConsts from './utils/constants.js'
 import platformChars from './utils/custom-chars.js'
-import { getDeviceCapabilities } from './utils/device-capabilities.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) {
@@ -860,7 +714,6 @@ export default class {
       }
 
       const devInstance = route.handler
-      const doAWSPolling = route.awsPolling
 
       let accessory
       if (route.externalCategory) {
@@ -882,161 +735,12 @@ export default class {
       // Set the logging level for this device
       this.applyAccessoryLogging(accessory)
 
-      // Add the temperatureSource config to the context if exists
-      if (deviceConf.temperatureSource) {
-        accessory.context.temperatureSource = deviceConf.temperatureSource
-      }
-
-      // Add the openApiTempUnit config to the context if set to something other than auto
-      if (deviceConf.openApiTempUnit && deviceConf.openApiTempUnit !== 'auto') {
-        accessory.context.openApiTempUnit = deviceConf.openApiTempUnit
-      } else {
-        delete accessory.context.openApiTempUnit
-      }
-
-      // Get a supported command list if provided, with their options
-      if (device.supportCmds && Array.isArray(device.supportCmds)) {
-        accessory.context.supportedCmds = device.supportCmds
-        accessory.context.supportedCmdsOpts = {}
-
-        device.supportCmds.forEach((cmd) => {
-          if (device?.properties?.[cmd]) {
-            accessory.context.supportedCmdsOpts[cmd] = device.properties[cmd]
-          }
-        })
-      }
-
-      // Add some initial context information which is changed later
-      accessory.context.hasAwsControl = false
-      accessory.context.useAwsControl = false
-      accessory.context.hasOpenApiControl = false
-      accessory.context.useOpenApiControl = false
-      accessory.context.hasBleControl = false
-      accessory.context.useBleControl = false
-      accessory.context.hasLanControl = device.isLanDevice
-      accessory.context.useLanControl = accessory.context.hasLanControl
-      accessory.context.firmware = false
-      accessory.context.hardware = false
-      accessory.context.image = false
-
-      // Overrides for when a custom IP is provided, for a light which is not BLE only
-      if (
-        deviceConf.customIPAddress
-        && accessory.context.hasLanControl
-        && accessory.context.hasAwsControl
-        && platformConsts.models.rgb.includes(device.model)
-      ) {
-        accessory.context.hasLanControl = true
-        accessory.context.useLanControl = true
-      }
-
-      // If the device is LAN-only, then sync the display name with the label in the configuration
-      if (device.isLanOnly) {
-        accessory.displayName = device.deviceName
-      }
-
-      // See if we have extra HTTP client info for this device
-      if (device.httpInfo) {
-        // Save the hardware and firmware versions
-        accessory.context.firmware = device.httpInfo.versionSoft
-        accessory.context.hardware = device.httpInfo.versionHard
-
-        // It's possible to show a nice little icon of the device in the Homebridge UI
-        if (device.httpInfo.deviceExt && device.httpInfo.deviceExt.extResources) {
-          try {
-            const parsed = JSON.parse(device.httpInfo.deviceExt.extResources)
-            if (parsed && parsed.skuUrl) {
-              accessory.context.image = parsed.skuUrl
-            }
-          } catch {
-            // Ignore malformed extResources
-          }
-        }
-
-        // HTTP info lets us see if AWS/BLE connection methods are available
-        if (device.httpInfo.deviceExt && device.httpInfo.deviceExt.deviceSettings) {
-          let parsed
-          try {
-            parsed = JSON.parse(device.httpInfo.deviceExt.deviceSettings)
-          } catch {
-            this.log.debugWarn('[%s] failed to parse deviceSettings, skipping AWS/BLE setup.', accessory.displayName)
-          }
-
-          // Check to see if AWS is possible
-          if (parsed) {
-            if (parsed.topic) {
-              accessory.context.hasAwsControl = true
-              accessory.context.awsTopic = parsed.topic
-
-              if (this.awsClient) {
-                accessory.context.useAwsControl = true
-                accessory.context.awsBrightnessNoScale = deviceConf.awsBrightnessNoScale
-                accessory.context.awsColourMode = deviceConf.awsColourMode || platformConsts.defaultValues.awsColourMode
-                awsDevices.push(device.device)
-
-                // Certain models need AWS polling
-                if (doAWSPolling) {
-                  awsDevicesToPoll.push(device.device)
-                }
-              }
-            }
-
-            // Check to see if BLE is possible
-            if (parsed.bleName) {
-              const providedBle = parsed.address ? parsed.address.toLowerCase() : device.device.substring(6).toLowerCase()
-              accessory.context.hasBleControl = !!parsed.bleName
-              accessory.context.bleAddress = deviceConf.customAddress
-                ? deviceConf.customAddress.toLowerCase()
-                : providedBle
-              accessory.context.bleName = parsed.bleName
-              accessory.context.bleWriteUuid = getDeviceCapabilities(accessory.context.gvModel).bleWriteUuid
-              if (this.bleClient) {
-                accessory.context.useBleControl = true
-              }
-            }
-
-            // Gateway subdevices (e.g. leak sensors paired to an H5044) include
-            // their gateway id and slot number, which we need to match real-time
-            // leak events relayed by the gateway over AWS (#1276)
-            if (hasProperty(parsed, 'sno') && parsed.gatewayInfo?.device) {
-              accessory.context.gatewaySno = parsed.sno
-              accessory.context.gatewayDevice = parsed.gatewayInfo.device
-            }
-
-            // Get a min and max temperature/humidity range to show in the homebridge-ui
-            if (hasProperty(parsed, 'temCali')) {
-              accessory.context.minTemp = parsed.temMin / 100
-              accessory.context.maxTemp = parsed.temMax / 100
-              accessory.context.offTemp = parsed.temCali
-            }
-            if (hasProperty(parsed, 'humCali')) {
-              accessory.context.minHumi = parsed.humMin / 100
-              accessory.context.maxHumi = parsed.humMax / 100
-              accessory.context.offHumi = parsed.humCali
-            }
-          }
-        }
-      }
-
-      if (device.openApiInfo) {
-        accessory.context.hasOpenApiControl = true
-        accessory.context.useOpenApiControl = !!this.openApiClient
-        accessory.context.openApiCapabilities = device.openApiInfo.byInstance || {}
-
-        // Log what Govee says this device can do. Working out whether a model
-        // exposes something like a night light otherwise means reverse
-        // engineering its status messages, when the answer is right here
-        const instances = Object.entries(accessory.context.openApiCapabilities)
-          .map(([instance, capability]) => `${instance} (${capability?.type ?? 'unknown type'})`)
-        this.log.debug(
-          '[%s] openapi category [%s] capabilities [%s].',
-          accessory.displayName,
-          device.openApiInfo.category || 'unknown',
-          instances.join(', ') || 'none',
-        )
-      }
+      applyDeviceContext(this, accessory, device, deviceConf, {
+        awsDevices,
+        awsDevicesToPoll,
+        doAWSPolling: route.awsPolling,
+      })
 
-      // Create the instance for this device type
       accessory.control = new devInstance(this, accessory)
 
       // Log the device initialisation

package/lib/utils/device-context.js

@@ -0,0 +1,179 @@
+import platformConsts from './constants.js'
+import { getDeviceCapabilities } from './device-capabilities.js'
+import { hasProperty } from './functions.js'
+
+/**
+ * Fills in everything a handler needs to know about a device before it is
+ * built: which connections are available, what firmware it reports, the limits
+ * it works within, and what Govee's api says it can do.
+ *
+ * Lifted out of the platform unchanged. It is data assembly rather than
+ * anything to do with Homebridge, and it was making the one method that sets a
+ * device up twice as long as it needed to be.
+ *
+ * @param {object} platform the platform, for logging and settings
+ * @param {object} accessory the accessory being set up
+ * @param {object} device the device as Govee describes it
+ * @param {object} deviceConf this device's settings
+ * @param {object} joins where to record the connections this device can use -
+ *   `awsDevices`, `awsDevicesToPoll`, and whether this kind of device needs its
+ *   status asking for over AWS
+ */
+export function applyDeviceContext(platform, accessory, device, deviceConf, joins) {
+  const { awsDevices, awsDevicesToPoll, doAWSPolling } = joins
+  // Add the temperatureSource config to the context if exists
+  if (deviceConf.temperatureSource) {
+    accessory.context.temperatureSource = deviceConf.temperatureSource
+  }
+
+  // Add the openApiTempUnit config to the context if set to something other than auto
+  if (deviceConf.openApiTempUnit && deviceConf.openApiTempUnit !== 'auto') {
+    accessory.context.openApiTempUnit = deviceConf.openApiTempUnit
+  } else {
+    delete accessory.context.openApiTempUnit
+  }
+
+  // Get a supported command list if provided, with their options
+  if (device.supportCmds && Array.isArray(device.supportCmds)) {
+    accessory.context.supportedCmds = device.supportCmds
+    accessory.context.supportedCmdsOpts = {}
+
+    device.supportCmds.forEach((cmd) => {
+      if (device?.properties?.[cmd]) {
+        accessory.context.supportedCmdsOpts[cmd] = device.properties[cmd]
+      }
+    })
+  }
+
+  // Add some initial context information which is changed later
+  accessory.context.hasAwsControl = false
+  accessory.context.useAwsControl = false
+  accessory.context.hasOpenApiControl = false
+  accessory.context.useOpenApiControl = false
+  accessory.context.hasBleControl = false
+  accessory.context.useBleControl = false
+  accessory.context.hasLanControl = device.isLanDevice
+  accessory.context.useLanControl = accessory.context.hasLanControl
+  accessory.context.firmware = false
+  accessory.context.hardware = false
+  accessory.context.image = false
+
+  // Overrides for when a custom IP is provided, for a light which is not BLE only
+  if (
+    deviceConf.customIPAddress
+    && accessory.context.hasLanControl
+    && accessory.context.hasAwsControl
+    && platformConsts.models.rgb.includes(device.model)
+  ) {
+    accessory.context.hasLanControl = true
+    accessory.context.useLanControl = true
+  }
+
+  // If the device is LAN-only, then sync the display name with the label in the configuration
+  if (device.isLanOnly) {
+    accessory.displayName = device.deviceName
+  }
+
+  // See if we have extra HTTP client info for this device
+  if (device.httpInfo) {
+    // Save the hardware and firmware versions
+    accessory.context.firmware = device.httpInfo.versionSoft
+    accessory.context.hardware = device.httpInfo.versionHard
+
+    // It's possible to show a nice little icon of the device in the Homebridge UI
+    if (device.httpInfo.deviceExt && device.httpInfo.deviceExt.extResources) {
+      try {
+        const parsed = JSON.parse(device.httpInfo.deviceExt.extResources)
+        if (parsed && parsed.skuUrl) {
+          accessory.context.image = parsed.skuUrl
+        }
+      } catch {
+        // Ignore malformed extResources
+      }
+    }
+
+    // HTTP info lets us see if AWS/BLE connection methods are available
+    if (device.httpInfo.deviceExt && device.httpInfo.deviceExt.deviceSettings) {
+      let parsed
+      try {
+        parsed = JSON.parse(device.httpInfo.deviceExt.deviceSettings)
+      } catch {
+        platform.log.debugWarn('[%s] failed to parse deviceSettings, skipping AWS/BLE setup.', accessory.displayName)
+      }
+
+      // Check to see if AWS is possible
+      if (parsed) {
+        if (parsed.topic) {
+          accessory.context.hasAwsControl = true
+          accessory.context.awsTopic = parsed.topic
+
+          if (platform.awsClient) {
+            accessory.context.useAwsControl = true
+            accessory.context.awsBrightnessNoScale = deviceConf.awsBrightnessNoScale
+            accessory.context.awsColourMode = deviceConf.awsColourMode || platformConsts.defaultValues.awsColourMode
+            awsDevices.push(device.device)
+
+            // Certain models need AWS polling
+            if (doAWSPolling) {
+              awsDevicesToPoll.push(device.device)
+            }
+          }
+        }
+
+        // Check to see if BLE is possible
+        if (parsed.bleName) {
+          const providedBle = parsed.address ? parsed.address.toLowerCase() : device.device.substring(6).toLowerCase()
+          accessory.context.hasBleControl = !!parsed.bleName
+          accessory.context.bleAddress = deviceConf.customAddress
+            ? deviceConf.customAddress.toLowerCase()
+            : providedBle
+          accessory.context.bleName = parsed.bleName
+          accessory.context.bleWriteUuid = getDeviceCapabilities(accessory.context.gvModel).bleWriteUuid
+          if (platform.bleClient) {
+            accessory.context.useBleControl = true
+          }
+        }
+
+        // Gateway subdevices (e.g. leak sensors paired to an H5044) include
+        // their gateway id and slot number, which we need to match real-time
+        // leak events relayed by the gateway over AWS (#1276)
+        if (hasProperty(parsed, 'sno') && parsed.gatewayInfo?.device) {
+          accessory.context.gatewaySno = parsed.sno
+          accessory.context.gatewayDevice = parsed.gatewayInfo.device
+        }
+
+        // Get a min and max temperature/humidity range to show in the homebridge-ui
+        if (hasProperty(parsed, 'temCali')) {
+          accessory.context.minTemp = parsed.temMin / 100
+          accessory.context.maxTemp = parsed.temMax / 100
+          accessory.context.offTemp = parsed.temCali
+        }
+        if (hasProperty(parsed, 'humCali')) {
+          accessory.context.minHumi = parsed.humMin / 100
+          accessory.context.maxHumi = parsed.humMax / 100
+          accessory.context.offHumi = parsed.humCali
+        }
+      }
+    }
+  }
+
+  if (device.openApiInfo) {
+    accessory.context.hasOpenApiControl = true
+    accessory.context.useOpenApiControl = !!platform.openApiClient
+    accessory.context.openApiCapabilities = device.openApiInfo.byInstance || {}
+
+    // Log what Govee says this device can do. Working out whether a model
+    // exposes something like a night light otherwise means reverse
+    // engineering its status messages, when the answer is right here
+    const instances = Object.entries(accessory.context.openApiCapabilities)
+      .map(([instance, capability]) => `${instance} (${capability?.type ?? 'unknown type'})`)
+    platform.log.debug(
+      '[%s] openapi category [%s] capabilities [%s].',
+      accessory.displayName,
+      device.openApiInfo.category || 'unknown',
+      instances.join(', ') || 'none',
+    )
+  }
+
+  // Create the instance for this device type
+}

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.16",
+  "version": "11.32.2-beta.18",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",