@homebridge-plugins/homebridge-govee 11.37.1 → 11.38.0-beta.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
+## v11.38.0 (Pending Release)
+
+### Changed
+
+- feat: show which slot the kettle target temperature comes from, settled by two owner runs
+- fix(h1370): send fan power to the fan instead of the lights, and give it the two light tiles
+- feat(h1370): add the oscillation control, read from the fan's own speed frame
+
 ## v11.37.1 (2026-08-21)
 
 ### Changed

package/lib/device/fan-H1370.js

@@ -15,15 +15,22 @@ import { logUnknownData } from '../utils/report-unknown.js'
 import GoveeDevice from './base.js'
 
 /*
-  Codes below were decoded from a real device's AWS status reports in
-  https://github.com/homebridge-plugins/homebridge-govee/issues/1307
-  Status aa 31 [?] [speed] [direction] = fan speed and airflow direction
-  Status aa 36 01 01 / aa 36 00 00 = fan power on/off
-  The light reports through the standard state/brightness/kelvin fields
-  (colour temperature only, 2700-6500K)
-
-  The H1310 and R1310 share this handler. They report six speeds against the
-  H1370's twelve, so the scale comes from the capabilities table (#1352)
+  ⚠️ This is the BASE for the ceiling fans, not a handler any model is mapped
+  to. Every one of them - H1310, R1310 and H1370 - runs `fan-ceiling.js`, the
+  subclass, which reads the two lights and the fan correctly.
+
+  What is left here is the single-light fallback that subclass drops back to
+  when a device cannot reach its per-light api switches. Read it as "the least
+  this hardware can do", not as a description of the hardware.
+
+  ⚠️ The comment that used to sit here said `aa 36 01 01` was fan power on the
+  H1370. It is not: it is the two lights, on every model. Labelled captures on
+  #1358 settled it - switching the fan on left `aa 36` at `00 00` and moved
+  `aa 31` byte three instead. `internalStateUpdate` below still sends the light
+  frame, which is exactly why no model is mapped straight to this class.
+
+  Speeds differ - six on the H1310, twelve on the H1370 - so the scale comes
+  from the capabilities table (#1352)
 */
 export default class GoveeFanH1370 extends GoveeDevice {
   constructor(platform, accessory) {
@@ -142,7 +149,9 @@ export default class GoveeFanH1370 extends GoveeDevice {
         return
       }
 
-      // Mirrors the fan power status code aa 36 01 01 (on) / aa 36 00 00 (off)
+      // ⚠️ `aa 36` is the two LIGHTS, not the fan (#1358). Kept only because a
+      // device without its api switches has nothing else to send; the subclass
+      // every model uses overrides this with the fan's own toggle
       const hexValues = value ? [0x33, 0x36, 0x01, 0x01] : [0x33, 0x36, 0x00, 0x00]
 
       // Send the request to the platform sender function

package/lib/device/{fan-H1310.js → fan-ceiling.js}

@@ -8,14 +8,23 @@ import {
   sleep,
 } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
-import deviceFanH1370 from './fan-H1370.js'
+import deviceFanCeilingBase from './fan-H1370.js'
 
 /**
- * The two lights an H1310 has, the api switch each one answers to, and the bit
- * each one sets in the `aa 42` status.
+ * The ceiling fans with two lights: the H1310, its newer R1310 naming, and the
+ * H1370.
  *
- * Those switches are the only way to reach one light without the other -
- * `powerSwitch` is the whole unit, fan included.
+ * ⚠️ The H1370 was on the base handler until captures posted on #1358 settled
+ * that it speaks exactly the same language as the H1310 - `aa 36` is the two
+ * lights and `aa 31` byte three is the fan, on both. The base handler had it
+ * the other way round, so switching the fan on in HomeKit sent `33 36 01 01`
+ * and turned both lights on without ever reaching the fan.
+ *
+ * The H1370 additionally oscillates, which the H1310 does not.
+ *
+ * The two lights, the api switch each one answers to, and the bit each one
+ * sets in the `aa 42` status. Those switches are the only way to reach one
+ * light without the other - `powerSwitch` is the whole unit, fan included.
  */
 /**
  * ⚠️ The fan has ONE brightness and ONE colour, shared by both lights - the
@@ -67,6 +76,9 @@ const FAN_CODE = '31'
 const FAN_TOGGLE = 'fanToggle'
 const REVERSE_AIRFLOW = 'reverseAirflowToggle'
 
+/** Oscillation, which the H1370 has and the H1310 does not. */
+const OSCILLATE = 'fanOscillateToggle'
+
 /**
  * Reads which lights are lit out of a status, from whichever of the two frames
  * the fan sent, normalised to the `aa 42` mask.
@@ -111,7 +123,7 @@ function fanIsRunningFrom(commands) {
   return running
 }
 
-export default class GoveeFanH1310 extends deviceFanH1370 {
+export default class GoveeFanCeiling extends deviceFanCeilingBase {
   constructor(platform, accessory) {
     super(platform, accessory)
 
@@ -131,7 +143,19 @@ export default class GoveeFanH1310 extends deviceFanH1370 {
     this.canSendFanToggle = !!accessory.context.openApiCapabilities?.[FAN_TOGGLE]
       && !!accessory.context.useOpenApiControl
 
-    if (this.service.testCharacteristic(this.hapChar.SwingMode)) {
+    // Oscillation. The H1310 cannot oscillate and the H1370 can, so this is
+    // gated on the capability rather than on the model - and anything left
+    // over on a fan that turns out not to have it is removed, which is what
+    // this handler already had to do for the tower fan's control (#1352)
+    this.canOscillate = !!accessory.context.openApiCapabilities?.[OSCILLATE]
+      && !!accessory.context.useOpenApiControl
+
+    if (this.canOscillate) {
+      this.service
+        .getCharacteristic(this.hapChar.SwingMode)
+        .onSet(async value => this.internalSwingUpdate(value))
+      this.cacheSwing = this.service.getCharacteristic(this.hapChar.SwingMode).value
+    } else if (this.service.testCharacteristic(this.hapChar.SwingMode)) {
       this.service.removeCharacteristic(this.service.getCharacteristic(this.hapChar.SwingMode))
     }
 
@@ -263,6 +287,39 @@ export default class GoveeFanH1310 extends deviceFanH1370 {
     }
   }
 
+  /**
+   * Oscillation on and off.
+   *
+   * The fan reports it in the eighth byte of its speed frame, but there is no
+   * frame known to SEND it, so this is api-only - which is why the control is
+   * gated on the capability being reachable rather than merely present.
+   *
+   * @param {number} value 1 swinging, 0 still
+   */
+  async internalSwingUpdate(value) {
+    try {
+      if (this.cacheSwing === value) {
+        return
+      }
+
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'openApi',
+        openApi: {
+          instance: OSCILLATE,
+          capabilityType: 'devices.capabilities.toggle',
+          value: value === 1 ? 1 : 0,
+        },
+      })
+
+      this.cacheSwing = value
+      this.accessory.log(`current oscillation [${value === 1 ? 'on' : 'off'}]`)
+    } catch (err) {
+      this.failUpdate(err, () => {
+        this.service.updateCharacteristic(this.hapChar.SwingMode, this.cacheSwing)
+      })
+    }
+  }
+
   /**
    * The device-wide on/off field is the whole unit having power here, not the
    * light: a fan reporting `onOff` 1 has been seen with `aa 36 00` (fan off)
@@ -342,6 +399,30 @@ export default class GoveeFanH1310 extends deviceFanH1370 {
       })
     }
 
+    // Oscillation, read off the eighth byte of the same speed frame. Proven
+    // against ekalp's labelled captures on #1358, where switching it off, on
+    // and off again was the only thing that byte did - `aa 31 01 04 00 00 00
+    // 01` swinging and `... 00` still, with every other byte unchanged
+    if (this.canOscillate) {
+      let swinging
+      ;(params.commands || []).forEach((command) => {
+        const hexParts = hexToTwoItems(base64ToHex(command))
+        if (getTwoItemPosition(hexParts, 1) === 'aa' && getTwoItemPosition(hexParts, 2) === FAN_CODE) {
+          swinging = getTwoItemPosition(hexParts, 8) === '01' ? 1 : 0
+        }
+      })
+
+      if (swinging === undefined && params.toggles?.[OSCILLATE] !== undefined) {
+        swinging = params.toggles[OSCILLATE] ? 1 : 0
+      }
+
+      if (swinging !== undefined && this.cacheSwing !== swinging) {
+        this.cacheSwing = swinging
+        this.service.updateCharacteristic(this.hapChar.SwingMode, swinging)
+        this.accessory.log(`current oscillation [${swinging === 1 ? 'on' : 'off'}]`)
+      }
+    }
+
     // Airflow direction is a separate capability from the lights, so it gets
     // its own guard rather than sharing theirs
     if (!this.canReverseAirflow) {

package/lib/device/index.js

@@ -10,8 +10,7 @@ import {
 import deviceCoolerSingle from './cooler-single.js'
 import deviceDehumidifierH7150 from './dehumidifier-H7150.js'
 import deviceDiffuserH7161 from './diffuser-H7161.js'
-import deviceFanH1310 from './fan-H1310.js'
-import deviceFanH1370 from './fan-H1370.js'
+import deviceFanCeiling from './fan-ceiling.js'
 import deviceFanH7100 from './fan-H7100.js'
 import deviceFanH7105 from './fan-H7105.js'
 import deviceFanH7107 from './fan-H7107.js'
@@ -61,9 +60,12 @@ export default {
   deviceDehumidifierBasic,
   deviceDiffuserBasic,
   deviceFanBasic,
-  deviceFanH1310,
-  deviceFanH1370,
-  deviceFanR1310: deviceFanH1310, // R1310 is the newer naming of the H1310
+  // The three ceiling fans all speak the same language - two lights on `aa 36`
+  // and the fan on `aa 31` - settled by the captures on #1358. The H1370 was
+  // on the base handler, which had those the other way round
+  deviceFanH1310: deviceFanCeiling,
+  deviceFanH1370: deviceFanCeiling,
+  deviceFanR1310: deviceFanCeiling, // R1310 is the newer naming of the H1310
   deviceFanH7100,
   deviceFanH7102: deviceFanH7100, // identical to the H7100
   deviceFanH7106: deviceFanH7100, // identical to the H7100

package/lib/device/kettle.js

@@ -503,14 +503,53 @@ export default class extends GoveeDevice {
       }
 
       switch (deviceFunction) {
-        case '0500': { // current mode
+        case '0500': { // which slot the target temperature comes from
+          // Settled by two owner runs in #1337, both with the kettle at 212°F
+          // so that only the control used differed:
+          //
+          //   aa 05 00 02   after tapping the first memory preset in the app
+          //   aa 05 00 01   after setting 212°F by hand with the slider
+          //
+          // So the byte points at the temperature slot the target comes from:
+          // 01 is the custom target slot, 02-05 are the memory presets - the
+          // same numbering as the aa 05 <slot> frames above. And it tracks
+          // which CONTROL was used, not the number: 212°F set by slider still
+          // reads slot 1, even though the first preset holds exactly 212°F.
+          //
+          // Two honest gaps. Slots 03-05 are inferred from the pattern - only
+          // 01 and 02 have been seen. And the switch-command examples below,
+          // which predate those runs, number the drink modes differently
+          // (green tea 02, oolong 03...); both cannot be right for this
+          // kettle, so they are kept only until a mode-switch run settles it:
+          //
           // switch to green tea_: aa050002000000000000000000000000000000ad
           // switch to oolong tea: aa050003000000000000000000000000000000ac
           // switch to coffee____: aa050004000000000000000000000000000000ab
           // switch to black tea_: aa050005000000000000000000000000000000aa
           // switch to preset1___: aa050001010000000000000000000000000000af
           // switch to preset2___: aa050001020000000000000000000000000000ac
-          // No point in changing any switches for the sake of three seconds, no action taken here
+          const slot = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)
+          if (slot < 1 || slot > 5) {
+            logUnknownData(this.accessory, {
+              kind: 'status',
+              source: 'AWS',
+              raw: hexString,
+              hex: hexParts.join(''),
+              extra: { note: 'aa 05 00 frame pointing at a slot the kettle does not have' },
+            })
+            break
+          }
+          const line = slot === 1
+            ? 'target temperature set from [custom temperature]'
+            : `target temperature set from [memory preset ${slot - 1}]`
+          // The kettle repeats this in every startup burst - a change is worth
+          // a normal log line, a repeat is not
+          if (this.cacheTargetSlot === slot) {
+            this.accessory.logDebug(line)
+          } else {
+            this.cacheTargetSlot = slot
+            this.accessory.log(line)
+          }
           break
         }
         case '1001': { // current temperature of the water

package/package.json

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