@homebridge-plugins/homebridge-govee 11.32.2-beta.2 → 11.32.2-beta.21

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/lib/utils/dispatch.js

@@ -0,0 +1,159 @@
+import deviceTypes from '../device/index.js'
+import platformConsts from './constants.js'
+
+/**
+ * Works out which handler a device should get.
+ *
+ * This used to be a long chain of `else if` inside the platform, which meant
+ * adding a device type involved editing the file that also does config parsing,
+ * discovery and connection setup. It is a table now, read top to bottom, so a
+ * new type is a row.
+ *
+ * Only the choice lives here. Creating the accessory stays with the platform,
+ * because that talks to Homebridge - so this returns what to build rather than
+ * building it, and can be tested on its own.
+ */
+
+/**
+ * How a model list picks its handler.
+ *
+ * - `handler`  one handler for every model in the list
+ * - `prefix`   look for a handler named after the model, eg `deviceFanH7100`
+ * - `fallback` used when `prefix` finds nothing, so a model nobody has worked
+ *              out still gets power rather than being left unsupported
+ * - `choose`   for the few lists where the answer depends on the device or the
+ *              owner's settings
+ * - `awsPolling` these devices need their status asking for over AWS
+ */
+const routes = [
+  {
+    list: 'rgb',
+    choose: ({ deviceConf }) => (deviceConf.showAs === 'switch' ? 'deviceLightSwitch' : 'deviceLight'),
+  },
+  { list: 'switchSingle', choose: chooseSingleSwitch },
+  {
+    list: 'switchDouble',
+    choose: ({ deviceConf }) => (showAs(deviceConf) === 'switch' ? 'deviceSwitchDouble' : 'deviceOutletDouble'),
+  },
+  {
+    list: 'switchTriple',
+    choose: ({ deviceConf }) => (showAs(deviceConf) === 'switch' ? 'deviceSwitchTriple' : 'deviceOutletTriple'),
+  },
+  { list: 'sensorLeak', handler: 'deviceSensorLeak' },
+  { list: 'sensorPresence', handler: 'deviceSensorPresence' },
+  {
+    list: 'sensorThermo',
+    choose: ({ deviceConf }) => (deviceConf.showExtraSwitch ? 'deviceSensorThermoSwitch' : 'deviceSensorThermo'),
+  },
+  { list: 'sensorThermo4', handler: 'deviceSensorThermo4' },
+  { list: 'sensorMonitor', handler: 'deviceSensorMonitor', awsPolling: true },
+  { list: 'sensorCO2', handler: 'deviceSensorCO2', awsPolling: true },
+  { list: 'fan', prefix: 'deviceFan', fallback: 'deviceFanBasic' },
+  { list: 'heater1', choose: chooseHeater, awsPolling: true },
+  { list: 'heater2', handler: 'deviceHeater2', awsPolling: true },
+  { list: 'humidifier', prefix: 'deviceHumidifier', fallback: 'deviceHumidifierBasic', awsPolling: true },
+  { list: 'dehumidifier', prefix: 'deviceDehumidifier', fallback: 'deviceDehumidifierBasic', awsPolling: true },
+  { list: 'purifier', prefix: 'devicePurifier', fallback: 'devicePurifierBasic', awsPolling: true },
+  { list: 'diffuser', prefix: 'deviceDiffuser', fallback: 'deviceDiffuserBasic', awsPolling: true },
+  { list: 'sensorButton', handler: 'deviceSensorButton' },
+  { list: 'sensorContact', handler: 'deviceSensorContact' },
+  { list: 'kettle', handler: 'deviceKettle' },
+  { list: 'iceMaker', prefix: 'deviceIceMaker', fallback: 'deviceIceMakerBasic' },
+  { list: 'template', handler: 'deviceTemplate' },
+]
+
+function showAs(deviceConf) {
+  return deviceConf.showAs || platformConsts.defaultValues.showAs
+}
+
+/**
+ * A single socket can be shown as all sorts of things, because people use them
+ * for all sorts of things. Three of those are televisions, which Homebridge has
+ * to publish as their own accessory rather than as a tile on the bridge.
+ */
+function chooseSingleSwitch({ deviceConf }) {
+  switch (showAs(deviceConf)) {
+    case 'audio':
+      return { handler: 'deviceTVSingle', externalCategory: 34 }
+    case 'box':
+      return { handler: 'deviceTVSingle', externalCategory: 35 }
+    case 'stick':
+      return { handler: 'deviceTVSingle', externalCategory: 36 }
+    case 'cooler':
+      // Standing in for a cooler means reading a temperature from somewhere
+      // else, and without that there is nothing to show
+      return deviceConf.temperatureSource
+        ? { handler: 'deviceCoolerSingle' }
+        : { skip: 'needsTemperatureSource' }
+    case 'heater':
+      return deviceConf.temperatureSource
+        ? { handler: 'deviceHeater2Single' }
+        : { skip: 'needsTemperatureSource' }
+    case 'purifier':
+      return 'devicePurifierSingle'
+    case 'switch':
+      return 'deviceSwitchSingle'
+    case 'tap':
+      return 'deviceTapSingle'
+    case 'valve':
+      return 'deviceValveSingle'
+    default:
+      return 'deviceOutletSingle'
+  }
+}
+
+/**
+ * Some of these heaters report the room temperature and some do not, and the
+ * two need different tiles - a plain fan against a heater with a temperature
+ * readout. Rather than leave the owner to work that out and tick a box, take
+ * Govee's own word for it where the device says so, and otherwise use what a
+ * previous run learnt from the readings themselves. An owner who has already
+ * set the option still wins, so nobody's tile changes under them.
+ */
+function chooseHeater({ device, deviceConf, cachedContext }) {
+  const reportsTemperature = device.openApiInfo?.byInstance?.sensorTemperature
+    ? true
+    : cachedContext?.supportsAmbientTemp
+  return (deviceConf.tempReporting ?? reportsTemperature)
+    ? 'deviceHeater1B'
+    : 'deviceHeater1A'
+}
+
+function normalise(answer) {
+  return typeof answer === 'string' ? { handler: answer } : answer
+}
+
+/**
+ * Decide what to build for a device.
+ *
+ * @param {object} device the device as Govee describes it
+ * @param {object} [deviceConf] this device's settings
+ * @param {object} [cachedContext] the context of the accessory from a previous
+ *   run, where there is one - some choices depend on what was learnt before
+ * @returns {object|null} `{ handler, handlerKey, awsPolling, externalCategory,
+ *   skip }`, or null when the model is not one we handle
+ */
+export function resolveDeviceType(device, deviceConf = {}, cachedContext = undefined) {
+  const route = routes.find(entry => platformConsts.models[entry.list]?.includes(device.model))
+  if (!route) {
+    return null
+  }
+
+  const chosen = route.choose
+    ? normalise(route.choose({ device, deviceConf, cachedContext }))
+    : { handler: route.handler ?? (deviceTypes[`${route.prefix}${device.model}`] ? `${route.prefix}${device.model}` : route.fallback) }
+
+  if (chosen.skip) {
+    return { skip: chosen.skip, list: route.list }
+  }
+
+  return {
+    list: route.list,
+    handlerKey: chosen.handler,
+    handler: deviceTypes[chosen.handler],
+    awsPolling: !!route.awsPolling,
+    externalCategory: chosen.externalCategory,
+  }
+}
+
+export { routes }

package/lib/utils/functions.js

@@ -22,6 +22,15 @@ const farToCen = temp => Math.round(((temp - 32) * 5) / 9)
  */
 function generateCodeFromHexValues(hexValues, returnAsHexBuffer = false) {
   const cmdSection = Buffer.from(hexValues.flat())
+
+  // More than 19 bytes leaves no room for the checksum. Without this the
+  // padding length goes negative, which produces an empty pad rather than an
+  // error, and the result is a packet longer than 20 bytes that the device
+  // will not understand - with nothing said about why
+  if (cmdSection.length > 19) {
+    throw new Error(`Command is ${cmdSection.length} bytes, which is longer than a packet allows`)
+  }
+
   const padSection = Buffer.from(Array.from({ length: 19 - cmdSection.length }).fill(0))
   const noXSection = Buffer.concat([cmdSection, padSection])
   let checksum = 0

package/lib/utils/lang-en.js

@@ -106,7 +106,6 @@ export default {
   loginSuccess: 'login successful',
   logoutFail: 'could not log out of Govee account as',
   needHTTPClient: 'requires HTTP client',
-  newScene: 'new scene code',
   noCreds: 'username and/or password not provided',
   noConnMethod: 'no connection method available, see https://shorturl.at/eCN04 for more info',
   noDevices: 'no data received from Govee server whilst obtaining devices',
@@ -134,5 +133,4 @@ export default {
   syncStillRunning: 'skipping this sync as the previous one has not finished yet',
   viaAL: 'via adaptive lighting',
   statusCodes: 'device status codes',
-  unknownCommand: 'unknown command in payload received',
 }

package/lib/utils/report-unknown.js

@@ -0,0 +1,156 @@
+import { base64ToHex } from './functions.js'
+
+/**
+ * Logging for anything the plugin receives but does not understand yet.
+ *
+ * Adding support for a new device or a new function almost always stalls on the
+ * same thing: the maintainer has to go back and forth with the owner asking for
+ * the model, the firmware version, which connection the data arrived on, and
+ * the raw payload. This builds all of that into a single line the owner can
+ * copy straight into a GitHub issue, so the first report is usually enough.
+ *
+ * The line is deliberately one piece of JSON rather than prose - it is one
+ * copy-paste for the user, and it can be read back without picking it apart.
+ */
+
+// Remembers what has already been reported, so a code the device repeats every
+// few seconds is only shouted about once. Keyed by device, kind and payload, so
+// a genuinely different unknown value is still surfaced.
+const alreadyReported = new Set()
+
+/**
+ * Reset the record of what has been reported. Only needed by tests, and when
+ * the platform restarts and wants a fresh session.
+ */
+export function resetReportedUnknowns() {
+  alreadyReported.clear()
+}
+
+/**
+ * True the first time a given thing is seen, false every time after.
+ *
+ * For the places that have something worth reporting but no accessory to hang
+ * it off, such as a sensor broadcasting nearby that the plugin cannot decode.
+ * Lets those log loudly once and quietly thereafter, the same as the rest.
+ *
+ * @param {string} fingerprint identifies the thing being reported
+ */
+export function isFirstReport(fingerprint) {
+  if (alreadyReported.has(fingerprint)) {
+    return false
+  }
+  alreadyReported.add(fingerprint)
+  return true
+}
+
+/**
+ * Report a control the plugin knows the device has, but does not yet know the
+ * command for, and then fail the request.
+ *
+ * This is how a model gets added before every last detail is known. The things
+ * that are certain - usually power - work straight away, and anything still
+ * unknown says so out loud instead of pretending to work. Failing the request
+ * matters: HomeKit shows the control as not responding, which sends the owner
+ * to the log, where they find the line to paste into an issue. A control that
+ * silently did nothing would just look broken.
+ *
+ * @param {object} accessory the accessory the control belongs to
+ * @param {object} details
+ * @param {string} details.control what was asked for, eg 'fan speed'
+ * @param {*} [details.value] the value HomeKit asked for
+ * @returns {string} the message that was logged, mainly for tests
+ */
+export function reportUnsupportedControl(accessory, { control, value } = {}) {
+  const context = accessory?.context || {}
+  const report = {
+    model: context.gvModel,
+    firmware: context.firmware,
+    hardware: context.hardware,
+    control,
+    requested: value,
+  }
+  Object.keys(report).forEach((key) => {
+    if (report[key] === undefined || report[key] === null || report[key] === '') {
+      delete report[key]
+    }
+  })
+
+  const line = `the ${control} for this model is not known yet, so this did not happen - please report this line so it can be added: ${JSON.stringify(report)}`
+  const fingerprint = `${context.gvDeviceId || accessory?.displayName}|unsupported|${control}`
+
+  if (alreadyReported.has(fingerprint)) {
+    accessory?.logDebug?.(line)
+  } else {
+    alreadyReported.add(fingerprint)
+    accessory?.logWarn?.(line)
+  }
+
+  return line
+}
+
+/**
+ * Log an unrecognised payload with everything needed to add support for it.
+ *
+ * @param {object} accessory the accessory the data arrived for
+ * @param {object} details
+ * @param {string} details.kind what was not understood, eg 'scene' or 'command'
+ * @param {string} [details.source] the connection it came in on, eg 'AWS'
+ * @param {*} [details.raw] the payload exactly as received
+ * @param {string} [details.hex] the payload as hex, worked out from raw if omitted
+ * @param {object} [details.extra] any further fields worth including
+ */
+export function logUnknownData(accessory, {
+  kind,
+  source,
+  raw,
+  hex,
+  extra,
+} = {}) {
+  if (!accessory) {
+    return
+  }
+
+  const context = accessory.context || {}
+
+  // Work out the hex form when the payload is base64, since the hex is what
+  // actually gets read when working out what a code means.
+  let hexValue = hex
+  if (!hexValue && typeof raw === 'string') {
+    try {
+      hexValue = base64ToHex(raw)
+    } catch {
+      // Not base64, so the raw value is the useful form on its own
+    }
+  }
+
+  const report = {
+    model: context.gvModel,
+    firmware: context.firmware,
+    hardware: context.hardware,
+    source: source || 'unknown',
+    kind,
+    raw: typeof raw === 'object' ? JSON.stringify(raw) : raw,
+    ...(hexValue && hexValue !== raw ? { hex: hexValue } : {}),
+    ...extra,
+  }
+
+  // Drop anything we do not actually have, so the line stays readable
+  Object.keys(report).forEach((key) => {
+    if (report[key] === undefined || report[key] === null || report[key] === '') {
+      delete report[key]
+    }
+  })
+
+  const line = `unrecognised ${kind} - please include this line if you report it: ${JSON.stringify(report)}`
+  const fingerprint = `${context.gvDeviceId || accessory.displayName}|${kind}|${report.raw}`
+
+  // Say it once loudly enough to be noticed, then keep quiet about that exact
+  // payload for the rest of the session.
+  if (alreadyReported.has(fingerprint)) {
+    accessory.logDebug?.(line)
+    return
+  }
+
+  alreadyReported.add(fingerprint)
+  accessory.logWarn?.(line)
+}

package/package.json

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