Arduino Home Assistant integration 🏠

ArduinoHA allows to integrate an Arduino/ESP based device with Home Assistant using MQTT. The library is designed to use as low resources (RAM/flash) as possible. Initially, it was optimized to work on Arduino Uno with Ethernet Shield, but I successfully use it on ESP8266/ESP8255 boards in my projects.

PlatformIO

library.json declares the PubSubClient dependency for Library Manager / LDF. Example:

lib_deps =
    https://github.com/alexhopeoconnor/arduino-home-assistant.git

(library.properties remains the source of truth for the Arduino IDE 1.x/2.x library manager name home-assistant-integration.)

Features

• Two-way communication (state reporting and command execution)
• MQTT discovery (device is added to the Home Assistant panel automatically)
• MQTT Last Will and Testament
• Support for custom MQTT messages (publishing and subscribing)
• Auto reconnect with MQTT broker
• Reporting availability (online/offline states) of a device
• Doxygen documentation for all classes
• Covered by unit tests (AUnit + EpoxyDuino + AUniter)

Discovery Notes

ArduinoHA supports two MQTT discovery modes:

• Single-component discovery, which remains the default behavior and publishes one retained discovery payload per entity.
• Device discovery, which can be enabled explicitly with HAMqtt::enableDeviceDiscovery() and publishes a single retained homeassistant/device/.../config payload with component mappings under cmps.

For entity ID suggestions in Home Assistant, prefer setDefaultEntityId() over setObjectId(). setObjectId() is still available as a legacy fallback, but newer Home Assistant versions are moving toward default_entity_id.

If you need to manage discovery at runtime:

• Use HABaseDeviceType::republishDiscovery() after changing discovery-relevant config at runtime.
• Use HABaseDeviceType::removeFromDiscovery() to clear the retained discovery payload for a single entity.

When device discovery mode is enabled, runtime discovery refreshes automatically clear any stale retained per-entity config before republishing the device discovery payload.

Supported HA types

Home Assistant type	Supported
Alarm control panel	❌
Binary sensor	✅
Button	✅
Camera	✅
Cover	✅
Device tracker	✅
Device trigger	✅
Event	❌
Fan	✅
Humidifier	❌
Image	❌
HVAC	✅
Lawn mower	❌
Light	✅
Lock	✅
Number	✅
Scene	✅
Select	✅
Sensor	✅
Siren	❌
Switch	✅
Update	❌
Tag scanner	✅
Text	✅
Vacuum	❌
Valve	❌
Water heater	❌

Examples

Example	Description
Binary sensor	Using the binary sensor as a door contact sensor.
Button	Adding simple buttons to the Home Assistant panel.
Camera	Publishing the preview from the ESP32-CAM module.
Cover	Controlling a window cover (open / close / stop).
Device trigger	Implementation of a simple wall switch that reports press and hold states.
Fan	Controlling a simple fan (state + speed).
HVAC	HVAC controller with multiple modes, power control and target temperature.
Lock	A simple door lock that's controlled by the Home Assistant.
Light	A simple light that allows changing brightness, color temperature and RGB color.
Number	Adding an interactive numeric slider in the Home Assistant panel.
Scene	Adding a custom scene in the Home Assistant panel.
Select	A dropdown selector that's displayed in the Home Assistant panel.
Sensor	A simple sensor that reports a state in a string representation (open / opening / close).
Analog sensor	Reporting the analog pin's voltage to the Home Assistant.
Integer sensor	Reporting the device's uptime to the Home Assistant.
Switch	The LED that's controlled by the Home Assistant.
Multi-switch	Multiple switches controlled by the Home Assistant.
Tag scanner	Scanning RFID tags using the MFRC522 module.
Availability	Reporting entities' availability (online / offline) to the Home Assistant.
Advanced availability	Advanced availability reporting with MQTT LWT (Last Will and Testament).
MQTT advanced	Subscribing to custom topics and publishing custom messages.
MQTT with credentials	Establishing connection with a MQTT broker using the credentials.
NodeMCU (ESP8266)	Basic example for ESP8266 devices.
Arduino Nano 33 IoT	Basic example for Arduino Nano 33 IoT (SAMD family).
mDNS discovery	Make your ESP8266 discoverable via the mDNS.

Compatible hardware

The library uses the Arduino Ethernet Client API for interacting with the network hardware. It should work fine as long as the Client class is available.

Here is the list of devices on which the library was tested:

• Arduino Uno
• Arduino Mega
• Arduino Nano
• Arduino Pro Mini
• Arduino Nano 33 IoT
• Arduino Due
• NodeMCU
• Controllino Mega (Pure)
• Controllino Maxi (Pure)
• ESP-01
• ESP32-CAM
• Sonoff Dual R2
• Sonoff Dual R3
• Sonoff Basic
• Sonoff Mini
• Tuya Wi-Fi switch module
• Tuya Wi-Fi curtain module

Please note that it's not the complete list of supported devices. You may try to use the library on any device that uses Arduino core.