I have a Big Ass Fans Haiku H/I Series fan fitted with an indirect/uplight but no downlight. The Big Ass Fans app consistently recognizes and controls the indirect light, while Home Assistant’s official Big Ass Fans integration leaves the corresponding light entity unavailable. The fan entity and its other controls continue to work.
The problem
The apparent issue is capability detection. On an uplight-only fan, the firmware may not report the normal downlight capability even though the regular light protocol properties control the uplight. The official integration may therefore retain an unavailable light entity instead of creating a functioning one.
Temporarily installing a conventional light kit caused the fan to recognize the light, but that was not a practical or permanent solution. Matter is not required for this workaround.
The solution
This companion custom integration creates a brightness-capable Indirect Light entity for a fan already configured through Home Assistant’s official Big Ass Fans integration.
It deliberately reuses the official integration’s existing device object and socket connection. It does not:
-
Open a competing connection to the fan
-
Replace or modify the official integration
-
Require a factory reset
-
Require Matter
-
Require changes to
configuration.yaml
Initial testing was performed with:
-
Home Assistant Core 2026.8.3
-
Haiku H/I Series fan
-
Fan firmware 3.3.8
-
Official Big Ass Fans integration already configured
On/off control and dimming work, and the entity remains available after a complete Home Assistant reboot.
Project and download
Repository and complete documentation:
Direct download — version 0.1.0 ZIP:
Release page:
This is currently a manual custom-component installation and is not yet distributed through HACS.
Important: create a backup first
Before installing:
-
Go to Settings > System > Backups.
-
Select Create backup.
-
Create a full backup and wait for it to finish.
-
Download the completed backup to another computer for additional protection.
This provides a clean rollback point before adding custom files or changing entity IDs.
Installation
-
Download and extract the release ZIP.
-
Locate the
custom_components/baf_uplightfolder in the extracted package. -
Copy the
baf_uplightfolder into/config/custom_components/. -
Confirm that the resulting path is:
/config/custom_components/baf_uplight/manifest.json -
Restart Home Assistant.
-
Open Settings > Devices & services > Add integration.
-
Search for Big Ass Fans Indirect Light.
-
Select the affected fan.
-
Test the new Indirect Light entity’s on/off and brightness controls.
-
Restart or reboot Home Assistant and test it again before renaming entities or updating automations.
No configuration.yaml changes are required.
Optional entity-ID migration
If dashboards or automations already reference the old unavailable light entity:
-
Record the entity IDs of both the old and new light entities.
-
Rename the old unavailable entity to a temporary legacy entity ID.
-
Give the new working Indirect Light entity the old entity ID.
-
Test on/off, dimming, dashboards, scripts, scenes, and automations.
-
Retain the legacy entity until testing is complete so the change can easily be reversed.
Rollback
To remove the custom integration:
-
Reverse any entity-ID exchange.
-
Remove Big Ass Fans Indirect Light under Settings > Devices & services.
-
Delete
/config/custom_components/baf_uplight/. -
Restart Home Assistant.
-
Restore the full pre-installation backup if necessary.
The official Big Ass Fans integration is not modified.
Testing and feedback
This has initially been tested with one Haiku H/I Series fan and should be treated as an early workaround.
I created this with my favorite AI and wanted to share it because I found it so useful. This is also my first such contribution - so I hope you all find it useful too.
Please do not post fan MAC addresses, local IP addresses, backup files, credentials, tokens, or other private configuration data.
This project is independent community work and is not affiliated with or endorsed by Big Ass Fans.