@homebridge-plugins/homebridge-ewelink 12.19.0 → 12.19.1-beta.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@homebridge-plugins/homebridge-ewelink` will be documented in this file.
 
+## v12.19.1 (Pending Release)
+
+### Changed
+
+- feat(fan): add an option to show ifan speed as a percentage, so siri's levels work (#551)
+- fix(api): send fan speeds on the fan's own scale, so medium no longer turns it off
+- ci: update github actions to their latest versions
+
 ## v12.19.0 (2026-10-18)
 
 ### Changed

package/config.schema.json

@@ -1218,6 +1218,14 @@
                 "functionBody": "return (model.fanDevices && model.fanDevices[arrayIndices] && ['ifan'].includes(model.fanDevices[arrayIndices].deviceModel) && !model.fanDevices[arrayIndices].ignoreDevice);"
               }
             },
+            "speedAsPercent": {
+              "type": "boolean",
+              "title": "Show Speed As Percentage",
+              "description": "If true, the fan speed shows as a percentage (low 33%, medium 66%, high 99%) instead of levels 1 to 3. Siri's low, medium and high only work with a percentage. Changing this re-adds the fan to HomeKit, so check any scenes or automations that use it.",
+              "condition": {
+                "functionBody": "return (model.fanDevices && model.fanDevices[arrayIndices] && ['ifan'].includes(model.fanDevices[arrayIndices].deviceModel) && !model.fanDevices[arrayIndices].ignoreDevice);"
+              }
+            },
             "ipAddress": {
               "type": "string",
               "title": "IP Address",
@@ -1788,6 +1796,7 @@
             "fanDevices[].overrideLogging",
             "fanDevices[].deviceModel",
             "fanDevices[].hideLight",
+            "fanDevices[].speedAsPercent",
             "fanDevices[].ipAddress"
           ]
         }

package/lib/connection/api.js

@@ -446,21 +446,16 @@ export default class {
         await accessory.control.internalColourUpdate(newHKStatus)
         break
       }
-      case 'speed':
-        // The new status for speed must be low, medium or high
-        switch (newValue) {
-          case 'low':
-            newHKStatus = 33
-            break
-          case 'medium':
-            newHKStatus = 66
-            break
-          case 'high':
-            newHKStatus = 99
-            break
-          default:
-            throw new Error('Value must be \'low\', \'medium\' or \'high\' for characteristic:speed')
+      case 'speed': {
+        // The new status for speed must be low, medium or high. Some fans count
+        // their speed in levels 1 to 3 rather than a percentage, and sending
+        // those a percentage read as out of range, so medium turned them off
+        const levels = { low: 1, medium: 2, high: 3 }
+        if (!levels[newValue]) {
+          throw new Error('Value must be \'low\', \'medium\' or \'high\' for characteristic:speed')
         }
+        const inLevels = accServ.getCharacteristic(this.hapChar.RotationSpeed).props.maxValue <= 3
+        newHKStatus = inLevels ? levels[newValue] : levels[newValue] * 33
 
         // Check the accessory has a correct set handler for speed
         if (!accessory.control.internalSpeedUpdate) {
@@ -470,6 +465,7 @@ export default class {
         // Call the set handler to send the request to eWeLink
         await accessory.control.internalSpeedUpdate(newHKStatus)
         break
+      }
       case 'state':
         // The new status for state must be on, off or toggle
         switch (newValue) {

package/lib/device/fan.js

@@ -20,6 +20,7 @@ export default class {
     // Set up custom variables for this device type
     const deviceConf = platform.deviceConf[accessory.context.eweDeviceId] || {}
     this.hideLight = deviceConf.hideLight
+    this.speedAsPercent = deviceConf.speedAsPercent
 
     // Set the correct logging variables for this accessory
     switch (deviceConf.overrideLogging) {
@@ -41,6 +42,16 @@ export default class {
         break
     }
 
+    // Rebuild the fan service if it was cached under the other speed scale, as
+    // HomeKit keeps the old props until the service itself is replaced
+    const existingService = this.accessory.getService(this.hapServ.Fan)
+    if (existingService) {
+      const { props } = existingService.getCharacteristic(this.hapChar.RotationSpeed)
+      if (props.maxValue !== (this.speedAsPercent ? 100 : 3)) {
+        this.accessory.removeService(existingService)
+      }
+    }
+
     // Add the fan service if it doesn't already exist
     this.service = this.accessory.getService(this.hapServ.Fan) || this.accessory.addService(this.hapServ.Fan)
 
@@ -49,15 +60,19 @@ export default class {
       .getCharacteristic(this.hapChar.On)
       .onSet(async value => this.internalStateUpdate(value))
 
-    // Add the set handler to the fan rotation speed characteristic
+    // Add the set handler to the fan rotation speed characteristic. Levels 1-3
+    // match the remote, but Siri and a tap on the slider only work with a
+    // percentage, so that is offered as an option (#551)
     this.service
       .getCharacteristic(this.hapChar.RotationSpeed)
-      .setProps({
-        maxValue: 3,
-        minStep: 1,
-        minValue: 0,
-        unit: 'unitless', // This is actually from HAP for Bluetooth LE Specification, but fits
-      })
+      .setProps(this.speedAsPercent
+        ? { maxValue: 100, minStep: 33, minValue: 0, unit: 'percentage' }
+        : {
+            maxValue: 3,
+            minStep: 1,
+            minValue: 0,
+            unit: 'unitless', // This is actually from HAP for Bluetooth LE Specification, but fits
+          })
       .onSet(async value => this.internalSpeedUpdate(value))
 
     // Check to see if the user has hidden the light channel
@@ -116,6 +131,7 @@ export default class {
     const opts = JSON.stringify({
       hideLight: this.hideLight,
       logging: this.enableDebugLogging ? 'debug' : normalLogging,
+      speedAsPercent: this.speedAsPercent,
     })
     this.log('[%s] %s %s.', this.name, this.lang.devInitOpts, opts)
   }
@@ -170,13 +186,7 @@ export default class {
         switches: [],
       }
       const newState = value >= 1 ? 'on' : 'off'
-      let newSpeed
-
-      if (value < 0 || value > 3) {
-        newSpeed = 0
-      } else {
-        newSpeed = value
-      }
+      const newSpeed = this.levelFromHK(value)
       if (newSpeed === this.cacheSpeed) {
         return
       }
@@ -202,7 +212,7 @@ export default class {
       if (newSpeed === 0) {
         // Update the rotation speed back to the previous value (with the fan still off)
         setTimeout(() => {
-          this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+          this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.levelToHK(this.cacheSpeed))
         }, 2000)
         return
       }
@@ -213,7 +223,7 @@ export default class {
     } catch (err) {
       this.platform.deviceUpdateError(this.accessory, err, true)
       setTimeout(() => {
-        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.levelToHK(this.cacheSpeed))
       }, 2000)
       throw new this.hapErr(-70402)
     }
@@ -294,7 +304,7 @@ export default class {
       }
       if (speed !== this.cacheSpeed && this.cacheState === 'on') {
         this.cacheSpeed = speed
-        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.levelToHK(this.cacheSpeed))
         if (params.updateSource && this.enableLogging) {
           this.log(
             '[%s] %s [%s].',
@@ -318,17 +328,8 @@ export default class {
 
   currentState() {
     const toReturn = {}
-    let speedLabel
-    const speed = this.service.getCharacteristic(this.hapChar.RotationSpeed).value
-    if (speed === 0) {
-      speedLabel = 'off'
-    } else if (speed <= 1) {
-      speedLabel = 'low'
-    } else if (speed <= 2) {
-      speedLabel = 'medium'
-    } else {
-      speedLabel = 'high'
-    }
+    const level = this.levelFromHK(this.service.getCharacteristic(this.hapChar.RotationSpeed).value)
+    const speedLabel = level === 0 ? 'off' : this.speed2label[level]
     toReturn.services = ['fan']
     toReturn.fan = {
       state: this.service.getCharacteristic(this.hapChar.On).value ? 'on' : 'off',
@@ -343,6 +344,23 @@ export default class {
     return toReturn
   }
 
+  // A HomeKit rotation speed as a fan level, 0 (off) to 3. On the percentage
+  // scale 1-33 is low, 34-66 medium and 67-100 high
+  levelFromHK(value) {
+    if (!this.speedAsPercent) {
+      return value < 0 || value > 3 ? 0 : value
+    }
+    if (value <= 0) {
+      return 0
+    }
+    return value <= 33 ? 1 : value <= 66 ? 2 : 3
+  }
+
+  // A fan level as a HomeKit rotation speed, on whichever scale is in use
+  levelToHK(level) {
+    return this.speedAsPercent && level ? level * 33 : level
+  }
+
   markStatus(isOnline) {
     this.isOnline = isOnline
   }

package/lib/platform.js

@@ -321,6 +321,7 @@ export default class {
                   case 'resetOnStartup':
                   case 'scaleBattery':
                   case 'showHeatCool':
+                  case 'speedAsPercent':
                     if (typeof v === 'string') {
                       logQuotes(`${key}.${id}.${k}`)
                     }

package/lib/utils/constants.js

@@ -164,6 +164,7 @@ export default {
       'ignoreDevice',
       'deviceModel',
       'hideLight',
+      'speedAsPercent',
       'ipAddress',
     ],
     sensorDevices: [

package/package.json

@@ -3,7 +3,7 @@
   "displayName": "Homebridge eWeLink",
   "alias": "eWeLink",
   "type": "module",
-  "version": "12.19.0",
+  "version": "12.19.1-beta.1",
   "description": "Homebridge plugin to integrate eWeLink devices into HomeKit.",
   "author": {
     "name": "bwp91",