minihass¶

Module to provide classes and methods to communicate with Home Assistant over MQTT, intended for use with CircuitPython.

class minihass.Device(mqtt_client: MQTT, device_id: str = '', name: str = '', manufacturer: str = '', hw_version: str = '', connections: list[tuple[str, str]] = [], entities: list[Entity] = [], logger_name: str = 'minimqtt')¶

A class representing a Home Assistant device.

A Device represents a physical device with its own control unit, or a service. A CircuitPython-based microcontroller might provide multiple sensors, or expose multiple controls and services to Home Assistant; this would represent one device with multiple entities. In most cases you will only have one Device object, although it it technically possible to create multiple objects in one instance of CircuitPython using this module.

Caution

The MQTT client used to create a Device object must not be connected at the time of instantiation. The devices uses a Last Will and Testament message to mark the device and its entities as unavailable after losing its connection to the MQTT broker, and the LWT is sent as part of the connection process.

Parameters:

mqtt_client (adafruit_minimqtt.adafruit_minimqtt.MQTT) – MMQTT object for communicating with Home Assistant.
device_id (str, optional) – Gloablly unique identifier for the Home Assistant device. Auto-generated if not specified.
name (str, optional) – Device name. Auto-generated if not specified.
manufacturer (str, optional) – Device manufacturer to appear in Home Assistant’s device registry. Defaults to None
hw_version (str, optional) – Device hardware version to appear in Home Assistant’s device registry, Defaults to None
connections (list[tuple(str, str)], optional) – List of tuples of Home Assistant device connections e.g. [('mac', 'de:ad:be:ef:d0:0d')]. Defaults to None.
entities (list[Entity], optional) – List of entity objects to include as part of the device. Defaults to None

device_id¶

Effective Device ID. Either normalized from the device_id parameter, or derived from name

Type:: str

mqtt_client¶

MQTT client.

Type:: adafruit_minimqtt.adafruit_minimqtt.MQTT

connections¶

List of Home Aassistant device connections.

Type:: list[tuple(str, str)]

property entities: list[Entity]¶

A list of Entity objects associated with the device.

This is a read-only property. Modify this property with the add_entity() and delete_entity() methods.

Returns:: List of Entity subclasses.
Return type:: list[Entity]

property availability: bool¶: Availability of the device. Setting this entity to false makes any entities belonging to this device appear as unavailable in Home Assistant. Setting this property triggers publish_availability().

add_entity(entity: Entity) → bool¶

Add an entity to the device

Parameters:

Entity (Entity) – Entity to add.

Returns:

True if the entity was added. False if the entity: is already a member of the device.

Return type:

bool

delete_entity(entity: Entity) → bool¶

Delete an entity from the device

Parameters:

entity (Entity) – Entity to delete.

Returns:

True if the entity is deleted, False if the entity: was not a member of the device

Return type:

bool

announce(clean: bool = False) → bool¶

Send MQTT discovery messages for all device entities.

Used immediately after connnecting to the MQTT broker to configure the corresponding entities in Home Assistant. Individual entities can be announced with their own Entity.announce() methods.

Parameters:: clean (bool, optional) – Remove previously discovered entites that are no longer present. Defaults to False.
Returns:: True if successful.
Return type:: bool

publish_state_queue() → bool¶

Publish any queued states for all device entities

Returns:: True if at least one sensor state was published.
Return type:: bool

publish_availability()¶

Explicitly publishes availability of the device.

This function is called automatically when availability property is changed.

Returns:: True if successful.
Return type:: bool

mqtt_on_connect_cb(mqtt_client, userdata, flags, rc)¶: Callback for the MQTT client’s on_connect attribute. Sends announcement messages for all configured entities, publishes any outstanding entity states, and publishes its own availability as True

class minihass.Entity(*args, name: str = '', entity_category: str = '', device_class: str = '', object_id: str = '', icon: str = '', enabled_by_default: bool = True, mqtt_client: MQTT | None = None, logger_name: str = 'minimqtt', **kwargs)¶

Parent class for child classes representing Home Assistant entities. Cannot be instantiated directly.

Parameters:

name (int, optional) – Entity Name. Can be null if only the device name is relevant. One of name or object_id must be set.
device_class (str, optional) – Device class of the entity. Defaults to None
entity_category (str, optional) – Set to specify DIAGNOSTIC or CONFIG entities.
object_id (str, optional) – Set to generate entity_id from object_id instead of name. One of name or object_id must be set.
icon (str, optional) – Send update events even when the state hasn’t changed, defaults to False
enabled_by_default (bool, optional) – Defines the number of seconds after the sensor’s state expires, if it’s not updated. After expiry, the sensor’s state becomes unavailable. Defaults to False.
mqtt_client (adafruit_minimqtt.adafruit_minimqtt.MQTT, optional) – MMQTT object for communicating with Home Assistant. If the entity is a member of a device, the device’s broker will be used instead.
logger_name (str) – Name for the adafruit_logging.logger used by this object. Defaults to 'minihass'.

property mqtt_client: MQTT¶: Sets or gets the MQTT client for this entity. If this entity is a member of a device, the device MQTT client will be returned.

property availability: bool¶: Availability of the entity. Setting this entity to false makes the entity appear as unavailable in Home Assistant. This may be desired if, for instance, the sensor providing this entity’s state is not initialized or has not yet returned a valid state, or if the hardware that implements commands from Home Assistant is not ready. Setting this property triggers publish_availability().

announce()¶

Send MQTT discovery message for this entity only.

Raises:

ValueError – If the entity or its parent device does not have a valid mqtt_client set.
RuntimeError – If the MQTT client is not connected

withdraw()¶

Send MQTT discovery message to remove this entity.

Raises:

ValueError – If the entity or its parent device does not have a valid mqtt_client set.
RuntimeError – If the MQTT client is not connected

publish_availability()¶

Explicitly publishes availability of the entity.

This function is called automatically when availability property is changed.

Returns:: True if successful.
Return type:: bool

class minihass.SensorEntity(*args, queue='yes', logger_name='minimqtt', **kwargs)¶

Mixin class representing a Home Assistant Entity that publishes states

Parameters:: queue ("yes"|"no"|"always", optional) – Controls state queuing behaviour. If "yes", if publishing to the MQTT broker fails, the message will be queued and can be re-published, by calling the device’s Device.publish_state_queue() method. If "no", unpublished states are not queued, but can still be explicitly published by calling the entity’s publish_state() method. If "always", states are not automatically published and will alawys be queued. Defaults to "yes".

announce()¶

Send MQTT discovery message for this entity only.

Raises:

ValueError – If the entity or its parent device does not have a valid mqtt_client set.
RuntimeError – If the MQTT client is not connected

property availability: bool¶: Availability of the entity. Setting this entity to false makes the entity appear as unavailable in Home Assistant. This may be desired if, for instance, the sensor providing this entity’s state is not initialized or has not yet returned a valid state, or if the hardware that implements commands from Home Assistant is not ready. Setting this property triggers publish_availability().

property mqtt_client: MQTT¶: Sets or gets the MQTT client for this entity. If this entity is a member of a device, the device MQTT client will be returned.

publish_availability()¶

Explicitly publishes availability of the entity.

This function is called automatically when availability property is changed.

Returns:: True if successful.
Return type:: bool

withdraw()¶

Send MQTT discovery message to remove this entity.

Raises:

ValueError – If the entity or its parent device does not have a valid mqtt_client set.
RuntimeError – If the MQTT client is not connected

property state¶: Gets or sets the state of a sensor entity. Setting this parameter calls publish_state()

publish_state()¶

Explicitly publishes state of the entity.

This function is called automatically when state property is changed.

class minihass.BinarySensor(*args, force_update: bool = False, expire_after: int = 0, **kwargs)¶

Class representing a Home Assistant Binary Sensor entity.

Note

A BinarySensor object takes all parameters from both the Entity and SensorEntity classes, as well as the parameters listed below.

Parameters:

force_update (bool, optional) – Specifies whether the entity should be enabled when it is first added, defaults to False.
expire_after (int, optional) – Defines the number of seconds before the sensor’s state expires, if it’s not updated. After expiry, the sensor’s state becomes unavailable. Defaults to 0.

property state¶: Gets or sets the state of a sensor entity. Setting this parameter calls publish_state()

announce()¶

Send MQTT discovery message for this entity only.

Raises:

ValueError – If the entity or its parent device does not have a valid mqtt_client set.
RuntimeError – If the MQTT client is not connected

property availability: bool¶: Availability of the entity. Setting this entity to false makes the entity appear as unavailable in Home Assistant. This may be desired if, for instance, the sensor providing this entity’s state is not initialized or has not yet returned a valid state, or if the hardware that implements commands from Home Assistant is not ready. Setting this property triggers publish_availability().

property mqtt_client: MQTT¶: Sets or gets the MQTT client for this entity. If this entity is a member of a device, the device MQTT client will be returned.

publish_availability()¶

Explicitly publishes availability of the entity.

This function is called automatically when availability property is changed.

Returns:: True if successful.
Return type:: bool

publish_state()¶

Explicitly publishes state of the entity.

This function is called automatically when state property is changed.

withdraw()¶

Send MQTT discovery message to remove this entity.

Raises:

ValueError – If the entity or its parent device does not have a valid mqtt_client set.
RuntimeError – If the MQTT client is not connected