IR MaxxAir Fan Control in Home Assistant via ESPHome

Control your IR (infrared) enabled MaxxAir Fan from Home Assistant via ESPHome.

This ESPHome configuration and Automation Blueprint are free and open source. Consider joining a Smarty Van YouTube Membership tier to show some love. 🥰🤓

Watch the YouTube video about this project

Project Components

This project is made up of two parts:

1. ESPHome YAML configuration: for an ESP microcontroller that utilizes an IR LED to control an Airxcel MaxxAir Fan with IR (7000k/7500k models).
2. Home Assistant Automation Blueprint: to enable Auto Fan and set your preferences

Home Assistant Entities Created

Automation Blueprint Options

ESPHome Configuration

The included ESPHome configuration replicates a majority of the features available on the MaxxAir Fan IR remote:

• 10 speeds of an AIR OUT fan (lid open)
• 10 speeds of an AIR IN fan (lid open)
• 10 speeds of AIR IN (lid closed) — a.k.a "Celing Fan Mode"
• Lid Open (fan off)
• Lid Close (fan off)

🚨 Home Assistant fan FORWARD = MaxxAir Fan AIR OUT — Home Assistant fan REVERSE = MaxxAir Fan AIR IN

This configuration creates 4 entities in Home Assistant:

1. Fan: A 10-speed fan with forward and reverse direction
2. Switch: A Ceiling Fan switch——turn Ceiling Fan Mode on and off
3. Switch: An Auto Fan switch——used by the Auto Fan Automation Blueprint
4. Cover: A cover to represent and control the state of the fan's lid/cover

The ESPHome YAML logic manages the states of all four entities based on user input to the other entities much like the MaxxAir Fan remote:

• Enabling Ceiling Fan Mode automatically sets the Fan's direction to Reverse (as the MaxxAir Fan's Ceiling Fan Mode only pushes air downwards when the lid is closed)
• Manually controlling the Fan will disable Auto Fan
• The state of the Lid cover entity is updated to reflect the state of the lid
• When the Fan is off, the Lid cover entity's UP and DOWN (OPEN / CLOSE) buttons will open and close the lid of the MaxxAir Fan without turning on the fan (passive ventiliation)
• When the fan is on, closing the lid will engage Ceiling Fan Mode
• When the fan is on, disabling Ceiling Fan Mode will open the lid and the fan will continue operating in REVERSE (AIR IN)
• Turning off Auto Fan will turn off the fan

Install ESPHome Configuration

• Create a new ESPHome deivce called "MaxxAir Fan Control" in the ESPHome add-on
• Choose ESP8266 (or any board, we'll overwrite this in the following steps)
• After the device has been created, skip the initial install
• Edit the configuration of your new device and copy the configuration yaml in this repo into your ESPHome device configuration, overwriting the existing configuration
• Change your board and pin definitions if necessary then save and close
• Open Secrets (top right) in the ESPHome builder and add secrets for:
  • wifi_ssid
  • wifi_password
• Add OTA password and API encryption to your configuration if desired
• Save and Install (wirelesly if you can, or use a USB and ESPHome Webtools)

Auto Fan

The Auto Fan Automation Blueprint imitates (and improves) the MaxxAir IR remote's thermostatic control. When Auto Fan is enabled, your fan's speed will be adjusted based on configurable temperature thresholds, minimum and maximum fan speeds, and a temperature sensor of your choosing.

Auto Fan never turns your fan off, only assigns speeds based on temperature. Turn off the Fan or Auto Fan to power off the Fan.

The Auto Fan Automation Blueprint can be used with any Home Assistant fan, though it will only send 10 speeds (10%, 20%, 30%, etc)

Install Auto Fan Blueprint

To install the Smarty Van Auto Fan Blueprint, navigate to your Home Assistant Blueprints and click the "Import Blueprint" button. Paste the link to the bluprint in this repo.

Hardware

Building your ESP IR device requires four items:

• ESP8266 (or ESP32)——This configuration assumes a Wemos D1 Mini but any ESP8266/32 should work (as long as you update pin asignments accordingly)
• An IR LED
• A 220Ω resistor
• A 5v power supply for your ESP——I've used a 12v to 5v down converter

Wiring Diagram

• Annode of LED through resistor to 3V3
• Cathode of LED to GPIO pin

License: Personal Use Only (Non-Commercial)

This project is released under a Personal Use License, which restricts usage to non-commercial purposes only. Please read the terms carefully before using or modifying the code.

License Terms

Copyright © 2025 Mike Goubeaux

Permission is hereby granted to any person obtaining a copy of this software and associated documentation files (the "Software"), to use the Software solely for personal, non-commercial purposes.

Restrictions:

The Software may not be used, distributed, or sold for commercial purposes without prior written permission from the copyright owner. Modification of the Software for personal use is allowed, but modified versions may not be distributed commercially. Attribution to the original author must be retained in any copy or modification of the Software. Disclaimer

The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the authors be liable for any claim, damages, or other liability arising from the use of the Software.

Clarification of Non-Commercial Use

Non-commercial use means the use of this software for personal purposes or academic projects, without any financial gain or benefit. If you wish to use this project for commercial purposes, please contact the author to request permission.