JBHaMqttDiscovery
Loading...
Searching...
No Matches
JBHaMqttDiscovery

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

  1. ArduinoJson
  2. PubSubClient or AsyncMqttClient
  3. JBLogger

PubSubClient (polling required)

#include <PubSubClient.h>
#include <HaDiscovery.h>
#include <transport/PubSubClientTransport.h>
WiFiClient wifi;
PubSubClient mqtt(wifi);
PubSubClientTransport transport(mqtt);
HaDiscovery ha(transport);
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()
});
// Configure mqtt server/credentials through the transport, then connect:
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(); // REQUIRED
ha.tick(); // Recommended: enables auto "on-connect" availability publish
}
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;
AsyncMqttClientTransport transport(mqtt);
HaDiscovery ha(transport);
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()
});
// Configure mqtt host/credentials/LWT through the transport, then connect:
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() {
// nothing required for HaDiscovery
}
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);
// later:
ha.publishState("temperature", "22.5");

Switch

.common = { .object_id="relay1", .name="Desk Light", .icon="mdi:lightbulb" }
};
ha.publishSwitchDiscovery(relay);
// later:
ha.publishStateSwitch("relay1", true); // ON

Binary sensor

.common = { .object_id="motion", .name="Hallway Motion", .icon="mdi:motion-sensor" },
.device_class = "motion"
};
ha.publishBinarySensorDiscovery(motion);
// later:
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);
// later:
ha.pressButton("restart");
Configuration for a Home Assistant MQTT Discovery button.
Definition HaDiscovery.h:140