MQTT DiscoveryStream integration for Home Assistant

This is an "extension" of the builtin mqtt_statestream integration and builds on the version by koying.

The integration publishes MQTT Discovery information for the supported entities, publishes any state changes and handles returned commands from the slave home assistant instance.

Supported entities

Provides discovery & command support for:

Entity Type	Entity Created	Commands Supported
Binary Sensor	binary_sensor
Button	button	Press
Climate	climate	Set HVAC Mode, Set Preset Mode, Set Temperature
Cover	cover	Open, Close, Stop, Set Position, Set Tilt Position
Device Tracker	device_tracker
Event	event
Input Boolean	switch	Turn On, Turn Off
Input Button	button	Press
Input Number	number	Set Value
Input Select	select	Select Option
Input Text	text	Set Value
Light	light	Turn On, Turn Off
Number	number	Set Value
Scene	scene	Apply
Sensor	sensor
Select	select	Select Option
Switch	switch	Turn On, Turn Off
Text	text	Set Value

Buy Me A Beer 🍻

I work on this integration because I like things to work well for myself and others. Whilst I have now made significant changes to the integration, it would not be as it stands today without the initial creation by @koying. Please don't feel you are obligated to donate, but of course it is appreciated.

Pre-requisites

1. MQTT configured

Installation

HACS

1. Launch HACS
2. Navigate to the Integrations section
3. Add this repository as an Custom Repository (Integration) via the menu at top right (Only required if you wish to use this forked version).
4. Search for "MQTT DiscoveryStream Alt"
5. Select "Install this repository"
6. Restart Home Assistant

Home Assistant

The integration is configured via YAML only.

Example:

mqtt_discoverystream_alt:
  base_topic: test_HA
  publish_attributes: false
  publish_timestamps: true
  publish_discovery: true
  include:
    entities:
      - sensor.owm_hourly_humidity
      - sensor.jellyfin_cloud
      - light.wled_esp
  exclude:
    entities:
      - sensor.plug_xiaomi_1_electrical_measurement

Configuration

Options

This integration can only be configured via YAML. The base options are the same as the mqtt_statestream one.

key	default	required	description
base_topic	none	yes	Base topic used to generate the actual topic used to publish.
discovery_topic	--->	no	Topic where the configuration topics will be created. Defaults to base_topic
command_topic	--->	no	Topic where any command responses will be created. Defaults to base_topic
publish_attributes	false	no	Publish attributes of the entity as well as the state.
publish_timestamps	false	no	Publish the last_changed and last_updated timestamps for the entity.
publish_discovery	false	no	Publish the discovery topic ("config").
publish_retain	false	no	When set to true publishes messages with retain bit turned on.
unique_prefix	mqtt	no	Prefix applied to the unique id of the created entity
republish_time	5 mins	no	Sets the time between iterations of republishing discovery/state for all entities.
include / exclude	none	no	Configure which integrations should be included / excluded from publishing.
local_status	none	no	See below
remote_status	none	no	See below

local_status

In order for the remote HA instance to be informed when the local HA instance goes offline (and therefore its entities are unavailable), the local HA status needs to be available at the remote broker. By default, at the local end it is located at homeassistant/status, which users will likely rewrite to a different location on the remote broker.

key	default	required	description
topic	none	no	Topic at the slave for master's HA status. Defaults to base_topic + /status.
online_status	online	no	As configured in MQTT integration for master's HA online status.
offline_status	offline	no	As configured in MQTT integration for master's HA offline status.

  local_status:
    topic: master/status
    online_status: online
    offline_status: offline

remote_status

In order for the master HA instance to be informed when the remote HA instance has come online (and therefore that it should resend discovery information), the remote HA status needs to be available at the local broker. By default, at the remote end it is located at homeassistant/status, which users will likely rewrite to a different location on the local broker.

key	default	required	description
topic	none	no	Topic at the master for slave's HA status. Defaults to base_topic + /status.
online_status	online	no	As configured in MQTT integration for slave's HA online status.

  remote_status:
    topic: master/status
    online_status: online

Services

A service called publish_discovery_state is provided when publish_discovery is enabled in the configuration. The service triggers a re-publication of the discovery and current state information for each entity that matches the inclusion/exclusion filter. There are no attributes/parameters for the service.

Topic Handling

• Discovery messages will be published to the discovery_topic when publish_discovery is enabled.
• State messages will be sent to the base_topic.
• Commands from entities at the slave site will be subscribed to on the command_topic.
• Birth messages from the slave site will be subscribed to on the birth_topic, which must end in /status. /status will be added to the topic if missing.

Discovery of entities and Publication of states

Discovery and state messages will be published under 4 situations:

1. Completion of Home Assistant startup
2. Connection of slave broker and receipt of online message at the birth_topic
3. Initiation of publish_discovery_state service
4. First change of state of an entity, where none of the first 3 items has occurred

Flowchart

Startup

sequenceDiagram
participant H as Home Assistant Master
participant I as Integration
participant M as Core/<br/>Master Broker
participant S as Core/<br/>Slave Broker
participant R as Home Assistant Slave
opt
  H->>I: Entity changed state
  I->>M: Publish discovery<br/>(discovery_topic)
  M->>S: Bridge discovery<br/>(homeassistant)
  S->>R: Create entity
  S->>M: Subscribe to state changes (base_topic)
  I->>M: Subscribe to commands (command_topic)
note right of I: Wait 1.5 seconds
  I->>M: Publish state<br/>(base_topic)
  M->>S: Bridge state<br/>(base_topic)
  S->>R: Set state

end
H->>M: Home Assistant Started<br/>(homeassistant/status)
M->>S: Bridge HA Online<br/>(local_topic)
I->>H: Listen for event `homeassistant_started`
H->>I: Event `homeassistant_started`
note right of I: Perform Discovery and State Publication
I->>H: Listen for event `homeassistant_stop`

Loading

Running

sequenceDiagram
participant H as Home Assistant Master
participant I as Integration
participant M as Core/<br/>Master Broker
participant S as Core/<br/>Slave Broker
participant R as Home Assistant Slave
opt
  H->>+I: Entity changed state
  I->>M: Publish state<br/>(base_topic)
  M->>S: Bridge state<br/>(base_topic)
  S->>R: Set state
end

opt
  R->>S: Home Assistant Started<br/>(homeassistant/status)
  S->>M: Bridge HA Online<br/>(remote_topic)
  M->>I: Remote HA Online
note right of I: Perform Discovery and State Publication
end
opt
  R->>S: Command initiated
  S->>S: Publish command<br/>(command_topic)
  S->>M: Bridge command<br/>(command_topic)
  M->>H: Perform command on entity
  H->>I: Entity changed state
  I->>M: Publish state<br/>(base_topic)
  M->>S: Bridge state<br/>(base_topic)
  S->>R: Set state
end
opt
  H->>+I: Service request
note right of I: Perform Discovery and State Publication
  I->>-H: End
end

Loading

Shutdown

sequenceDiagram
participant H as Home Assistant Master
participant I as Integration
participant M as Core/<br/>Master Broker
participant S as Core/<br/>Slave Broker
participant R as Home Assistant Slave
H->>I: Event `homeassistant_stop`
loop
  I->>M: Publish availability offline<br/>(base_topic)
  M->>S: Bridge availability offline<br/>(base_topic)
  S->>R: Mark entity unavailable
end
H->>M: Home Assistant Stopped<br/>(homeassistant/status)
M->>S: Bridge HA Offline<br/>(local_topic)

Loading

Discovery and State Publication

sequenceDiagram
participant H as Home Assistant Master
participant I as Integration
participant M as Core/<br/>Master Broker
participant S as Core/<br/>Slave Broker
participant R as Home Assistant Slave
loop 
  I->>M: Publish discovery<br/>(discovery_topic)
  M->>S: Bridge discovery<br/>(discovery_topic)
  S->>R: Create entity
  S->>M: Subscribe to state changes (base_topic)
  I->>M: Subscribe to commands (command_topic)
end
note right of I: Wait 1.5 seconds
loop 
  I->>M: Publish state<br/>(base_topic)
  M->>S: Bridge state<br/>(base_topic)
  S->>R: Set state
end

Loading

Credits

• This custom component is based upon the mqtt_statestream one from HA Core.
• Extends the capabilties of the mqtt_discoverystream custom integration by koying.