v1.3.0 — Reverse direction for DC fans

What's new

Forward/reverse direction control for DC fans (#4, thanks @markjandejong)

The fan entity now exposes a direction (forward/reverse) control on fans that actually support electronic reverse. The integration auto-detects reverse-capable DC motors — via the fan_type byte the fan reports — and shows the control by default. Direction changes apply instantly, whether the fan is stopped or spinning. A per-fan Change direction option (Settings → Devices → Configure) lets you override the auto-detection either way.

AC fans are unaffected: capacitor-switched AC motors reverse via a physical switch on the motor housing, not over Bluetooth, so the control stays hidden unless you enable it manually.

Upgrade notes

No action required — backward compatible. If your fan isn't auto-detected, enable Change direction in the integration's options.

• AC fans: no change; the direction control stays hidden.
• DC fans: a forward/reverse control appears automatically.

Tested on

• DC motor fan with electronic reverse — blades physically reverse (instantly, whether stopped or spinning) and the direction reads back reliably; confirmed on real hardware by @markjandejong (#4) - thank you!
• 3-speed AC fan (BTCR9 + BTT9) — direction correctly stays hidden (no electronic reverse)

Also in this release

• README overhaul — clearer Bluetooth-only scope so Fanimation FanSync WiFi fans aren't mistaken for supported, a "which receiver do I have?" self-test, reorganized around the install decision, and a dedicated tools/README.md for the diagnostic scripts.

v1.2.1 — Fix manual fan setup

Bug fixes

Fixed: adding a fan manually crashed with ValueError: Unable to convert schema (#5, thanks @JesusSanchezLopez)

The manual setup form (Settings → Devices & Services → Add Integration → Fanimation BLE Ceiling Fan) failed to render because the MAC-address field used a vol.Match regex validator, which Home Assistant's frontend cannot serialize. This broke any setup that doesn't go through Bluetooth auto-discovery — for example adding a second fan, or installs relying on an ESP32 Bluetooth proxy.

MAC validation now runs in the config-flow handler instead of the schema, so the form renders correctly and an invalid address shows a clear inline error instead of a traceback.

Bonus: the MAC field now accepts colon-, dash-, and dot-separated formats as well as bare hex (e.g. aabbccddeeff) — all normalized automatically.

• Also hardened config-flow translations (added the already_in_progress abort string and a CI completeness test that catches missing translation keys).

Upgrade notes

No action required. Backward-compatible patch release — existing fans keep working unchanged, and stored MAC/unique-ID format is preserved.

Credits

Bug report and root-cause traceback by @JesusSanchezLopez. Thank you.

v1.2.0 - DC fan support (configurable speed count)

What's new

Dynamic speed count for DC fans (#1, thanks @JesusSanchezLopez)
The integration now adapts to fans with more than 3 speeds. Set "Number of fan speeds" under Settings -> Devices & Services -> Fanimation -> ⋮ -> Configure to match your hardware (e.g. 32 for the Odyn 84" with TR305 remote, 6 for smaller DC fans). The fan UI becomes a percentage slider, and the low / medium / high presets scale with the configured count - so on a 32-speed fan, "high" maps to speed 32 rather than speed 3.

Bug fixes

• Fixed ValueError: The item "5" is not in "[1, 2, 3]" raised when an RF remote set a DC fan above speed 3 with the integration still configured for 3 speeds. (#1)
• Fixed a stuck-off loop with default_speed = "Last Used" and a misconfigured speed count: the entity cached the requested speed before sending the BLE write, so when the BTCR9 firmware silently rejected an out-of-range speed byte (turning the fan off with no error), "Last Used" turn-on would resend the bad value forever. _last_speed now syncs from the verified GET_STATUS response.

Tested on

• 3-speed AC fans (BTCR9 controller) on HA Yellow running HA 2026.2.3
• 4 AC + DC fans including the Odyn 84" (TR305 FanSync remote), community-tested by @JesusSanchezLopez

Credits

Bug report, original PR, and real-DC-hardware verification by @JesusSanchezLopez. Thank you.

v1.1.0 — Options Flow & Soft Unavailable

What's New

Options Flow (Settings → Devices → Configure)

Per-fan settings are now configurable through the HA UI:

• Default turn-on speed — Last used, Low, Medium, or High
• Default light brightness — 0 = last used, 1-100 = fixed level
• Disconnect notification — persistent alert on first BLE failure
• Unavailable threshold — how many poll failures before entities go grey

Changes take effect immediately — no restart needed.

Soft Unavailable

Entities no longer go grey on the first BLE hiccup. Instead:

• Last-known state is preserved during transient failures
• A persistent notification fires on the first failure (auto-dismissed on recovery)
• Entities only go unavailable after a configurable threshold (default ≈ 1 hour)
• A connection_status attribute shows "connected" or "unreachable (N attempts, ~X hr)" on all entities

Also

• 27 new tests (coordinator, fan, light, options flow)
• Screenshots and updated README

Full Changelog: v1.0.0...v1.1.0

v1.0.0 — Initial HACS Release

Fanimation BLE Ceiling Fan — v1.0.0

Local Bluetooth control of Fanimation ceiling fans using the BTCR9 FanSync Bluetooth receiver. No cloud, no app dependency.

Features

• Fan speed: Off / Low / Medium / High
• Downlight brightness: 0–100%
• Sleep timer: 0–360 minutes (turns off fan + light on expiry)
• RF remote coexistence: Read-before-write ensures physical remote changes are never overwritten
• Bluetooth auto-discovery: Detects fans named "CeilingFan" automatically
• Persistent BLE connection: Commands respond in ~600ms

Installation

1. Add this repo as a custom repository in HACS
2. Install "Fanimation BLE Ceiling Fan"
3. Restart Home Assistant
4. Fan is auto-discovered, or add manually with MAC address

Entities

Entity	Type	Controls
Fan	fan	Speed (off/low/med/high)
Downlight	light	On/off, brightness (0-100%)
Sleep Timer	number	0-360 minutes

Works with ESP32 Bluetooth proxies.