MQTT for Home Assistant (built-in integration)

About

MQTT is a built-in integration that connects Home Assistant to an MQTT broker and works locally. It supports many entity platforms, including sensors, switches, lights-style controls such as fans and covers, climate, cameras, locks and vacuums. New devices can show up through automatic discovery, which uses a configurable topic prefix. Birth and will messages can be set with their own topic, payload, quality of service and retain options. The connection supports username and password login, custom CA certificates, client certificates, a choice of transport and a keep alive interval. Actions publish a message to a topic, export messages from a topic to a file, and reload entities defined in YAML. It is set up in the UI, and its connection settings can be changed later.

Automatic summary of Home Assistant's source code. Something wrong? Get in touch

Supports

Works locally Talks to your devices on your own network. No vendor cloud in between.
Set up in the UI Add it in Settings, Devices and services. Nothing to download.
Device triggers Its devices can start automations directly.
Adds new devices New devices show up without setting it up again.
Change settings later Its connection settings can change without removing it.
Platinum quality Home Assistant's own rating of its code and setup experience.
Updated with Home Assistant Ships and updates with every Home Assistant release.

Provides

Climate
Water heaters
Humidifiers
Fans
Covers
Valves
Cameras
Locks
Alarms
Vacuums
Switches
Sensors
Presence

Setting it up

It is added under Settings, Devices and services, with Add integration.

Broker

BrokerThe hostname or IP address of your MQTT broker.
PasswordThe password to log in to your MQTT broker.
PortThe port your MQTT broker listens to. For example 1883.
MQTT protocolThe MQTT protocol version that is used. Note that Home Assistant will silently change to version 5 if your broker supports it.
UsernameThe username to log in to your MQTT broker.
Upload custom CA certificate fileThe custom CA certificate file to validate your MQTT broker's certificate.
Upload client certificate fileThe client certificate to authenticate against your MQTT broker.
Client ID (leave empty for a randomly generated one)The unique ID to identify the Home Assistant MQTT API as MQTT client. It is recommended to leave this option blank.
Upload private key fileThe private key file that belongs to your client certificate.
PasswordThe password for the private key file (if set).
The time between sending keep alive messagesA value less than 90 seconds is advised. Defaults to 60 seconds.
Broker certificate validationWhen already set to Custom, a custom CA validation certificate is configured. Select Auto for automatic CA validation, or upload a custom CA certificate, to allow validating your MQTT broker's certificate.
Use a client certificateWhen already selected, client certificate authentication is enabled. Upload a client certificate and key to enable.
Ignore broker certificate validationOption to ignore validation of your MQTT broker's certificate.
MQTT transportThe transport to be used for the connection to your MQTT broker.

Re-authentication required with the MQTT broker

PasswordThe password to log in to your MQTT broker.
UsernameThe username to log in to your MQTT broker.

After setup

Enable birth messageWhen set, Home Assistant will publish an online message to your MQTT broker when MQTT is ready.
Birth message payloadThe "birth" message that is published when MQTT is ready and connected.
Birth message QoSThe quality of service of the "birth" message that is published when MQTT is ready and connected
Birth message retainWhen set, Home Assistant will retain the "birth" message published to your MQTT broker.
Birth message topicThe MQTT topic where Home Assistant will publish a "birth" message.
Enable discoveryOption to enable MQTT automatic discovery.
Discovery prefixThe prefix of configuration topics the MQTT integration will subscribe to.
Discovery QoSThe quality of service for discovery subscriptions to your MQTT broker.
Enable will messageWhen set, Home Assistant will ask your broker to publish a "will" message when MQTT is stopped or when it loses the connection to your broker.
Will message payloadThe message your MQTT broker "will" publish when the MQTT integration is stopped or when the connection is lost.
Will message QoSThe quality of service of the "will" message that is published by your MQTT broker.
Will message retainWhen set, your MQTT broker will retain the "will" message.
Will message topicThe MQTT topic your MQTT broker will publish a "will" message to.

Texts from Home Assistant's source code, Apache License 2.0.

Actions

ExportWrites all messages on a specific topic into the mqtt_dump.txt file in your configuration folder.Fields: Duration, Topic
PublishPublishes a message to an MQTT topic.Fields: Evaluate payload, Message Expiry Interval, Payload, QoS, Retain, Topic
ReloadReloads MQTT entities from the YAML-configuration.

Troubleshooting

DiagnosticsDownloads a diagnostics file to attach to a bug report.
Repair noticesNotices it can show in Settings, Repairs:MQTT protocol migration failed, MQTT is not set up correctly