IR2MQTT - WebGUI and ESPHome component

[steelcuts (Angelo)]

Hey everyone,

Integrating old Infrared devices (TVs, ACs, soundbars) into Home Assistant usually means recording IR codes, pasting them into YAML files, and trying to keep track of endless dummy switches. I wanted a clean, UI-driven way to handle this, so I built IR2MQTT .

https://postimg.cc/LYYpTqR1https://i.postimg.cc/B6NnJDVM/showcase.gif(image larger than 3 MB)

How it works IR2MQTT is a backend and web interface that acts as an IR gateway. Instead of writing config files, you manage your physical remotes, macros, and IR codes entirely through the frontend. Any device or button you configure is automatically published to Home Assistant via MQTT Auto-Discovery .

To make the hardware side reliable, I wrote a custom ESPHome external component . It handles the actual IR TX/RX on an ESP8266/ESP32 and communicates directly with the IR2MQTT backend (either wirelessly via MQTT or directly via USB/Serial to your host).

Main Features

• Integrated IR Databases: I’ve hooked up the Flipper-IRDB and Probono IRDB directly. Search for your device brand (e.g., Samsung TV) and import the full remote layout with one click—no manual learning required.
• Live Learning Mode: If a code isn’t in the database, just point your physical remote at the ESP receiver. The UI captures the code in real-time via WebSockets so you can easily assign it to a button.
• Macros & Sequences: Create automations directly in the UI (like “TV Power On” → 2s delay → “Soundbar Power On” → “Input HDMI 1” ) and expose the entire sequence as a single switch in Home Assistant.
• Easy Installation: Run the backend as a standalone Docker container or install it directly as a Home Assistant Add-on.

Getting Started The setup process is straightforward: flash your ESP board with the bridge component, spin up the IR2MQTT app, and start adding your devices via the UI. The repositories each includes a full manual explaining the setup, MQTT topic structure, and ESPHome config instructions.

• GitHub Repository: GitHub - steelcuts/ir2mqtt · GitHub

I’d love to hear your feedback or help out if you run into any issues setting it up!

[JimmyHotcakes0235]

Maybe im just old fashioned or something but, I think people should learn those bare basics like capturing codes, assigning them to a button and then logging/saving it all as a .txt file for future reference. IDK, maybe im just a little jaded and feel like the easier things get, the more useless others get because of how easy everything is…

Very cool project to create and share though! If no one else remembers to do this at a bare minimum then I’ll do it for everyone. Thank you for the work you put into this and for making it available for all and for free!

[steelcuts (Angelo)]

You’re not wrong! Knowing the bare basics is definitely useful. That’s the whole reason I was able to code all of this. I just like building tools, and had the feeling that this one, if implemented correctly with great UI/UX, could really benefit others.

I’m also aware that there is the new IR/RF Proxy from HA, but still, I had to build this one. Don’t forget that this isn’t only available as a Home Assistant add-on, it can also be used as a standalone Docker container. That makes integrating it into other smart home systems easy as can be. I don’t even know how capable other systems are regarding IR. And since there was Zigbee2MQTT… it just made sense!

Glad you like the project though, and i really appreciate the star on GH, cheers!

[zodyking (The Engineer)]

Sir/Mam i had this on the long list of shit to do,

thank you for building this saved me ton of time

[steelcuts (Angelo)]

Haha, glad I could cross that off your list! It took me about 3 months to build, which is absolutely nuts, but mainly because I really wanted to make sure it’s solid with proper unit, feature, and E2E testing. Enjoy the extra free time!

[cameron]

Hi this is brilliant it’s going to change a lot of my HomeAssistant IR control of my devices.

I am looking forward to trying this out. But not sure how to wire the IR tx/rx onto the ESP32 could you give a diagram of it.

Thank you.

[steelcuts (Angelo)]

Hi Cameron, this is awesome! Thank you for giving it a try, and of course, I’m here to help.

Could you please tell me exactly what hardware (which specific ESP32 board, and what IR Transmitter / Receiver modules) you are using? A link or a picture would be great.

The reason I ask is that ESP32 boards have very different pin layouts, and the pins on IR modules (VCC, GND, Data) often change order depending on the manufacturer. Knowing your exact hardware helps me give you a precise wiring diagram so we don’t accidentally fry anything! Looking forward to getting this set up with you.

[cameron]

Thanks. I am using ESP32-C3 super mini dev board
and a ir receiver module (ky-022). I managed to take a ir emitter out of an old remote control.

Hope this helps.

[zodyking (The Engineer)]

btw you can upload gif straight to to your post, use canva to turn video/screenshots into a gif

[steelcuts (Angelo)]

The C3 Super Mini is perfect for this. Here’s how you should wire it:

1. IR Receiver (KY-022)

• GND → GND
• VCC → 3V3
• S (Signal) → GPIO 2

2. IR Emitter (Bare LED)
Since it’s a bare LED, use a resistor (around 100-220 Ohm) to protect the GPIO.

• Anode (+, long leg, rounded edge on case) → GPIO 3
• Cathode (-, short leg, flat edge on case) → GND

Your Config:
You can use this snippet. I’ve updated the board type to esp32-c3-devkitm-1 (which should for the Super Mini) and set the pins to match the wiring above:

substitutions:
  device_name: ir2mqtt-bridge-wifi
  rx_pin: GPIO2
  tx_pin: GPIO3
  # Note: The C3 Super Mini has a built-in blue LED on GPIO 8 if you want to use it
  status_led_pin: GPIO8 

esphome:
  name: ${device_name}

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: arduino

# ... rest of your wifi/mqtt config ...

remote_receiver:
  - id: rx1
    pin: 
      number: ${rx_pin}
      inverted: True
      mode: INPUT_PULLUP

remote_transmitter:
  - id: tx1
    pin: ${tx_pin}
    carrier_duty_percent: 50%
    non_blocking: true

ir2mqtt_bridge:
  # If you don't have an addressable RGB LED (WS2812) connected, 
  # you might want to remove the status_led line or use a simple light platform.
  # status_led: status_light 
  receivers: [rx1]
  transmitters: [tx1]

Full examples (Lan/Wifi/Serial) → ir2mqtt_bridge/examples at main · steelcuts/ir2mqtt_bridge · GitHub

One tip: The range with a bare LED and resistor will be limited (1-2 meters). It’s great for testing, but if you want to control devices across the room later, you should look into adding a transistor (like a 2N2222) to drive the LED with more power.

Let me know if you get it running!

Edit: I’ve just updated the documentation in the repo to include these details (with schematics). Hopefully, that makes the setup process even clearer! Hardware Setup Guide | IR2MQTT

[steelcuts (Angelo)]

Thanks for the tip! I actually tried, but I messed up the recording and the showcase gif ended up way too big for the forum’s upload limit. I was in a bit of a rush to get the post out, so I just used the external links.

Is there actually a way to edit the post now so I can swap them for smaller versions?

[cameron]

Wow this is really helpful thanks for this I will try and have a go as soon as I get back from holiday.

Thanks again.

[zodyking (The Engineer)]

@steelcuts

Thanks for the tip! I actually tried, but I messed up the recording and the showcase gif ended up way too big for the forum’s upload limit. I was in a bit of a rush to get the post out, so I just used the external links.

Is there actually a way to edit the post now so I can swap them for smaller versions?

Yes, there shoukd be a pencil icon on the main post

[steelcuts (Angelo)]

A quick update on the project! It’s been an incredible week, IR2MQTT actually got featured on Hackaday a few days ago!

Reading through the feedback here (especially the questions about wiring!) and on other platforms, I noticed two main things:

1. People want to see how the UI feels, but setting up a Docker container and an MQTT broker just to “click around” is a bit of a hassle.
2. A lot of folks want to try the project but aren’t super familiar with ESP32s, ESPHome, or wiring up IR LEDs from scratch.

To address this, I’ve been working on two major additions:

1. A Fully Interactive Live Demo I built a demo infrastructure that spins up a completely isolated, temporary Docker stack exclusively for you. You get your own backend, a private Mosquitto broker, and a simulated IR bridge.

Try the Live Demo here: https://ir2mqtt.steelcuts.net/

Tip for testing: To make it easy to play around without physical hardware, the simulated IR bridge automatically broadcasts a dummy NEC IR code every 3 seconds. You can use this to try out the “Learn IR Code” feature, assign the code to a virtual device, and build your first automation right in your browser!

2. Comprehensive Hardware & First Setup Guide To make getting started as easy as possible, I completely overhauled the documentation and added a massive, step-by-step hardware guide. It covers literally everything from scratch:

• Exactly which ESP32 boards and IR components to buy
• Simple wiring diagrams (including high-power transistor circuits for whole-room coverage)
• Copy & paste ESPHome configurations
• A full first-run walkthrough to get everything connected to Home Assistant

Read the new Hardware Guide here: Hardware Setup Guide | IR2MQTT

I’d love for you to try out the demo or let me know if the new hardware guide makes getting started easier.