Arduino Home Assistant integration

ArduinoHA is the maintained MQTT-discovery library behind compact Arduino, ESP8266, and ESP32 integrations with Home Assistant. It uses Arduino's standard network Client API and is continuously compile-tested on ESP8266 and ESP32. Device discovery requires Home Assistant 2024.11.0 or newer; single-component discovery remains supported.

Why use it

Home Assistant discovery: entities appear automatically from retained MQTT discovery payloads.
Two-way entities: report local state and receive Home Assistant commands with a small, explicit API.
One physical device: group multiple entities, metadata, shared availability, and MQTT Last Will under HADevice.
Control the footprint: compile out entity implementations a firmware does not use.
Two discovery shapes: start with one payload per entity or opt into a single device-discovery payload.

Start with a sensor

#include <ESP8266WiFi.h>
#include <ArduinoHA.h>

WiFiClient client;
HADevice device;
HAMqtt mqtt(client, device);
HASensorNumber temperature("temperature");

void setup() {
    byte mac[WL_MAC_ADDR_LENGTH];
    WiFi.macAddress(mac);
    device.setUniqueId(mac, sizeof(mac));

    WiFi.begin("SSID", "password");
    while (WiFi.status() != WL_CONNECTED) delay(500);

    temperature.setName("Temperature");
    temperature.setUnitOfMeasurement("°C");
    mqtt.begin("mqtt.local", "mqtt_user", "mqtt_password");
}

void loop() {
    mqtt.loop();
    // Call temperature.setValue(...) when your reading changes.
}

Read Getting started before copying this into production: it explains object lifetime, MQTT lifecycle, ESP32 includes, and install routes.

Install

lib_deps =
    home-assistant-integration=https://github.com/alexhopeoconnor/arduino-home-assistant.git#v3.1.0

PlatformIO clones the Git repository and checks out the ref after #; that ref is a release tag, not a GitHub Release asset. Arduino IDE is supported through the included library.properties; see Getting started.

Documentation

The documentation map is the starting point:

Getting started: connection lifecycle and minimal sketches.
Device and discovery: device metadata, discovery modes, and runtime refresh.
MQTT usage: callbacks, availability, custom MQTT, logging, and footprint flags.
Entity guide: supported entity types and the best matching example.
Examples: curated entry points and the full example index.

Development and releases

./scripts/bump-version.sh vMAJOR.MINOR.PATCH
# Replace the generated CHANGELOG TODO with the release summary.
./scripts/test.sh compile --platform esp8266
./scripts/test.sh compile --platform esp32
./scripts/check-docs.sh
./scripts/prepare-release.sh vMAJOR.MINOR.PATCH --tag

The release preflight validates both package manifests and the matching changelog section. A pushed tag repeats the board-free compile checks and creates a GitHub Release from that section; it does not publish to the PlatformIO Registry or deploy firmware.

See the changelog and licence.

3.5 KiB Raw Blame History