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

package/lib/utils/capabilities.js

@@ -0,0 +1,220 @@
+/**
+ * What a device can do, worked out from several sources rather than one table.
+ *
+ * Writing out all six hundred models by hand is a job nobody finishes, and it
+ * throws away the two things we already have: Govee's own API says what each
+ * device can do, and some behaviour depends on firmware rather than model. So
+ * instead of a table this asks a series of layers and takes the first answer:
+ *
+ *   1. user config      an explicit setting always wins
+ *   2. firmware         this model, at or above this firmware version
+ *   3. model            written down because someone worked it out
+ *   4. discovered       what this particular device reported it can do
+ *   5. family           what this kind of appliance usually has
+ *
+ * Most models never need an entry of their own. They are answered by what the
+ * device reported plus the family defaults, which is why this scales to models
+ * nobody has written down.
+ *
+ * ⚠️ Family defaults are deliberately generous. A control this plugin has
+ * offered for years may be in use by someone, and taking it away to tidy up
+ * would break a working setup. Only a model entry - written after someone
+ * confirmed it - is allowed to say a device does not have something.
+ */
+
+import { compareVersions } from './device-capabilities.js'
+
+/**
+ * What each kind of appliance usually offers.
+ *
+ * These are the fallback, so they describe the group rather than any one model.
+ * Where a group has historically been given a control, it stays here even if
+ * some members turn out not to have it - see the warning above.
+ */
+const familyControls = {
+  heater1: { swing: true, lock: true, light: false },
+  heater2: { swing: true, lock: true, light: true },
+  fan: { swing: true, lock: false, light: false },
+  humidifier: { swing: false, lock: false, light: false },
+  dehumidifier: { swing: false, lock: false, light: false },
+  purifier: { swing: false, lock: false, light: false },
+  iceMaker: { swing: false, lock: false, light: false },
+  diffuser: { swing: false, lock: false, light: false },
+}
+
+const emptyControls = {
+  swing: false,
+  lock: false,
+  light: false,
+  humiditySensor: false,
+  temperatureSensor: false,
+  modes: false,
+}
+
+/**
+ * Controls worked out for a particular model.
+ *
+ * Only add a model here once its controls are actually known. An entry is
+ * trusted over what the device reports, and it is the only thing allowed to
+ * take a control away.
+ */
+const modelControls = {
+  // Heaters. These match what Govee's own app offers for each model.
+  // Added new, so there is nobody whose setup could be broken by them
+  H7137: { swing: false, lock: false, light: false },
+  H713E: { swing: false, lock: false, light: false },
+
+  // Diffusers are power only, which is what the plugin already offers
+  H7161: { swing: false, lock: false, light: false },
+  H7162: { swing: false, lock: false, light: false },
+}
+
+/**
+ * Controls a model is believed NOT to have, which are still being offered.
+ *
+ * These are recorded rather than applied. Each has been offered for a long
+ * time, so an owner may be relying on it, and taking it away to match a
+ * capability list would break a working setup for the sake of tidiness. The
+ * evidence is written down here so nobody has to work it out twice, and so
+ * there is a list to check the next time an owner of one of these gets in
+ * touch.
+ *
+ * Move an entry into `modelControls` once an owner confirms the control really
+ * does nothing.
+ */
+const unconfirmedMissing = {
+  H713A: { swing: false },
+  H713B: { swing: false },
+  H713C: { swing: false },
+  H7135: { swing: false, light: false },
+}
+
+/**
+ * Controls that only appear at or above a firmware version. Same shape as the
+ * protocol overrides next door: a list per model, oldest rule first.
+ */
+const firmwareControls = {}
+
+/**
+ * What Govee's API calls a capability, and which control it means to us.
+ *
+ * These names come back per device, so they say what this particular unit can
+ * do rather than what its model generally can. That makes them the only source
+ * here that works for a model nobody has written down.
+ */
+const discoveryMap = {
+  oscillationToggle: 'swing',
+  lockToggle: 'lock',
+  nightlightToggle: 'light',
+  mainLightToggle: 'light',
+  backgroundLightToggle: 'light',
+  sensorHumidity: 'humiditySensor',
+  sensorTemperature: 'temperatureSensor',
+  workMode: 'modes',
+}
+
+/**
+ * Turn the capability list a device reported into controls.
+ *
+ * Only ever adds. A capability the device did not mention is left undecided so
+ * a later layer can answer, because the API not listing something is not proof
+ * the device cannot do it.
+ */
+function fromDiscovery(openApiCapabilities) {
+  const discovered = {}
+  Object.keys(openApiCapabilities || {}).forEach((instance) => {
+    const control = discoveryMap[instance]
+    if (control) {
+      discovered[control] = true
+    }
+  })
+  return discovered
+}
+
+/**
+ * Config settings that name a control directly, so an owner can turn something
+ * off that their device does not really have without waiting for a release.
+ */
+function fromConfig(deviceConf) {
+  const chosen = {}
+  if (deviceConf?.hideLight === true) {
+    chosen.light = false
+  }
+  if (deviceConf?.hideSwing === true) {
+    chosen.swing = false
+  }
+  return chosen
+}
+
+function firmwareLayer(model, firmware) {
+  if (!firmware) {
+    return {}
+  }
+  const applied = {}
+  const rules = [...(firmwareControls[model] || [])]
+    .sort((a, b) => compareVersions(a.minVersion, b.minVersion))
+  rules.forEach((rule) => {
+    if (compareVersions(firmware, rule.minVersion) >= 0) {
+      Object.assign(applied, rule.controls)
+    }
+  })
+  return applied
+}
+
+/**
+ * Work out what a device can do.
+ *
+ * @param {object} context describing the device
+ * @param {string} context.model the govee model, eg 'H7130'
+ * @param {string} [context.family] which set of defaults to fall back on
+ * @param {string} [context.firmware] the firmware version the device reported
+ * @param {object} [context.openApiCapabilities] what the api said it can do
+ * @param {object} [context.deviceConf] this device's settings
+ * @returns {{ controls: object, sources: object }} the controls, and which
+ *   layer decided each one - the second is for the log, so an unexpected answer
+ *   can be traced without guessing
+ */
+export function resolveControls(context = {}) {
+  const {
+    model,
+    family,
+    firmware,
+    openApiCapabilities,
+    deviceConf,
+  } = context
+
+  // Lowest priority first, so a later layer overwrites an earlier one
+  const layers = [
+    ['family', familyControls[family] || {}],
+    ['discovered', fromDiscovery(openApiCapabilities)],
+    ['model', modelControls[model] || {}],
+    ['firmware', firmwareLayer(model, firmware)],
+    ['config', fromConfig(deviceConf)],
+  ]
+
+  const controls = { ...emptyControls }
+  const sources = {}
+
+  layers.forEach(([name, values]) => {
+    Object.entries(values).forEach(([control, value]) => {
+      controls[control] = value
+      sources[control] = name
+    })
+  })
+
+  return { controls, sources }
+}
+
+/**
+ * A one-line summary of where each answer came from, for the debug log. Reading
+ * "swing from family" tells you nobody has confirmed it, which is a different
+ * situation from "swing from model".
+ */
+export function describeSources(sources) {
+  return Object.entries(sources)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([control, source]) => `${control} from ${source}`)
+    .join(', ') || 'nothing known'
+}
+
+export { familyControls, modelControls, unconfirmedMissing }

package/lib/utils/command-builder.js

@@ -67,7 +67,7 @@ function buildStateDualCommand(params) {
 }
 
 function buildStateOutletCommand(params, context) {
-  const caps = getDeviceCapabilities(context.gvModel)
+  const caps = getDeviceCapabilities(context.gvModel, context.firmware)
   return {
     awsParams: {
       cmd: 'turn',
@@ -118,7 +118,7 @@ function buildOpenApiCommand(params) {
 }
 
 function buildBrightnessCommand(params, context) {
-  const caps = getDeviceCapabilities(context.gvModel)
+  const caps = getDeviceCapabilities(context.gvModel, context.firmware)
   return {
     awsParams: {
       cmd: 'brightness',
@@ -143,7 +143,7 @@ function buildBrightnessCommand(params, context) {
 }
 
 function buildColorCommand(params, context) {
-  const caps = getDeviceCapabilities(context.gvModel)
+  const caps = getDeviceCapabilities(context.gvModel, context.firmware)
   const { r, g, b } = params.value
 
   let awsParams
@@ -180,7 +180,7 @@ function buildColorCommand(params, context) {
 }
 
 function buildColorTempCommand(params, context) {
-  const caps = getDeviceCapabilities(context.gvModel)
+  const caps = getDeviceCapabilities(context.gvModel, context.firmware)
   const [r, g, b] = k2rgb(params.value)
 
   let awsParams
@@ -224,6 +224,8 @@ function buildSceneCommand(params) {
   if (params.value[0]) {
     const splitCode = params.value[0].split(',')
     result.awsParams = { cmd: 'ptReal', data: { command: splitCode } }
+    // The local api accepts `ptReal` even though it is not in the documented
+    // command set, which is what lets scenes work without the cloud
     result.lanParams = { cmd: 'ptReal', data: { command: splitCode } }
   }
   if (params.value[1]) {

package/lib/utils/config-parser.js

@@ -0,0 +1,280 @@
+import platformConsts from './constants.js'
+import { parseDeviceId } from './functions.js'
+import platformLang from './lang-en.js'
+
+const WHITESPACE_REGEX = /\s+/g
+
+/**
+ * Reads the user's settings, warns about anything that will not be used, and
+ * fills in the defaults for the rest.
+ *
+ * Lifted out of the platform unchanged. It was the largest single thing in
+ * there and had nothing to do with talking to devices, so a change to how a
+ * device works no longer means opening the same file as a change to how a
+ * setting is read.
+ *
+ * It writes `config`, `deviceConf` and `ignoredDevices` onto the platform
+ * rather than returning them, which is how it always worked.
+ */
+export function applyUserConfig(platform, config) {
+  // These shorthand functions save line space during config parsing
+  const logDefault = (k, def) => {
+    platform.log.warn('%s [%s] %s %s.', platformLang.cfgItem, k, platformLang.cfgDef, def)
+  }
+  const logDuplicate = (k) => {
+    platform.log.warn('%s [%s] %s.', platformLang.cfgItem, k, platformLang.cfgDup)
+  }
+  const logIgnore = (k) => {
+    platform.log.warn('%s [%s] %s.', platformLang.cfgItem, k, platformLang.cfgIgn)
+  }
+  const logIgnoreItem = (k) => {
+    platform.log.warn('%s [%s] %s.', platformLang.cfgItem, k, platformLang.cfgIgnItem)
+  }
+  const logIncrease = (k, min) => {
+    platform.log.warn('%s [%s] %s %s.', platformLang.cfgItem, k, platformLang.cfgLow, min)
+  }
+  const logQuotes = (k) => {
+    platform.log.warn('%s [%s] %s.', platformLang.cfgItem, k, platformLang.cfgQts)
+  }
+  const logRemove = (k) => {
+    platform.log.warn('%s [%s] %s.', platformLang.cfgItem, k, platformLang.cfgRmv)
+  }
+
+  // Begin applying the user's config
+  Object.entries(config).forEach((entry) => {
+    const [key, val] = entry
+    switch (key) {
+      case 'apiKey':
+      case 'code':
+      case 'password':
+      case 'username':
+        if (typeof val !== 'string' || val === '') {
+          logIgnore(key)
+        } else {
+          platform.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 {
+          platform.config[key] = subnets
+        }
+        break
+      }
+      case 'awsDisable':
+      case 'bleDisable':
+      case 'colourSafeMode':
+      case 'disableDeviceLogging':
+      case 'ignoreMatter':
+      case 'lanDisable':
+        if (typeof val === 'string') {
+          logQuotes(key)
+        }
+        platform.config[key] = val === 'false' ? false : !!val
+        break
+      case 'bleControlInterval':
+      case 'bleRefreshTime':
+      case 'httpRefreshTime':
+      case 'lanRefreshTime':
+      case 'lanScanInterval': {
+        if (typeof val === 'string') {
+          logQuotes(key)
+        }
+        const intVal = Number.parseInt(val, 10)
+        if (Number.isNaN(intVal)) {
+          logDefault(key, platformConsts.defaultValues[key])
+          platform.config[key] = platformConsts.defaultValues[key]
+        } else if (intVal < platformConsts.minValues[key]) {
+          logIncrease(key, platformConsts.minValues[key])
+          platform.config[key] = platformConsts.minValues[key]
+        } else {
+          platform.config[key] = intVal
+        }
+        break
+      }
+      case 'dehumidifierDevices':
+      case 'fanDevices':
+      case 'heaterDevices':
+      case 'humidifierDevices':
+      case 'iceMakerDevices':
+      case 'kettleDevices':
+      case 'leakDevices':
+      case 'lightDevices':
+      case 'purifierDevices':
+      case 'diffuserDevices':
+      case 'switchDevices':
+      case 'thermoDevices':
+        if (Array.isArray(val) && val.length > 0) {
+          val.forEach((x) => {
+            if (!x.deviceId) {
+              logIgnoreItem(key)
+              return
+            }
+            const id = parseDeviceId(x.deviceId)
+            if (Object.keys(platform.deviceConf).includes(id)) {
+              logDuplicate(`${key}.${id}`)
+              return
+            }
+            const entries = Object.entries(x)
+            if (entries.length === 1) {
+              logRemove(`${key}.${id}`)
+              return
+            }
+            platform.deviceConf[id] = {}
+            entries.forEach((subEntry) => {
+              const [k, v] = subEntry
+              switch (k) {
+                case 'adaptiveLightingShift':
+                case 'brightnessStep':
+                case 'lowBattThreshold': {
+                  if (typeof v === 'string') {
+                    logQuotes(`${key}.${k}`)
+                  }
+                  const intVal = Number.parseInt(v, 10)
+                  if (Number.isNaN(intVal)) {
+                    logDefault(`${key}.${id}.${k}`, platformConsts.defaultValues[k])
+                    platform.deviceConf[id][k] = platformConsts.defaultValues[k]
+                  } else if (intVal < platformConsts.minValues[k]) {
+                    logIncrease(`${key}.${id}.${k}`, platformConsts.minValues[k])
+                    platform.deviceConf[id][k] = platformConsts.minValues[k]
+                  } else {
+                    platform.deviceConf[id][k] = intVal
+                  }
+                  break
+                }
+                case 'awsBrightnessNoScale':
+                case 'hideLight':
+                case 'hideModeGreenTea':
+                case 'hideModeOolongTea':
+                case 'hideModeCoffee':
+                case 'hideModeBlackTea':
+                case 'showCustomMode1':
+                case 'showCustomMode2':
+                case 'showExtraSwitch':
+                case 'tempReporting':
+                  if (typeof v === 'string') {
+                    logQuotes(`${key}.${id}.${k}`)
+                  }
+                  platform.deviceConf[id][k] = v === 'false' ? false : !!v
+                  break
+                case 'awsColourMode':
+                case 'openApiTempUnit':
+                case 'showAs': {
+                  if (typeof v !== 'string' || !platformConsts.allowed[k].includes(v)) {
+                    logIgnore(`${key}.${id}.${k}`)
+                  } else {
+                    platform.deviceConf[id][k] = v
+                  }
+                  break
+                }
+                case 'customAddress':
+                case 'customIPAddress':
+                  if (typeof v !== 'string' || v === '') {
+                    logIgnore(`${key}.${id}.${k}`)
+                  } else {
+                    platform.deviceConf[id][k] = v.replace(WHITESPACE_REGEX, '')
+                  }
+                  break
+                case 'deviceId':
+                  break
+                case 'diyMode':
+                case 'diyModeTwo':
+                case 'diyModeThree':
+                case 'diyModeFour':
+                case 'musicMode':
+                case 'musicModeTwo':
+                case 'scene':
+                case 'sceneTwo':
+                case 'sceneThree':
+                case 'sceneFour':
+                case 'segmented':
+                case 'segmentedTwo':
+                case 'segmentedThree':
+                case 'segmentedFour':
+                case 'temperatureSource':
+                case 'videoMode':
+                case 'videoModeTwo': {
+                  if (typeof v === 'string') {
+                    platform.log.warn(`${key}.${id}.${k} incorrectly configured - please use the config screen to reconfigure this item:`)
+                    platform.log.warn(`${key}.${id}.${k}: ${v}`)
+                  }
+                  if (typeof v === 'object') {
+                    // object - only allowed keys are 'sceneCode', 'bleCode' and 'showAs'
+                    const subEntries = Object.entries(v)
+                    if (subEntries.length > 0) {
+                      platform.deviceConf[id][k] = {}
+                      subEntries.forEach((subSubEntry) => {
+                        const [k1, v1] = subSubEntry
+                        switch (k1) {
+                          case 'bleCode':
+                          case 'sceneCode':
+                            if (typeof v1 !== 'string' || v1 === '') {
+                              logIgnore(`${key}.${id}.${k}.${k1}`)
+                            } else {
+                              platform.deviceConf[id][k][k1] = v1
+                            }
+                            break
+                          case 'showAs': {
+                            if (typeof v1 !== 'string' || !['default', 'switch'].includes(v1)) {
+                              logIgnore(`${key}.${id}.${k}.${k1}`)
+                            } else {
+                              platform.deviceConf[id][k][k1] = v1
+                            }
+                            break
+                          }
+                          default:
+                            logIgnore(`${key}.${id}.${k}.${k1}`)
+                            break
+                        }
+                      })
+                    } else {
+                      logIgnore(`${key}.${id}.${k}`)
+                    }
+                  } else {
+                    logIgnore(`${key}.${id}.${k}`)
+                  }
+                  break
+                }
+                case 'ignoreDevice':
+                  if (typeof v === 'string') {
+                    logQuotes(`${key}.${id}.${k}`)
+                  }
+                  if (!!v && v !== 'false') {
+                    platform.ignoredDevices.push(id)
+                  }
+                  break
+                case 'label':
+                  if (typeof v !== 'string' || v === '') {
+                    logIgnore(`${key}.${id}.${k}`)
+                  } else {
+                    platform.deviceConf[id][k] = v
+                  }
+                  break
+                default:
+                  logRemove(`${key}.${id}.${k}`)
+              }
+            })
+          })
+        } else {
+          logIgnore(key)
+        }
+        break
+      case 'name':
+      case 'platform':
+        break
+      default:
+        logRemove(key)
+        break
+    }
+  })
+}