JBHaMqttDiscovery
Loading...
Searching...
No Matches
HaDiscovery Class Reference

Home Assistant MQTT Discovery publisher (transport-agnostic). More...

#include <HaDiscovery.h>

Public Member Functions

 HaDiscovery (MqttTransport &transport, const char *discovery_prefix="homeassistant", const char *base_topic_prefix="devices")
 Construct a Home Assistant MQTT Discovery publisher.
void setLogLevel (LogLevel level)
 Set the minimum log level for the internal logger.
void setDevice (const HaDeviceInfo &dev)
 Set the device information used in dev object of Discovery payloads.
void tick ()
 Periodic processing hook.
void publishAvailabilityOnline (bool retained=true, uint8_t qos=1)
 Publish "online" availability payload to the availability topic (retained by default).
void publishAvailabilityOffline (bool retained=true, uint8_t qos=1)
 Publish "offline" availability payload to the availability topic (retained by default).
bool publishSensorDiscovery (const HaSensorConfig &cfg, bool retained=true, uint8_t qos=1)
 Publish a sensor Discovery config (retained by default).
bool publishSwitchDiscovery (const HaSwitchConfig &cfg, bool retained=true, uint8_t qos=1)
 Publish a switch Discovery config (retained by default).
bool publishBinarySensorDiscovery (const HaBinarySensorConfig &cfg, bool retained=true, uint8_t qos=1)
 Publish a binary_sensor Discovery config (retained by default).
bool publishButtonDiscovery (const HaButtonConfig &cfg, bool retained=true, uint8_t qos=1)
 Publish a button Discovery config (retained by default).
bool removeEntity (const char *component, const char *object_id, uint8_t qos=1)
 Remove an entity from Home Assistant by clearing its retained config topic.
bool publishState (const char *object_id, const char *payload, bool retained=false, uint8_t qos=0)
 Publish an entity state payload using default state topic for object_id.
bool publishStateSwitch (const char *object_id, bool on, bool retained=false, uint8_t qos=0)
 Publish a switch state ("ON"/"OFF") using default state topic.
bool pressButton (const char *object_id, const char *payload=nullptr, bool retained=false, uint8_t qos=0)
 Publish a button "press" command to the default command topic.
bool removeEntity (const std::string &component, const std::string &object_id, uint8_t qos=1)
 Overload of removeEntity using std::string.
bool removeEntity (const char *component, const std::string &object_id, uint8_t qos=1)
 Overload of removeEntity using std::string for object_id.
bool removeEntity (const std::string &component, const char *object_id, uint8_t qos=1)
 Overload of removeEntity using std::string for component.
bool publishState (const std::string &object_id, const std::string &payload, bool retained=false, uint8_t qos=0)
 Overload of publishState using std::string.
bool publishState (const std::string &object_id, const char *payload, bool retained=false, uint8_t qos=0)
 Overload of publishState using std::string for object_id.
bool publishState (const char *object_id, const std::string &payload, bool retained=false, uint8_t qos=0)
 Overload of publishState using std::string for payload.
bool publishStateSwitch (const std::string &object_id, bool on, bool retained=false, uint8_t qos=0)
 Overload of publishStateSwitch using std::string for object_id.
bool pressButton (const std::string &object_id, const std::string &payload, bool retained=false, uint8_t qos=0)
 Overload of pressButton using std::string.
bool pressButton (const std::string &object_id, const char *payload, bool retained=false, uint8_t qos=0)
 Overload of pressButton using std::string for object_id.
bool pressButton (const std::string &object_id, bool retained=false, uint8_t qos=0)
 Overload of pressButton using std::string for object_id (no payload).

Detailed Description

Home Assistant MQTT Discovery publisher (transport-agnostic).

Typical usage:

  • Construct with a MqttTransport implementation
  • Provide device info via setDevice()
  • Publish discovery configs (retained)
  • Publish states as needed

For async transports, onConnect is invoked automatically. For sync transports, call tick() periodically to detect reconnection transitions.

Constructor & Destructor Documentation

◆ HaDiscovery()

HaDiscovery::HaDiscovery ( MqttTransport & transport,
const char * discovery_prefix = "homeassistant",
const char * base_topic_prefix = "devices" )

Construct a Home Assistant MQTT Discovery publisher.

Parameters
MQTT TransportsMQTT transport adapter
discovery_prefixHome Assistant discovery prefix (default "homeassistant")
base_topic_prefixBase topic prefix for device topics (default "devices")

Member Function Documentation

◆ pressButton()

bool HaDiscovery::pressButton ( const char * object_id,
const char * payload = nullptr,
bool retained = false,
uint8_t qos = 0 )

Publish a button "press" command to the default command topic.

Parameters
object_idEntity object_id
payloadPayload string to publish (if nullptr uses default "PRESS")
retainedRetain flag (usually false)
qosQoS level (usually 0 or 1)
Returns
true if publish was accepted by transport, false otherwise

◆ publishAvailabilityOffline()

void HaDiscovery::publishAvailabilityOffline ( bool retained = true,
uint8_t qos = 1 )

Publish "offline" availability payload to the availability topic (retained by default).

Parameters
retainedRetain flag (recommended true)
qosQoS level (recommended 1 for availability if supported)

◆ publishAvailabilityOnline()

void HaDiscovery::publishAvailabilityOnline ( bool retained = true,
uint8_t qos = 1 )

Publish "online" availability payload to the availability topic (retained by default).

Parameters
retainedRetain flag (recommended true)
qosQoS level (recommended 1 for availability if supported)

◆ publishBinarySensorDiscovery()

bool HaDiscovery::publishBinarySensorDiscovery ( const HaBinarySensorConfig & cfg,
bool retained = true,
uint8_t qos = 1 )

Publish a binary_sensor Discovery config (retained by default).

Parameters
cfgBinary sensor configuration
retainedRetain flag (recommended true)
qosQoS level (recommended 1 for discovery if supported)
Returns
true if publish was accepted by transport, false otherwise

◆ publishButtonDiscovery()

bool HaDiscovery::publishButtonDiscovery ( const HaButtonConfig & cfg,
bool retained = true,
uint8_t qos = 1 )

Publish a button Discovery config (retained by default).

Parameters
cfgButton configuration
retainedRetain flag (recommended true)
qosQoS level (recommended 1 for discovery if supported)
Returns
true if publish was accepted by transport, false otherwise

◆ publishSensorDiscovery()

bool HaDiscovery::publishSensorDiscovery ( const HaSensorConfig & cfg,
bool retained = true,
uint8_t qos = 1 )

Publish a sensor Discovery config (retained by default).

Parameters
cfgSensor configuration
retainedRetain flag (recommended true)
qosQoS level (recommended 1 for discovery if supported)
Returns
true if publish was accepted by transport, false otherwise

◆ publishState()

bool HaDiscovery::publishState ( const char * object_id,
const char * payload,
bool retained = false,
uint8_t qos = 0 )

Publish an entity state payload using default state topic for object_id.

Parameters
object_idEntity object_id
payloadNull-terminated payload string
retainedRetain flag (usually false for state)
qosQoS level (usually 0 for state)
Returns
true if publish was accepted by transport, false otherwise

◆ publishStateSwitch()

bool HaDiscovery::publishStateSwitch ( const char * object_id,
bool on,
bool retained = false,
uint8_t qos = 0 )

Publish a switch state ("ON"/"OFF") using default state topic.

Parameters
object_idEntity object_id
ontrue -> "ON", false -> "OFF"
retainedRetain flag (usually false)
qosQoS level (usually 0)
Returns
true if publish was accepted by transport, false otherwise

◆ publishSwitchDiscovery()

bool HaDiscovery::publishSwitchDiscovery ( const HaSwitchConfig & cfg,
bool retained = true,
uint8_t qos = 1 )

Publish a switch Discovery config (retained by default).

Parameters
cfgSwitch configuration
retainedRetain flag (recommended true)
qosQoS level (recommended 1 for discovery if supported)
Returns
true if publish was accepted by transport, false otherwise

◆ removeEntity()

bool HaDiscovery::removeEntity ( const char * component,
const char * object_id,
uint8_t qos = 1 )

Remove an entity from Home Assistant by clearing its retained config topic.

Home Assistant removes the entity when the Discovery config topic is published with an empty payload and retain=true.

Parameters
componentComponent name (e.g. "sensor", "switch")
object_idEntity object_id used in the config topic
qosQoS level (recommended 1 if supported)
Returns
true if publish was accepted by transport, false otherwise

◆ setDevice()

void HaDiscovery::setDevice ( const HaDeviceInfo & dev)

Set the device information used in dev object of Discovery payloads.

This must be called before publishing discovery configs if you want correct device registry behavior.

Parameters
devDevice info struct (pointers must remain valid)

◆ setLogLevel()

void HaDiscovery::setLogLevel ( LogLevel level)

Set the minimum log level for the internal logger.

Parameters
levelThe minimum log level to be logged.

◆ tick()

void HaDiscovery::tick ( )

Periodic processing hook.

For synchronous MQTT clients (e.g. PubSubClient), call this from loop(). For asynchronous clients, this is typically not required but harmless.


The documentation for this class was generated from the following files: