homebridge-bigassfans-2 v1.1.6

homebridge-bigassfans-2 is a Homebridge plugin for controlling Big Ass Fans i6, es6, Haiku H/I Series, and Haiku L Series ceiling fans with firmware version 3.0 or greater. Compatible with Homebridge 1.8+ and Homebridge 2.0.

This is a fork of homebridge-i6-bigAssFans by @oogje, updated and modernized with Fanv2 support, bug fixes, and improved code quality.

What's New in This Fork

Homebridge 2.0 / Fanv2 Service

• Uses the modern Fanv2 HomeKit service instead of the legacy Fan service.
• Whoosh Mode is now a native SwingMode characteristic in the fan tile -- no separate switch needed.
• Fan Auto Mode is now a native TargetFanState characteristic (Manual / Auto) in the fan tile -- no separate switch needed.
• CurrentFanState reports whether the fan is Inactive, Idle, or Blowing Air.
• Legacy cached Fan and whooshSwitch services are automatically cleaned up on upgrade.

Home App labeling note: Apple labels the native SwingMode control as Oscillate in the Home app. In this plugin, Oscillate = Big Ass Fans Whoosh. Apple also labels TargetFanState as Fan Mode: Manual / Auto; in this plugin, Auto = the fan's built-in Big Ass Fans auto mode.

Bug Fixes

• Connection stability -- Reconnections now re-send the initialization and capability query to the fan, fixing the issue where a daily restart was required to restore communication (upstream #41).
• Fans offline at startup -- All connection errors (including ECONNREFUSED) now trigger automatic retry with exponential backoff, so fans that are powered off or unreachable at boot will connect once available (upstream #35).
• mDNS hostname support -- Removed forced IPv4 (family: 4) from the TCP connection, allowing mDNS .local hostnames and IPv6 to work correctly (upstream #29).
• varint encoding bug -- Fixed an operator-precedence bug in varint_encode where the continuation bit (| 0x80) was applied to the return value of Array.push() instead of the byte being pushed. This could cause incorrect protobuf encoding for values over 127 (e.g., color temperature).
• Multi-fan shared state -- Eight module-level variables (debug state, reboot tracking, occupancy tracking, etc.) were shared across all fan instances, causing cross-talk between fans in multi-fan setups. These are now per-instance.

Code Quality

• Removed unnecessary declare const Buffer that suppressed TypeScript type checking.
• Fixed debugLevels type from number[] to Record<string, number>.
• Modernized import net = require('net') to import * as net from 'net'.
• Updated ESLint config to remove deprecated rules from @typescript-eslint v8.
• Updated tsconfig.json with skipLibCheck for HB2 type compatibility.
• Stale chunk fragments are now cleared on reconnect to prevent corrupt protobuf data.

v1.1.6

• Improved downlight auto-detection compatibility for fans that expose color-temperature control but underreport the primary downlight capability flag.
• Downlight services now refresh correctly if capability information improves after the initial startup message.
• Added regression coverage for downlight inference and override precedence.

v1.1.5

• Fixed fan-only and noLights setups so inbound fan state updates are no longer blocked waiting for a light target selector message that may never arrive.
• External fan changes from the Big Ass Fans app now flow back into HomeKit correctly even when the accessory has no light services.
• Added regression coverage for fan state dispatch when targetBulb is unknown.

v1.1.4

• External fan changes made in the Big Ass Fans app are now pulled back into HomeKit on the next probe cycle, even when the fan does not send an unsolicited state update.
• HomeKit Active / CurrentFanState now stay in sync more reliably for external auto-mode transitions.
• Added regression checks covering periodic state refresh and external auto-mode synchronization.

v1.1.3

• External fan changes made in the Big Ass Fans app now update HomeKit Active / CurrentFanState more reliably, including auto-mode transitions.
• Added a regression check covering external auto-mode state synchronization.

v1.1.2

• Added startup capability summary logging so users can see which features each fan actually reports and which are exposed in HomeKit.
• Added README guidance recommending a minimal config first, then adding overrides only when needed.

v1.1.1

• Added a lightweight regression harness for parser and reconnect edge cases.
• Package metadata now reflects the current release series consistently.

v1.0.3

• Hardened protobuf parsing so malformed or truncated frames are safely dropped instead of risking a stuck parse loop.
• The optional debug TCP port now listens on 127.0.0.1 only.
• Fans removed from config.fans are automatically cleaned out of the Homebridge accessory cache.
• The Homebridge UI now exposes the additional documented configuration options from this README.

Features

• Turn fan and/or light(s) on or off
• Change fan speed and direction (Big Ass Fans discourages reversing speed)
• Ability to disable the fan direction control
• Change brightness level of LED light
• Adjust color temperature (i6 downlight)
• Control UV-C light
• Whoosh Mode (native SwingMode in the fan tile)
• Fan Auto Mode (native TargetFanState in the fan tile)
• Light Auto Mode (optional switch)
• Dim to Warm (optional switch, i6 fans)
• Eco Mode (optional switch, Haiku fans)
• Expose occupancy (motion) sensors
• Display temperature sensor (Haiku fans, i6 with remote)
• Display humidity sensor (i6 with remote)
• Night Light / Standby LED control (brightness, color)
• Incremental brightness and speed buttons (optional)

Requirements

• Homebridge 1.8.0 or newer (including Homebridge 2.0)
• Node.js 20.15.1 or newer (20.x, 22.x, or 24.x)

Installation

If you are not already running Homebridge, see the Homebridge documentation to get started.

Install from npm

sudo npm install -g homebridge-bigassfans-2

Install from this repo

sudo npm install -g applemanj/homebridge-bigAssFans-2

Configuration

Add the BigAssFans-i6 platform in config.json inside your Homebridge configuration directory.

Note: The platform value remains "BigAssFans-i6" for compatibility.

Minimal Example

{
  "platforms": [
    {
      "platform": "BigAssFans-i6",
      "fans": [
        {
          "name": "Living Room Fan",
          "mac": "20:F8:5E:00:00:00",
          "ip": "192.168.1.150"
        }
      ]
    }
  ]
}

Multi-Fan Example

{
  "platforms": [
    {
      "platform": "BigAssFans-i6",
      "fans": [
        {
          "name": "Living Room i6",
          "mac": "20:F8:5E:00:00:00",
          "ip": "livingroom-fan.local",
          "showLightAutoSwitch": true,
          "showDimToWarmSwitch": true
        },
        {
          "name": "Bedroom Haiku",
          "mac": "20:F8:5E:00:00:01",
          "ip": "192.168.1.151",
          "showLightAutoSwitch": true,
          "showEcoModeSwitch": true
        }
      ]
    }
  ]
}

Recommended Minimal Config

Start with the smallest config that identifies each fan:

{
  "platform": "BigAssFans-i6",
  "fans": [
    {
      "name": "Bedroom Fan",
      "ip": "192.168.1.150",
      "mac": "20:F8:5E:00:00:00"
    }
  ]
}

Then let the plugin detect the fan's capabilities at startup and only add override options if you actually need them, for example:

• noLights if you want to hide all lighting services
• disableDirectionControl if you want to hide reverse control
• showTemperature or showHumidity if you want to override the default sensor exposure behavior
• downlightEquipped / uplightEquipped only if auto-detection is wrong for your fan

Configuration Fields

Required

| Field | Description | |-------|-------------| | platform | Must be "BigAssFans-i6" | | fans | Array of fan objects | | name | Display name for the fan | | ip | IP address or hostname (mDNS .local names supported) | | mac | MAC address (found in the Big Ass Fans app under Wi-Fi settings) |

Optional Switches

| Field | Default | Description | |-------|---------|-------------| | showFanAutoSwitch | false | Add a legacy separate switch for Fan Auto (also available natively in fan tile via TargetFanState) | | showLightAutoSwitch | false | Add a switch for Light Auto mode | | showDimToWarmSwitch | false | Add a switch for Dim to Warm (i6 fans) | | showEcoModeSwitch | false | Add a switch for Eco Mode (Haiku fans) | | disableDirectionControl | false | Hide the fan direction control |

Advanced

| Field | Default | Description | |-------|---------|-------------| | probeFrequency | 60000 | Keep-alive and state-refresh interval in milliseconds (0 disables periodic probing) | | noLights | false | Hide all light controls | | showHumidity | true | Expose humidity sensor | | showTemperature | true | Expose temperature sensor | | downlightEquipped | auto | Override downlight detection (true/false) | | uplightEquipped | auto | Override uplight detection (true/false) | | showFanOccupancySensor | false | Expose fan occupancy sensor | | showLightOccupancySensor | false | Expose light occupancy sensor | | showStandbyLED | false | Expose night light / standby LED controls | | enableIncrementalButtons | false | Add +/- buttons for brightness and fan speed | | incrementalButtonsDelay | 500 | Auto-reset delay for incremental buttons (ms) | | enableDebugPort | false | Enable a localhost-only TCP debug port for runtime debug level changes |

Migrating from homebridge-i6-bigassfans

1. Uninstall the old plugin and install this one.
2. Clear your Homebridge accessory cache -- the switch from Fan to Fanv2 service requires fresh accessories. (The plugin will attempt to remove the legacy Fan service automatically, but a cache clear ensures a clean state.)
3. Remove showWhooshSwitch from your config -- Whoosh is now built into the fan tile as SwingMode.
4. showFanAutoSwitch is optional -- Fan Auto is now built into the fan tile as TargetFanState. You can keep the legacy switch if you prefer a separate control.
5. The platform value stays "BigAssFans-i6" -- no config change needed there.

Upgrading from the Original Plugin -- What Changes in HomeKit

| Before (Fan service) | After (Fanv2 service) | |---|---| | On/Off toggle | Active (Inactive / Active) | | Separate Whoosh switch | SwingMode in fan tile | | Separate Fan Auto switch | TargetFanState (Manual / Auto) in fan tile | | No fan state feedback | CurrentFanState (Inactive / Idle / Blowing Air) | | Rotation Speed (%) | Rotation Speed (%) -- unchanged | | Rotation Direction | Rotation Direction -- unchanged |

Home App Terminology

Because this plugin uses Apple's native Fanv2 service, some labels in the Home app use Apple's generic fan wording instead of Big Ass Fans branding:

| Home App Label | Big Ass Fans Feature | |---|---| | Oscillate | Whoosh | | Fan Mode: Manual | Fan manual mode | | Fan Mode: Auto | Big Ass Fans fan auto mode |

The behavior is mapped correctly; only the labels are Apple's.

State changes made outside HomeKit, such as turning a fan on in the Big Ass Fans app, are also reflected back into HomeKit so the fan tile stays in sync. If the fan does not push that update on its own, the plugin will pick it up on the next probe/state-refresh cycle.

Troubleshooting

1. Make sure you can control your fan from the official Big Ass Fans app before troubleshooting the plugin.

2. Run Homebridge in debug mode for additional diagnostics:

   homebridge -D

3. Check the startup capability summary in the Homebridge logs. After each fan connects, the plugin logs which features were detected and which ones are being exposed or hidden by config. This is the easiest way to confirm whether your fan actually reports temperature, humidity, lights, occupancy, standby LED support, and similar capabilities.

4. If external app changes seem delayed in HomeKit, lower probeFrequency. With the default 60000, it can take up to about 60 seconds for a change made in the Big Ass Fans app to appear in HomeKit if the fan does not push an unsolicited update. A lower value such as 10000 or 15000 will refresh more quickly.

5. Clear the accessory cache if you see duplicate or stale services after upgrading from the original plugin.

6. Check the Issues for known problems and solutions.

7. If enableDebugPort is enabled, connect from the Homebridge host itself. The debug port now listens on 127.0.0.1 only.

Tips

• If you cannot change the fan icon in Apple's Home app and the fan is shown as a single tile, switch to Show as Separate Tiles, change the icon, then switch back to Show as Single Tile.
• If the Home app does not show the option to separate tiles (e.g., a Haiku with no light and no optional switches), temporarily add "showTemperature": false to your config, restart, change the icon, then remove the setting.

Acknowledgments

This fork builds on the work of @oogje and the contributors to homebridge-i6-bigAssFans.

Special thanks to:

• @bdraco for identifying the protobuf protocol
• @jfroy for building a working BAF protobuf controller
• @pponce for Haiku implementation, testing, and collaboration
• @knmorgan for bug reports and code contributions
• @aveach and all users who reported issues and helped debug
• homebridge-miot -- style guide
• HAP-NodeJS & Homebridge -- for making this possible
• Big Ass Fans -- for their awesome products

License

MIT