@homebridge-plugins/homebridge-govee 11.34.2-beta.6 → 11.34.2-beta.8

package/CHANGELOG.md

@@ -19,7 +19,10 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - fix: apply the openapi disable and refresh settings instead of asking for them to be removed
 - fix: say once when a bluetooth reading arrives for an unknown device, not on every broadcast
 - fix: reject a refresh time so large it would make the plugin poll every millisecond
-- fix(H5054): don't let a slow leak warning block other sensors
+- fix(H5054): don't let a slow leak warning block other sensors (#1348)
+- fix: mark sensor batteries low at the configured threshold
+- feat: show whether the kettle is heating, keeping warm or idle (#1337)
+- fix: give the H5106 a battery service, so its low battery setting does something
 
 ## v11.34.1 (2026-08-06)
 

package/lib/device/base.js

@@ -53,6 +53,27 @@ export default class GoveeDevice {
     return !!existing
   }
 
+  updateBattery(battery) {
+    if (!this.battService || !Number.isFinite(battery) || battery < 0 || battery > 100) {
+      return
+    }
+
+    if (battery !== this.cacheBatt) {
+      this.cacheBatt = battery
+      this.battService.updateCharacteristic(this.hapChar.BatteryLevel, this.cacheBatt)
+      this.accessory.log(`${platformLang.curBatt} [${this.cacheBatt}%]`)
+    }
+
+    const lowBattery = battery <= this.lowBattThreshold ? 1 : 0
+    const currentLowBattery = Number(this.battService
+      .getCharacteristic(this.hapChar.StatusLowBattery)
+      .value)
+
+    if (lowBattery !== currentLowBattery) {
+      this.battService.updateCharacteristic(this.hapChar.StatusLowBattery, lowBattery)
+    }
+  }
+
   /**
    * Give up on a control, put it back the way it was, and tell HomeKit.
    *

package/lib/device/kettle.js

@@ -28,12 +28,16 @@ import GoveeDevice from './base.js'
 /**
  * The water temperature out of a status frame, in celsius.
  *
- * The frame carries it as two bytes of hundredths of a degree fahrenheit. That
- * layout has never been confirmed against a kettle sitting at a known
- * temperature, so the result is checked before it is used: a kettle holds
- * water, and a figure outside freezing to a little past boiling is not a
- * temperature at all - it means this model packs the frame differently.
- * Returning nothing then leaves the tile absent rather than wrong.
+ * The frame carries it as two bytes of hundredths of a degree fahrenheit. An
+ * owner confirmed that layout against three known points on an H7171 (#1337):
+ * cold water read 0x1edc = 79.00F, the moment the kettle beeped at its 142F
+ * target it read 0x3778 = 142.00F, and it drifted to 0x39d0 = 148.00F after.
+ *
+ * The result is still checked before it is used, because only the one model has
+ * been seen: a kettle holds water, and a figure outside freezing to a little
+ * past boiling is not a temperature at all - it means that model packs the
+ * frame differently. Returning nothing then leaves the tile absent rather than
+ * wrong.
  *
  * @param {string[]} hexParts the frame split into bytes
  * @returns {number|undefined} the reading in celsius, or undefined if the
@@ -51,6 +55,33 @@ function readingToCelsius(hexParts) {
   return farToCen(fahrenheit)
 }
 
+/**
+ * What the kettle says it is doing, from the state byte of an `aa 19` frame.
+ *
+ * Worked out from a full run an owner instrumented for us (#1337), matching the
+ * frames against a running commentary of what the kettle was doing:
+ *
+ *   00  idle      two seconds after they switched it off
+ *   01  heating   the moment they turned it on, and a second after setting a
+ *                 temperature on an earlier run
+ *   04  reached   as the water hit the target and the kettle beeped
+ *   02  warming   held for the next three and a half minutes of keep warm
+ *
+ * `04` and `02` arrive in the same second, so which of the pair marks reaching
+ * the target and which marks entering keep warm is read from their order, not
+ * proven separately. Both leave the kettle no longer heating, which is what the
+ * sensor reflects, so the distinction only affects the wording in the log.
+ *
+ * Only these four have been seen, all with keep warm switched on. Anything else
+ * falls through to the unknown-data report, which is how these were found.
+ */
+const HEATING_STATES = {
+  '00': { label: 'idle', heating: false },
+  '01': { label: 'heating', heating: true },
+  '02': { label: 'keeping warm', heating: false },
+  '04': { label: 'reached target', heating: false },
+}
+
 export default class extends GoveeDevice {
   constructor(platform, accessory) {
     super(platform, accessory)
@@ -294,6 +325,45 @@ export default class extends GoveeDevice {
     }
   }
 
+  /**
+   * Reflect what the kettle says it is doing.
+   *
+   * The tile is added the first time a state frame arrives rather than up
+   * front, for the same reason as the temperature tile above: only the H7171
+   * has been seen sending these, and a tile that never updates cannot be told
+   * apart from a real reading.
+   *
+   * @param {string} stateByte the state byte of an `aa 19` frame
+   */
+  updateHeatingState(stateByte) {
+    const state = HEATING_STATES[stateByte]
+    if (!state) {
+      return
+    }
+
+    if (!this.serviceHeating) {
+      this.serviceHeating = this.accessory.getService('Heating')
+      if (!this.serviceHeating) {
+        this.serviceHeating = this.accessory.addService(this.hapServ.ContactSensor, 'Heating', 'heating')
+        this.serviceHeating.addCharacteristic(this.hapChar.ConfiguredName)
+        this.serviceHeating.updateCharacteristic(this.hapChar.ConfiguredName, 'Heating')
+      }
+    }
+
+    if (this.cacheHeatingState === state.label) {
+      return
+    }
+    this.cacheHeatingState = state.label
+
+    this.serviceHeating.updateCharacteristic(
+      this.hapChar.ContactSensorState,
+      state.heating
+        ? this.hapChar.ContactSensorState.CONTACT_DETECTED
+        : this.hapChar.ContactSensorState.CONTACT_NOT_DETECTED,
+    )
+    this.accessory.log(`current status [${state.label}]`)
+  }
+
   externalUpdate(params) {
     // Handle OpenAPI workMode
     if (params.workMode) {
@@ -369,13 +439,23 @@ export default class extends GoveeDevice {
         case '2301': { // scheduled start on
           break
         }
+        // What the kettle is doing - see HEATING_STATES above. `1900` used to be
+        // treated as a startup frame, which it only looked like because a kettle
+        // is usually idle when it connects; it is really the idle state and is
+        // sent whenever the kettle reaches it.
+        case '1900':
+        case '1901':
+        case '1902':
+        case '1904': {
+          this.updateHeatingState(getTwoItemPosition(hexParts, 3))
+          break
+        }
         // Also sent on startup, alongside the preset list above. What each one
         // carries has not been worked out, and nothing here needs them, so they
         // are known-and-ignored rather than reported every time (#1337)
         case '1701': // a second form of the on-base report
         case '1f06':
-        case '1f08':
-        case '1900': {
+        case '1f08': {
           this.accessory.logDebug(`startup status [${deviceFunction}]: ${hexString}`)
           break
         }

package/lib/device/sensor-leak.js

@@ -47,19 +47,7 @@ export default class extends GoveeDevice {
       this.platform.updateAccessoryStatus(this.accessory, this.cacheOnline)
     }
 
-    // Check to see if the provided battery is different from the cached state
-    if (Number.isFinite(params.battery) && params.battery !== this.cacheBatt) {
-      // Battery is different so update Homebridge with new values
-      this.cacheBatt = params.battery
-      this.battService.updateCharacteristic(this.hapChar.BatteryLevel, this.cacheBatt)
-      this.battService.updateCharacteristic(
-        this.hapChar.StatusLowBattery,
-        this.cacheBatt < this.lowBattThreshold ? 1 : 0,
-      )
-
-      // Log the change
-      this.accessory.log(`${platformLang.curBatt} [${this.cacheBatt}%]`)
-    }
+    this.updateBattery(params.battery)
 
     // Check to see if the provided leak status is different from the cached state
     if (hasProperty(params, 'leakDetected') && params.leakDetected !== this.cacheLeak) {

package/lib/device/sensor-monitor.js

@@ -28,6 +28,15 @@ export default class extends GoveeDevice {
     this.cacheTemp = this.tempService.getCharacteristic(this.hapChar.CurrentTemperature).value
     this.updateCache()
 
+    // Add the battery service if it doesn't already exist. The device reports a
+    // battery in the HTTP device list the same way the thermo sensors do, and
+    // this handler already took a lowBattThreshold from the config - it just had
+    // nowhere to put the reading, so the setting did nothing and the level never
+    // reached HomeKit
+    this.battService = this.accessory.getService(this.hapServ.Battery)
+      || this.accessory.addService(this.hapServ.Battery)
+    this.cacheBatt = this.battService.getCharacteristic(this.hapChar.BatteryLevel).value
+
     // Add the humidity service if it doesn't already exist
     this.humiService = this.accessory.getService(this.hapServ.HumiditySensor)
       || this.accessory.addService(this.hapServ.HumiditySensor)
@@ -59,6 +68,8 @@ export default class extends GoveeDevice {
     // where the AWS channel never delivers for this model. The fields use the
     // same semantics as the thermo-hygrometer sensors: hundredths of a degree
     // and hundredths of a percent
+    this.updateBattery(params.battery)
+
     if (hasProperty(params, 'temperature')) {
       let newTemp = Number.parseInt(params.temperature + this.accessory.context.offTemp, 10)
       newTemp /= 100

package/lib/device/sensor-thermo-switch.js

@@ -104,19 +104,7 @@ export default class extends GoveeDevice {
       return
     }
 
-    // Check to see if the provided battery is different from the cached state
-    if (Number.isFinite(params.battery) && params.battery !== this.cacheBatt && this.battService) {
-      // Battery is different so update Homebridge with new values
-      this.cacheBatt = params.battery
-      this.battService.updateCharacteristic(this.hapChar.BatteryLevel, this.cacheBatt)
-      this.battService.updateCharacteristic(
-        this.hapChar.StatusLowBattery,
-        this.cacheBatt < this.lowBattThreshold ? 1 : 0,
-      )
-
-      // Log the change
-      this.accessory.log(`${platformLang.curBatt} [${this.cacheBatt}%]`)
-    }
+    this.updateBattery(params.battery)
 
     // Check to see if the provided temperature is different from the cached state
     if (hasProperty(params, 'temperature')) {

package/lib/device/sensor-thermo.js

@@ -80,19 +80,7 @@ export default class extends GoveeDevice {
       return
     }
 
-    // Check to see if the provided battery is different from the cached state
-    if (Number.isFinite(params.battery) && params.battery !== this.cacheBatt && this.battService) {
-      // Battery is different so update Homebridge with new values
-      this.cacheBatt = params.battery
-      this.battService.updateCharacteristic(this.hapChar.BatteryLevel, this.cacheBatt)
-      this.battService.updateCharacteristic(
-        this.hapChar.StatusLowBattery,
-        this.cacheBatt < this.lowBattThreshold ? 1 : 0,
-      )
-
-      // Log the change
-      this.accessory.log(`${platformLang.curBatt} [${this.cacheBatt}%]`)
-    }
+    this.updateBattery(params.battery)
 
     // Check to see if the provided temperature is different from the cached state
     if (hasProperty(params, 'temperature')) {

package/package.json

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