@homebridge-plugins/homebridge-govee 11.26.1 → 11.27.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
+## v11.27.0 (2026-07-13)
+
+### Changes
+
+- feat: add fan and light control for the H1370 ceiling fan (#1307)
+- feat: add support for the new R-prefix light and fan models (#1313)
+
 ## v11.26.1 (2026-07-12)
 
 ### Changes

package/lib/device/fan-H1370.js

@@ -0,0 +1,354 @@
+import {
+  base64ToHex,
+  generateCodeFromHexValues,
+  generateRandomString,
+  getTwoItemPosition,
+  hexToTwoItems,
+  parseError,
+  sleep,
+} from '../utils/functions.js'
+import platformLang from '../utils/lang-en.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 01 [speed] = fan speed (1-12)
+  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)
+*/
+export default class {
+  constructor(platform, accessory) {
+    // 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
+
+    // Set up variables from the accessory
+    this.accessory = accessory
+
+    // Set up custom variables for this device type
+    const deviceConf = platform.deviceConf[accessory.context.gvDeviceId]
+    this.hideLight = deviceConf && deviceConf.hideLight
+
+    // Add the fan service if it doesn't already exist
+    this.service = this.accessory.getService(this.hapServ.Fanv2) || this.accessory.addService(this.hapServ.Fanv2)
+
+    // Add the set handler to the fan on/off characteristic
+    this.service
+      .getCharacteristic(this.hapChar.Active)
+      .onSet(async value => this.internalStateUpdate(value))
+    this.cacheState = this.service.getCharacteristic(this.hapChar.Active).value ? 'on' : 'off'
+
+    // Add the set handler to the fan rotation speed characteristic
+    this.service
+      .getCharacteristic(this.hapChar.RotationSpeed)
+      .setProps({
+        maxValue: 12,
+        minStep: 1,
+        minValue: 0,
+        unit: 'unitless',
+      })
+      .onSet(async value => this.internalSpeedUpdate(value))
+    this.cacheSpeed = this.service.getCharacteristic(this.hapChar.RotationSpeed).value
+
+    if (this.hideLight) {
+      if (this.accessory.getService(this.hapServ.Lightbulb)) {
+        // Remove the light service if it exists
+        this.accessory.removeService(this.accessory.getService(this.hapServ.Lightbulb))
+      }
+    } else {
+      // Add the light service if it doesn't already exist
+      this.lightService = this.accessory.getService(this.hapServ.Lightbulb) || this.accessory.addService(this.hapServ.Lightbulb)
+
+      // Add the set handler to the lightbulb on/off characteristic
+      this.lightService.getCharacteristic(this.hapChar.On).onSet(async (value) => {
+        await this.internalLightStateUpdate(value)
+      })
+      this.cacheLightState = this.lightService.getCharacteristic(this.hapChar.On).value ? 'on' : 'off'
+
+      // Add the set handler to the lightbulb brightness characteristic
+      this.lightService
+        .getCharacteristic(this.hapChar.Brightness)
+        .onSet(async (value) => {
+          await this.internalBrightnessUpdate(value)
+        })
+      this.cacheBright = this.lightService.getCharacteristic(this.hapChar.Brightness).value
+
+      // Add the set handler to the lightbulb colour temperature characteristic
+      // The light is colour temperature only, 2700K (370 mired) to 6500K (154 mired)
+      this.lightService
+        .getCharacteristic(this.hapChar.ColorTemperature)
+        .setProps({
+          maxValue: 370,
+          minValue: 154,
+        })
+        .onSet(async (value) => {
+          await this.internalCTUpdate(value)
+        })
+      this.cacheMired = this.lightService.getCharacteristic(this.hapChar.ColorTemperature).value
+      this.cacheKelvin = 0
+    }
+
+    // Output the customised options to the log
+    const opts = JSON.stringify({
+      hideLight: this.hideLight,
+    })
+    platform.log('[%s] %s %s.', accessory.displayName, platformLang.devInitOpts, opts)
+  }
+
+  async internalStateUpdate(value) {
+    try {
+      const newValue = value ? 'on' : 'off'
+
+      // Don't continue if the new value is the same as before
+      if (this.cacheState === newValue) {
+        return
+      }
+
+      // Mirrors the fan power status code aa 36 01 01 (on) / aa 36 00 00 (off)
+      const hexValues = value ? [0x33, 0x36, 0x01, 0x01] : [0x33, 0x36, 0x00, 0x00]
+
+      // Send the request to the platform sender function
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'ptReal',
+        value: generateCodeFromHexValues(hexValues),
+      })
+
+      // Cache the new state and log if appropriate
+      if (this.cacheState !== newValue) {
+        this.cacheState = newValue
+        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.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  async internalSpeedUpdate(value) {
+    try {
+      // Don't continue if the value is 0
+      if (value === 0) {
+        return
+      }
+
+      // Don't continue if the new value is the same as before
+      if (this.cacheSpeed === value) {
+        return
+      }
+
+      // Mirrors the fan speed status code aa 31 01 [speed]
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'ptReal',
+        value: generateCodeFromHexValues([0x33, 0x31, 0x01, value]),
+      })
+
+      // Cache the new state and log if appropriate
+      if (this.cacheSpeed !== value) {
+        this.cacheSpeed = value
+        this.accessory.log(`${platformLang.curSpeed} [${value}]`)
+      }
+    } 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.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  async internalLightStateUpdate(value) {
+    try {
+      const newValue = value ? 'on' : 'off'
+
+      // Don't continue if the new value is the same as before
+      if (this.cacheLightState === newValue) {
+        return
+      }
+
+      // Send the request to the platform sender function
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'state',
+        value: newValue,
+      })
+
+      // Cache the new state and log if appropriate
+      if (this.cacheLightState !== newValue) {
+        this.cacheLightState = newValue
+        this.accessory.log(`${platformLang.curLight} [${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.lightService.updateCharacteristic(this.hapChar.On, this.cacheLightState === 'on')
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  async internalBrightnessUpdate(value) {
+    try {
+      // This acts like a debounce function when endlessly sliding the brightness scale
+      const updateKeyBright = generateRandomString(5)
+      this.updateKeyBright = updateKeyBright
+      await sleep(350)
+      if (updateKeyBright !== this.updateKeyBright) {
+        return
+      }
+
+      // Don't continue if the new value is the same as before
+      if (value === this.cacheBright) {
+        return
+      }
+
+      // Send the request to the platform sender function
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'brightness',
+        value,
+      })
+
+      // Cache the new state and log if appropriate
+      if (this.cacheBright !== value) {
+        this.cacheBright = value
+        this.accessory.log(`${platformLang.curBright} [${value}%]`)
+      }
+    } 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.lightService.updateCharacteristic(this.hapChar.Brightness, this.cacheBright)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  async internalCTUpdate(value) {
+    try {
+      // This acts like a debounce function when endlessly sliding the colour wheel
+      const updateKeyCT = generateRandomString(5)
+      this.updateKeyCT = updateKeyCT
+      await sleep(300)
+      if (updateKeyCT !== this.updateKeyCT) {
+        return
+      }
+
+      // Convert mired to kelvin to nearest 100, clamped to the light's range
+      const kelvin = Math.round(1000000 / value / 100) * 100
+      const k = Math.min(Math.max(kelvin, 2700), 6500)
+
+      // Don't continue if the new value is the same as before
+      if (this.cacheKelvin === k) {
+        return
+      }
+
+      // Send the request to the platform sender function
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'colorTem',
+        value: k,
+      })
+
+      // Cache the new state and log if appropriate
+      this.cacheMired = value
+      this.cacheKelvin = k
+      this.accessory.log(`${platformLang.curColour} [${k}K]`)
+    } 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.lightService.updateCharacteristic(this.hapChar.ColorTemperature, this.cacheMired)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  externalUpdate(params) {
+    // The standard state/brightness/kelvin fields report the light
+    if (!this.hideLight) {
+      if (params.state && params.state !== this.cacheLightState) {
+        this.cacheLightState = params.state
+        this.lightService.updateCharacteristic(this.hapChar.On, this.cacheLightState === 'on')
+        this.accessory.log(`${platformLang.curLight} [${this.cacheLightState}]`)
+      }
+
+      if (params.brightness && params.brightness !== this.cacheBright) {
+        this.cacheBright = params.brightness
+        this.lightService.updateCharacteristic(this.hapChar.Brightness, this.cacheBright)
+        this.accessory.log(`${platformLang.curBright} [${this.cacheBright}%]`)
+      }
+
+      if (params.kelvin && params.kelvin !== this.cacheKelvin) {
+        const k = Math.min(Math.max(params.kelvin, 2700), 6500)
+        const mired = Math.min(Math.max(Math.round(1000000 / k), 154), 370)
+        this.cacheKelvin = k
+        this.cacheMired = mired
+        this.lightService.updateCharacteristic(this.hapChar.ColorTemperature, this.cacheMired)
+        this.accessory.log(`${platformLang.curColour} [${k}K]`)
+      }
+    }
+
+    // Check for fan status codes
+    (params.commands || []).forEach((command) => {
+      const hexString = base64ToHex(command)
+      const hexParts = hexToTwoItems(hexString)
+
+      // Return now if not a device query update code
+      if (getTwoItemPosition(hexParts, 1) !== 'aa') {
+        return
+      }
+
+      const deviceFunction = `${getTwoItemPosition(hexParts, 2)}${getTwoItemPosition(hexParts, 3)}`
+
+      switch (deviceFunction) {
+        case '3101': {
+          // Fan speed
+          const newSpeed = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)
+          if (newSpeed >= 1 && newSpeed <= 12 && this.cacheSpeed !== newSpeed) {
+            this.cacheSpeed = newSpeed
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+            this.accessory.log(`${platformLang.curSpeed} [${this.cacheSpeed}]`)
+          }
+          break
+        }
+        case '3601': {
+          // Fan on
+          if (this.cacheState !== 'on') {
+            this.cacheState = 'on'
+            this.service.updateCharacteristic(this.hapChar.Active, 1)
+            this.accessory.log(`${platformLang.curState} [on]`)
+          }
+          break
+        }
+        case '3600': {
+          // Fan off
+          if (this.cacheState !== 'off') {
+            this.cacheState = 'off'
+            this.service.updateCharacteristic(this.hapChar.Active, 0)
+            this.accessory.log(`${platformLang.curState} [off]`)
+          }
+          break
+        }
+        default:
+          this.accessory.logDebugWarn(`${platformLang.newScene}: [${command}] [${hexString}]`)
+          break
+      }
+    })
+  }
+}

package/lib/device/index.js

@@ -5,6 +5,7 @@ import deviceDehumidifierH7152 from './dehumidifier-H7152.js'
 import deviceDiffuserH7161 from './diffuser-H7161.js'
 import deviceDiffuserH7162 from './diffuser-H7162.js'
 import deviceFanH1310 from './fan-H1310.js'
+import deviceFanH1370 from './fan-H1370.js'
 import deviceFanH7100 from './fan-H7100.js'
 import deviceFanH7101 from './fan-H7101.js'
 import deviceFanH7102 from './fan-H7102.js'
@@ -71,6 +72,8 @@ export default {
   deviceDiffuserH7161,
   deviceDiffuserH7162,
   deviceFanH1310,
+  deviceFanH1370,
+  deviceFanR1310: deviceFanH1310, // R1310 is the newer naming of the H1310
   deviceFanH7100,
   deviceFanH7101,
   deviceFanH7102,

package/lib/utils/constants.js

@@ -492,6 +492,16 @@ export default {
       'H8840',
       'H8841',
       'HXXXX', // placeholder for LAN-only configured models
+      'R1250',
+      'R1401',
+      'R14A1',
+      'R14C0',
+      'R14C1',
+      'R14C2',
+      'R1501',
+      'R1630',
+      'R16D0',
+      'R1741',
     ],
     switchSingle: ['H5001', 'H5080', 'H5081', 'H5083', 'H5086', 'H7014'],
     switchDouble: ['H5082'],
@@ -529,7 +539,7 @@ export default {
     sensorThermo4: ['H5198'],
     sensorMonitor: ['H5106'],
     sensorCO2: ['H5140'], // CO2 + temp + humidity monitor, AWS opcode 0x0A — closes #1179
-    fan: ['H1310', 'H7100', 'H7101', 'H7102', 'H7105', 'H7106', 'H7107', 'H7111'],
+    fan: ['H1310', 'H1370', 'H7100', 'H7101', 'H7102', 'H7105', 'H7106', 'H7107', 'H7111', 'R1310'],
     heater1: ['H7130', 'H713A', 'H713B', 'H713C'],
     heater2: ['H7131', 'H7132', 'H7133', 'H7134', 'H7135'],
     dehumidifier: ['H7150', 'H7151', 'H7152'],
@@ -543,7 +553,6 @@ export default {
     kettle: ['H7170', 'H7171', 'H7173', 'H7175', 'H717A'],
     template: [
       'H1162', // https://github.com/homebridge-plugins/homebridge-govee/issues/422
-      'H1370', // https://github.com/homebridge-plugins/homebridge-govee/issues/1307
       'H1167', // https://github.com/homebridge-plugins/homebridge-govee/issues/1142
       'H5010', // https://github.com/homebridge-plugins/homebridge-govee/issues/1235
       'H5024', // https://github.com/homebridge-plugins/homebridge-govee/issues/835
@@ -600,6 +609,8 @@ export default {
     'H70C4',
     'H70C5',
     'H8015',
+    'R1401',
+    'R14C0',
   ],
 
   httpRetryCodes: ['ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN', 'ECONNABORTED'],

package/package.json

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