Class HaEntity<TConfig>

Namespace

HaMqttDiscoverable.Entities

Assembly

HaMqttDiscoverable.dll

Base class for every discoverable entity. Handles building the MQTT topics, publishing the Home Assistant discovery payload, publishing state, and (for entities that accept commands) subscribing to the command topic.

public abstract class HaEntity<TConfig> : IAsyncDisposable where TConfig : EntityConfig

Type Parameters

TConfig

Inheritance

object

HaEntity<TConfig>

Implements

IAsyncDisposable

Derived

AlarmControlPanel

BinarySensor

Button

Camera

Climate

Cover

Date

DateTimeEntity

DeviceTracker

Event

Fan

Humidifier

Image

LawnMower

Light

LockEntity

Notify

Number

Scene

Select

Sensor

Siren

Switch

Text

Time

Update

Vacuum

Valve

WaterHeater

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

HaEntity(HaMqttConnection, TConfig)

Computes this entity's MQTT topics from its config. Call PublishDiscoveryAsync(CancellationToken) to make it visible to Home Assistant.

protected HaEntity(HaMqttConnection connection, TConfig config)

Parameters

connection HaMqttConnection

config TConfig

Properties

BaseTopic

The common MQTT topic prefix this entity's topics are built from ({prefix}/{component}/{device}/{object}, with no trailing segment). Exposed so subclasses that need extra topics beyond StateTopic/CommandTopic (e.g. a cover's tilt topics) can build their own from the same root instead of hand-rolling it.

protected string BaseTopic { get; }

Property Value

string

CommandTopic

The topic this entity listens on for commands from Home Assistant, or null if it doesn't accept commands.

public string? CommandTopic { get; }

Property Value

string

Config

The configuration this entity was created with.

public TConfig Config { get; }

Property Value

TConfig

Connection

The MQTT connection this entity publishes through.

protected HaMqttConnection Connection { get; }

Property Value

HaMqttConnection

DiscoveryTopic

The retained topic Home Assistant reads the discovery payload from.

public string DiscoveryTopic { get; }

Property Value

string

HasStateTopic

Whether this entity type reports a state at all. Stateless entities like Button override this to false.

protected virtual bool HasStateTopic { get; }

Property Value

bool

StateTopic

The topic this entity publishes its state to.

public string StateTopic { get; }

Property Value

string

SupportsCommands

Whether this entity type accepts commands from Home Assistant (e.g. switches, numbers). Sensors are read-only and return false.

protected virtual bool SupportsCommands { get; }

Property Value

bool

Methods

DisposeAsync()

Unsubscribes from the command topic, if subscribed. Does not remove the entity from Home Assistant - call RemoveAsync(CancellationToken) for that.

public virtual ValueTask DisposeAsync()

Returns

ValueTask

EnrichDiscoveryPayload(JsonObject)

Allows subclasses to add fields to the discovery payload that aren't part of EntityConfig directly.

protected virtual void EnrichDiscoveryPayload(JsonObject payload)

Parameters

payload JsonObject

OnCommandReceivedAsync(string)

Called with the raw payload every time a message arrives on CommandTopic. Overridden by controllable entity types.

protected virtual Task OnCommandReceivedAsync(string payload)

Parameters

payload string

Returns

Task

PublishDiscoveryAsync(CancellationToken)

Publishes the Home Assistant MQTT discovery payload for this entity (retained), and subscribes to its command topic if it accepts commands. Call this once after constructing the entity and connecting to the broker; call it again any time you change Config to update Home Assistant's copy.

public virtual Task PublishDiscoveryAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task

PublishStateAsync(string, bool, CancellationToken)

Publishes a raw state payload to StateTopic.

public Task PublishStateAsync(string state, bool retain = true, CancellationToken cancellationToken = default)

Parameters

state string

retain bool

cancellationToken CancellationToken

Returns

Task

PublishStateAsync<TState>(TState, bool, CancellationToken)

Serializes state to JSON and publishes it to StateTopic. Useful for entities with a JSON state schema.

public Task PublishStateAsync<TState>(TState state, bool retain = true, CancellationToken cancellationToken = default)

Parameters

state TState

retain bool

cancellationToken CancellationToken

Returns

Task

Type Parameters

TState

RegisterAuxiliaryCommandTopic(string, Func<string, Task>)

Registers an additional MQTT topic this entity should subscribe to for commands, beyond its primary CommandTopic. Used by entities with more than one independently controllable feature (e.g. a cover's position, or a climate device's fan mode). Call this from the constructor - subscription happens when PublishDiscoveryAsync(CancellationToken) is called.

protected void RegisterAuxiliaryCommandTopic(string topic, Func<string, Task> handler)

Parameters

topic string

handler Func<string, Task>

RemoveAsync(CancellationToken)

Removes this entity from Home Assistant by publishing an empty retained payload to its discovery topic, and unsubscribes from its command topic.

public virtual Task RemoveAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task