homebridge-ir-fan

Homebridge plugin for IR-controlled fans with full HomeKit integration.
Designed for use with Aqara Hub M3 (IR blaster) or any IR hub.

Each fan exposes the following in HomeKit:

• On/Off — via the native Fan tile
• Speed 1–12 — via rotation speed slider (mapped to 0–100%)
• Rotation On/Off — oscillation toggle on the fan tile
• 4 Mode switches — Normal, Turbo, Auto, Night (mutually exclusive)

Installation

npm install -g homebridge-ir-fan

Or search for homebridge-ir-fan in the Homebridge UI plugin browser.

Configuration

{
  "platforms": [
    {
      "platform": "IRFan",
      "name": "IR Fan",
      "fans": [
        {
          "name": "Bedroom Fan",
          "manufacturer": "Generic",
          "model": "IR Fan 12-speed",
          "serial": "001"
        },
        {
          "name": "Living Room Fan",
          "manufacturer": "Generic",
          "model": "IR Fan 12-speed",
          "serial": "002"
        }
      ]
    }
  ]
}

HomeKit Accessories per Fan

For a fan named "Bedroom Fan", the following accessories are created:

| Accessory | Type | Description | |---|---|---| | Bedroom Fan | Fan v2 | On/Off + Speed + Rotation | | Bedroom Fan – Normal | Switch | Activates Normal mode | | Bedroom Fan – Turbo | Switch | Activates Turbo mode | | Bedroom Fan – Auto | Switch | Activates Auto mode | | Bedroom Fan – Night | Switch | Activates Night mode |

Mode switches are mutually exclusive — turning one on automatically turns the others off.

Speed Mapping

HomeKit exposes speed as a percentage (0–100%). This plugin maps it to fan speeds 1–12:

| HomeKit % | Fan Speed | |---|---| | 8% | 1 | | 17% | 2 | | 25% | 3 | | 33% | 4 | | 42% | 5 | | 50% | 6 | | 58% | 7 | | 67% | 8 | | 75% | 9 | | 83% | 10 | | 92% | 11 | | 100% | 12 |

Aqara Integration

This plugin manages the HomeKit state of your fan. To actually send IR commands:

1. Use Apple Home automations triggered by accessory state changes
2. Route those automations to your Aqara Hub M3 via scenes or the Aqara app

A future version may include direct Aqara API integration.

Logs

Every state change is logged with full details:

[Bedroom Fan] State → {"active":true,"speed":6,"speedPercent":50,"swing":false,"mode":"Turbo"}