@homebridge-plugins/homebridge-govee 11.35.1-beta.0 → 11.35.1-beta.2

package/CHANGELOG.md

@@ -7,6 +7,11 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 ### 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)
+- fix: keep saving eve history for a device with a slash in its name
+- fix: write eve history atomically, so an interrupted write cannot corrupt it
+- fix: recover from an unreadable eve history instead of retrying forever
 
 ## v11.35.0 (2026-08-09)
 

package/lib/device/kettle.js

@@ -82,6 +82,11 @@ function readingToCelsius(hexParts) {
 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 },
@@ -371,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) {
@@ -390,11 +444,26 @@ 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)
@@ -419,7 +488,8 @@ export default class extends GoveeDevice {
           return
         }
 
-        const line = `preset ${slot} is set to ${tempInF}°F [${Math.round(((tempInF - 32) * 5) / 9)}°C]`
+        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
@@ -461,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/lib/fakegato/fakegato-history.js

@@ -141,12 +141,15 @@ export default function (homebridge) {
             (err, loaded) => {
               if (err) {
                 this.log('FGH load error: %s.', err)
-              } else {
-                if (loaded) {
-                  this.log('FGH loaded from storage.')
-                }
-                this.loaded = true
+              } else if (loaded) {
+                this.log('FGH loaded from storage.')
               }
+              // Ready either way. A history that could not be read starts
+              // empty, which is the only thing left to do with it - leaving
+              // this unset instead would park save() in a 100ms retry that
+              // never ends, so a single unreadable file cost a busy loop for
+              // the lifetime of the plugin
+              this.loaded = true
             },
           )
         }.bind(this),
@@ -595,27 +598,37 @@ export default function (homebridge) {
       homebridge.globalFakeGatoStorage.read({
         service: this,
         callback: function (err, data) {
-          if (!err) {
-            if (data) {
-              try {
-                // this.log('[%s] read data [%s].', this.accessoryName, data)
-                const jsonFile = typeof data === 'object' ? data : JSON.parse(data)
-                this.firstEntry = jsonFile.firstEntry
-                this.lastEntry = jsonFile.lastEntry
-                this.usedMemory = jsonFile.usedMemory
-                this.refTime = jsonFile.refTime
-                this.initialTime = jsonFile.initialTime
-                this.history = jsonFile.history
-                this.extra = jsonFile.extra
-              } catch (e) {
-                this.log('FGH error fetching data - invalid JSON [%s].', e)
-                cb(e, false)
-              }
-              cb(null, true)
-            }
-          } else {
+          // No history stored yet, or a file with nothing in it. There is
+          // nothing to restore either way, and the caller still has to be told
+          // so: an empty file used to answer nothing at all, which left the
+          // service waiting to be loaded while save() retried every 100ms for
+          // as long as the plugin ran
+          if (err || !data) {
             cb(null, false)
+            return
+          }
+
+          try {
+            // this.log('[%s] read data [%s].', this.accessoryName, data)
+            const jsonFile = typeof data === 'object' ? data : JSON.parse(data)
+            this.firstEntry = jsonFile.firstEntry
+            this.lastEntry = jsonFile.lastEntry
+            this.usedMemory = jsonFile.usedMemory
+            this.refTime = jsonFile.refTime
+            this.initialTime = jsonFile.initialTime
+            this.history = jsonFile.history
+            this.extra = jsonFile.extra
+          } catch (e) {
+            // A file that will not parse was cut short. The entries are gone
+            // whatever happens next, so the caller is told once and the service
+            // starts empty - this used to report the failure and then
+            // immediately report success as well, over the top of it
+            this.log('FGH error fetching data - invalid JSON [%s].', e)
+            cb(e, false)
+            return
           }
+
+          cb(null, true)
         }.bind(this),
       })
     }

package/lib/fakegato/fakegato-storage.js

@@ -1,9 +1,31 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import process from 'node:process'
 
 const hostname = os.hostname().split('.')[0]
 
+/**
+ * Path separators, as the platform actually understands them.
+ *
+ * A history file is named after the accessory, and an accessory is named by
+ * whoever set the device up. A name carrying a separator stops being a name
+ * once it reaches `path.join`: it reads as a directory that does not exist, so
+ * the write fails with ENOENT and - because nothing here passes a callback -
+ * the error goes nowhere. A device called "Kitchen/Diner" simply never saved
+ * its history, with nothing in the log to say so. HAP-NodeJS guards its own
+ * storage keys against the same thing.
+ *
+ * Only genuine separators are replaced, and only where they are one. A
+ * backslash is an ordinary filename character on Linux, so replacing it there
+ * would rename the file of anyone already using one and lose their history.
+ */
+const PATH_SEPARATORS = process.platform === 'win32' ? /[\\/]/g : /\//g
+
+function toFileNamePart(name) {
+  return String(name ?? '').replace(PATH_SEPARATORS, '-')
+}
+
 export default class {
   constructor(params) {
     if (!params) {
@@ -27,7 +49,7 @@ export default class {
       const newWriter = {
         service,
         callback: params.callback,
-        fileName: `${hostname}_${service.accessoryName}_persist.json`,
+        fileName: `${hostname}_${toFileNamePart(service.accessoryName)}_persist.json`,
       }
       const onReady = typeof params.onReady === 'function' ? params.onReady : () => {}
       newWriter.storageHandler = fs
@@ -67,15 +89,36 @@ export default class {
           ? writer.callback
           : () => {}
       const fileLoc = path.join(writer.path, writer.fileName)
+      // Written to a temporary file and renamed over the target, so a write cut
+      // short by a restart or a power cut leaves the previous history intact
+      // rather than a half-written file that will not parse.
+      //
+      // The leading dot matters: this is HAP-NodeJS's persist directory, and it
+      // reads every file that does not start with one into memory at startup -
+      // so a temporary file left behind by a crash would be loaded, and kept,
+      // for the life of every run after it. The pid keeps child bridges sharing
+      // the directory from racing on the same temporary name.
+      const tempLoc = path.join(writer.path, `.${writer.fileName}.${process.pid}.tmp`)
       this.log(
         '[%s] FGS write file [%s] [%s].',
         params.service.accessoryName,
         fileLoc,
         params.data.substring(1, 81),
       )
-      writer.storageHandler.writeFile(fileLoc, params.data, 'utf8', (...args) => {
-        this.writing = false
-        callBack(args)
+      writer.storageHandler.writeFile(tempLoc, params.data, 'utf8', (writeErr) => {
+        if (writeErr) {
+          // the temporary file may never have been created, so a failure to
+          // remove it is not worth reporting over the write error itself
+          writer.storageHandler.unlink(tempLoc, () => {
+            this.writing = false
+            callBack(writeErr)
+          })
+          return
+        }
+        writer.storageHandler.rename(tempLoc, fileLoc, (renameErr) => {
+          this.writing = false
+          callBack(renameErr || null)
+        })
       })
     } else {
       setTimeout(() => this.write(params), 100)

package/package.json

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