SmartIR is an MIT-licensed, community-maintained custom integration for Home Assistant that controls climate devices, media players, fans and lights through IR and RF controllers, and it is aimed at people running a self-hosted Home Assistant instance who want appliances that only answer to a handheld remote to appear as ordinary Home Assistant entities.
What it is
SmartIR lives in Home Assistant's custom-integration ecosystem: it is a Python package placed in the custom_components directory as custom_components/smartir, with modules including init.py, climate.py, fan.py, light.py and media_player.py, and it is enabled by a single smartir entry in configuration.yaml. It sits between Home Assistant and an IR/RF transmitter, translating the commands issued for a climate, media player, fan or light entity into signals that a controller such as Broadlink, Xiaomi IR Remote (ChuangmiIr), LOOK.in Remote, an ESPHome user-defined service for a remote transmitter, or an MQTT publish service can actually send.
The problem it solves is the gap between devices whose only control path is an infrared remote and Home Assistant's native platforms. An air conditioner, television, fan or light in that position is otherwise invisible to the home automation system; SmartIR supplies the missing integration layer, so the device becomes an entity that can be automated and scripted alongside everything else instead of being operated from a separate handset.
Key capabilities
- Presents four Home Assistant platform types — climate, media player, fan and light — each with its own setup guide in docs/CLIMATE.md, docs/MEDIA_PLAYER.md, docs/FAN.md and docs/LIGHT.md.
- Drives five controller backends from one integration: Broadlink, Xiaomi IR Remote (ChuangmiIr), LOOK.in Remote, an ESPHome user-defined service for a remote transmitter, and Home Assistant's MQTT publish service.
- Ships with out-of-the-box codes for more than 120 climate devices, mainly for the Broadlink controller, contributed by the community.
- Checks for updates at every Home Assistant startup and prompts to install them, and blocks an update when the newest SmartIR version is incompatible with the running Home Assistant instance.
- Exposes update behaviour in YAML, with check_updates set to false to disable the check and update_branch set to rc to follow the release-candidate branch.
- Installs either manually by copying the custom_components folder into the configuration directory, or through HACS by adding SmartIR as a custom repository.
Who uses it and how
- Households running Home Assistant with a Broadlink hub and one or more IR-controlled air conditioners — the largest documented group, since the bundled 120-plus climate code set is mainly for Broadlink.
- Users of Xiaomi IR Remote (ChuangmiIr) hardware, who keep the same entity model while swapping the transmitter underneath.
- ESPHome builders who already expose a user-defined service for a remote transmitter and want SmartIR to supply the device codes and platform logic on top of it.
- Setups where the transmitter is reached through MQTT and Home Assistant's MQTT publish service, which suits hardware that is not a first-class Home Assistant integration.
- Contributors who extend and maintain device codes and platform documentation; the repository's 1,251 forks reflect a community-built device list rather than a vendor-shipped one.
Getting started
Copy the custom_components folder into the Home Assistant configuration directory so that custom_components/smartir exists, then add smartir to configuration.yaml. Alternatively, add SmartIR as a custom repository in HACS and let HACS handle installation and updates.
How it compares
The facts name no comparable integration; the controllers listed — Broadlink, ChuangmiIr, LOOK.in, ESPHome and MQTT — are backends that SmartIR drives rather than alternatives to it. On the supplied information, SmartIR stands alone in this registry.
When to use it — and when not to
Choose it when Home Assistant is already running and one of the five supported controllers is in place, and be ready to operate Home Assistant itself and to edit configuration.yaml by hand, since the documented setup is YAML-based with no configuration interface described. Skip it if no supported transmitter is available, or if a managed service is wanted, because this is a self-hosted custom component that carries Home Assistant's operational burden. Two caveats are worth noting: platform setup instructions live in separate documentation files rather than in the README, and although the code is MIT-licensed, the README adds a project-specific restriction that the name "SmartIR" must not be used in forks or derivative works, which anyone rebranding a fork should read first.
project readme (upstream, from github) — read inline
⚠️ Warning
You are free to fork, modify, and use the code in this repository in accordance with the applicable open-source license.
However, the name "SmartIR" must not be used in any capacity, especially for promoting, rebranding, or distributing your own fork or derivative works.
Please respect this guideline to preserve the original project's identity.
Overview
SmartIR is a custom integration for controlling climate devices, media players, fans and lights via infrared controllers.
SmartIR currently supports the following controllers:
More than 120 climate devices are currently supported out-of-the-box, mainly for the Broadlink controller, thanks to our awesome community.
Don't forget to star the repository if you had fun!
Installation
Manual
(1) Place the custom_components folder in your configuration directory (or add its contents to an existing custom_components folder).
It should look similar to this:
<config directory>/
|-- custom_components/
| |-- smartir/
| |-- __init__.py
| |-- climate.py
| |-- fan.py
| |-- light.py
| |-- media_player.py
| |-- etc...
(2) Add the following to your configuration.yaml file.
smartir:
SmartIR automatically detects updates after each HA startup and asks you to install them. It also has a mechanism that prevents you from updating if the last SmartIR version is incompatible with your HA instance. You can disable this feature by setting SmartIR as follows:
smartir:
check_updates: false
If you would like to get updates from the rc branch (Release Candidate), configure SmartIR as follows:
smartir:
update_branch: rc
(3) Configure a platform.
HACS
If you want HACS to handle installation and updates, add SmartIR as a custom repository. In this case, it is recommended that you turn off automatic updates, as above.
Platform setup instructions
Click on the links below for instructions on how to configure each platform.
See also