Getting started

Prerequisites

ArduinoHA talks to Home Assistant over MQTT (TCP). You need an MQTT broker reachable from your board. On Home Assistant OS, the Mosquitto add-on is a common choice.

Install the library

PlatformIO (recommended): add the maintained release tag in platformio.ini. Its library.json resolves PubSubClient:

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

Arduino IDE: this fork is not indexed by Library Manager. Download the source archive for a release, extract it, move the extracted library directory to <sketchbook>/libraries/home-assistant-integration, and restart the IDE.

You also need a network Client (Ethernet or Wi-Fi) compatible with the Arduino networking API.

Minimal layout

Create HADevice and HAMqtt once (global or inside a long-lived object).
Call HAMqtt::begin(...) once, at the end of setup() — it only stores broker settings; the actual connection runs during HAMqtt::loop().
Call mqtt.loop() regularly in loop() (not necessarily every iteration).
Construct entity classes (sensors, switches, …) before or after HAMqtt; ArduinoHA registers both orders. Keep all objects alive for the whole MQTT lifetime and configure discovery before the first connection.

Ethernet (example)

#include <Ethernet.h>
#include <ArduinoHA.h>

byte mac[] = {0x00, 0x10, 0xFA, 0x6E, 0x38, 0x4A};
EthernetClient client;
HADevice device(mac, sizeof(mac));
HAMqtt mqtt(client, device);

void setup() {
    Ethernet.begin(mac);  // Bring up the network Client before MQTT can connect.
    mqtt.begin("192.168.1.50", "mqtt_user", "mqtt_password");  // Connection begins in mqtt.loop().
}

void loop() {
    Ethernet.maintain();  // Renews DHCP leases where the Ethernet library requires it.
    mqtt.loop();          // Services MQTT connection, discovery, and entity traffic.
}

ESP8266 / ESP32 (example)

#if defined(ESP8266)
#include <ESP8266WiFi.h>
#elif defined(ESP32)
#include <WiFi.h>
#endif
#include <ArduinoHA.h>

WiFiClient client;
HADevice device;
HAMqtt mqtt(client, device);

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

    WiFi.begin("SSID", "password");
    // Keep this blocking wait only in a minimal sketch. Production firmware
    // should retry, time out, or hand control to its provisioning flow.
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
    }

    // begin() stores broker settings; mqtt.loop() performs connection and recovery.
    mqtt.begin("192.168.1.50", "mqtt_user", "mqtt_password");
}

void loop() {
    mqtt.loop();  // Service reconnects, subscriptions, and discovery publishing.
}

`begin()` variants

All are valid; pick one. Hostnames work instead of IP addresses.

mqtt.begin("192.168.1.50") — anonymous, port 1883
mqtt.begin("192.168.1.50", 8888) — anonymous, custom port
mqtt.begin("192.168.1.50", "user", "pass") — credentials, port 1883
mqtt.begin("192.168.1.50", 8888, "user", "pass") — credentials + custom port

begin() is intentionally a one-time configuration call. Reconnects are owned by mqtt.loop(), which uses the configured reconnect interval. Do not call begin() in a reconnect timer. mqtt.disconnect() now also produces the registered disconnected and state-change callbacks, making an explicit shutdown observable in the same way as a transport loss.

Use Home Assistant 2024.11.0 or newer when opting into device discovery. See Device & discovery for the required staged migration from an existing single-component device.

Security note

Credentials go over plain TCP unless you use a TLS-capable stack and broker setup. On a trusted LAN this is often acceptable; treat untrusted networks accordingly.

Examples

See examples/ — start with nodemcu / nano33iot or an entity example matching what you need.

4.1 KiB Raw Blame History