Device

class nirahmq.device.Device[source]

Bases: object

A wrapper class for a Home Assistant device.

The class stores an instance of an nirahmq.mqtt.MQTTClient and DiscoveryInfo. At initialization, they are configured, command topics are subscribed to and callbacks are registered. At runtime, availability and dynamic component addition and removal are managed automatically.

Tip

The class can be used as a dictionary proxy to the provided DiscoveryInfo.components attribute.

__init__(mqtt_client: MQTTClient, discovery_info: DiscoveryInfo, node_id: str | None = None, discovery_prefix: str = 'homeassistant', state_prefix: str = 'nirahmq', use_status: bool = False, remove_on_exit: bool = False, status_callback: ComponentCallback[Device] | None = None) → None[source]

Initialize the Home Assistant device wrapper.

Parameters:

  • mqtt_client (MQTTClient) – The MQTT client instance to use

  • discovery_info (DiscoveryInfo) – The Home Assistant device discovery information

  • node_id (str | None) – The node_id to use in MQTT topics

  • discovery_prefix (str) – The MQTT topic prefix Home Assistant uses for discovery

  • state_prefix (str) – The MQTT topic prefix to use for state and command topics

  • use_status (bool) – Use availability

  • remove_on_exit (bool) – Remove device on disconnect

  • status_callback (ComponentCallback['Device'] | None) – The callback to call when Home Assistant publishes and availability message

Tip

Set the node_id when using multiple devices to group them together for better organization.

announce() → None[source]

Send the Home Assistant discovery message.

component_register(name: str, component: ComponentBase, announce: bool = True) → None[source]

Register a new component with Home Assistant.

Parameters:

  • name (str) – The internal name of the component to use

  • component (ComponentBase) – The component to register

  • announce (bool) – Whether to announce the registration

Raises:

ValueError – If the component with the specified name is already registered

remove() → None[source]

Remove the device from Home Assistant and cleanup leftover topics.

remove_component(name: str, announce: bool = True) → None[source]

Unregister a component from Home Assistant.

Parameters:

  • name (str) – The internal name of the component

  • announce (bool) – Whether to announce the deregistration

Raises:

ValueError – If the component with the specified name isn’t registered

set_availability(state: bool) → None[source]

Set device availability state.

Only works if use_status was set to True in Device constructor.

Parameters:

state (bool) – The availability state

class nirahmq.device.DeviceInfo[source]

Bases: BaseModel

Dataclass that stores information about a Home Assistant device.

configuration_url: str
connections: Annotated[list[tuple[str, str]], Len(min_length=1, max_length=None)]
hw_version: str
identifiers: str | Annotated[list[str], Len(min_length=1, max_length=None)]
manufacturer: str
model: str
model_id: str
name: str
serial_number: str
suggested_area: str
sw_version: str
property unique_id: str[source]
use_hash: bool
via_device: str
class nirahmq.device.DiscoveryInfo[source]

Bases: Availability

Dataclass that stores the discovery info used for Home Assistant device discovery.

command_topic: CommandTopic
components: dict[str, Annotated[ComponentBase, SerializeAsAny()]]
device: DeviceInfo
encoding: str
origin: OriginInfo
qos: QoS
state_topic: StateTopic
class nirahmq.device.OriginInfo[source]

Bases: BaseModel

Dataclass that stores the Home Assistant device origin information.

name: str
support_url: str
sw_version: str