An Arduino library for Home Assistant MQTT Auto Discovery.
What is this library?
JBHaMqttDiscovery makes sensors and devices connected to Arduino/ESP8266/ESP32 devices show up automatically in Home Assistant via MQTT Discovery.
It helps you builds the correct discovery topics and JSON configuration payloads and publishes them as retained messages, so Home Assistant can create entities (e.g. sensors, switches, binary sensors, buttons) without manual UI/YAML setup.
It is also transport-agnostic: you can use different MQTT client libraries through a small “transport” adapter (e.g. PubSubClient or AsyncMqttClient), while keeping the same discovery API in your firmware.
Usage
Dependencies
- ArduinoJson
- PubSubClient or AsyncMqttClient
- JBLogger
PubSubClient (polling required)
#include <PubSubClient.h>
#include <HaDiscovery.h>
#include <transport/PubSubClientTransport.h>
WiFiClient wifi;
PubSubClient mqtt(wifi);
void setup() {
String mac = WiFi.macAddress();
mac.replace(":", "");
String nodeId = "esp8266_" + mac;
ha.setDevice({
.node_id = nodeId.c_str(),
.name = "Office Node",
.manufacturer = "YourBrand",
.model = "ESP8266",
.sw_version = "1.0.0",
.identifiers = mac.c_str()
});
transport.setServer("mqtt-broker.local", 1883, "user", "pass");
mqtt.connect(nodeId.c_str(), "user", "pass");
.common = { .object_id="relay1", .name="Desk Relay" }
};
ha.publishSwitchDiscovery(sw);
.common = { .object_id="temperature", .name="Office Temperature" },
.unit_of_measurement="°C",
.device_class="temperature"
};
ha.publishSensorDiscovery(temp);
}
void loop() {
mqtt.loop();
ha.tick();
}
Home Assistant MQTT Discovery publisher (transport-agnostic).
Definition HaDiscovery.h:169
MQTT transport adapter for PubSubClient.
Definition PubSubClientTransport.h:21
Configuration for a Home Assistant MQTT Discovery sensor.
Definition HaDiscovery.h:84
Configuration for a Home Assistant MQTT Discovery switch.
Definition HaDiscovery.h:100
AsyncMqttClient (event-driven, no polling required)
#include <AsyncMqttClient.h>
#include <HaDiscovery.h>
#include <transport/AsyncMqttClientTransport.h>
AsyncMqttClient mqtt;
void setup() {
String mac = WiFi.macAddress();
mac.replace(":", "");
String nodeId = "esp32_" + mac;
ha.setDevice({
.node_id = nodeId.c_str(),
.name = "Kitchen Node",
.manufacturer = "YourBrand",
.model = "ESP32",
.sw_version = "1.0.0",
.identifiers = mac.c_str()
});
transport.setServer("mqtt-broker.local", 1883, "user", "pass");
mqtt.connect();
.common = { .object_id="temperature", .name="Kitchen Temperature" },
.unit_of_measurement="°C",
.device_class="temperature",
.state_class="measurement"
};
ha.publishSensorDiscovery(temp);
.common = { .object_id="relay1", .name="Kitchen Light" }
};
ha.publishSwitchDiscovery(relay);
}
void loop() {
}
MQTT transport adapter for AsyncMqttClient.
Definition AsyncMqttClientTransport.h:24
Entity usage
Sensor
.common = { .object_id="temperature", .name="Kitchen Temperature", .icon="mdi:thermometer" },
.unit_of_measurement="°C",
.device_class="temperature",
.state_class="measurement"
};
ha.publishSensorDiscovery(temp);
ha.publishState("temperature", "22.5");
Switch
.common = { .object_id="relay1", .name="Desk Light", .icon="mdi:lightbulb" }
};
ha.publishSwitchDiscovery(relay);
ha.publishStateSwitch("relay1", true);
Binary sensor
.common = { .object_id="motion", .name="Hallway Motion", .icon="mdi:motion-sensor" },
.device_class = "motion"
};
ha.publishBinarySensorDiscovery(motion);
ha.publishState("motion", "ON");
Configuration for a Home Assistant MQTT Discovery binary_sensor.
Definition HaDiscovery.h:121
Button
.common = { .object_id="restart", .name="Restart Device", .icon="mdi:restart" },
.payload_press = "PRESS"
};
ha.publishButtonDiscovery(restart);
ha.pressButton("restart");