QuietCool BLE — Home Assistant Integration

Native Bluetooth Low Energy integration for QuietCool attic and whole-house fans. Auto-discovers fans, enables full speed and smart-mode control, and exposes temperature, humidity, and timer sensors — all using the stock manufacturer firmware with no hardware modification required.

Status

Hardware-confirmed working on the AFG SMT PRO-2.0 (firmware IT-BLT-ATTICFAN_V3.0). All 10 entities — fan control, smart mode, temperature, humidity, timers, and threshold configuration — verified on real hardware.

Supported Devices

Model	CFM	Speeds	BLE Name	Status
AFG SMT PRO-2.0 Smart Attic Fan	1945	Low / High	ATTICFAN_*	✅ Hardware confirmed
AFG SMT ES-2.0 / ES-3.0	Various	Low / High	ATTICFAN_*	🔲 Protocol confirmed, untested
AFG SMT NR-A (2022 revision)	Various	Low / High	ATTICFAN_*	🔲 Protocol confirmed, untested
Other ESP32-based QuietCool controllers	Various	Unknown	ATTICFAN_*	🔲 Untested

All supported controllers advertise over BLE with a name beginning with ATTICFAN.

Firmware 3.9+ note: Fan control, smart mode, and threshold configuration work on all firmware versions. Temperature and humidity sensors are unavailable on firmware ≥ 3.9 until the V2 GetWorkState protocol code is confirmed — see Protocol Research.

What You Get

Fan control

• Turn on / off
• Low and High speed presets

Smart Mode (TH — Thermostat + Humidity)

• Automatic on/off based on attic temperature and humidity thresholds
• Full threshold configuration from HA — no app required
• Mode selector: Idle / Timer / TH

Sensors

• Attic temperature in °F
• Attic humidity in %
• Timer countdown (seconds remaining)
• Protect temperature (overtemp safety cutoff — diagnostic)

General

• Auto-discovery — HA detects the fan automatically when in Bluetooth range
• BT Proxy support — works through ESPHome Bluetooth Proxies for extended range
• Firmware and hardware version shown in device info

Prerequisites

• Home Assistant 2023.7 or newer
• Bluetooth adapter on your HA host, or an ESPHome BT Proxy on the same network
• QuietCool fan powered on and within Bluetooth range during initial setup

Installation

HACS (recommended)

1. Open HACS → Integrations → ⋮ → Custom repositories
2. Add https://github.com/rwarner/ha-quietcool-ble with category Integration
3. Search for QuietCool BLE and install it
4. Restart Home Assistant

Manual

Copy custom_components/quietcool_ble/ into your HA config's custom_components/ directory and restart.

Setup

When your fan is powered on and in BLE range, HA will show a notification:

New device discovered: QuietCool Fan

1. Click Configure in the notification (or go to Settings → Integrations → Add Integration → QuietCool BLE)
2. Confirm the device name and MAC address shown
3. Hold the physical Pair button on your QuietCool fan controller until the light flashes
4. Click Submit in the HA UI
5. Done — all entities appear automatically

Finding the Pair Button

The Pair button is on the wall control unit or the small controller box mounted near the fan motor. It is typically labeled "Pair" or has a Bluetooth symbol. On the AFG SMT PRO-2.0, it is on the controller board inside the fan housing.

Entities

Entity	Type	Unit	Notes
Fan	fan	—	On/off, Low / High speed preset
Mode	select	—	Idle / Timer / TH (smart mode)
Fan Speed	sensor	—	Physical speed: Off / Low / High
Temperature	sensor	°F	Attic temp: Temp_Sample / 10
Humidity	sensor	%	Attic humidity: direct integer
Timer Remaining	sensor	s	Countdown when in Timer mode
Protect Temperature	sensor	°F	Overtemp safety cutoff (diagnostic)
High Temp Threshold	number	°F	TH mode activates above this
Medium Temp Threshold	number	°F	2-speed fans switch LOW→HIGH above this
Low Temp Threshold	number	°F	TH mode deactivates below this
High Humidity Threshold	number	%	TH mode activates above this

Smart Mode (TH)

TH mode lets the fan controller automatically turn the fan on and off based on attic temperature and humidity. The thresholds are stored on the device and persist across power cycles and HA restarts.

The Fan Speed sensor shows whether the blades are actually spinning (Off / Low / High). In TH mode the fan entity shows as "on" (control mode is active), but Fan Speed will read Off whenever the current conditions haven't triggered it yet.

Select TH from the Mode dropdown to activate it. Adjust the threshold number entities to match your comfort targets — changes take effect immediately without restarting the fan.

Example targets for a typical attic fan:

• High Temp: 85–95°F (fan turns on)
• Low Temp: 65–75°F (fan turns off)
• High Humidity: 80–90%

Automations

Turn on at Low speed when attic exceeds 90°F:

automation:
  trigger:
    platform: numeric_state
    entity_id: sensor.attic_gable_fan_temperature
    above: 90
  action:
    service: fan.turn_on
    target:
      entity_id: fan.attic_gable_fan
    data:
      preset_mode: Low

Switch to High speed above 100°F:

automation:
  trigger:
    platform: numeric_state
    entity_id: sensor.attic_gable_fan_temperature
    above: 100
  action:
    service: fan.turn_on
    target:
      entity_id: fan.attic_gable_fan
    data:
      preset_mode: High

Turn off when temperature drops below 75°F:

automation:
  trigger:
    platform: numeric_state
    entity_id: sensor.attic_gable_fan_temperature
    below: 75
  action:
    service: fan.turn_off
    target:
      entity_id: fan.attic_gable_fan

Activate TH smart mode at sunset:

automation:
  trigger:
    platform: sun
    event: sunset
  action:
    service: select.select_option
    target:
      entity_id: select.attic_gable_fan_mode
    data:
      option: TH

Troubleshooting

Fan not discovered:

• Ensure the fan is powered on
• Check that your HA host has Bluetooth or an ESPHome BT proxy configured
• Try moving a BT proxy closer to the fan

Pairing failed:

• Hold the Pair button (not just tap) until the light flashes, then click Submit in HA
• Only one device can be paired at a time. If the QuietCool Android app was used recently, it may have claimed the pairing slot. Try again.

Integration shows "unavailable" after setup:

• Power cycle the fan controller
• In HA: Settings → Integrations → QuietCool BLE → ⋮ → Reload

QuietCool app stopped working after setup: The fan stores exactly one pairing credential. Pairing with the QuietCool Android app will overwrite it and break this integration until you re-pair (Settings → Integrations → QuietCool BLE → ⋮ → Re-authenticate).

Threshold changes not sticking: Thresholds are written with the SetTempHumidity command and confirmed with a GetParameter read on the next poll. If the UI shows the new value but the next poll reverts it, open an issue with your debug logs.

Enabling debug logs:

logger:
  default: warning
  logs:
    custom_components.quietcool_ble: debug

Restart HA, then reproduce the problem. Logs appear in Settings → System → Logs. Each BLE command and its raw JSON response are logged at DEBUG level.

Security

This integration communicates directly with your fan over Bluetooth Low Energy. Be aware:

• No link-layer encryption. BLE communication is unencrypted — a firmware limitation that cannot be fixed in the integration.
• Single pairing credential. The device stores one credential. Pairing another client overwrites it and breaks this integration.

For home use the risk profile is similar to any locally-controlled smart home device.

How It Works

QuietCool's ESP32-based BLE controllers advertise under names starting with ATTICFAN. All communication uses a single GATT characteristic with JSON commands:

Service:  000000ff-0000-1000-8000-00805f9b34fb
Char:     0000ff01-0000-1000-8000-00805f9b34fb

Two protocol versions exist depending on firmware:

V1 (firmware < 3.9) — string command names, full response keys:

→ {"Api": "GetWorkState"}
← {"Mode": "TH", "Range": "HIGH", "Temp_Sample": 908, "Humidity_Sample": 23}

V2 (firmware ≥ 3.9) — numeric command codes, single-character response keys, QQ prefix:

→ {"A": 17}
← QQ{"A": 17, "N": "ATTICFAN_XXXX", "M": "...", "S": "..."}

The integration auto-detects the protocol version on first connection.

Smart mode thresholds (V1)

Thresholds are written with SetTempHumidity. All six fields are required per poll:

→ {"Api": "SetTempHumidity", "SetTemp_H": 86, "SetTemp_M": 75, "SetTemp_L": 65,
   "SetHum_H": 90, "SetHum_L": 255, "SetHum_Range": "LOW"}
← {"Api": "SetTempHumidity", "Flag": "TRUE"}

Known Protocol Gaps

The V2 numeric API code for GetWorkState has not yet been publicly confirmed. Until it is, temperature and humidity sensors will be unavailable on firmware ≥ 3.9 devices. Fan control and smart mode still work because SetMode and SetTime are accepted in V1 format on V2 firmware.

Protocol Research

Source	Contribution
emerose/quietcool	Original V1 reverse-engineering: command names, response keys, Temp_Sample / 10 formula
alex-spyksma/quietcool	Additional commands: GetVersion, GetRemainTime, GetParameter, SetTempHumidity
u/secretoftheeast on Reddit	Discovered firmware 3.9+ V2 protocol: QQ prefix, numeric codes, single-character keys
HA Community thread	Community reports and device compatibility

If you have firmware ≥ 3.9 and want to help unlock temperature/humidity sensors, capturing a BLE GetWorkState exchange with nRF Sniffer, Wireshark + HCI log, or Android BLE debugging would unblock it. Open an issue at this repo.

Changelog

v0.2.3

• Add "Fan Speed" sensor (Off / Low / High) showing physical running state, independent of control mode — useful in TH mode where the fan cycles automatically
• Fix: transient BLE GATT errors (e.g. ESPHome proxy error 133) no longer appear as ERROR in the HA log — already handled internally with backoff retry

v0.2.2

• Fix: polling could halt permanently if the device held the BLE connection open long enough for the coordinator's 60s idle-disconnect timer to fire first. The idle disconnect was marked "expected" so no follow-up poll was ever scheduled, silencing all entity updates until HA restarted.

v0.2.1

• Fix: poll halt on unexpected errors; stuck timer in TH mode; raised minimum HA version

v0.2.0

• Full entity suite: fan control, smart mode (TH), temperature, humidity, timer, threshold configuration
• Hardware-confirmed BLE protocol on AFG SMT PRO-2.0

v0.1.0

• Initial release

Related Projects

• emerose/quietcool — Python BLE CLI tool; primary protocol reference
• alex-spyksma/quietcool — fork with additional command documentation
• awkaplan/quietcool-esphome — ESPHome firmware replacement (alternative approach, no stock BLE)
• stabbylambda/homeassistant-quietcool — earlier HA integration attempt (cloud-based)