@homebridge-plugins/homebridge-govee 11.32.2-beta.9 → 11.32.2

package/CHANGELOG.md

@@ -2,10 +2,12 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
-## v11.32.2 (Pending Release)
+## v11.32.2 (2026-08-03)
 
 ### Changed
 
+- fix: stop shipping the test files to npm, since they are only needed in the repository
+- fix: BLE device control on macOS by resolving peripherals via advertised name (#1336) (@Perafan18)
 - fix: implement the H7107's oscillation toggle, which threw a not-implemented error when tapped (#1334)
 - fix: also send the H7107's oscillation command as the multiSync frame the fan itself uses, since the first shape only turned it off sometimes (#1334)
 - fix: send the H7107's oscillation-off command without the swing-range bytes, matching the zero-tailed frame the fan echoes back (#1334)
@@ -20,8 +22,35 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - feat: add the H7103 and H7112 fans and the H5085 plug, with unknown controls saying so instead of guessing
 - feat: give every appliance type a starting handler, so a new model works for on and off and asks for the rest
 - refactor: point models that behave identically at one shared handler instead of copies of the same file
-- fix: stop shipping the test files to npm, since they are only needed in the repository
-- docs: keep the structure notes outside the repository, since they are working notes rather than plugin documentation
+- fix: refuse to send a bluetooth command too long to fit in a packet, rather than sending a longer one the device quietly ignores
+- test: record what every supported model turns into, so a change can be shown to have altered nothing
+- feat: work out what an appliance can do from what the device itself reports, so a model nobody has written down still gets the right controls
+- feat: offer oscillation and the child lock on any appliance that reports having them, driven through govee's api rather than needing that model's command codes
+- refactor: point three more models at a shared handler instead of a near-copy of the same file, keeping each one's behaviour exactly as it was
+- fix: give the H7124 the air quality handling the H7123 already had, so a poor reading is named properly and stops being logged over and over (#1261)
+- refactor: point the H7151 and H7111 at the handlers they were byte-for-byte copies of
+- refactor: build the ice maker size codes from the model rather than writing both orderings out by hand
+- refactor: build the switch and outlet tiles of a multi-socket device from one handler instead of two copies of it
+- fix: move the H7152 dehumidifier's speed slider when it reports a new speed, which until now only the H7150 and H7151 did
+- refactor: point the H7101 and H7111 fans at the H7100 handler they matched command for command
+- 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
+- test: check what the plugin sends over aws, the local network and the public api, none of which was covered before
+- feat: say when govee has not listed a capability the plugin is about to use, since the request then succeeds and the device does nothing
+- docs: note that the local network api accepts the raw command form, which is how scenes work without the cloud
+- refactor: give every device one shared starting point, so the way a failed command is reported and undone is decided in one place rather than a hundred
+- feat: recognise eleven more meat thermometers, which report what they send so their readings can be worked out, and stop the one already known printing its whole update as a warning
+- feat: add the H5161 power strip and give the H7184 kitchen composter an on and off switch
+- feat: recognise three more sensors, which report what they send, and say plainly in the log why a sensor has no tile yet
+- feat: add ble encryption for the H3001 solar string lights, which silently ignore unencrypted frames (#1328) (@dominick-han)
+- fix: mention an unrecognised bluetooth broadcast once, and only for one of your own sensors, since a scan also hears your lights and the neighbours
+- fix: say "device(s)" in the connection summary, since the count is often one
+- fix: stop the macOS bluetooth scan leaving its timer running once the device has been found
+- docs: say that macOS bluetooth support is new and ask for reports, rather than stating it works
+- chore(deps): dependency updates
 
 ## v11.32.1 (2026-08-02)
 

package/README.md

@@ -29,7 +29,7 @@ Homebridge plugin to integrate Govee devices into HomeKit
 - To use this plugin, you will need to already have:
   - [Node](https://nodejs.org): latest version of `v22`, `v24` or `v26` - any other major version is not supported.
   - [Homebridge](https://homebridge.io): `v1.6` or above - refer to link for more information and installation instructions.
-  - For bluetooth connectivity, it may be necessary to install extra packages on your system, see [Bluetooth Control](https://github.com/homebridge-plugins/homebridge-govee/wiki/Bluetooth-Control). Bluetooth works best when using a Raspberry Pi, not been tested on Windows, and Mac devices are unsupported.
+  - For bluetooth connectivity, it may be necessary to install extra packages on your system, see [Bluetooth Control](https://github.com/homebridge-plugins/homebridge-govee/wiki/Bluetooth-Control). Bluetooth works best on a Raspberry Pi, and has not been tested on Windows. macOS is newly supported from `v11.32.2` and has only been tried on a handful of devices so far - you will need to give the `node` binary running Homebridge permission under System Settings → Privacy & Security → Bluetooth, and please do report anything that does not work.
 
 ### Setup
 

package/lib/connection/ble.js

@@ -3,8 +3,10 @@ import process from 'node:process'
 
 import btClient from '@stoprocent/noble'
 
+import { buildHandshake, isHandshakeFrame, parseHandshakeResponse, V2Session } from '../utils/ble-crypto.js'
 import { BLE_STAGE_TIMEOUTS, UUID } from '../utils/ble-protocol.js'
 import { decodeAny } from '../utils/decode.js'
+import { getDeviceCapabilities } from '../utils/device-capabilities.js'
 import { base64ToHex, generateCodeFromHexValues, hexToTwoItems, sleep } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
 import { isFirstReport } from '../utils/report-unknown.js'
@@ -20,6 +22,7 @@ const H5101_UUID = '0001'
 const POWER_ON_TIMEOUT = BLE_STAGE_TIMEOUTS.powerOn
 const CONNECTION_TIMEOUT = BLE_STAGE_TIMEOUTS.connect
 const WRITE_TIMEOUT = BLE_STAGE_TIMEOUTS.write
+const HANDSHAKE_TIMEOUT = BLE_STAGE_TIMEOUTS.handshake
 const SETTLE_DELAY = BLE_STAGE_TIMEOUTS.settle
 
 /*
@@ -121,30 +124,39 @@ export default class BLEConnection {
     try {
       const { uuid, address, rssi, advertisement } = peripheral
 
-      // Skip if not a valid Govee sensor. Sensors whose broadcast the plugin
-      // cannot decode yet are logged rather than dropped in silence, since the
-      // hex is the one thing needed to add a model, and there is no other way
-      // for an owner to get hold of it.
+      // A broadcast this plugin cannot decode is worth reporting rather than
+      // dropping in silence, since the hex is the one thing needed to add a
+      // model and an owner has no other way to get hold of it.
       if (!isValidPeripheral(peripheral)) {
         const unknownName = advertisement?.localName
         if (unknownName && unknownName.toLowerCase().startsWith('govee')) {
           const raw = advertisement.manufacturerData
             ? advertisement.manufacturerData.toString('hex')
             : 'no manufacturer data'
-          const line = `[BLE] unrecognised govee sensor - please include this line if you report it: ${JSON.stringify({
-            name: unknownName,
-            address,
-            source: 'BLE',
-            kind: 'broadcast',
-            raw,
-          })}`
-
-          // Say it once so it is actually noticed, then stay quiet about this
-          // sensor for the rest of the session - it rebroadcasts constantly.
+
+          // A device rebroadcasts constantly, so say this once and then stay
+          // quiet about it for the rest of the session. This has to come first:
+          // gating it on the warning below would leave every other broadcast
+          // ungoverned, and a debug log would fill with the same line.
           if (isFirstReport(`ble|${address}|${raw}`)) {
-            this.log.warn(line)
-          } else {
-            this.log.debug(line)
+            const line = `[BLE] unrecognised broadcast from a govee device - please include this line if you report it: ${JSON.stringify({
+              name: unknownName,
+              address,
+              source: 'BLE',
+              kind: 'broadcast',
+              raw,
+            })}`
+
+            // Only one of this account's own sensors is worth putting in front
+            // of someone: that is the case where the plugin should be reading
+            // the broadcast and cannot. A light of theirs broadcasts just as
+            // often but is driven over aws/lan/ble, and an address that is not
+            // on the account at all may belong to a neighbour.
+            if (this.platform.hasBleSensor(address)) {
+              this.log.warn(line)
+            } else {
+              this.log.debug(line)
+            }
           }
         }
         return
@@ -265,8 +277,19 @@ export default class BLEConnection {
       const finalBuffer = this.prepareCommandBuffer(params)
       accessory.logDebug(`sending command: ${finalBuffer.toString('hex')}`)
 
+      // Encrypted models refuse the plain frame. Because writes are
+      // unacknowledged, they refuse it silently, so the handshake has to happen
+      // here rather than being discovered by a failed write. It is per
+      // connection: the frame counter resets with the link.
+      let payload = finalBuffer
+      if (getDeviceCapabilities(accessory.context.gvModel).bleEncryption === 'v2') {
+        const session = await this.negotiateSession(accessory, characteristic, characteristics)
+        payload = session.seal(finalBuffer)
+        accessory.logDebug(`encrypted as: ${payload.toString('hex')}`)
+      }
+
       // Write without response then allow time for the BLE controller to transmit before disconnecting
-      await this.writeWithTimeout(characteristic, finalBuffer, WRITE_TIMEOUT)
+      await this.writeWithTimeout(characteristic, payload, WRITE_TIMEOUT)
       accessory.logDebug('command sent successfully')
       await sleep(SETTLE_DELAY)
     } catch (err) {
@@ -299,11 +322,77 @@ export default class BLEConnection {
     }
   }
 
+  /**
+   * Exchange a session key with an encrypted model.
+   *
+   * Unlike every other path in this client we need a reply, which arrives as a
+   * notification on UUID.NOTIFY. Note that we deliberately do NOT subscribe:
+   * these lights push notifications without the client ever writing the client
+   * characteristic configuration descriptor.
+   * Calling subscribeAsync() here makes the descriptor write hang and the light
+   * then drops the connection, so listening is both sufficient and required.
+   *
+   * The reply is authenticated - parseHandshakeResponse throws if the GCM tag
+   * does not verify - which turns a wrong key into a real error rather than a
+   * light that silently ignores every command.
+   *
+   * Returns a V2Session that wraps outgoing frames.
+   */
+  async negotiateSession(accessory, writeCharacteristic, characteristics) {
+    const notifyCharacteristic = Object.values(characteristics).find(
+      char => char.uuid.replace(HYPHEN_REGEX, '') === UUID.NOTIFY,
+    )
+    if (!notifyCharacteristic) {
+      throw new Error('Notify characteristic not found, cannot negotiate encryption')
+    }
+
+    let resolveReply
+    let rejectReply
+    const reply = new Promise((resolve, reject) => {
+      resolveReply = resolve
+      rejectReply = reject
+    })
+    // Attach a handler immediately: if the write below throws, the timeout would
+    // otherwise reject an unawaited promise and crash the process.
+    reply.catch(() => {})
+
+    const onData = (data) => {
+      // The light also pushes state frames here; take only the handshake.
+      if (isHandshakeFrame(data)) {
+        resolveReply(data)
+      }
+    }
+    notifyCharacteristic.on('data', onData)
+    const timer = setTimeout(
+      () => rejectReply(new Error('Encryption handshake timeout')),
+      HANDSHAKE_TIMEOUT,
+    )
+
+    try {
+      const { frame, txIvKey } = buildHandshake()
+      accessory.logDebug(`sending handshake: ${frame.toString('hex')}`)
+      await this.writeWithTimeout(writeCharacteristic, frame, WRITE_TIMEOUT)
+
+      const response = await reply
+      accessory.logDebug(`handshake reply: ${response.toString('hex')}`)
+
+      const { devInfo, sku, mac } = parseHandshakeResponse(response)
+      accessory.logDebug(`handshake verified for ${sku} at ${mac}`)
+
+      return new V2Session({ txIvKey, devInfo })
+    } finally {
+      clearTimeout(timer)
+      notifyCharacteristic.removeListener('data', onData)
+    }
+  }
+
   async connectWithTimeout(address, timeout) {
     let timeoutId
     try {
       return await Promise.race([
-        btClient.connectAsync(address),
+        process.platform === 'darwin'
+          ? this.connectByNameDarwin(address, timeout)
+          : btClient.connectAsync(address),
         new Promise((_, reject) => {
           timeoutId = setTimeout(() => reject(new Error('Connection timeout')), timeout)
         }),
@@ -313,6 +402,54 @@ export default class BLEConnection {
     }
   }
 
+  // macOS: CoreBluetooth never exposes MAC addresses, so connect-by-address can
+  // never resolve. Govee devices advertise a local name whose suffix is the last
+  // two bytes of their MAC (e.g. Govee_H617A_325A for ...:32:5A), so scan and
+  // match on that instead, then connect to the discovered peripheral directly.
+  async connectByNameDarwin(address, timeout) {
+    const suffix = address.replace(/:/g, '').slice(-4).toLowerCase()
+    this.darwinPeripheralCache = this.darwinPeripheralCache ?? new Map()
+    const cached = this.darwinPeripheralCache.get(suffix)
+    if (cached) {
+      try {
+        await cached.connectAsync()
+        return cached
+      } catch (err) {
+        this.darwinPeripheralCache.delete(suffix)
+        this.log.debug('[BLE] cached peripheral for %s failed (%s), rescanning.', suffix, err.message)
+      }
+    }
+    const peripheral = await new Promise((resolve, reject) => {
+      let done = false
+      let scanTimeoutId
+      function onDiscover(p) {
+        const name = (p.advertisement?.localName ?? '').toLowerCase()
+        if (name.endsWith(suffix) && (name.startsWith('govee') || name.startsWith('ihoment'))) {
+          finish(resolve, p)
+        }
+      }
+      function finish(fn, value) {
+        if (done) {
+          return
+        }
+        done = true
+        // The device is usually found in well under a second, so without this
+        // the timer stays live for the rest of its window and holds the event
+        // loop open. The two timeouts above clear theirs the same way.
+        clearTimeout(scanTimeoutId)
+        btClient.removeListener('discover', onDiscover)
+        btClient.stopScanningAsync().catch(() => {})
+        fn(value)
+      }
+      btClient.on('discover', onDiscover)
+      btClient.startScanningAsync([], true).catch(err => finish(reject, err))
+      scanTimeoutId = setTimeout(() => finish(reject, new Error(`no peripheral advertising name suffix ${suffix} found in scan`)), Math.max(timeout - 1000, 4000))
+    })
+    this.darwinPeripheralCache.set(suffix, peripheral)
+    await peripheral.connectAsync()
+    return peripheral
+  }
+
   async writeWithTimeout(characteristic, buffer, timeout) {
     let timeoutId
     try {

package/lib/connection/openapi.js

@@ -3,6 +3,7 @@ import mqtt from 'mqtt'
 
 import { k2rgb } from '../utils/colour.js'
 import { describeControlFailure, parseError } from '../utils/functions.js'
+import { isFirstReport } from '../utils/report-unknown.js'
 
 const BASE_URL = 'https://openapi.api.govee.com'
 
@@ -381,6 +382,23 @@ export default class {
     if (capability?.type && capability?.instance) {
       return capability
     }
+
+    // The device never listed this one. Govee will still accept the request and
+    // answer as though it worked, then do nothing - so without saying something
+    // here the control simply appears broken with no clue why. Said once per
+    // device and capability, then dropped to debug
+    const fingerprint = `openapi-unlisted|${accessory.context.gvDeviceId}|${instance}`
+    const message = `govee did not list [${instance}] for this device, so that command may be ignored - please report this line if the control does not work: ${JSON.stringify({
+      model: accessory.context.gvModel,
+      instance,
+      listed: Object.keys(lookup),
+    })}`
+    if (isFirstReport(fingerprint)) {
+      accessory.logDebugWarn(message)
+    } else {
+      accessory.logDebug(message)
+    }
+
     return {
       type: fallbackType,
       instance,

package/lib/device/appliance-basic.js

@@ -1,6 +1,8 @@
-import { base64ToHex, getTwoItemPosition, hexToTwoItems, parseError } from '../utils/functions.js'
+import { describeSources, resolveControls } from '../utils/capabilities.js'
+import { base64ToHex, getTwoItemPosition, hexToTwoItems } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
 import { logUnknownData, reportUnsupportedControl } from '../utils/report-unknown.js'
+import GoveeDevice from './base.js'
 
 /**
  * A starting point for any appliance whose power command is known but whose
@@ -19,25 +21,32 @@ import { logUnknownData, reportUnsupportedControl } from '../utils/report-unknow
  *
  * Once that data arrives the model gets a proper handler and stops using this.
  */
-class ApplianceBasic {
+class ApplianceBasic extends GoveeDevice {
   constructor(platform, accessory, config) {
-    // Set up variables from the platform
-    this.hapChar = platform.api.hap.Characteristic
-    this.hapErr = platform.api.hap.HapStatusError
-    this.hapServ = platform.api.hap.Service
-    this.platform = platform
-
+    super(platform, accessory)
     // Set up variables from the accessory
-    this.accessory = accessory
     this.config = config
 
+    // Work out what this particular device can do, rather than what its model
+    // generally can - for a model nobody has written down, what the device
+    // itself reported is all there is to go on
+    const resolved = resolveControls({
+      model: accessory.context.gvModel,
+      family: config.family,
+      firmware: accessory.context.firmware,
+      openApiCapabilities: accessory.context.openApiCapabilities,
+      deviceConf: platform.deviceConf?.[accessory.context.gvDeviceId],
+    })
+    this.controls = resolved.controls
+    this.cacheToggles = {}
+    this.discoveredControls = []
+
     // Some appliances can have a richer tile, but only if the device reports
     // the reading that tile needs - HomeKit's humidifier, for example, has to
     // show a current humidity, and plenty of Govee humidifiers never send one.
-    // Where Govee tells us the device has that sensor, use the better tile;
-    // otherwise fall back to the plain one, which needs nothing extra.
-    const hasSensor = config.richCapability
-      && !!accessory.context.openApiCapabilities?.[config.richCapability]
+    // Where the device says it has that sensor, use the better tile; otherwise
+    // fall back to the plain one, which needs nothing extra.
+    const hasSensor = config.richControl && this.controls[config.richControl]
     const serviceName = (config.richService && hasSensor) ? config.richService : config.service
     this.usingRichService = serviceName === config.richService
 
@@ -57,7 +66,7 @@ class ApplianceBasic {
     // The plain Fan service switches on a boolean `On`, while Fanv2 and
     // AirPurifier use `Active`. Follow whichever this service uses, so these
     // tiles behave like the hand-written handlers for the same kind of device.
-    const usesOn = serviceName === 'Fan'
+    const usesOn = serviceName === 'Fan' || serviceName === 'Switch'
     this.powerChar = usesOn ? this.hapChar.On : this.hapChar.Active
     this.powerOn = usesOn ? true : 1
     this.powerOff = usesOn ? false : 0
@@ -94,10 +103,76 @@ class ApplianceBasic {
       this.cacheVariable = this.service.getCharacteristic(this.variableChar).value
     }
 
+    // A control the device told us about can be driven through Govee's own api
+    // by name, without knowing this model's command bytes. So unlike the
+    // settings above, these work rather than asking to be reported.
+    this.addDiscoveredToggle('swing', 'SwingMode', 'oscillationToggle')
+    this.addDiscoveredToggle('lock', 'LockPhysicalControls', 'lockToggle')
+
     // Output the customised options to the log
     const opts = JSON.stringify({})
     platform.log('[%s] %s %s.', accessory.displayName, platformLang.devInitOpts, opts)
-    this.accessory.log(`on and off are supported for this model, the ${config.variableLabel || 'other settings'} are not known yet`)
+    this.accessory.logDebug(`controls: ${describeSources(resolved.sources)}`)
+
+    const working = ['on and off', ...this.discoveredControls]
+    this.accessory.log(`${working.join(', ')} ${working.length > 1 ? 'are' : 'is'} supported for this model, the ${config.variableLabel || 'other settings'} are not known yet`)
+  }
+
+  /**
+   * Offer a control the device said it has, driven through Govee's api by the
+   * name the device gave it.
+   *
+   * This is the one place a model nobody has tested gets something that really
+   * works beyond power: the api takes the capability name, so the command bytes
+   * for this model never have to be known.
+   */
+  addDiscoveredToggle(control, characteristic, instance) {
+    const char = this.hapChar[characteristic]
+
+    // The device has to have named this capability itself. Knowing the model
+    // usually has a turning head is not enough - the api is driven by the name
+    // the device reported, so without it there is nothing to send, and the
+    // switch would fail every time it was touched.
+    const reported = !!this.accessory.context.openApiCapabilities?.[instance]
+
+    if (!reported || !this.controls[control] || !char) {
+      if (this.service.testCharacteristic?.(char)) {
+        this.service.removeCharacteristic(this.service.getCharacteristic(char))
+      }
+      return
+    }
+
+    this.service
+      .getCharacteristic(char)
+      .onSet(async value => this.internalToggleUpdate(control, char, instance, value))
+    this.cacheToggles[control] = this.service.getCharacteristic(char).value
+
+    this.discoveredControls.push(control === 'swing' ? 'oscillation' : 'the child lock')
+  }
+
+  async internalToggleUpdate(control, characteristic, instance, value) {
+    const previous = this.cacheToggles[control]
+    try {
+      if (previous === value) {
+        return
+      }
+
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'openApi',
+        openApi: {
+          instance,
+          capabilityType: 'devices.capabilities.toggle',
+          value: value ? 1 : 0,
+        },
+      })
+
+      this.cacheToggles[control] = value
+      this.accessory.log(`current ${control} [${value ? 'on' : 'off'}]`)
+    } catch (err) {
+      this.failUpdate(err, () => {
+        this.service.updateCharacteristic(characteristic, previous)
+      })
+    }
   }
 
   async internalStateUpdate(value) {
@@ -129,14 +204,9 @@ class ApplianceBasic {
       }
       this.accessory.log(`${platformLang.curState} [${newValue}]`)
     } catch (err) {
-      // Catch any errors during the process
-      this.accessory.logWarn(`${platformLang.devNotUpdated} ${parseError(err)}`)
-
-      // Throw a 'no response' error and set a timeout to revert this after 2 seconds
-      setTimeout(() => {
+      this.failUpdate(err, () => {
         this.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
-      }, 2000)
-      throw new this.hapErr(-70402)
+      })
     }
   }
 
@@ -229,6 +299,7 @@ export function makeBasicAppliance(config) {
 
 // Fan-shaped appliances: a speed slider that is not worked out yet
 export const deviceFanBasic = makeBasicAppliance({
+  family: 'fan',
   service: 'Fanv2',
   variableChar: 'RotationSpeed',
   variableLabel: 'fan speed',
@@ -236,6 +307,7 @@ export const deviceFanBasic = makeBasicAppliance({
 
 // Ice makers reuse the fan tile, with the slider standing in for ice size
 export const deviceIceMakerBasic = makeBasicAppliance({
+  family: 'iceMaker',
   service: 'Fanv2',
   variableChar: 'RotationSpeed',
   variableLabel: 'ice size',
@@ -245,11 +317,12 @@ export const deviceIceMakerBasic = makeBasicAppliance({
 // has to show a current humidity and many Govee humidifiers never report one.
 // A model that does report it gets the proper humidifier tile instead.
 export const deviceHumidifierBasic = makeBasicAppliance({
+  family: 'humidifier',
   service: 'Fan',
   variableChar: 'RotationSpeed',
   variableLabel: 'mist level',
   richService: 'HumidifierDehumidifier',
-  richCapability: 'sensorHumidity',
+  richControl: 'humiditySensor',
   richVariableChar: 'RelativeHumidityHumidifierThreshold',
   richReadingChar: 'CurrentRelativeHumidity',
   currentStateChar: 'CurrentHumidifierDehumidifierState',
@@ -258,11 +331,12 @@ export const deviceHumidifierBasic = makeBasicAppliance({
 })
 
 export const deviceDehumidifierBasic = makeBasicAppliance({
+  family: 'dehumidifier',
   service: 'Fan',
   variableChar: 'RotationSpeed',
   variableLabel: 'fan speed',
   richService: 'HumidifierDehumidifier',
-  richCapability: 'sensorHumidity',
+  richControl: 'humiditySensor',
   richVariableChar: 'RelativeHumidityDehumidifierThreshold',
   richReadingChar: 'CurrentRelativeHumidity',
   currentStateChar: 'CurrentHumidifierDehumidifierState',
@@ -270,7 +344,25 @@ export const deviceDehumidifierBasic = makeBasicAppliance({
   currentStateOff: 0, // inactive
 })
 
+// Diffusers are power only, so there is no variable control to offer. They use
+// the same tile as the models already handled, so a new one looks the same
+export const deviceDiffuserBasic = makeBasicAppliance({
+  family: 'diffuser',
+  service: 'AirPurifier',
+  currentStateChar: 'CurrentAirPurifierState',
+  currentStateOn: 2, // purifying air
+  currentStateOff: 0, // inactive
+})
+
+// A composter is on or off. It has a mode and a light too, but neither is
+// worked out, so they are left off rather than shown as controls that do nothing
+export const deviceComposterBasic = makeBasicAppliance({
+  family: 'composter',
+  service: 'Switch',
+})
+
 export const devicePurifierBasic = makeBasicAppliance({
+  family: 'purifier',
   service: 'AirPurifier',
   variableChar: 'RotationSpeed',
   variableLabel: 'fan speed',

package/lib/device/base.js

@@ -0,0 +1,80 @@
+import { parseError } from '../utils/functions.js'
+import platformLang from '../utils/lang-en.js'
+
+/**
+ * What every device handler needs, in one place.
+ *
+ * Each handler used to open with the same five assignments, build its tiles the
+ * same way, and end every control with the same six-line failure block. That
+ * last one was written out a hundred times over, which meant the delay before a
+ * control snaps back, and the error HomeKit is given, were a hundred separate
+ * decisions that happened to agree.
+ */
+export default class GoveeDevice {
+  constructor(platform, accessory) {
+    this.hapChar = platform.api.hap.Characteristic
+    this.hapErr = platform.api.hap.HapStatusError
+    this.hapServ = platform.api.hap.Service
+    this.platform = platform
+    this.accessory = accessory
+  }
+
+  /**
+   * The line at startup saying which of this device's settings are not the
+   * defaults.
+   */
+  logInitOptions(options = {}) {
+    this.platform.log(
+      '[%s] %s %s.',
+      this.accessory.displayName,
+      platformLang.devInitOpts,
+      JSON.stringify(options),
+    )
+  }
+
+  /**
+   * Get a tile, making it if it is not there yet.
+   */
+  getOrAddService(serviceType, name, subtype) {
+    return this.accessory.getService(name ?? serviceType)
+      || this.accessory.addService(serviceType, name, subtype)
+  }
+
+  /**
+   * Drop a tile if the device has one, for when a setting has changed what this
+   * device should look like. Leaving the old one behind gives the owner a tile
+   * that no longer does anything.
+   */
+  removeServiceIfPresent(serviceType) {
+    const existing = this.accessory.getService(serviceType)
+    if (existing) {
+      this.accessory.removeService(existing)
+    }
+    return !!existing
+  }
+
+  /**
+   * Give up on a control, put it back the way it was, and tell HomeKit.
+   *
+   * The three parts matter together: the log line says what went wrong, the
+   * revert stops the tile showing a state the device is not in, and the error
+   * is what makes HomeKit show it as not responding rather than quietly
+   * accepting a change that never happened.
+   *
+   * `revert` is a function rather than a value so it is read when it runs, two
+   * seconds later, which is the behaviour this replaced.
+   *
+   * @param {Error} err whatever went wrong
+   * @param {Function} [revert] puts the control back
+   * @throws {object} always - the caller is expected to let this bubble up
+   */
+  failUpdate(err, revert) {
+    this.accessory.logWarn(`${platformLang.devNotUpdated} ${parseError(err)}`)
+
+    if (revert) {
+      setTimeout(revert, 2000)
+    }
+
+    throw new this.hapErr(-70402)
+  }
+}