ustd::HomeAssistant Class Reference

#include <home_assistant.h>

Public Types
enum	DeviceType { }
	HomeAssistant Device Type. More...

Public Member Functions
	HomeAssistant (String name, String manufacturer, String model, String version)
void	begin (Scheduler *_pSched, bool initialAutodiscovery=false)
void	setAutoDiscovery (bool enabled)
void	addAttributes (String attribGroup, String manufacturer="", String model="", String version="")
void	addSwitch (String name, String human="", String dev_cla="", String icon="", String attribs="")
void	addSwitch (String name, int channel, String human="", String dev_cla="", String icon="", String attribs="")
void	addMultiSwitch (String name, int count, String human="", String dev_cla="", String icon="", String attribs="")
void	addLight (String name, String human="", DeviceType type=LightDim, String icon="", String attribs="", String effects="")
void	addLight (String name, int channel, String human="", DeviceType type=LightDim, String icon="", String attribs="", String effects="")
void	addMultiLight (String name, int count, String human="", DeviceType type=LightDim, String icon="", String attribs="")
void	addSensor (String name, String value, String human="", String dev_cla="", String unit="", String icon="", String val_tpl="", int exp_aft=-1, bool frc_upd=false, String attribs="")
void	addSensor (String name, String value, int channel, String human="", String dev_cla="", String unit="", String icon="", String val_tpl="", int exp_aft=-1, bool frc_upd=false, String attribs="")
void	addMultiSensor (String name, String value, int count, String human="", String dev_cla="", String unit="", String icon="", String val_tpl="", int exp_aft=-1, bool frc_upd=false, String attribs="")
void	addBinarySensor (String name, String value, String human="", String dev_cla="", String unit="", String icon="", String val_tpl="", int exp_aft=-1, bool frc_upd=false, int off_dly=-1, String attribs="")
void	addBinarySensor (String name, String value, int channel, String human="", String dev_cla="", String unit="", String icon="", String val_tpl="", int exp_aft=-1, bool frc_upd=false, int off_dly=-1, String attribs="")
void	addMultiBinarySensor (String name, String value, int count, String human="", String dev_cla="", String unit="", String icon="", String val_tpl="", int exp_aft=-1, bool frc_upd=false, int off_dly=-1, String attribs="")

Detailed Description

mupplet-core HomeAssistant Device Autodiscovery Helper

This class implements support for the "MQTT Discovery" feature of HomeAssistant. By creating an instance of this class, and by specifiying the affected entites, the device will be able to advertise the exported entites to HomeAsisstant using the specified MWTT messages. (See https://www.home-assistant.io/docs/mqtt/discovery/ for details)

Messages

Incoming Messages

The HomeAssistant helper reacts to the following messages:

Topic	Message Body	Description
ha/state/set	on or off	Enables or disables entity discovery.
ha/state/get		Requests the current entity discovery state.

Outgoing Messages

Topic	Message Body	Description
ha/state	on or off	Current State of the entity discovery
ha/attribs/<attribGroup>	{ ... }	Current entity attributes (See below)

Entity attributes are sent as JSON object and are displayed as attributes to an entity. The HomeAssistant Device Autodiscovery Helper always sends the attribute group device that will contain such data:

{
  "RSSI": "52",
  "Signal (dBm)": "-74",
  "Mac": "84:F3:EB:1A:2F:D8",
  "IP": "192.168.107.241",
  "Host": "test-esp-d1mini-01",
  "Manufacturer": "Starfleet Engineering",
  "Model": "Tricorder Mark VII",
  "Version": "3.14.15"
}

Sample Integration

#define __ESP__ 1   // Platform defines required, see ustd library doc, mainpage.
#include "scheduler.h"
#include "net.h"
#include "mqtt.h"
#include "home_assistant.h"
#include "mup_airq_bme280.h"
#include "mup_light_pca9685.h"
 
ustd::Scheduler sched;
ustd::AirQualityBme280 bme( "bme280", BME280_ADDRESS_ALTERNATE,
                            ustd::AirQualityBme280::SampleMode::MEDIUM );
ustd::LightsPCA9685 panel("panel");
ustd::HomeAssistant ha("Tricorder", "Starfleet Engineering", "Tricorder Mark VII", "3.14.15");
 
void setup() {
    net.begin(&sched);
    ota.begin(&sched);
    mqtt.begin(&sched);
    bme.begin(&sched);
    panel.begin(&sched);
    ha.begin(&sched, true);
 
    ha.addSensor("bme280","temperature");
    ha.addSensor("bme280","humidity");
    ha.addSensor("bme280","pressure");
    ha.addMultiLight("panel", 16);
}

Member Enumeration Documentation

DeviceType

enum ustd::HomeAssistant::DeviceType

HomeAssistant Device Type.

Enumerator
BinarySensor	Sensor reporting numerical or state values.
Switch	Sensor reporting binary states.
Light	A simple device that can only be switched on and off.
LightDim	A simple light that can only be switched on and off.
LightWW	A light that can be dimmed.
LightRGB	A light with light temperature that can be dimmed.
LightRGBW	A color light.
LightRGBWW	A color light with additional white component. A color light with additional white compoenent that can be "tempered"

Constructor & Destructor Documentation

HomeAssistant()

ustd::HomeAssistant::HomeAssistant ( String  name, String  manufacturer, String  model, String  version  )

inline

Instantiate a HomeAssistant Autodiscovery Helper

No interaction is performed, until begin() is called.

Parameters

name	Name of the device
manufacturer	Manufacutrer of the deivce
model	Model of the device
version	Version of the device

Member Function Documentation

addAttributes()

void ustd::HomeAssistant::addAttributes ( String  attribGroup, String  manufacturer = "", String  model = "", String  version = ""  )

inline

Adds a specific attribute group for the device

By adding an attribute group, the device sends a full set of attributes every time the network state changes under the topic ha/attribs/<attribGroup>. The default attribute group 'device' is already defined automatically using the device information supplied in the constructor. Adding additional attribute groups is only useful if specific entities should provide more detailed information about the manufacturer of the hardware and/or the hardware/software revision.

Parameters

attribGroup	Name of the attribute group
manufacturer	(default is the value defined in the constructor). Name of the manufacturer
model	(default is the value defined in the constructor). Name of the model
version	(default is the value defined in the constructor). Software or hardware version information

addBinarySensor() [1/2]

void ustd::HomeAssistant::addBinarySensor ( String  name, String  value, int  channel, String  human = "", String  dev_cla = "", String  unit = "", String  icon = "", String  val_tpl = "", int  exp_aft = -1, bool  frc_upd = false, int  off_dly = -1, String  attribs = ""  )

inline

Adds an entity definition for a binary sensor

This method adds a definition for a specific channel of a multichannel binary sensor entity. HomeAssistant will treat such as device as a "Binary Sensor". Binary Sensors are devices that reports binary values (on or off) like buttons (e.g. Switch), remote controls, etc.

Parameters

name	Unique name of the referenced mupplet
value	Name of the value reported by the mupplet
channel	Number of the channel
human	Optional human readable name for HomeAssistant entity
dev_cla	Optional device class for the sensor (See: https://www.home-assistant.io/integrations/binary_sensor/)
unit	Optional alternative unit for the reported data
icon	Optional alternative icon
val_tpl	Optional value template to extract the value
exp_aft	Optional expiration time in seconds after which the value expires
frc_upd	If true the value update will be notified also if the value was not changed
off_dly	Optional delay in seconds after which the sensor’s state will be updated back to off
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

addBinarySensor() [2/2]

void ustd::HomeAssistant::addBinarySensor ( String  name, String  value, String  human = "", String  dev_cla = "", String  unit = "", String  icon = "", String  val_tpl = "", int  exp_aft = -1, bool  frc_upd = false, int  off_dly = -1, String  attribs = ""  )

inline

Adds an entity definition for a binary sensor

This method adds a definition for a binary sensor entity. HomeAssistant will treat such as device as a "Binary Sensor". Binary Sensors are devices that reports binary values (on or off) like buttons (e.g. Switch), remote controls, etc.

Parameters

name	Unique name of the referenced mupplet
value	Name of the value reported by the mupplet
human	Optional human readable name for HomeAssistant entity
dev_cla	Optional device class for the sensor (See: https://www.home-assistant.io/integrations/binary_sensor/)
unit	Optional alternative unit for the reported data
icon	Optional alternative icon
val_tpl	Optional value template to extract the value
exp_aft	Optional expiration time in seconds after which the value expires
frc_upd	If true the value update will be notified also if the value was not changed
off_dly	Optional delay in seconds after which the sensor’s state will be updated back to off
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

addLight() [1/2]

void ustd::HomeAssistant::addLight ( String  name, int  channel, String  human = "", DeviceType  type = LightDim, String  icon = "", String  attribs = "", String  effects = ""  )

inline

Adds an entity definition for a light entity

This method adds a definition for a specific channel of a multichannel light entity. HomeAssistant will treat such a device as a "Light". Lights are devices that support multiple operating modes like Light or LightsPCA9685 (See: https://www.home-assistant.io/integrations/light/)

Parameters

name	Unique name of the referenced mupplet
channel	Number of the channel
human	Optional human readable name for HomeAssistant entity
type	Optional type of light (default: LightDim)
icon	Optional alternative icon
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)
effects	Optional string containing a comma-separated list of special effect names

addLight() [2/2]

void ustd::HomeAssistant::addLight ( String  name, String  human = "", DeviceType  type = LightDim, String  icon = "", String  attribs = "", String  effects = ""  )

inline

Adds an entity definition for a light entity

This method adds a definition for light entity. HomeAssistant will treat such a device as a "Light". Lights are devices that support multiple operating modes like Light or LightsPCA9685 (See: https://www.home-assistant.io/integrations/light/)

Parameters

name	Unique name of the referenced mupplet
human	Optional human readable name for HomeAssistant entity
type	Optional type of light (default: LightDim)
icon	Optional alternative icon
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)
effects	Optional string containing a comma-separated list of special effect names

addMultiBinarySensor()

void ustd::HomeAssistant::addMultiBinarySensor ( String  name, String  value, int  count, String  human = "", String  dev_cla = "", String  unit = "", String  icon = "", String  val_tpl = "", int  exp_aft = -1, bool  frc_upd = false, int  off_dly = -1, String  attribs = ""  )

inline

Adds entity definitions for multiple binary sensors

This method adds a definition for all channels of a multichannel binary sensor entity. HomeAssistant will treat such as device as a "Binary Sensor". Binary Sensors are devices that reports binary values (on or off) like buttons (e.g. Switch), remote controls, etc.

Parameters

name	Unique name of the referenced mupplet
value	Name of the value reported by the mupplet
count	Number of channels of the referenced mupplet
human	Optional human readable name for HomeAssistant entity
dev_cla	Optional device class for the sensor (See: https://www.home-assistant.io/integrations/binary_sensor/)
unit	Optional alternative unit for the reported data
icon	Optional alternative icon
val_tpl	Optional value template to extract the value
exp_aft	Optional expiration time in seconds after which the value expires
frc_upd	If true the value update will be notified also if the value was not changed
off_dly	Optional delay in seconds after which the sensor’s state will be updated back to off
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

addMultiLight()

void ustd::HomeAssistant::addMultiLight ( String  name, int  count, String  human = "", DeviceType  type = LightDim, String  icon = "", String  attribs = ""  )

inline

Adds entity definitions for multiple light entities

This method adds a definition for all channels of a multichannel light entity. HomeAssistant will treat such a device as a "Light". Lights are devices that support multiple operating modes like Light or LightsPCA9685 (See: https://www.home-assistant.io/integrations/light/)

Parameters

name	Unique name of the referenced mupplet
count	Number of channels of the referenced mupplet
human	Optional human readable name for HomeAssistant entity
type	Optional type of light (default: LightDim)
icon	Optional alternative icon
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

addMultiSensor()

void ustd::HomeAssistant::addMultiSensor ( String  name, String  value, int  count, String  human = "", String  dev_cla = "", String  unit = "", String  icon = "", String  val_tpl = "", int  exp_aft = -1, bool  frc_upd = false, String  attribs = ""  )

inline

Adds entity definitions for a multiple sensors

This method adds a definition for all channels of a multichannel sensor entity. HomeAssistant will treat such as device as a "Sensor". Sensors are devices that reports any kind of values like thermometers or similar.

Parameters

name	Unique name of the referenced mupplet
value	Name of the value reported by the mupplet
count	Number of channels of the referenced mupplet
human	Optional human readable name for HomeAssistant entity
dev_cla	Optional device class for the sensor (See: https://www.home-assistant.io/integrations/sensor/)
unit	Optional alternative unit for the reported data
icon	Optional alternative icon
val_tpl	Optional value template to extract the value
exp_aft	Optional expiration time in seconds after which the value expires
frc_upd	If true the value update will be notified also if the value was not changed
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

addMultiSwitch()

void ustd::HomeAssistant::addMultiSwitch ( String  name, int  count, String  human = "", String  dev_cla = "", String  icon = "", String  attribs = ""  )

inline

Adds entity definitions for multiple switchable entities

This method adds definitions for all channels of a multichannel switchable entity. HomeAssistant will treat such as device as a "Switch". Switches are devices that can be switched on or off like DigitalOut.

Parameters

name	Unique name of the referenced mupplet
count	Number of channels of the referenced mupplet
human	Optional human readable name for HomeAssistant entity
dev_cla	Optional device class for the switch (See: https://www.home-assistant.io/integrations/switch/)
icon	Optional alternative icon
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

addSensor() [1/2]

void ustd::HomeAssistant::addSensor ( String  name, String  value, int  channel, String  human = "", String  dev_cla = "", String  unit = "", String  icon = "", String  val_tpl = "", int  exp_aft = -1, bool  frc_upd = false, String  attribs = ""  )

inline

Adds an entity definition for asensor

This method adds a definition for a specific channel of a multichannel sensor entity. HomeAssistant will treat such as device as a "Sensor". Sensors are devices that reports any kind of values like thermometers or similar.

Parameters

name	Unique name of the referenced mupplet
value	Name of the value reported by the mupplet
channel	Number of the channel
human	Optional human readable name for HomeAssistant entity
dev_cla	Optional device class for the sensor (See: https://www.home-assistant.io/integrations/sensor/)
unit	Optional alternative unit for the reported data
icon	Optional alternative icon
val_tpl	Optional value template to extract the value
exp_aft	Optional expiration time in seconds after which the value expires
frc_upd	If true the value update will be notified also if the value was not changed
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

addSensor() [2/2]

void ustd::HomeAssistant::addSensor ( String  name, String  value, String  human = "", String  dev_cla = "", String  unit = "", String  icon = "", String  val_tpl = "", int  exp_aft = -1, bool  frc_upd = false, String  attribs = ""  )

inline

Adds an entity definition for a sensor

This method adds a definition for a sensor entity. HomeAssistant will treat such as device as a "Sensor". Sensors are devices that reports any kind of values like thermometers or similar.

Parameters

name	Unique name of the referenced mupplet
value	Name of the value reported by the mupplet
human	Optional human readable name for HomeAssistant entity
dev_cla	Optional device class for the sensor (See: https://www.home-assistant.io/integrations/sensor/)
unit	Optional alternative unit for the reported data
icon	Optional alternative icon
val_tpl	Optional value template to extract the value
exp_aft	Optional expiration time in seconds after which the value expires
frc_upd	If true the value update will be notified also if the value was not changed
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

addSwitch() [1/2]

void ustd::HomeAssistant::addSwitch ( String  name, int  channel, String  human = "", String  dev_cla = "", String  icon = "", String  attribs = ""  )

inline

Adds an entity definition for a switchable entity

This method adds a definition for a specific channel of a multichannel switchable entity. HomeAssistant will treat such as device as a "Switch". Switches are devices that can be switched on or off like DigitalOut.

Parameters

name	Unique name of the referenced mupplet
channel	Number of the channel
human	Optional human readable name for HomeAssistant entity
dev_cla	Optional device class for the switch (See: https://www.home-assistant.io/integrations/switch/)
icon	Optional alternative icon
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

addSwitch() [2/2]

void ustd::HomeAssistant::addSwitch ( String  name, String  human = "", String  dev_cla = "", String  icon = "", String  attribs = ""  )

inline

Adds an entity definition for a switchable entity

This method adds a definition for a switchable entity. HomeAssistant will treat such as device as a "Switch". Switches are devices that can be switched on or off like DigitalOut.

Parameters

name	Unique name of the referenced mupplet
human	Optional human readable name for HomeAssistant entity
dev_cla	Optional device class for the switch (See: https://www.home-assistant.io/integrations/switch/)
icon	Optional alternative icon
attribs	Optional alternative attribute group (by default all entities reference the "device" attributes group)

begin()

void ustd::HomeAssistant::begin ( Scheduler *  _pSched, bool  initialAutodiscovery = false  )

inline

Initialize the HomeAssistant discovery helper and start operation

Parameters

_pSched	Pointer to a muwerk scheduler object, used to create worker tasks and for message pub/sub.
initialAutodiscovery	Initial state of the HomeAssistant Autodiscovery Helper if not already saved into the filesystem.

setAutoDiscovery()

void ustd::HomeAssistant::setAutoDiscovery ( bool  enabled )

inline

Activates or deactivates HomeAssistant MQTT discovery

Parameters

enabled

true if devices shall be advertised to HomeAssistant, false if not

---

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

• src/home_assistant.h