Big Ass Fans smart home integration, free and open source
Big Ass Fans ceiling fans (Haiku, i6, es6) on the local network: speed, whoosh, light, sensors.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
This integration controls Big Ass Fans ceiling fans and lights from Gladys, on the local network, without any cloud account: Haiku (H/I Series, with or without light), i6, es6 and the Haiku L lights. It speaks the protocol of the current Big Ass Fans app (TCP port 31415) and keeps one connection open to each fan, so a change made with the remote or the app shows in Gladys at once.
Developed without the hardware: feedback welcome. The integration follows the protocol as documented by the open-source library aiobafi6 and the Home Assistant
bafintegration, and is tested against a simulated fan, not a real one. If something behaves differently on your fan, please open an issue: https://github.com/guim31/gladys-bigassfans/issues
This integration is not affiliated with, endorsed or sponsored by Big Ass Fans.
Prerequisites
- Gladys Assistant 5.1 or later.
- A Big Ass Fans fan or light set up in the current Big Ass Fans app, on the same local network as Gladys. Haiku fans need firmware 3.0 or later; older Haiku fans driven by the former SenseME app are not supported.
- Gladys must be able to reach the fan on TCP port 31415 (no firewall or guest network between them).
- Give the fan a fixed address in your router (DHCP reservation): the integration follows an address change, but a fixed one avoids a short loss of control.
Configuration
Automatic discovery
Open the integration, then the Discovery tab: the fans that announce themselves on the network
(mDNS service _api._tcp, captured by Gladys for the integration) are listed with the name they
have in the Big Ass Fans app. Click Add to Gladys on each one you want.
The Search for fans button of the Configuration screen runs the search again and reports what it found: the fans, their address, and the ones that do not answer.
Adding a fan by its IP address
If a fan is not found (another network segment, mDNS filtered by the router), enter its IP address in IP addresses of the fans, separated by commas. The integration connects to it directly.
Language
Language of the feature names sets the names given to the features of new devices (Fan, Speed, Light...) and the language of the error messages: English, French (default), German or Spanish. Gladys freezes a name when the device is added; to change it later, rename the feature in Gladys.
Devices
One Gladys device per fan, named as in the Big Ass Fans app. Only what the device has is created.
Fan
| Feature | What it does |
|---|---|
| Fan | On / off. |
| Fan auto mode | The fan's own auto mode (occupancy, Auto Comfort). Off stops the fan. |
| Speed | The 7 speeds of the fan, 0 when it is off. A speed turns it on. |
| Direction | Forward (summer) or reverse (winter), when the fan can reverse. |
| Whoosh (natural breeze) | Varies the speed like a natural breeze. |
On, off and auto are the three positions of the same mode: Fan on leaves the auto mode, Fan auto mode on leaves the plain "on". Setting a speed while the fan is in auto mode switches it to plain "on" at that speed, like the Big Ass Fans app does.
Light
For the fans with a downlight or an uplight, and the Haiku L lights.
| Feature | What it does |
|---|---|
| Light | On / off. |
| Light auto mode | The light's own auto mode (it follows the occupancy sensor). |
| Brightness | 0 to 100 %, in the 16 steps of the light. A brightness turns it on. |
| Color temperature | In kelvins, between the warmest and coolest white the light reports. |
Sensors
Read only, on the fans that have them.
| Feature | What it does |
|---|---|
| Temperature | The temperature the fan measures, in °C (fans with Auto Comfort). |
| Humidity | The relative humidity, in %, when the fan measures it. |
| Occupancy | Someone is in the room (fans with Auto Comfort and a recent firmware). It resets after about 4.5 minutes without motion. |
Scenes
Trigger: Fan switched outside Gladys
Fires when a fan is turned off, on or to auto without Gladys: from its remote, its wall control, the Big Ass Fans app, or by itself (return to auto). The changes Gladys makes never fire it, so a scene using it cannot loop.
- Fan: one fan, or empty for all.
- New mode: Off, On, Auto, several, or empty for any.
- Variables for the next actions: the new mode (
off,on,auto) and the speed (0 to 7).
Action: Boost the fan for a while
Runs the fan at a speed (1 to 7, default 7) for some minutes (default 15, at most 720), then puts it back as it was: off, at its previous speed, or in auto mode. If someone changes the fan during the boost (speed, on/off, auto), it is left as they set it. A new boost on the same fan replaces the running one and still restores the state from before the first. The end of the boost is given as an output (ISO date). A restart of the integration during a boost cancels the restore.
Scene examples
- Morning breeze: at 7:00 on weekdays, Boost the fan for a while in the bedroom at speed 3 for 30 minutes.
- Air conditioning off when the fan takes over: trigger Fan switched outside Gladys with New mode = On → turn the air conditioner of the room off.
- Winter: when the outdoor temperature drops below 10 °C, set Direction to reverse and Speed to 1, so the warm air under the ceiling comes down without a draft.
- Light with presence: when Occupancy of the living-room fan goes to 1 after sunset, turn Light on at 40 % Brightness.
Widget
The integration offers no dashboard widget: the Gladys device box already shows and drives every feature of a fan (on/off, speed slider, direction, light), and the boost belongs in scenes.
How the fans are refreshed
- The fans push their changes on the connection the integration keeps open: a change from the remote shows within a second.
- The integration also queries every property once a minute (as aiobafi6 does), which proves the connection works and catches a missed change; Gladys itself never polls these devices.
- A value that does not change is published again every 6 hours, so Gladys never shows "no recent value".
- The integration looks for new fans and new addresses every 15 minutes.
- There is no cloud, account or quota: everything stays on your network. One connection per fan.
Troubleshooting
- No fan in the Discovery tab: check that the fan works in the Big Ass Fans app on the same network, then press Search for fans. If the report says the automatic discovery is unavailable, or the fan is on another network segment, enter its IP address.
- "Does not answer": the fan is off at the breaker, changed address, or something blocks TCP port 31415 between Gladys and the fan. The integration retries by itself and logs one line when it comes back.
- A Haiku fan is never found: it may still run the SenseME firmware (before 3.0). Update it from the Big Ass Fans app.
- A feature is missing: only the features the fan reports are created. A sensor that appears later (after an update) is offered by an Update button in the Discovery tab.
- Detailed logs: set the environment variable
LOG_LEVEL=debugon the integration to see every connection and query.
Limits
- Developed and tested without a real fan (see above): the speeds, light levels and modes follow aiobafi6 and Home Assistant.
- The former SenseME protocol (Haiku fans before firmware 3.0, UDP) is not supported.
- Sleep mode, schedules, rooms, Auto Comfort settings (ideal temperature, speed range), the eco mode, the LED indicators and the beep are not exposed: the protocol does not offer sleep mode, and the others are settings made once in the Big Ass Fans app.
- The fan's RPM is not published.
- Some fans may accept only one local connection at a time: if another home automation system is connected to the same fan, one of them may lose it.
- A boost in progress is not restored after a restart of the integration.
Credits
The protocol knowledge comes from aiobafi6 (jfroy) and from
the Home Assistant baf integration (bdraco, jfroy), both under the Apache 2.0 license. Big Ass
Fans, Haiku, i6 and es6 are trademarks of their owner.
Configuration settings
These are the settings Big Ass Fans asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Finding your fans | section | No | Fans and lights on the same network as Gladys are found automatically: open the Discovery tab. They need the firmware of the current Big Ass Fans app (Haiku 3.0 or later, i6, es6). If one is missing, enter its IP address below. |
| IP addresses of the fans | string | No | Optional, separated by commas. Only needed for the fans automatic discovery does not find. |
| Language of the feature names | select | No | Names given to the features of new devices (Fan, Speed, Light...) and language of the error messages. |
How to install Big Ass Fans in Gladys
- In Gladys, open Integrations: Big Ass Fans appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-bigassfans:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-bigassfans.
Big Ass Fans requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Big Ass Fans is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation