homebridge-bigassfans-2 v1.1.39

homebridge-bigassfans-2 is a Homebridge platform plugin for Big Ass Fans i6, es6, Haiku H/I Series, and Haiku L Series ceiling fans running firmware 3.0 or newer.

This fork builds on homebridge-i6-bigAssFans by @oogje, modernizing the plugin for current Homebridge releases with Fanv2 controls, improved reconnect/state handling, safer parsing, live diagnostics, and a custom Homebridge Settings UI.

Highlights

• Compatible with Homebridge 1.8+ and Homebridge 2.0.
• Uses HomeKit Fanv2 for native fan controls.
• Maps Big Ass Fans Whoosh mode to HomeKit SwingMode.
• Maps Big Ass Fans fan auto mode to HomeKit TargetFanState.
• Supports fan speed, on/off, direction, lights, color temperature, Eco Mode, occupancy, temperature, humidity, UVC, and standby LED features when supported by the fan.
• Keeps HomeKit state in sync with changes made outside HomeKit, including the Big Ass Fans app, on the next state refresh.
• Includes a custom Settings UI with per-fan diagnostics and conservative capability-based suggestions.

See Release Notes.md for the full release history.

What's New

v1.1.39

• Removed the large platform-name panel from the normal admin UI flow.
• Moved Save Settings and configuration status into the page header.
• Improved status badge contrast for better readability in Homebridge dark mode.
• Tightened this README for public npm/GitHub presentation.

Requirements

• Homebridge 1.8.0 or newer, including Homebridge 2.0.
• Node.js 20.15.1 or newer. Node 20, 22, and 24 are tested in CI.
• A supported Big Ass Fans / Haiku fan on the same network as Homebridge.
• The fan's IP address or hostname and MAC address from the Big Ass Fans app Wi-Fi settings.

Installation

Install through the Homebridge UI, or install from npm:

sudo npm install -g homebridge-bigassfans-2

For a GitHub install:

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

Configuration

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

The platform value intentionally remains "BigAssFans-i6" for compatibility with the original plugin. The Homebridge Settings UI includes a custom admin page for this plugin and is the easiest way to configure fans, test connectivity, and review detected capabilities.

Minimal Example

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

Multi-Fan Example

{
  "platforms": [
    {
      "name": "Big Ass Fans",
      "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",
          "showEcoModeSwitch": true
        }
      ]
    }
  ]
}

Recommended Approach

Start with the required fields only:

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

Then let the plugin detect each fan's capabilities at startup. Add optional fields only when you want to expose extra HomeKit services or override detection.

Common optional choices:

• Use noLights: true to hide all light-related controls.
• Use disableDirectionControl: true to hide the fan reverse/direction control.
• Use downlightEquipped or uplightEquipped only when auto-detection is wrong.
• Use showTemperature or showHumidity to control sensor exposure when the fan supports those sensors.

Configuration Fields

Platform Fields

| Field | Required | Description | |-------|----------|-------------| | platform | Yes | Must be "BigAssFans-i6". | | name | Yes | Display name for this Homebridge platform instance. | | fans | Yes | Array of fan objects to expose. |

Fan Identity Fields

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Display name for the fan in HomeKit. | | ip | Yes | IP address, DNS hostname, or mDNS .local hostname. | | mac | Yes | Fan MAC address from the Big Ass Fans app Wi-Fi settings. |

Optional HomeKit Services

| Field | Default | Description | |-------|---------|-------------| | showFanAutoSwitch | false | Adds a legacy separate Fan Auto switch. Fan Auto is also available natively in the fan tile. | | showLightAutoSwitch | false | Adds Light Auto when the fan has lights. | | showDimToWarmSwitch | false | Adds Dim to Warm when supported by the fan. | | showEcoModeSwitch | false | Adds Eco Mode when supported by the fan. | | showHumidity | true | Exposes humidity when supported by the fan. | | showTemperature | true | Exposes temperature when supported by the fan. | | showFanOccupancySensor | false | Exposes fan occupancy when supported by the fan. | | showLightOccupancySensor | false | Exposes light occupancy when supported by the fan. | | showStandbyLED | false | Exposes night light / standby LED controls when supported by the fan. Hidden if noLights is enabled. | | enableIncrementalButtons | false | Adds momentary +/- buttons for brightness and fan speed. |

Advanced Fields

| Field | Default | Description | |-------|---------|-------------| | probeFrequency | 60000 | Keep-alive and state-refresh interval in milliseconds. Set to 0 to disable periodic probing. | | noLights | false | Hides all light-related services, including downlight, uplight, UVC, and standby LED controls. | | disableDirectionControl | false | Hides the fan direction/reverse control in HomeKit. | | downlightEquipped | "auto" | Downlight detection mode. Use "auto" or omit for detection, true to force visible, or false to force hidden. | | uplightEquipped | "auto" | Uplight detection mode. Use "auto" or omit for detection, true to force visible, or false to force hidden. | | incrementalButtonsDelay | 500 | Auto-reset delay for optional +/- buttons, in milliseconds. | | enableDebugPort | false | Enables a localhost-only TCP debug port for runtime debug level changes and detailed timing diagnostics. Leave off for normal use. |

Custom Settings UI

The custom Homebridge Settings UI provides:

• A compact fan list focused on the fields most users need.
• Per-fan Test Connection checks.
• Test All Fans diagnostics.
• Live capability summaries when the fan reports capability details.
• Conservative suggested settings for options enabled in config but not reported by the fan.

Suggested settings only hide unsupported or inactive options. They do not automatically enable optional services or undo intentional light-control overrides. After applying suggestions, save settings and restart the child bridge so HomeKit can remove hidden services.

Home App Terminology

Because this plugin uses Apple's native Fanv2 service, the Home app uses Apple's generic fan labels:

| 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.

Migrating from homebridge-i6-bigAssFans

1. Uninstall the old plugin and install homebridge-bigassfans-2.
2. Keep "platform": "BigAssFans-i6" in your config.
3. Remove showWhooshSwitch; Whoosh is now native SwingMode in the fan tile.
4. Treat showFanAutoSwitch as optional; Fan Auto is now native TargetFanState in the fan tile.
5. Clear the Homebridge accessory cache if HomeKit shows duplicate or stale services after migration.

Troubleshooting

1. Confirm the fan works in the official Big Ass Fans app.
2. Use the plugin Settings UI Test Connection or Test All Fans diagnostics.
3. Check the Homebridge startup log for each fan's detected capability summary.
4. If external app changes are slow to appear in HomeKit, lower probeFrequency from the default 60000 to a value such as 10000 or 15000.
5. If stale services remain after changing optional service settings, save settings, restart the child bridge, and clear the Homebridge accessory cache if needed.
6. If HomeKit shows stale state, No Response, or ignores changes while plugin logs look healthy, reboot your Apple Home Hubs.
7. Leave enableDebugPort off unless actively troubleshooting. When enabled, it listens on 127.0.0.1 only.

Tips

• If Apple's Home app will not let you change the fan icon while grouped as one tile, switch to Show as Separate Tiles, change the icon, then switch back to Show as Single Tile.
• If a fan has no light and no optional services, temporarily add "showTemperature": false, restart, change the icon, then remove that 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, @knmorgan, @aveach, and the users who reported issues and helped debug.
• HAP-NodeJS, Homebridge, and Big Ass Fans.

License

MIT