@homebridge-plugins/homebridge-govee 11.35.0 → 11.35.1-beta.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
+## v11.35.1 (Pending Release)
+
+### Changed
+
+- fix: stop reading an h7173 startup frame as a kettle preset temperature (#1351)
+- fix: call the kettle's first temperature slot the target, not preset 1 (#1337)
+- feat: show how long the kettle will keep the water warm for (#1337)
+
 ## v11.35.0 (2026-08-09)
 
 ### Changed

package/lib/device/kettle.js

@@ -75,6 +75,18 @@ function readingToCelsius(hexParts) {
  * 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.
  */
+// The range a kettle preset can plausibly sit in. The lowest Govee kettles go
+// is around 40°C for delicate teas, and water stops being water at 100°C - so
+// 90°F to 212°F covers every real preset with room to spare, while excluding
+// the 0 and 1 the H7173 puts in that byte (#1351).
+const KETTLE_PRESET_MIN_F = 90
+const KETTLE_PRESET_MAX_F = 212
+
+// The app offers a keep warm of 30 minutes to 2 hours. A day is far past
+// anything a kettle would offer, while leaving room for a model that allows
+// more than the H7171 does.
+const KETTLE_KEEP_WARM_MAX_MINS = 1440
+
 const HEATING_STATES = {
   '00': { label: 'idle', heating: false },
   '01': { label: 'heating', heating: true },
@@ -364,6 +376,55 @@ export default class extends GoveeDevice {
     this.accessory.log(`current status [${state.label}]`)
   }
 
+  /**
+   * Show how long the kettle will hold the water once it has boiled.
+   *
+   * An `aa 22 01` frame carries the keep warm duration twice over, as two
+   * sixteen-bit counts of minutes. The owner in #1337 proved that outright:
+   * with the app set to two hours the frame read `aa 22 01 00 78 00 78`, and
+   * seconds after they changed it to thirty minutes the kettle sent
+   * `aa 22 01 00 1e 00 1e`. 0x78 is 120 and 0x1e is 30.
+   *
+   * The frame's checksum did not move between those two, which fits: the two
+   * copies are equal, so whatever one contributes the other takes back out.
+   *
+   * What the second copy is for is still unknown - a remaining time alongside
+   * the configured one would explain it, but it has only ever been seen equal
+   * to the first. So a pair that disagrees is treated as a frame this plugin
+   * cannot read rather than quietly ignored, which is what would get it
+   * decoded.
+   *
+   * @param {string} hexString the whole frame, for the log if it cannot be read
+   * @param {string[]} hexParts the frame split into bytes
+   */
+  updateKeepWarmDuration(hexString, hexParts) {
+    const configured = hexToDecimal(`${getTwoItemPosition(hexParts, 4)}${getTwoItemPosition(hexParts, 5)}`)
+    const second = hexToDecimal(`${getTwoItemPosition(hexParts, 6)}${getTwoItemPosition(hexParts, 7)}`)
+
+    // A keep warm that runs for no time at all, or for more than a day, is not
+    // a duration - it means this model packs the frame differently
+    const plausible = Number.isFinite(configured)
+      && configured > 0
+      && configured <= KETTLE_KEEP_WARM_MAX_MINS
+
+    if (!plausible || configured !== second) {
+      logUnknownData(this.accessory, {
+        kind: 'status',
+        source: 'AWS',
+        raw: hexString,
+        hex: hexParts.join(''),
+        extra: { note: 'aa 22 01 frame that does not carry one keep warm duration twice' },
+      })
+      return
+    }
+
+    if (this.cacheKeepWarmMins === configured) {
+      return
+    }
+    this.cacheKeepWarmMins = configured
+    this.accessory.log(`keep warm is set to ${configured} minutes`)
+  }
+
   externalUpdate(params) {
     // Handle OpenAPI workMode
     if (params.workMode) {
@@ -383,15 +444,52 @@ export default class extends GoveeDevice {
 
       const deviceFunction = `${getTwoItemPosition(hexParts, 2)}${getTwoItemPosition(hexParts, 3)}`
 
-      // On startup the kettle lists the temperature each of its presets is set
-      // to, one frame per preset: aa 05 <slot> <degrees F>. That is a different
-      // thing from aa 05 00 <mode> below, which is a mode change - the slot
-      // byte is what tells them apart. Nothing here needs the values, so they
-      // are logged for reference rather than reported as unrecognised (#1337)
+      // On startup the kettle lists the temperature held in each of its
+      // temperature slots, one frame per slot: aa 05 <slot> <degrees F>. That
+      // is a different thing from aa 05 00 <mode> below, which is a mode
+      // change - the slot byte is what tells them apart. Nothing here needs the
+      // values, so they are logged for reference rather than reported as
+      // unrecognised (#1337)
+      //
+      // Slot 01 is NOT a memory preset, it is the target the kettle is set to
+      // right now. Two runs from the owner in #1337 show it moving on its own:
+      // 212°F on 3 Aug, then 142°F on both 8 and 11 Aug, matching the `setTem`
+      // of 14200 carried in the same message, while slots 02-05 never budged.
+      // The memory presets are therefore slots 02-05, which is why the number
+      // printed below is one less than the slot.
+      //
+      // Those four are also not in the same order as the mode commands at the
+      // top of this file. The owner's app lists M1-M4 as black tea 212, green
+      // tea 180, oolong 195, coffee 205, which is the order slots 02-05 arrive
+      // in - whereas the switch commands number green tea 02, oolong 03, coffee
+      // 04 and black tea 05. So the slots follow the app's list rather than the
+      // mode ids, and no attempt is made here to name them.
       if (getTwoItemPosition(hexParts, 2) === '05' && getTwoItemPosition(hexParts, 3) !== '00') {
         const slot = Number.parseInt(getTwoItemPosition(hexParts, 3), 16)
         const tempInF = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)
-        const line = `preset ${slot} is set to ${tempInF}°F [${Math.round(((tempInF - 32) * 5) / 9)}°C]`
+
+        // ⚠️ The `aa 05 <slot> <degrees F>` reading came from ONE kettle, the
+        // H7171 in #1337. The H7173 sends the same two leading bytes with a
+        // fourth byte of 0 or 1, which is plainly not a temperature - and the
+        // plugin cheerfully announced "preset 1 is set to 0°F [-18°C]" (#1351).
+        //
+        // So the shape alone is not enough to claim a meaning. A preset a
+        // kettle could actually hold is the test; anything else is a frame this
+        // plugin cannot read yet, and reporting it as such is what gets it
+        // decoded rather than guessed at.
+        if (tempInF < KETTLE_PRESET_MIN_F || tempInF > KETTLE_PRESET_MAX_F) {
+          logUnknownData(this.accessory, {
+            kind: 'status',
+            source: 'AWS',
+            raw: hexString,
+            hex: hexParts.join(''),
+            extra: { note: 'aa 05 frame whose fourth byte is not a preset temperature' },
+          })
+          return
+        }
+
+        const label = slot === 1 ? 'target temperature' : `memory preset ${slot - 1}`
+        const line = `${label} is set to ${tempInF}°F [${Math.round(((tempInF - 32) * 5) / 9)}°C]`
         // Worth seeing in a normal log, but only once each. The kettle sends
         // these when it connects, and if a firmware ever repeats them on a
         // timer this keeps five lines from becoming five every few minutes
@@ -433,8 +531,11 @@ export default class extends GoveeDevice {
           }
           break
         }
+        case '2201': { // keep warm on, and for how long
+          this.updateKeepWarmDuration(hexString, hexParts)
+          break
+        }
         case '2200': // keep warm off
-        case '2201': // keep warm on
         case '2300': // scheduled start off
         case '2301': { // scheduled start on
           break

package/package.json

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