🕷️ Crawler Inspector

URL Lookup

Direct Parameter Lookup

Raw Queries and Responses

1. Shard Calculation

Query:

Response:

Calculated Shard: 77 (from laksa023)

2. Crawled Status Check

Query:

curl -X POST \
  'http://laksa077.int.ahrefs:8124/' \
  -H 'Content-Type: text/plain' \
  -H 'X-ClickHouse-Database: crawler3' \
  -H 'Authorization: Basic YXBpOg==' \
  -d 'SELECT getAhrefsURLFromUnparsed(src_unparsed) AS found_url, ifNull(toUnixTimestamp(download_stamp), 0) AS crawl_time, ifNull(toUnixTimestamp(props_url_first_seen), 0) AS first_indexed_time, download_http_code AS http_code, src_unparsed AS src_unparsed, src_root_hash AS src_root_hash, history_drop_reason AS history_drop_reason, meta_title AS meta_title, meta_descriptions AS meta_descriptions, attrs_boilerpipe_text AS attrs_boilerpipe_text, attrs_markdown AS attrs_markdown, attrs_readable_markdown AS attrs_readable_markdown, meta_canonical AS meta_canonical FROM crawler3.page_info_local FINAL PREWHERE (src_root_hash, src_unparsed) IN ((getAhrefsRootHashFromUnparsed(getAhrefsUnparsedNoserviceFromURL(\'https://www.home-assistant.io/integrations/mqtt/\')), getAhrefsUnparsedNoserviceFromURL(\'https://www.home-assistant.io/integrations/mqtt/\'))) FORMAT JSONEachRow'

Response:

{"found_url":"https:\/\/www.home-assistant.io\/integrations\/mqtt\/","crawl_time":1775871354,"first_indexed_time":1569976917,"http_code":200,"src_unparsed":"io,home-assistant!www,\/integrations\/mqtt\/ s443","src_root_hash":"6959518072785130877","history_drop_reason":null,"meta_title":"MQTT - Home Assistant","meta_descriptions":["Instructions on how to setup MQTT within Home Assistant."],"attrs_boilerpipe_text":"MQTT (aka MQ Telemetry Transport) is a machine-to-machine or “Internet of Things” connectivity protocol on top of TCP\/IP. It allows extremely lightweight publish\/subscribe messaging transport.\nConfiguration\nTo add the\nMQTT\nservice to your Home Assistant instance, use this My button:\nManual configuration steps\nIf the above My button doesn’t work, you can also perform the following steps\nmanually:\nBrowse to your Home Assistant instance.\nGo to\nSettings > Devices & services\n.\nIn the bottom right corner, select the\nAdd Integration\nbutton.\nFrom the list, select\nMQTT\n.\nFollow the instructions on screen to complete the setup.\nMQTT devices and entities can be set up through\nMQTT discovery\nor\nadded manually\nvia YAML or subentries.\nConfiguration of MQTT components via MQTT discovery\nConfiguration of MQTT components via YAML\nYour first step to get MQTT and Home Assistant working is to choose a broker.\nThe easiest option is to install the official Mosquitto Broker app for Home Assistant (formerly known as Mosquitto Broker add-on). You can choose to set up and configure this app automatically when you set up the MQTT integration. Home Assistant will automatically generate and assign a safe username and password, and no further attention is required. This also works if you have already set up this app yourself in advance.\nYou can set up additional logins for your MQTT devices and services using the\nMosquitto app configuration\n.\nImportant\nWhen MQTT is set up with the official Mosquitto MQTT broker app, the broker’s credentials are generated and kept secret. If the official Mosquitto MQTT broker needs to be re-installed, make sure you save a copy of the app user options, like the additional logins. After re-installing the app, the MQTT integration will automatically update the new password for the re-installed broker. It will then reconnect automatically.\nAlternatively, you can use a different MQTT broker that you configure yourself, ensuring it is compatible with Home Assistant.\nSetting up a broker\nWhile public MQTT brokers are available, the easiest and most private option is running your own.\nThe recommended setup method is to use the\nMosquitto MQTT broker app\n.\nWarning\nNeither ActiveMQ MQTT broker nor the RabbitMQ MQTT Plugin are supported, use a known working broker like Mosquitto instead.\nThere are\nat least two\nissues\nwith the ActiveMQ MQTT broker which break MQTT message retention.\nBroker configuration\nMQTT broker settings are configured when the MQTT integration is first set up and can be changed later if needed.\nAdd the MQTT integration, then provide your broker’s hostname (or IP address) and port and (if required) the username and password that Home Assistant should use. To change the settings later, follow these steps:\nGo to\nSettings > Devices & services\n.\nSelect the MQTT integration.\nReconfigure the MQTT broker settings via\nSettings\n>\nDevices & services\n, select\n, and select\nReconfigure\n.\nMQTT subentries can also be reconfigured. Additional entities can be added, or an entity can be removed from the sub entry. Each MQTT subentry holds one MQTT device. The MQTT device must have at least one entity.\nImportant\nIf you experience an error message like\nFailed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed\n, then turn on\nAdvanced options\nand set\nBroker certificate validation\nto\nAuto\n.\nAdvanced broker configuration\nAdvanced broker configuration options include setting a custom client ID, setting a client certificate and key for authentication, and enabling TLS validation of the broker’s certificate for secure connection. To access the advanced settings, open the MQTT broker settings, switch on\nAdvanced options\n, and select\nNext\n. The advanced options will be shown by default if there are advanced settings active already.\nTip\nAdvanced broker options are accessible only when advanced mode is enabled (see user settings), or when advanced broker settings are configured already.\nAlternative client ID\nYou can set a custom MQTT client ID, this can help when debugging. Mind that the client ID must be unique. Leave this settings default if you want Home Assistant to generate a unique ID.\nKeep alive\nThe time in seconds between sending keep alive messages for this client. The default is 60 seconds. The keep alive setting should be at least 15 seconds.\nBroker certificate validation\nTo enable a secure connection to the broker, the broker certificate should be validated. If your broker uses a trusted certificate, then choose\nAuto\n. This validates the broker certificate against the bundled certificate authority (CA) certificates. If a self-signed certificate is used, select\nCustom\n. A custom PEM- or DER-encoded CA certificate can be uploaded. Select\nNext\nto show the control to upload the CA certificate.\nIf the server certificate does not match the hostname then validation will fail. To allow a connection without the verification of the hostname, turn the\nIgnore broker certificate validation\nswitch on.\nMQTT Protocol\nThe MQTT protocol setting defaults to version\n3.1.1\n. If your MQTT broker supports MQTT version 5 you can set the protocol setting to\n5\n.\nSecuring the connection\nWith a secure broker connection, it is possible to use a client certificate for authentication. To set the client certificate and private key, turn on the option\nUse a client certificate\nand select\nNext\nto reveal file upload controls. A client certificate and the corresponding private key must be uploaded together. Both client certificate and private key must be either PEM- or DER-encoded. If the private key is encrypted with a password, ensure you supply the correct password when uploading the client certificate and key files.\nUsing WebSockets as transport\nYou can select\nwebsockets\nas the transport method if your MQTT broker supports it. When you select\nwebsockets\nand select\nNext\n, you will be able to add a WebSockets path (default is\n\/\n) and WebSockets headers (optional). The target WebSockets URI\nws:\/\/{broker}:{port}{ws_path}\nis built with the\nbroker\n,\nport\n, and\nws_path\n(WebSocket path) settings.\nTo configure the WebSocket’s headers, supply a valid JSON dictionary string. For example,\n{ \"Authorization\": \"token\" , \"x-header\": \"some header\"}\n. The default transport method is\ntcp\n. The WebSockets transport can be secured using TLS and optionally using user credentials or a client certificate.\nNote\nA configured client certificate will only be active if broker certificate validation is enabled.\nConfigure MQTT options\nTo change the options, follow these steps:\nGo to\nSettings > Devices & services\n.\nSelect the MQTT integration.\nSelect\nConfigure\n, then\nRe-configure MQTT\n.\nTo open the MQTT options page, select\nNext\n.\nChange MQTT discovery options\nThe MQTT discovery options can be changed by following these steps:\nGo to\nSettings\n>\nDevices & services\n.\nFind the MQTT integration and select it.\nTo open the MQTT discovery options page, select the\nConfigure MQTT Options\nbutton.\nDiscovery options\nMQTT discovery is enabled by default. Discovery can be turned off. The prefix for the discovery topic (default\nhomeassistant\n) can be changed here as well.\nSee also\nMQTT Discovery section\nBirth and last will messages\nHome Assistant’s MQTT integration supports so-called Birth and Last Will and Testament (LWT) messages. The former is used to send a message after the service has started, and the latter is used to notify other clients about a disconnected client. Note that the LWT message will be sent both in case of a clean disconnect (for example, Home Assistant shutting down) and in case of an unclean disconnect (for example, Home Assistant crashing or losing its network connection).\nIf a disabled entity is enabled and added after 30 seconds, the MQTT integration will be reloaded and will cause all discovered MQTT entities to be unloaded.\nWhen MQTT starts up, all existing MQTT devices, entities, tags, and device triggers, will be unavailable until a discovery message is received and processed. A device or service that exposes the MQTT discovery should subscribe to the Birth message and use this as a trigger to send the\ndiscovery payload\n. To avoid high IO loads on the MQTT broker, adding some random delay in sending the discovery payload is recommended.\nAlternative approaches:\nRetaining the\ndiscovery payload\n: This will store the discovery payload at the MQTT broker, and offer it to the MQTT integration as soon as it subscribes for MQTT discovery. When there are a lot of entities, this can cause high IO loads.\nPeriodically resending the discovery payload: This can cause some delay, or a lot of IO if there are a lot of MQTT discovery messages.\nBy default, Home Assistant sends\nonline\nand\noffline\nto\nhomeassistant\/status\n.\nMQTT Birth and Last Will messages can be customized or disabled from the UI. To do this, select\nConfigure\non the integration page in the UI, then\nRe-configure MQTT\n, and then\nNext\n.\nTesting your setup\nThe\nmosquitto\nbroker package ships command line tools (often as\n*-clients\npackage) to send and receive MQTT messages. For sending test messages to a broker running on\nlocalhost\n, you can use\nmosquitto_pub\n, check the example below:\nmosquitto_pub -h\n127.0\n.0.1 -t homeassistant\/switch\/1\/on -m\n\"Switch is ON\"\nBash\nAnother way to send MQTT messages manually is to use the\nMQTT\nintegration in the frontend. Select\nSettings\non the left menu, select\nDevices & services\n, and select\nConfigure\nin the\nMosquitto broker\ntile. Enter something similar to the example below into the\ntopic\nfield under\nPublish a packet\nand select\nPublish\n.\nGo to\nSettings > Devices & services\n.\nSelect the Mosquitto broker integration, then select\nConfigure\n.\nEnter something similar to the example below into the\ntopic\nfield under\nPublish a packet\n. Select\nPublish\n.\nhomeassistant\/switch\/1\/power\nBash\nand in the Payload field\nON\nBash\nIn the\nListen to a topic\nfield, type\n#\nto see everything, or\nhomeassistant\/switch\/#\nto just follow a published topic, then select\nStart listening\n. The messages should appear similar to the text below:\nMessage\n23\nreceived on homeassistant\/switch\/1\/power\/stat\/POWER at\n12\n:16 PM:\nON\nQoS:\n0\n- Retain:\nfalse\nMessage\n22\nreceived on homeassistant\/switch\/1\/power\/stat\/RESULT at\n12\n:16 PM:\n{\n\"POWER\"\n:\n\"ON\"\n}\nQoS:\n0\n- Retain:\nfalse\nBash\nFor reading all messages sent on the topic\nhomeassistant\nto a broker running on localhost:\nmosquitto_sub -h\n127.0\n.0.1 -v -t\n\"homeassistant\/#\"\nBash\nNaming of MQTT Entities\nFor every configured MQTT entity Home Assistant automatically assigns a unique\nentity_id\n. If the\nunique_id\noption is configured, you can change the\nentity_id\nafter creation, and the changes are stored in the Entity Registry. The\nentity_id\nis generated when an item is loaded the first time.\nIf the\ndefault_entity_id\noption is set, then this will be used to generate the\nentity_id\n.\nIf, for example, we have configured a\nsensor\n, and we have set\ndefault_entity_id\nto\nsensor.test\n, then Home Assistant will try to assign\nsensor.test\nas\nentity_id\n. If\nsensor.test\nalready exists, Home Assistant will append a suffix to make it unique, for example,\nsensor.test_2\n.\nThis means any MQTT entity which is part of a device will\nautomatically have its\nfriendly_name\nattribute prefixed with the device name\nUnnamed\nbinary_sensor\n,\nbutton\n,\nnumber\n, and\nsensor\nentities will now be named by their device class instead of being named “MQTT binary sensor” and similar.\nIt’s allowed to set an MQTT entity’s name to\nNone\n(use\nnull\nin YAML) to mark it as the main feature of a device.\nNote that on each MQTT entity, the\nhas_entity_name\nattribute will be set to\nTrue\n. More details\ncan be found here\n.\nGrouping entities\nIf the MQTT entity represents a group of other entities, the member entities can be made visible in the UI by setting the list of unique IDs of the member entities in the\ngroup\nconfiguration option of the entity group:\ngroup\nA list of unique IDs of the member entities. Set this if the entity represents a group entity. Note that the member entities must be already configured before the member entities will become visible in the UI at the moment a group entity is loaded.\nMQTT Discovery\nThe discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the\nHTTP binary sensor\nand the\nHTTP sensor\n. To prevent multiple identical entries if a device reconnects, a unique identifier is necessary. Two parts are required on the device side: The configuration topic, and the device configuration as payload.\nMQTT discovery is enabled by default, but can be disabled. The prefix for the discovery topic (default\nhomeassistant\n) can be changed.\nSee the\nMQTT Options sections\nNote\nDocumentation on the MQTT components that support MQTT discovery\ncan be found here\n.\nDiscovery messages\nMQTT discovery supports two types of discovery messages:\nDevice discovery\n, which allows you to include several components in a single discovery message\nSingle component discovery\n, where you publish a separate discovery message for each component\nIf you use a device with multiple components, it is recommended to use MQTT device discovery. It reduces the number of messages sent, and allows you to send the device information only once.\nDiscovery topic\nThe discovery topic needs to follow a specific format:\n<discovery_prefix>\/<component>\/[<node_id>\/]<object_id>\/config\nText\n<discovery_prefix>\n: The Discovery Prefix defaults to\nhomeassistant\nand this prefix can be\nchanged\n.\n<component>\n: One of the supported MQTT integrations, for example,\nbinary_sensor\n, or\ndevice\nin case of device discovery.\n<node_id>\n: (\nOptional\n):  ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. The ID of the node must only consist of characters from the character class\n[a-zA-Z0-9_-]\n(alphanumerics, underscore and hyphen).\n<object_id>\n: The ID of the device. This allows for separate topics for each device. The ID of the device must only consist of characters from the character class\n[a-zA-Z0-9_-]\n(alphanumerics, underscore and hyphen).\nNote:\nThe\n<object_id>\nin the topic does not influence the resulting\nentity_id\n; use\ndefault_entity_id\nif you need to control the\nentity_id\n.\nThe\n<node_id>\nis optional, and can be used by clients to subscribe to their own (command) topics by using one wildcard topic like\n<discovery_prefix>\/+\/<node_id>\/+\/set\n.\nBest practice for entities with a\nunique_id\nis to set\n<object_id>\nto the\nunique_id\nand omit the\n<node_id>\n.\nDevice discovery payload\nA device can send a discovery payload to expose all components for a device.\nThe\n<component>\npart in the discovery topic must be set to\ndevice\n.\nAs an alternative, it is also possible for a device\nto send a discovery payload for each component\nit wants to set up.\nThe shared options at the root level of the JSON message must include:\ndevice\nmapping (abbreviated as\ndev\n)\norigin\nmapping (abbreviated as\no\n)\nThese mappings are mandatory and cannot be overridden at the entity\/component level.\nSupported shared options are:\nThe\navailability\noptions\n.\nThe\norigin\n(required)\noptions\ncommand_topic\nstate_topic\nqos\nencoding\nThe component specific options are placed as mappings under the\ncomponents\nkey (abbreviated as\ncmps\n) like:\n{\n\"dev\"\n:\n{\n\"ids\"\n:\n\"ea334450945afc\"\n,\n\"name\"\n:\n\"Kitchen\"\n,\n\"mf\"\n:\n\"Bla electronics\"\n,\n\"mdl\"\n:\n\"xya\"\n,\n\"sw\"\n:\n\"1.0\"\n,\n\"sn\"\n:\n\"ea334450945afc\"\n,\n\"hw\"\n:\n\"1.0rev2\"\n}\n,\n\"o\"\n:\n{\n\"name\"\n:\n\"bla2mqtt\"\n,\n\"sw\"\n:\n\"2.1\"\n,\n\"url\"\n:\n\"\nhttps:\/\/bla2mqtt.example.com\/support\n\"\n}\n,\n\"cmps\"\n:\n{\n\"some_unique_component_id1\"\n:\n{\n\"p\"\n:\n\"sensor\"\n,\n\"device_class\"\n:\n\"temperature\"\n,\n\"unit_of_measurement\"\n:\n\"°C\"\n,\n\"value_template\"\n:\n\"{{ value_json.temperature}}\"\n,\n\"unique_id\"\n:\n\"temp01ae_t\"\n}\n,\n\"some_unique_id2\"\n:\n{\n\"p\"\n:\n\"sensor\"\n,\n\"device_class\"\n:\n\"humidity\"\n,\n\"unit_of_measurement\"\n:\n\"%\"\n,\n\"value_template\"\n:\n\"{{ value_json.humidity}}\"\n,\n\"unique_id\"\n:\n\"temp01ae_h\"\n}\n}\n,\n\"state_topic\"\n:\n\"sensorBedroom\/state\"\n,\n\"qos\"\n:\n2\n}\nJSON\nNote\nThe components id’s under the\ncomponents\n(\ncmps\n) key, are used as part of the discovery identification. A\nplatform\n(\np\n) config option is required for each component config that is added to identify the component platform. Also required is a\nunique_id\nfor entity-based components.\nTo remove the components, publish an empty (retained) string payload to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it.\nAn empty config can be published as an update to remove a single component from the device discovery. Note that adding the\nplatform\n(\np\n) option is still required.\n{\n\"dev\"\n:\n{\n\"ids\"\n:\n\"ea334450945afc\"\n,\n\"name\"\n:\n\"Kitchen\"\n,\n\"mf\"\n:\n\"Bla electronics\"\n,\n\"mdl\"\n:\n\"xya\"\n,\n\"sw\"\n:\n\"1.0\"\n,\n\"sn\"\n:\n\"ea334450945afc\"\n,\n\"hw\"\n:\n\"1.0rev2\"\n}\n,\n\"o\"\n:\n{\n\"name\"\n:\n\"bla2mqtt\"\n,\n\"sw\"\n:\n\"2.1\"\n,\n\"url\"\n:\n\"\nhttps:\/\/bla2mqtt.example.com\/support\n\"\n}\n,\n\"cmps\"\n:\n{\n\"some_unique_component_id1\"\n:\n{\n\"p\"\n:\n\"sensor\"\n,\n\"device_class\"\n:\n\"temperature\"\n,\n\"unit_of_measurement\"\n:\n\"°C\"\n,\n\"value_template\"\n:\n\"{{ value_json.temperature}}\"\n,\n\"unique_id\"\n:\n\"temp01ae_t\"\n}\n,\n\"some_unique_id2\"\n:\n{\n\"p\"\n:\n\"sensor\"\n}\n}\n,\n\"state_topic\"\n:\n\"sensorBedroom\/state\"\n,\n\"qos\"\n:\n2\n}\nJSON\nThis will explicitly remove the humidity sensor and its entry.\nAfter removing a component, you should send another update with the removed component omitted from the configuration. This ensures that Home Assistant has the most up-to-date device configuration. For example:\n{\n\"dev\"\n:\n{\n\"ids\"\n:\n\"ea334450945afc\"\n,\n\"name\"\n:\n\"Kitchen\"\n,\n\"mf\"\n:\n\"Bla electronics\"\n,\n\"mdl\"\n:\n\"xya\"\n,\n\"sw\"\n:\n\"1.0\"\n,\n\"sn\"\n:\n\"ea334450945afc\"\n,\n\"hw\"\n:\n\"1.0rev2\"\n}\n,\n\"o\"\n:\n{\n\"name\"\n:\n\"bla2mqtt\"\n,\n\"sw\"\n:\n\"2.1\"\n,\n\"url\"\n:\n\"\nhttps:\/\/bla2mqtt.example.com\/support\n\"\n}\n,\n\"cmps\"\n:\n{\n\"some_unique_component_id1\"\n:\n{\n\"p\"\n:\n\"sensor\"\n,\n\"device_class\"\n:\n\"temperature\"\n,\n\"unit_of_measurement\"\n:\n\"°C\"\n,\n\"value_template\"\n:\n\"{{ value_json.temperature}}\"\n,\n\"unique_id\"\n:\n\"temp01ae_t\"\n}\n}\n,\n\"state_topic\"\n:\n\"sensorBedroom\/state\"\n,\n\"qos\"\n:\n2\n}\nJSON\nA component config part in a device discovery payload must have the\nplatform\n(\np\n) option set with the name of the\ncomponent\nand also must have at least one component specific config option. Entity components must have set the\nunique_id\noption and have a\ndevice\ncontext.\nMigration from single component to device discovery\nTo allow a smooth migration from single component discovery to device discovery:\nEnsure all entities have a\nunique_id\nand a\ndevice\ncontext.\nMove the\nobject_id\ninside the discovery payload, if that is available, or use a unique ID or the component.\nConsider using the previous\nnode_id\nas the new\nobject_id\nof the device discovery topic.\nEnsure the\nunique_id\nmatches and the\ndevice\ncontext has the correct identifiers.\nSend the following payload to all existing single component discovery topics:\n{\"migrate_discovery\": true }\n. This will unload the discovered item, but its settings will be retained.\nSwitch the discovery topic to the device discovery topic and include all the component configurations.\nClean up the single component discovery messages with an empty payload.\nDuring the migration steps, INFO messages will be logged to inform you about the progress of the migration.\nImportant\nConsider testing the migration process in a non-production environment before applying it to a live system.\nDiscovery migration example with a device automation and a sensor\nStep 1: Original single component discovery configurations:\nDiscovery topic single:\nhomeassistant\/device_automation\/0AFFD2\/bla1\/config\nDiscovery id:\n0AFFD2 bla1\n(both\n0AFFD2\nand\nbla1\nfrom the discovery topic)\nDiscovery payload single:\n{\n\"device\"\n:\n{\n\"identifiers\"\n:\n[\n\"0AFFD2\"\n]\n,\n\"name\"\n:\n\"Test device\"\n}\n,\n\"o\"\n:\n{\n\"name\"\n:\n\"foobar\"\n}\n,\n\"automation_type\"\n:\n\"trigger\"\n,\n\"payload\"\n:\n\"short_press\"\n,\n\"topic\"\n:\n\"foobar\/triggers\/button1\"\n,\n\"type\"\n:\n\"button_short_press\"\n,\n\"subtype\"\n:\n\"button_1\"\n}\nJSON\nDiscovery topic single:\nhomeassistant\/sensor\/0AFFD2\/bla2\/config\nDiscovery id:\n0AFFD2 bla2\n(both\n0AFFD2\nand\nbla2\nfrom the discovery topic)\nDiscovery payload single:\n{\n\"device\"\n:\n{\n\"identifiers\"\n:\n[\n\"0AFFD2\"\n]\n,\n\"name\"\n:\n\"Test device\"\n}\n,\n\"o\"\n:\n{\n\"name\"\n:\n\"foobar\"\n}\n,\n\"state_topic\"\n:\n\"foobar\/sensor\/sensor1\"\n,\n\"unique_id\"\n:\n\"bla_sensor001\"\n}\nJSON\nStep 2: Initiate migration by publishing to both discovery topics:\nWhen these single component discovery payloads are processed, and we want to initiate migration to device discovery, we need to publish …\n{\n\"migrate_discovery\"\n:\ntrue\n}\nJSON\n… to both discovery topics …\nhomeassistant\/device_automation\/0AFFD2\/bla1\/config\nhomeassistant\/sensor\/0AFFD2\/bla2\/config\nImportant\nCheck the logs to ensure this step is executed correctly.\nStep 3: Publish the new device discovery configuration:\nDiscovery topic device:\nhomeassistant\/device\/0AFFD2\/config\nDiscovery id:\n0AFFD2 bla\n(\n0AFFD2\nfrom discovery topic,\nbla\n: The key under\ncmps\nin the discovery payload)\nDiscovery payload device:\n{\n\"device\"\n:\n{\n\"identifiers\"\n:\n[\n\"0AFFD2\"\n]\n}\n,\n\"o\"\n:\n{\n\"name\"\n:\n\"foobar\"\n}\n,\n\"cmps\"\n:\n{\n\"bla1\"\n:\n{\n\"p\"\n:\n\"device_automation\"\n,\n\"automation_type\"\n:\n\"trigger\"\n,\n\"payload\"\n:\n\"short_press\"\n,\n\"topic\"\n:\n\"foobar\/triggers\/button1\"\n,\n\"type\"\n:\n\"button_short_press\"\n,\n\"subtype\"\n:\n\"button_1\"\n}\n,\n\"bla2\"\n:\n{\n\"p\"\n:\n\"sensor\"\n,\n\"state_topic\"\n:\n\"foobar\/sensor\/sensor1\"\n,\n\"unique_id\"\n:\n\"bla_sensor001\"\n}\n}\n}\nJSON\nImportant\nCheck the logs to ensure the migration was successful.\nStep 4: Clean up after successful migration:\nAfter the logs show a successful migration, the single component discovery topics can be cleaned up safely by publishing an empty payload to them.\nThe logs should indicate if the discovery migration was successful.\nOptional: Rolling back the migration:\nTo rollback publish …\n{\n\"migrate_discovery\"\n:\ntrue\n}\nJSON\nTo the device discovery topic(s).\nAfter that, re-publish the single component discovery payloads.\nAt last, clean up the device discovery payloads by publishing an empty payload.\nCheck the logs for every step.\nSingle component discovery payload\nWhen using single component discovery messages, the\n<component>\npart in the discovery topic must be one of the supported MQTT platforms.\nThe options in the payload are only used to set up one specific component. If a device contains multiple components, it is recommended to use\ndevice discovery\ninstead.\nMQTT entities can share device configuration, meaning one entity can include the full device configuration and other entities can link to that device by only setting mandatory fields.\nImportant\nThe mandatory fields were previously limited to at least one of\nconnection\nand\nidentifiers\n, but have now been extended to at least one of\nconnection\nand\nidentifiers\nas well as the\nname\n.\nExample discovery payload:\n{\n\"dev\"\n:\n{\n\"ids\"\n:\n\"ea334450945afc\"\n,\n\"name\"\n:\n\"Kitchen\"\n,\n\"mf\"\n:\n\"Bla electronics\"\n,\n\"mdl\"\n:\n\"xya\"\n,\n\"sw\"\n:\n\"1.0\"\n,\n\"sn\"\n:\n\"ea334450945afc\"\n,\n\"hw\"\n:\n\"1.0rev2\"\n}\n,\n\"o\"\n:\n{\n\"name\"\n:\n\"bla2mqtt\"\n,\n\"sw\"\n:\n\"2.1\"\n,\n\"url\"\n:\n\"\nhttps:\/\/bla2mqtt.example.com\/support\n\"\n}\n,\n\"device_class\"\n:\n\"temperature\"\n,\n\"unit_of_measurement\"\n:\n\"°C\"\n,\n\"value_template\"\n:\n\"{{ value_json.temperature}}\"\n,\n\"unique_id\"\n:\n\"temp01ae_t\"\n,\n\"state_topic\"\n:\n\"sensorBedroom\/state\"\n,\n\"qos\"\n:\n2\n}\nJSON\nTo remove the component, publish an empty string to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it.\nFor more examples\nsee\n.\nDiscovery payload\nThe payload must be a serialized JSON dictionary and will be checked like an entry in your\nconfiguration.yaml\nThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI.\n[Learn more]\nfile if a new device is added, with the exception that unknown configuration keys are allowed but ignored. This means that missing variables will be filled with the integration’s default values. All configuration variables which are\nrequired\nmust be present in the payload. The reason for allowing unknown documentation keys is allow some backwards compatibility, software generating MQTT discovery messages can then be used with older Home Assistant versions which will simply ignore new features.\nA discovery payload can be sent with a retain flag set. In that case, the discovery message will be stored at the MQTT broker and processed automatically when the MQTT integrations start. This method removes the need for it to be resent. A better approach, though, is for the software generating MQTT discovery messages to send discovery payload(s) when the MQTT integration sends the\nBirth message\n.\nSubsequent messages on a topic where a valid payload has been received will be handled as a configuration update, and a configuration update with an empty payload will cause a previously discovered device to be deleted.\nA base topic\n~\nmay be defined in the payload to conserve memory when the same topic base is used multiple times.\nIn the value of configuration variables ending with\n_topic\n,\n~\nwill be replaced with the base topic, if the\n~\noccurs at the beginning or end of the value.\nConfiguration variable names in the discovery payload may be abbreviated to conserve memory when sending a discovery message from memory constrained devices.\nIt is recommended to add information about the origin of MQTT entities by including the\norigin\noption (abbreviated as\no\n) in the discovery payload. For device discovery, this information is required. The origin details will be logged in the core event log when an item is discovered or updated. Adding origin information helps with troubleshooting and provides valuable context about the source of MQTT messages in your Home Assistant setup.\nNote: These options also support abbreviations, as shown in the table below.\nname\nThe name of the application that is the origin of the discovered MQTT item. (Required)\nsw_version\nSoftware version of the application that supplies the discovered MQTT item.\nsupport_url\nSupport URL of the application that supplies the discovered MQTT item.\nSupported abbreviations in MQTT discovery messages\nSupported abbreviations\n'act_t':               'action_topic',\n'act_tpl':             'action_template',\n'atype':               'automation_type',\n'aux_cmd_t':           'aux_command_topic',\n'aux_stat_t':          'aux_state_topic',\n'aux_stat_tpl':        'aux_state_template',\n'av_tones':            'available_tones',\n'avty':                'availability',\n'avty_mode':           'availability_mode',\n'avty_t':              'availability_topic',\n'avty_tpl':            'availability_template',\n'away_mode_cmd_t':     'away_mode_command_topic',\n'away_mode_stat_t':    'away_mode_state_topic',\n'away_mode_stat_tpl':  'away_mode_state_template',\n'b_tpl':               'blue_template',\n'bri_cmd_t':           'brightness_command_topic',\n'bri_cmd_tpl':         'brightness_command_template',\n'bri_scl':             'brightness_scale',\n'bri_stat_t':          'brightness_state_topic',\n'bri_tpl':             'brightness_template',\n'bri_val_tpl':         'brightness_value_template',\n'clr_temp_cmd_tpl':    'color_temp_command_template',\n'clr_temp_cmd_t':      'color_temp_command_topic',\n'clr_temp_k':           'color_temp_kelvin',\n'clr_temp_stat_t':     'color_temp_state_topic',\n'clr_temp_tpl':        'color_temp_template',\n'clr_temp_val_tpl':    'color_temp_value_template',\n'clrm_stat_t':         'color_mode_state_topic',\n'clrm_val_tpl':        'color_mode_value_template',\n'cmd_off_tpl':         'command_off_template',\n'cmd_on_tpl':          'command_on_template',\n'cmd_t':               'command_topic',\n'cmd_tpl':             'command_template',\n'cmps':                'components',\n'cod_arm_req':         'code_arm_required',\n'cod_dis_req':         'code_disarm_required',\n'cod_trig_req':        'code_trigger_required',\n'cont_type':           'content_type',\n'curr_temp_t':         'current_temperature_topic',\n'curr_temp_tpl':       'current_temperature_template',\n'def_ent_id':          'default_entity_id',\n'dev':                 'device',\n'dev_cla':             'device_class',\n'dir_cmd_t':           'direction_command_topic',\n'dir_cmd_tpl':         'direction_command_template',\n'dir_stat_t':          'direction_state_topic',\n'dir_val_tpl':         'direction_value_template',\n'dsp_prc':             'display_precision',\n'e':                   'encoding',\n'en':                  'enabled_by_default',\n'ent_cat':             'entity_category',\n'ent_pic':             'entity_picture',\n'evt_typ':             'event_types',\n'exp_aft':             'expire_after',\n'fanspd_lst':          'fan_speed_list',\n'flsh':                'flash',\n'flsh_tlng':           'flash_time_long',\n'flsh_tsht':           'flash_time_short',\n'fx_cmd_t':            'effect_command_topic',\n'fx_cmd_tpl':          'effect_command_template',\n'fx_list':             'effect_list',\n'fx_stat_t':           'effect_state_topic',\n'fx_tpl':              'effect_template',\n'fx_val_tpl':          'effect_value_template',\n'fan_mode_cmd_t':      'fan_mode_command_topic',\n'fan_mode_cmd_tpl':    'fan_mode_command_template',\n'fan_mode_stat_t':     'fan_mode_state_topic',\n'fan_mode_stat_tpl':   'fan_mode_state_template',\n'frc_upd':             'force_update',\n'g_tpl':               'green_template',\n'grp':                 'group',\n'hs_cmd_t':            'hs_command_topic',\n'hs_cmd_tpl':          'hs_command_template',\n'hs_stat_t':           'hs_state_topic',\n'hs_val_tpl':          'hs_value_template',\n'ic':                  'icon',\n'img_e':               'image_encoding',\n'img_t':               'image_topic',\n'init':                'initial',\n'hum_cmd_t':           'target_humidity_command_topic',\n'hum_cmd_tpl':         'target_humidity_command_template',\n'hum_stat_t':          'target_humidity_state_topic',\n'hum_state_tpl':       'target_humidity_state_template',\n'json_attr':           'json_attributes',\n'json_attr_t':         'json_attributes_topic',\n'json_attr_tpl':       'json_attributes_template',\n'l_ver_t':             'latest_version_topic',\n'l_ver_tpl':           'latest_version_template',\n'lrst_t':              'last_reset_topic',\n'lrst_val_tpl':        'last_reset_value_template',\n'max':                 'max',\n'max_hum':             'max_humidity',\n'max_k':               'max_kelvin',\n'max_mirs':            'max_mireds',\n'max_temp':            'max_temp',\n'migr_discvry':        'migrate_discovery',\n'min':                 'min',\n'min_hum':             'min_humidity',\n'min_k':               'min_kelvin',\n'min_mirs':            'min_mireds',\n'min_temp':            'min_temp',\n'mode':                'mode',\n'mode_cmd_t':          'mode_command_topic',\n'mode_cmd_tpl':        'mode_command_template',\n'mode_stat_t':         'mode_state_topic',\n'mode_stat_tpl':       'mode_state_template',\n'modes':               'modes',\n'name':                'name',\n'o':                   'origin',\n'off_dly':             'off_delay',\n'on_cmd_type':         'on_command_type',\n'ops':                 'options',\n'opt':                 'optimistic',\n'osc_cmd_t':           'oscillation_command_topic',\n'osc_cmd_tpl':         'oscillation_command_template',\n'osc_stat_t':          'oscillation_state_topic',\n'osc_val_tpl':         'oscillation_value_template',\n'p':                   'platform',\n'pct_cmd_t':           'percentage_command_topic',\n'pct_cmd_tpl':         'percentage_command_template',\n'pct_stat_t':          'percentage_state_topic',\n'pct_val_tpl':         'percentage_value_template',\n'pl':                  'payload',\n'pl_arm_away':         'payload_arm_away',\n'pl_arm_custom_b':     'payload_arm_custom_bypass',\n'pl_arm_home':         'payload_arm_home',\n'pl_arm_nite':         'payload_arm_night',\n'pl_arm_vacation':     'payload_arm_vacation',\n'pl_avail':            'payload_available',\n'pl_cln_sp':           'payload_clean_spot',\n'pl_cls':              'payload_close',\n'pl_dir_fwd':          'payload_direction_forward',\n'pl_dir_rev':          'payload_direction_reverse',\n'pl_disarm':           'payload_disarm',\n'pl_home':             'payload_home',\n'pl_inst':             'payload_install',\n'pl_loc':              'payload_locate',\n'pl_lock':             'payload_lock',\n'pl_not_avail':        'payload_not_available',\n'pl_not_home':         'payload_not_home',\n'pl_off':              'payload_off',\n'pl_on':               'payload_on',\n'pl_open':             'payload_open',\n'pl_osc_off':          'payload_oscillation_off',\n'pl_osc_on':           'payload_oscillation_on',\n'pl_paus':             'payload_pause',\n'pl_prs':              'payload_press',\n'pl_ret':              'payload_return_to_base',\n'pl_rst':              'payload_reset',\n'pl_rst_hum':          'payload_reset_humidity',\n'pl_rst_mode':         'payload_reset_mode',\n'pl_rst_pct':          'payload_reset_percentage',\n'pl_rst_pr_mode':      'payload_reset_preset_mode',\n'pl_stop':             'payload_stop',\n'pl_stop_tilt':        'payload_stop_tilt',\n'pl_stpa':             'payload_start_pause',\n'pl_strt':             'payload_start',\n'pl_toff':             'payload_turn_off',\n'pl_ton':              'payload_turn_on',\n'pl_trig':             'payload_trigger',\n'pl_unlk':             'payload_unlock',\n'pos':                 'reports_position',\n'pos_clsd':            'position_closed',\n'pos_open':            'position_open',\n'pr_mode_cmd_t':       'preset_mode_command_topic',\n'pr_mode_cmd_tpl':     'preset_mode_command_template',\n'pr_mode_stat_t':      'preset_mode_state_topic',\n'pr_mode_val_tpl':     'preset_mode_value_template',\n'pr_modes':            'preset_modes',\n'ptrn':                'pattern',\n'r_tpl':               'red_template',\n'rel_s':               'release_summary',\n'rel_u':               'release_url',\n'ret':                 'retain',\n'rgb_cmd_t':           'rgb_command_topic',\n'rgb_cmd_tpl':         'rgb_command_template',\n'rgb_stat_t':          'rgb_state_topic',\n'rgb_val_tpl':         'rgb_value_template',\n'rgbw_cmd_t':          'rgbw_command_topic',\n'rgbw_cmd_tpl':        'rgbw_command_template',\n'rgbw_stat_t':         'rgbw_state_topic',\n'rgbw_val_tpl':        'rgbw_value_template',\n'rgbww_cmd_t':         'rgbww_command_topic',\n'rgbww_cmd_tpl':       'rgbww_command_template',\n'rgbww_stat_t':        'rgbww_state_topic',\n'rgbww_val_tpl':       'rgbww_value_template',\n'send_cmd_t':          'send_command_topic',\n'send_if_off':         'send_if_off',\n'set_fan_spd_t':       'set_fan_speed_topic',\n'set_pos_t':           'set_position_topic',\n'set_pos_tpl':         'set_position_template',\n'pos_t':               'position_topic',\n'pos_tpl':             'position_template',\n'spd_rng_min':         'speed_range_min',\n'spd_rng_max':         'speed_range_max',\n'src_type':            'source_type',\n'stat_cla':            'state_class',\n'stat_closing':        'state_closing',\n'stat_clsd':           'state_closed',\n'stat_jam':            'state_jammed',\n'stat_locked':         'state_locked',\n'stat_locking':        'state_locking',\n'stat_off':            'state_off',\n'stat_on':             'state_on',\n'stat_open':           'state_open',\n'stat_opening':        'state_opening',\n'stat_stopped':        'state_stopped',\n'stat_unlocked':       'state_unlocked',\n'stat_unlocking':      'state_unlocking',\n'stat_t':              'state_topic',\n'stat_tpl':            'state_template',\n'stat_val_tpl':        'state_value_template',\n'step':                'step',\n'stype':               'subtype',\n'sug_dsp_prc':         'suggested_display_precision',\n'sup_clrm':            'supported_color_modes',\n'sup_dur':             'support_duration',\n'sup_vol':             'support_volume_set',\n'sup_feat':            'supported_features',\n'swing_mode_cmd_t':    'swing_mode_command_topic',\n'swing_mode_cmd_tpl':  'swing_mode_command_template',\n'swing_mode_stat_t':   'swing_mode_state_topic',\n'swing_mode_stat_tpl': 'swing_mode_state_template',\n't':                   'topic',\n'temp_cmd_t':          'temperature_command_topic',\n'temp_cmd_tpl':        'temperature_command_template',\n'temp_hi_cmd_t':       'temperature_high_command_topic',\n'temp_hi_cmd_tpl':     'temperature_high_command_template',\n'temp_hi_stat_t':      'temperature_high_state_topic',\n'temp_hi_stat_tpl':    'temperature_high_state_template',\n'temp_lo_cmd_t':       'temperature_low_command_topic',\n'temp_lo_cmd_tpl':     'temperature_low_command_template',\n'temp_lo_stat_t':      'temperature_low_state_topic',\n'temp_lo_stat_tpl':    'temperature_low_state_template',\n'temp_stat_t':         'temperature_state_topic',\n'temp_stat_tpl':       'temperature_state_template',\n'temp_unit':           'temperature_unit',\n'tilt_clsd_val':       'tilt_closed_value',\n'tilt_cmd_t':          'tilt_command_topic',\n'tilt_cmd_tpl':        'tilt_command_template',\n'tilt_max':            'tilt_max',\n'tilt_min':            'tilt_min',\n'tilt_opnd_val':       'tilt_opened_value',\n'tilt_opt':            'tilt_optimistic',\n'tilt_status_t':       'tilt_status_topic',\n'tilt_status_tpl':     'tilt_status_template',\n'tit':                 'title',\n'trns':                'transition',\n'uniq_id':             'unique_id',\n'unit_of_meas':        'unit_of_measurement',\n'url_t':               'url_topic',\n'url_tpl':             'url_template',\n'val_tpl':             'value_template',\n'whit_cmd_t':          'white_command_topic',\n'whit_scl':            'white_scale',\n'xy_cmd_t':            'xy_command_topic',\n'xy_cmd_tpl':          'xy_command_template',\n'xy_stat_t':           'xy_state_topic',\n'xy_val_tpl':          'xy_value_template',\nTxt\nSupported abbreviations for device registry configuration\n'cu':                  'configuration_url',\n'cns':                 'connections',\n'ids':                 'identifiers',\n'name':                'name',\n'mf':                  'manufacturer',\n'mdl':                 'model',\n'mdl_id':              'model_id',\n'hw':                  'hw_version',\n'sw':                  'sw_version',\n'sa':                  'suggested_area',\n'sn':                  'serial_number',\nTxt\nSupported abbreviations for origin info\n'name':                'name',\n'sw':                  'sw_version',\n'url':                 'support_url',\nTxt\nDiscovery messages and availability\nWhen MQTT discovery is set up, and a device or service sends a discovery message,\nan MQTT entity, tag, or device automation will be set up directly after receiving the message.\nWhen Home Assistant is restarting, discovered MQTT items with a unique ID will be unavailable until a new\ndiscovery message is received. MQTT items without a unique ID will not be added at startup.\nSo a device or service using MQTT discovery must make sure a configuration message is offered\nafter the\nMQTT\nintegration has been (re)started. There are two common approaches to make sure the\ndiscovered items are set up at startup:\nUsing Birth and Will messages to trigger setup\nUsing retained messages\nFinally, it is a best practice to publish your device or service availability status.\nUse the Birth and Will messages to trigger discovery\nWhen the\nMQTT\nintegration starts, a birth message is published at\nhomeassistant\/status\nby default.\nA device or service connected to the shared\nmqtt\nbroker can subscribe to this topic and use an\nonline\nmessage\nto trigger discovery messages. See also the\nbirth and last will messages\nsection. After the configs have been published, the state topics will need an update, so they need to be republished.\nUsing retained config messages\nAn alternative method for a device or service is to publish discovery messages with a\nretain\nflag. This will make sure\ndiscovery messages are replayed when the\nMQTT\nintegration connects to the broker.\nAfter the configs have been published, the state topics will need an update.\nUsing retained state messages\nState updates also need to be re-published after a config as been processed.\nThis can also be done by publishing\nretained\nmessages. As soon as a config is received (or replayed from a retained message),\nthe setup will subscribe any state topics. If a retained message is available at a state topic,\nthis message will be replayed so that the state can be restored for this topic.\nWarning\nA disadvantage of using retained messages is that these messages retain at the broker,\neven when the device or service stops working. They are retained even after the system or broker has been restarted.\nRetained messages can create ghost entities that keep coming back.\nEspecially when you have many entities, (unneeded) discovery messages can cause excessive system load. For this reason, use discovery messages with caution.\nUsing Availability topics\nA device or service can announce its availability by publishing a Birth message and set a Will message at the broker.\nWhen the device or service loses connection to the broker, the broker will publish the Will message.\nThis allows the\nMQTT\nintegration to make an entity unavailable.\nPlatform specific availability settings are available for\nmqtt\nentity platforms only.\nPlatform specific availability settings\nConfiguration Variables\navailability\nlist\n(\nOptional\n)\nA list of MQTT topics subscribed to receive availability (online\/offline) updates. Must not be used together with\navailability_topic\n.\npayload_available\nstring\n(\nOptional\n, default: online\n)\nThe payload that represents the available state.\npayload_not_available\nstring\n(\nOptional\n, default: offline\n)\nThe payload that represents the unavailable state.\ntopic\nstring\nRequired\nAn MQTT topic subscribed to receive availability (online\/offline) updates.\nvalue_template\ntemplate\n(\nOptional\n)\nDefines a\ntemplate\nto extract a device’s availability from the\ntopic\n. To determine the device’s availability, the result of this template will be compared to\npayload_available\nand\npayload_not_available\n.\navailability_topic\nstring\n(\nOptional\n)\nThe MQTT topic subscribed to receive availability (online\/offline) updates. Must not be used together with\navailability\n.\navailability_mode\nstring\n(\nOptional\n, default: latest\n)\nWhen\navailability\nis configured, this controls the conditions needed to set the entity to\navailable\n. Valid entries are\nall\n,\nany\n, and\nlatest\n. If set to\nall\n,\npayload_available\nmust be received on all configured availability topics before the entity is marked as online. If set to\nany\n,\npayload_available\nmust be received on at least one configured availability topic before the entity is marked as online. If set to\nlatest\n, the last\npayload_available\nor\npayload_not_available\nreceived on any configured availability topic controls the availability.\navailability_template\ntemplate\n(\nOptional\n)\nDefines a\ntemplate\nto extract device’s availability from the\navailability_topic\n. To determine the devices’s availability result of this template will be compared to\npayload_available\nand\npayload_not_available\n.\npayload_available\nstring\n(\nOptional\n, default: online\n)\nThe payload that represents the available state.\npayload_not_available\nstring\n(\nOptional\n, default: offline\n)\nThe payload that represents the unavailable state.\nDiscovery examples with component discovery\nMotion detection (binary sensor)\nA motion detection device which can be represented by a\nbinary sensor\nfor your garden would send its configuration as JSON payload to the Configuration topic. After the first message to\nconfig\n, then the MQTT messages sent to the state topic will update the state in Home Assistant.\nConfiguration topic:\nhomeassistant\/binary_sensor\/garden\/config\nState topic:\nhomeassistant\/binary_sensor\/garden\/state\nConfiguration payload with derived device name:\n{\n\"name\"\n:\nnull\n,\n\"device_class\"\n:\n\"motion\"\n,\n\"state_topic\"\n:\n\"homeassistant\/binary_sensor\/garden\/state\"\n,\n\"unique_id\"\n:\n\"motion01ad\"\n,\n\"device\"\n:\n{\n\"identifiers\"\n:\n[\n\"01ad\"\n]\n,\n\"name\"\n:\n\"Garden\"\n}\n}\nJSON\nRetain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts.\nIt is also a good idea to add a\nunique_id\nto allow changes to the entity and a\ndevice\nmapping so we can group all sensors of a device together. We can set “name” to\nnull\nif we want to inherit the device name for the entity. If we set an entity name, the\nfriendly_name\nwill be a combination of the device and entity name. If\nname\nis left away and a\ndevice_class\nis set, the entity name part will be derived from the\ndevice_class\n.\nExample configuration payload with no name set and derived\ndevice_class\nname:\n{\n\"name\"\n:\nnull\n,\n\"device_class\"\n:\n\"motion\"\n,\n\"state_topic\"\n:\n\"homeassistant\/binary_sensor\/garden\/state\"\n,\n\"unique_id\"\n:\n\"motion01ad\"\n,\n\"device\"\n:\n{\n\"identifiers\"\n:\n[\n\"01ad\"\n]\n,\n\"name\"\n:\n\"Garden\"\n}\n}\nJSON\nIf no name is set, a default name will be set by MQTT (\nsee the MQTT platform documentation\n).\nTo create a new sensor manually and with the name set to\nnull\nto derive the device name “Garden”:\nmosquitto_pub -r -h\n127.0\n.0.1 -p\n1883\n-t\n\"homeassistant\/binary_sensor\/garden\/config\"\n-m\n'{\"name\": null, \"device_class\": \"motion\", \"state_topic\": \"homeassistant\/binary_sensor\/garden\/state\", \"unique_id\": \"motion01ad\", \"device\": {\"identifiers\": [\"01ad\"], \"name\": \"Garden\" }}'\nBash\nUpdate the state:\nmosquitto_pub -h\n127.0\n.0.1 -p\n1883\n-t\n\"homeassistant\/binary_sensor\/garden\/state\"\n-m ON\nBash\nDelete the sensor by sending an empty message.\nmosquitto_pub -h\n127.0\n.0.1 -p\n1883\n-t\n\"homeassistant\/binary_sensor\/garden\/config\"\n-m\n''\nBash\nFor more details, refer to the\nMQTT testing section\n.\nSensors\nSetting up a sensor with multiple measurement values requires multiple consecutive configuration topic submissions.\nConfiguration topic no1:\nhomeassistant\/sensor\/sensorBedroomT\/config\nConfiguration payload no1:\n{\n\"device_class\"\n:\n\"temperature\"\n,\n\"state_topic\"\n:\n\"homeassistant\/sensor\/sensorBedroom\/state\"\n,\n\"unit_of_measurement\"\n:\n\"°C\"\n,\n\"value_template\"\n:\n\"{{ value_json.temperature}}\"\n,\n\"unique_id\"\n:\n\"temp01ae\"\n,\n\"device\"\n:\n{\n\"identifiers\"\n:\n[\n\"bedroom01ae\"\n]\n,\n\"name\"\n:\n\"Bedroom\"\n,\n\"manufacturer\"\n:\n\"Example sensors Ltd.\"\n,\n\"model\"\n:\n\"Example Sensor\"\n,\n\"model_id\"\n:\n\"K9\"\n,\n\"serial_number\"\n:\n\"12AE3010545\"\n,\n\"hw_version\"\n:\n\"1.01a\"\n,\n\"sw_version\"\n:\n\"2024.1.0\"\n,\n\"configuration_url\"\n:\n\"\nhttps:\/\/example.com\/sensor_portal\/config\n\"\n}\n}\nJSON\nConfiguration topic no2:\nhomeassistant\/sensor\/sensorBedroomH\/config\nConfiguration payload no2:\n{\n\"device_class\"\n:\n\"humidity\"\n,\n\"state_topic\"\n:\n\"homeassistant\/sensor\/sensorBedroom\/state\"\n,\n\"unit_of_measurement\"\n:\n\"%\"\n,\n\"value_template\"\n:\n\"{{ value_json.humidity}}\"\n,\n\"unique_id\"\n:\n\"hum01ae\"\n,\n\"device\"\n:\n{\n\"identifiers\"\n:\n[\n\"bedroom01ae\"\n]\n}\n}\nJSON\nThe sensor\nidentifiers\nor\nconnections\noption allows to set up multiple entities that share the same device.\nNote\nIf a device configuration is shared, then it is not needed to add all device details to the other entity configs. It is enough to add shared identifiers or connections to the device mapping for the other entity config payloads.\nA common state payload that can be parsed with the\nvalue_template\nin the sensor configs:\n{\n\"temperature\"\n:\n23.20\n,\n\"humidity\"\n:\n43.70\n}\nJSON\nEntities with command topics\nSetting up a light or switch is similar but requires a\ncommand_topic\nas mentioned in the\nMQTT switch documentation\n.\nConfiguration topic:\nhomeassistant\/switch\/irrigation\/config\nState topic:\nhomeassistant\/switch\/irrigation\/state\nCommand topic:\nhomeassistant\/switch\/irrigation\/set\nPayload:\n{\n\"name\"\n:\n\"Irrigation\"\n,\n\"command_topic\"\n:\n\"homeassistant\/switch\/irrigation\/set\"\n,\n\"state_topic\"\n:\n\"homeassistant\/switch\/irrigation\/state\"\n,\n\"unique_id\"\n:\n\"irr01ad\"\n,\n\"device\"\n:\n{\n\"identifiers\"\n:\n[\n\"garden01ad\"\n]\n,\n\"name\"\n:\n\"Garden\"\n}\n}\nJSON\nRetain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts.\nmosquitto_pub -r -h\n127.0\n.0.1 -p\n1883\n-t\n\"homeassistant\/switch\/irrigation\/config\"\n\\\n-m\n'{\"name\": \"Irrigation\", \"command_topic\": \"homeassistant\/switch\/irrigation\/set\", \"state_topic\": \"homeassistant\/switch\/irrigation\/state\", \"unique_id\": \"irr01ad\", \"device\": {\"identifiers\": [\"garden01ad\"], \"name\": \"Garden\" }}'\nBash\nSet the state:\nmosquitto_pub -h\n127.0\n.0.1 -p\n1883\n-t\n\"homeassistant\/switch\/irrigation\/set\"\n-m ON\nBash\nUsing abbreviations and base topic\nSetting up a switch using topic prefix and abbreviated configuration variable names to reduce payload length.\nConfiguration topic:\nhomeassistant\/switch\/irrigation\/config\nCommand topic:\nhomeassistant\/switch\/irrigation\/set\nState topic:\nhomeassistant\/switch\/irrigation\/state\nConfiguration payload:\n{\n\"~\"\n:\n\"homeassistant\/switch\/irrigation\"\n,\n\"name\"\n:\n\"garden\"\n,\n\"cmd_t\"\n:\n\"~\/set\"\n,\n\"stat_t\"\n:\n\"~\/state\"\n}\nJSON\nNote\nAnother example using abbreviations topic name and base topic\nSetting up a\nlight that takes JSON payloads\n, with abbreviated configuration variable names:\nConfiguration topic:\nhomeassistant\/light\/kitchen\/config\nCommand topic:\nhomeassistant\/light\/kitchen\/set\nState topic:\nhomeassistant\/light\/kitchen\/state\nExample state payload:\n{\"state\": \"ON\", \"brightness\": 255}\nConfiguration payload:\n{\n\"~\"\n:\n\"homeassistant\/light\/kitchen\"\n,\n\"name\"\n:\n\"Kitchen\"\n,\n\"uniq_id\"\n:\n\"kitchen_light\"\n,\n\"cmd_t\"\n:\n\"~\/set\"\n,\n\"stat_t\"\n:\n\"~\/state\"\n,\n\"schema\"\n:\n\"json\"\n,\n\"brightness\"\n:\ntrue\n}\nJSON\nExample with using abbreviated Device and Origin info in discovery messages\n{\n\"~\"\n:\n\"homeassistant\/light\/kitchen\"\n,\n\"name\"\n:\nnull\n,\n\"uniq_id\"\n:\n\"kitchen_light\"\n,\n\"cmd_t\"\n:\n\"~\/set\"\n,\n\"stat_t\"\n:\n\"~\/state\"\n,\n\"schema\"\n:\n\"json\"\n,\n\"dev\"\n:\n{\n\"ids\"\n:\n\"ea334450945afc\"\n,\n\"name\"\n:\n\"Kitchen\"\n,\n\"mf\"\n:\n\"Bla electronics\"\n,\n\"mdl\"\n:\n\"xya\"\n,\n\"mdl_id\"\n:\n\"ABC123\"\n,\n\"sw\"\n:\n\"1.0\"\n,\n\"sn\"\n:\n\"ea334450945afc\"\n,\n\"hw\"\n:\n\"1.0rev2\"\n}\n,\n\"o\"\n:\n{\n\"name\"\n:\n\"bla2mqtt\"\n,\n\"sw\"\n:\n\"2.1\"\n,\n\"url\"\n:\n\"\nhttps:\/\/bla2mqtt.example.com\/support\n\"\n}\n}\nJSON\nSupport by third-party tools\nThe following software has built-in support for MQTT discovery:\nanpr2mqtt\nArduinoHA\nArilux AL-LC0X LED controllers\nble2mqtt\ndiematic_server\ndigitalstrom-mqtt\nebusd\necowitt2mqtt\nEMS-ESP32 (and EMS-ESP)\nESPHome\nESPurna\ngo-iotdevice\nHASS.Agent\nIOTLink\n(starting with 2.0.0)\nMiFlora MQTT Daemon\nMyElectricalData\nMqDockerUp\nNuki Hub\nNuki Smart Lock 3.0 Pro\n,\nmore info\nOpenMQTTGateway\nOTGateway\nrethink\nroom-assistant\n(starting with 1.1.0)\nSmartHome\nSpeedTest-CLI MQTT\nSwitchBot-MQTT-BLE-ESP32\nTasmota\n(starting with 5.11.1e, development halted)\nTeddyCloud\nTeleinfo MQTT\n(starting with 3.0.0)\nTydom2MQTT\nUpdates2MQTT\nWhat’s up Docker?\n(starting with 3.5.0)\nWyzeSense2MQTT\nXiaomi DaFang Hacks\nZehnder Comfoair RS232 MQTT\nZigbee2MQTT\nThe following software also supports consuming MQTT discovery information that is intended for Home Assistant.\nCompatibility and features will vary, and not all devices may work.\nDomoticz\nopenHAB\nManual configured MQTT items\nSupport to allow\nadding manual items as a subentry via a config flow\n, is work in progress. Not all entity platforms are supported yet.\nFor most integrations, it is also possible to manually set up MQTT items in\nconfiguration.yaml\nThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI.\n[Learn more]\n. Read more\nabout configuration in YAML\n.\nMQTT supports two styles for configuring items in YAML. All configuration items are placed directly under the\nmqtt\nintegration key. Note that you cannot mix these styles. Use the\nYAML configuration listed per item\nstyle when in doubt.\nYAML configuration listed per item\nThis method expects all items to be in a YAML list. Each item has a\n{domain}\nkey and the item config is placed directly under the domain key. This method is considered as best practice. In all the examples we use this format.\nmqtt\n:\n-\n{\ndomain\n}\n:\nname\n:\n\"\"\n...\n-\n{\ndomain\n}\n:\nname\n:\n\"\"\n...\nYAML\nYAML configuration keyed and bundled by\n{domain}\nAll items are grouped per\n{domain}\nand where all configs are listed.\nmqtt\n:\n{\ndomain\n}\n:\n-\nname\n:\n\"\"\n...\n-\nname\n:\n\"\"\n...\nYAML\nIf you have a large number of manually configured items, you might want to consider\nsplitting up the configuration\n.\nEntity state updates\nEntities receive state updates via MQTT subscriptions. The payloads received on the state topics are processed to determine whether there is a significant change. If a change is detected, the entity will be updated.\nNote that MQTT device payloads often contain information for updating multiple entities that subscribe to the same topics. For example, a light status update might include information about link quality. This data can update a link quality sensor but is not used to update the light itself. MQTT filters out entity state updates when there are no changes.\nThe last reported state attribute\nBecause MQTT state updates are often repeated frequently, even when no actual changes exist, it is up to the MQTT subscriber to determine whether a status update was received. If the latest update is missed, it might take some time before the next one arrives. If a retained payload exists at the broker, that value will be replayed first, but it will be an update of a previous last state.\nMQTT devices often continuously generate numerous state updates. MQTT does not update\nlast_reported\nto avoid impacting system stability unless\nforce_update\nis set. Alternatively, an MQTT sensor can be created to measure the last update.\nUsing Templates\nThe MQTT integration supports templating. Read more\nabout using templates with the MQTT integration\n.\nExamples\nREST API\nUsing the\nREST API\nto send a message to a given topic.\nAutomations\nUse as\nscript\nin automations.\nautomation\n:\nalias\n:\n\"Send me a message when I get home\"\ntriggers\n:\n-\ntrigger\n:\nstate\nentity_id\n:\ndevice_tracker.me\nto\n:\n\"home\"\nactions\n:\n-\naction\n:\nscript.notify_mqtt\ndata\n:\ntarget\n:\n\"me\"\nmessage\n:\n\"I'm home\"\nscript\n:\nnotify_mqtt\n:\nsequence\n:\n-\naction\n:\nmqtt.publish\ndata\n:\npayload\n:\n\"\n{{\nmessage\n}}\n\"\ntopic\n:\n\"home\/\n{{\ntarget\n}}\n\"\nretain\n:\ntrue\nYAML\nPublish & Dump actions\nThe MQTT integration will register the\nmqtt.publish\naction, which allows publishing messages to MQTT topics.\nAction: Publish\nThe\nmqtt.publish\naction publishes a message to an MQTT topic.\nData attribute\nOptional\nDescription\ntopic\nno\nTopic to publish payload to.\npayload\nyes\nPayload to publish. Will publish an empty payload when\npayload\nis omitted.\nevaluate_payload\nyes\nIf a\nbytes\nliteral in\npayload\nshould be evaluated to publish raw data. (default: false)\nqos\nyes\nQuality of Service to use. (default: 0)\nretain\nyes\nIf message should have the retain flag set. (default: false)\nNote\nWhen\npayload\nis rendered from\ntemplate\nin a YAML script or automation, and the template renders to a\nbytes\nliteral, the outgoing MQTT payload will only be sent as\nraw\ndata, if the\nevaluate_payload\noption flag is set to\ntrue\n.\ntopic\n:\nhomeassistant\/light\/1\/command\npayload\n:\n\"ON\"\nYAML\ntopic\n:\nhomeassistant\/light\/1\/state\npayload\n:\n\"\n{{\nstates\n(\n'device_tracker.paulus'\n)\n}}\n\"\nYAML\ntopic\n:\n\"homeassistant\/light\/\n{{\nstates\n(\n'sensor.light_active'\n)\n}}\n\/state\"\npayload\n:\n\"\n{{\nstates\n(\n'device_tracker.paulus'\n)\n}}\n\"\nYAML\nBe aware that\npayload\nmust be a string.\nIf you want to send JSON using the YAML editor then you need to format\/escape\nit properly. Like:\ntopic\n:\nhomeassistant\/light\/1\/state\npayload\n:\n\"{\\\"Status\\\":\\\"off\\\", \\\"Data\\\":\\\"something\\\"}\"\nYAML\nThe example below shows how to publish a temperature sensor ‘Bathroom Temperature’.\nThe\ndevice_class\nis set, so it is not needed to set the “name” option. The entity\nwill inherit the name from the\ndevice_class\nset and also support translations.\nIf you set “name” in the payload the entity name will start with the device name.\naction\n:\nmqtt.publish\ndata\n:\ntopic\n:\nhomeassistant\/sensor\/Acurite\n-\n986\n-\n1R\n-\n51778\/config\npayload\n:\n>\n-\n{\n\"device_class\"\n:\n\"temperature\"\n,\n\"unit_of_measurement\"\n:\n\"\\u00b0C\"\n,\n\"value_template\"\n:\n\"\n{{\nvalue\n|\nfloat\n}}\n\"\n,\n\"state_topic\"\n:\n\"rtl_433\/rtl433\/devices\/Acurite-986\/1R\/51778\/temperature_C\"\n,\n\"unique_id\"\n:\n\"Acurite-986-1R-51778-T\"\n,\n\"device\"\n:\n{\n\"identifiers\"\n:\n\"Acurite-986-1R-51778\"\n,\n\"name\"\n:\n\"Bathroom\"\n,\n\"model\"\n:\n\"Acurite\"\n,\n\"model_id\"\n:\n\"986\"\n,\n\"manufacturer\"\n:\n\"rtl_433\"\n}\n}\nYAML\nExample of how to use\nqos\nand\nretain\n:\ntopic\n:\nhomeassistant\/light\/1\/command\npayload\n:\n\"ON\"\nqos\n:\n2\nretain\n:\ntrue\nYAML\nAction: Dump\nThe\nmqtt.dump\naction listens to the specified topic matcher and dumps all received messages within a specific duration into the file\nmqtt_dump.txt\nin your configuration folder. This is useful when debugging a problem.\nData attribute\nOptional\nDescription\ntopic\nno\nTopic to dump. Can contain a wildcard (\n#\nor\n+\n).\nduration\nyes\nDuration in seconds that we will listen for messages. Default is 5 seconds.\ntopic\n:\nzigbee2mqtt\/\n#\nYAML\nLogging\nThe\nlogger\nintegration allows the logging of received MQTT messages.\n# Example configuration.yaml entry\nlogger\n:\ndefault\n:\nwarning\nlogs\n:\nhomeassistant.components.mqtt\n:\ndebug\nYAML\nEvent\nevent_mqtt_reloaded\nEvent\nevent_mqtt_reloaded\nis fired when Manually configured MQTT entities have been reloaded and entities thus might have changed.\nThis event has no additional data.\nRemoving the integration\nGo to\nSettings\n>\nDevices & services\nand select the integration card.\nFrom the list of devices, select the integration instance you want to remove.\nNext to the entry, select the three dots\nmenu. Then, select\nDelete\n.\nNote: This action does not remove the\nMQTT broker\nor its data. If you want to completely remove MQTT:\nCheck your\nconfiguration.yaml\nThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI.\n[Learn more]\nand other YAML files for MQTT-related configurations and remove them\nReview your automations and scripts for any MQTT dependencies\nConsider backing up your configuration before making these changes\nHelp us improve our documentation\nSuggest an edit to this page, or provide\/view feedback for this page.\nEdit\nProvide feedback\nView pending feedback","attrs_markdown":"[2026\\.4.1](https:\/\/www.home-assistant.io\/blog\/2026\/04\/01\/release-20264\/ \"Latest version 2026.4.1 released April  3, 2026\")\n\n- [Getting started](https:\/\/www.home-assistant.io\/installation\/)\n- [Documentation](https:\/\/www.home-assistant.io\/docs\/)\n  - [Installation](https:\/\/www.home-assistant.io\/installation\/)\n  - [Automations](https:\/\/www.home-assistant.io\/docs\/automation\/)\n  - [Dashboards](https:\/\/www.home-assistant.io\/dashboards\/)\n  - [Voice assistants](https:\/\/www.home-assistant.io\/voice_control\/)\n  - [Device organization](https:\/\/www.home-assistant.io\/docs\/organizing\/)\n  - [Energy management](https:\/\/www.home-assistant.io\/docs\/energy\/)\n  - [Templating](https:\/\/www.home-assistant.io\/docs\/templating\/)\n  - [Advanced configuration](https:\/\/www.home-assistant.io\/docs\/configuration\/)\n- [Our hardware](https:\/\/www.home-assistant.io\/integrations\/mqtt\/)\n  - [Home Assistant Green](https:\/\/www.home-assistant.io\/green\/)\n  - [Connect ZBT-2](https:\/\/www.home-assistant.io\/connect\/zbt-2\/)\n  - [Connect ZWA-2](https:\/\/www.home-assistant.io\/connect\/zwa-2\/)\n  - [Voice Preview Edition](https:\/\/www.home-assistant.io\/voice-pe\/)\n- [Integrations](https:\/\/www.home-assistant.io\/integrations\/)\n- [Blog](https:\/\/www.home-assistant.io\/blog\/)\n- [Need help?](https:\/\/www.home-assistant.io\/help\/)\n- Search\n  \n  ```K`\n\nOn this page\n\nConfiguration\n\n- [Configuration](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configuration)\n- [Setting up a broker](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#setting-up-a-broker)\n- [Broker configuration](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#broker-configuration)\n  - [Advanced broker configuration](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#advanced-broker-configuration)\n- [Configure MQTT options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configure-mqtt-options)\n  - [Change MQTT discovery options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#change-mqtt-discovery-options)\n  - [Discovery options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-options)\n  - [Birth and last will messages](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#birth-and-last-will-messages)\n- [Testing your setup](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#testing-your-setup)\n- [Naming of MQTT Entities](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#naming-of-mqtt-entities)\n- [Grouping entities](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#grouping-entities)\n- [MQTT Discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#mqtt-discovery)\n  - [Discovery messages](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-messages)\n  - [Discovery messages and availability](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-messages-and-availability)\n  - [Using Availability topics](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#using-availability-topics)\n  - [Discovery examples with component discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-examples-with-component-discovery)\n  - [Support by third-party tools](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#support-by-third-party-tools)\n- [Manual configured MQTT items](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#manual-configured-mqtt-items)\n  - [YAML configuration listed per item](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#yaml-configuration-listed-per-item)\n  - [YAML configuration keyed and bundled by {domain}](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#yaml-configuration-keyed-and-bundled-by-domain)\n- [Entity state updates](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#entity-state-updates)\n  - [The last reported state attribute](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#the-last-reported-state-attribute)\n- [Using Templates](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#using-templates)\n  - [Examples](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#examples)\n- [Publish & Dump actions](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#publish--dump-actions)\n  - [Action: Publish](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#action-publish)\n  - [Action: Dump](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#action-dump)\n- [Logging](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#logging)\n- [Event event\\_mqtt\\_reloaded](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#event-event_mqtt_reloaded)\n- [Removing the integration](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#removing-the-integration)\n\n[Home](https:\/\/www.home-assistant.io\/) ▸ [Integrations](https:\/\/www.home-assistant.io\/integrations\/)\n\n# MQTT\n\nMQTT (aka MQ Telemetry Transport) is a machine-to-machine or “Internet of Things” connectivity protocol on top of TCP\/IP. It allows extremely lightweight publish\/subscribe messaging transport.\n\n## Configuration\nTo add the **MQTT** service to your Home Assistant instance, use this My button:\n\n[![](https:\/\/my.home-assistant.io\/badges\/config_flow_start.svg)](https:\/\/my.home-assistant.io\/redirect\/config_flow_start?domain=mqtt)\n\nManual configuration steps\n\nIf the above My button doesn’t work, you can also perform the following steps manually:\n\n- Browse to your Home Assistant instance.\n- Go to **[Settings \\> Devices & services](https:\/\/my.home-assistant.io\/redirect\/integrations)**.\n- In the bottom right corner, select the **[Add Integration](https:\/\/my.home-assistant.io\/redirect\/config_flow_start?domain=mqtt)** button.\n- From the list, select **MQTT**.\n- Follow the instructions on screen to complete the setup.\n\nMQTT devices and entities can be set up through [MQTT discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#mqtt-discovery) or [added manually](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#manual-configured-mqtt-items) via YAML or subentries.\n\nConfiguration of MQTT components via MQTT discovery\n\n- [Alarm control panel](https:\/\/www.home-assistant.io\/integrations\/alarm_control_panel.mqtt\/)\n- [Binary sensor](https:\/\/www.home-assistant.io\/integrations\/binary_sensor.mqtt\/)\n- [Button](https:\/\/www.home-assistant.io\/integrations\/button.mqtt\/)\n- [Camera](https:\/\/www.home-assistant.io\/integrations\/camera.mqtt\/)\n- [Cover](https:\/\/www.home-assistant.io\/integrations\/cover.mqtt\/)\n- [Climate (HVAC)](https:\/\/www.home-assistant.io\/integrations\/climate.mqtt\/)\n- [Device tracker](https:\/\/www.home-assistant.io\/integrations\/device_tracker.mqtt\/)\n- [Device trigger](https:\/\/www.home-assistant.io\/integrations\/device_trigger.mqtt\/)\n- [Event](https:\/\/www.home-assistant.io\/integrations\/event.mqtt\/)\n- [Fan](https:\/\/www.home-assistant.io\/integrations\/fan.mqtt\/)\n- [Humidifier](https:\/\/www.home-assistant.io\/integrations\/humidifier.mqtt\/)\n- [Image](https:\/\/www.home-assistant.io\/integrations\/image.mqtt\/)\n- [Lawn mower](https:\/\/www.home-assistant.io\/integrations\/lawn_mower.mqtt\/)\n- [Light](https:\/\/www.home-assistant.io\/integrations\/light.mqtt\/)\n- [Lock](https:\/\/www.home-assistant.io\/integrations\/lock.mqtt\/)\n- [Notify](https:\/\/www.home-assistant.io\/integrations\/notify.mqtt\/)\n- [Number](https:\/\/www.home-assistant.io\/integrations\/number.mqtt\/)\n- [Scene](https:\/\/www.home-assistant.io\/integrations\/scene.mqtt\/)\n- [Select](https:\/\/www.home-assistant.io\/integrations\/select.mqtt\/)\n- [Sensor](https:\/\/www.home-assistant.io\/integrations\/sensor.mqtt\/)\n- [Siren](https:\/\/www.home-assistant.io\/integrations\/siren.mqtt\/)\n- [Switch](https:\/\/www.home-assistant.io\/integrations\/switch.mqtt\/)\n- [Update](https:\/\/www.home-assistant.io\/integrations\/update.mqtt\/)\n- [Tag scanner](https:\/\/www.home-assistant.io\/integrations\/tag.mqtt\/)\n- [Text](https:\/\/www.home-assistant.io\/integrations\/text.mqtt\/)\n- [Vacuum](https:\/\/www.home-assistant.io\/integrations\/vacuum.mqtt\/)\n- [Valve](https:\/\/www.home-assistant.io\/integrations\/valve.mqtt\/)\n- [Water heater](https:\/\/www.home-assistant.io\/integrations\/water_heater.mqtt\/)\n\nConfiguration of MQTT components via YAML\n\n- [Alarm control panel](https:\/\/www.home-assistant.io\/integrations\/alarm_control_panel.mqtt\/)\n- [Binary sensor](https:\/\/www.home-assistant.io\/integrations\/binary_sensor.mqtt\/)\n- [Button](https:\/\/www.home-assistant.io\/integrations\/button.mqtt\/)\n- [Camera](https:\/\/www.home-assistant.io\/integrations\/camera.mqtt\/)\n- [Climate (HVAC)](https:\/\/www.home-assistant.io\/integrations\/climate.mqtt\/)\n- [Cover](https:\/\/www.home-assistant.io\/integrations\/cover.mqtt\/)\n- [Device tracker](https:\/\/www.home-assistant.io\/integrations\/device_tracker.mqtt\/)\n- [Event](https:\/\/www.home-assistant.io\/integrations\/event.mqtt\/)\n- [Fan](https:\/\/www.home-assistant.io\/integrations\/fan.mqtt\/)\n- [Humidifier](https:\/\/www.home-assistant.io\/integrations\/humidifier.mqtt\/)\n- [Image](https:\/\/www.home-assistant.io\/integrations\/image.mqtt\/)\n- [Lawn mower](https:\/\/www.home-assistant.io\/integrations\/lawn_mower.mqtt\/)\n- [Light](https:\/\/www.home-assistant.io\/integrations\/light.mqtt\/)\n- [Lock](https:\/\/www.home-assistant.io\/integrations\/lock.mqtt\/)\n- [Notify](https:\/\/www.home-assistant.io\/integrations\/notify.mqtt\/)\n- [Number](https:\/\/www.home-assistant.io\/integrations\/number.mqtt\/)\n- [Scene](https:\/\/www.home-assistant.io\/integrations\/scene.mqtt\/)\n- [Select](https:\/\/www.home-assistant.io\/integrations\/select.mqtt\/)\n- [Sensor](https:\/\/www.home-assistant.io\/integrations\/sensor.mqtt\/)\n- [Siren](https:\/\/www.home-assistant.io\/integrations\/siren.mqtt\/)\n- [Switch](https:\/\/www.home-assistant.io\/integrations\/switch.mqtt\/)\n- [Text](https:\/\/www.home-assistant.io\/integrations\/text.mqtt\/)\n- [Update](https:\/\/www.home-assistant.io\/integrations\/update.mqtt\/)\n- [Vacuum](https:\/\/www.home-assistant.io\/integrations\/vacuum.mqtt\/)\n- [Valve](https:\/\/www.home-assistant.io\/integrations\/valve.mqtt\/)\n- [Water heater](https:\/\/www.home-assistant.io\/integrations\/water_heater.mqtt\/)\n\nConfiguration of MQTT components via Subentries\n\n- [Alarm control panel](https:\/\/www.home-assistant.io\/integrations\/alarm_control_panel.mqtt\/)\n- [Binary sensor](https:\/\/www.home-assistant.io\/integrations\/binary_sensor.mqtt\/)\n- [Button](https:\/\/www.home-assistant.io\/integrations\/button.mqtt\/)\n- [Climate (HVAC)](https:\/\/www.home-assistant.io\/integrations\/climate.mqtt\/)\n- [Cover](https:\/\/www.home-assistant.io\/integrations\/cover.mqtt\/)\n- [Fan](https:\/\/www.home-assistant.io\/integrations\/fan.mqtt\/)\n- [Image](https:\/\/www.home-assistant.io\/integrations\/image.mqtt\/)\n- [Light](https:\/\/www.home-assistant.io\/integrations\/light.mqtt\/)\n- [Lock](https:\/\/www.home-assistant.io\/integrations\/lock.mqtt\/)\n- [Notify](https:\/\/www.home-assistant.io\/integrations\/notify.mqtt\/)\n- [Number](https:\/\/www.home-assistant.io\/integrations\/number.mqtt\/)\n- [Select](https:\/\/www.home-assistant.io\/integrations\/select.mqtt\/)\n- [Sensor](https:\/\/www.home-assistant.io\/integrations\/sensor.mqtt\/)\n- [Siren](https:\/\/www.home-assistant.io\/integrations\/siren.mqtt\/)\n- [Switch](https:\/\/www.home-assistant.io\/integrations\/switch.mqtt\/)\n- [Text](https:\/\/www.home-assistant.io\/integrations\/text.mqtt\/)\n- [Valve](https:\/\/www.home-assistant.io\/integrations\/valve.mqtt\/)\n- [Water heater](https:\/\/www.home-assistant.io\/integrations\/water_heater.mqtt\/)\n\nTo add an MQTT device via a Subentry, follow these steps:\n\n1. Go to **[Settings \\> Devices & services](https:\/\/my.home-assistant.io\/redirect\/integrations)**.\n2. Select the MQTT integration.\n3. Add a subentry via [**Settings** \\> **Devices & services**](https:\/\/my.home-assistant.io\/redirect\/integrations), select\n   , and select **Add MQTT device**.\n\nA device context and one or more entities can be added to the subentry.\n\nYour first step to get MQTT and Home Assistant working is to choose a broker.\n\nThe easiest option is to install the official Mosquitto Broker app for Home Assistant (formerly known as Mosquitto Broker add-on). You can choose to set up and configure this app automatically when you set up the MQTT integration. Home Assistant will automatically generate and assign a safe username and password, and no further attention is required. This also works if you have already set up this app yourself in advance. You can set up additional logins for your MQTT devices and services using the [Mosquitto app configuration](https:\/\/my.home-assistant.io\/redirect\/supervisor_addon\/?addon=core_mosquitto).\n\nImportant\n\nWhen MQTT is set up with the official Mosquitto MQTT broker app, the broker’s credentials are generated and kept secret. If the official Mosquitto MQTT broker needs to be re-installed, make sure you save a copy of the app user options, like the additional logins. After re-installing the app, the MQTT integration will automatically update the new password for the re-installed broker. It will then reconnect automatically.\n\nAlternatively, you can use a different MQTT broker that you configure yourself, ensuring it is compatible with Home Assistant.\n\n## Setting up a broker\nWhile public MQTT brokers are available, the easiest and most private option is running your own.\n\nThe recommended setup method is to use the [Mosquitto MQTT broker app](https:\/\/github.com\/home-assistant\/hassio-addons\/blob\/master\/mosquitto\/DOCS.md).\n\nWarning\n\nNeither ActiveMQ MQTT broker nor the RabbitMQ MQTT Plugin are supported, use a known working broker like Mosquitto instead. There are [at least two](https:\/\/issues.apache.org\/jira\/browse\/AMQ-6360) [issues](https:\/\/issues.apache.org\/jira\/browse\/AMQ-6575) with the ActiveMQ MQTT broker which break MQTT message retention.\n## Broker configuration\nMQTT broker settings are configured when the MQTT integration is first set up and can be changed later if needed.\n\nAdd the MQTT integration, then provide your broker’s hostname (or IP address) and port and (if required) the username and password that Home Assistant should use. To change the settings later, follow these steps:\n\n1. Go to **[Settings \\> Devices & services](https:\/\/my.home-assistant.io\/redirect\/integrations)**.\n2. Select the MQTT integration.\n3. Reconfigure the MQTT broker settings via [**Settings** \\> **Devices & services**](https:\/\/my.home-assistant.io\/redirect\/integrations), select\n   , and select **Reconfigure**.\n\nMQTT subentries can also be reconfigured. Additional entities can be added, or an entity can be removed from the sub entry. Each MQTT subentry holds one MQTT device. The MQTT device must have at least one entity.\n\nImportant\n\nIf you experience an error message like `Failed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed`, then turn on `Advanced options` and set [Broker certificate validation](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#broker-certificate-validation) to `Auto`.\n### Advanced broker configuration\nAdvanced broker configuration options include setting a custom client ID, setting a client certificate and key for authentication, and enabling TLS validation of the broker’s certificate for secure connection. To access the advanced settings, open the MQTT broker settings, switch on **Advanced options**, and select **Next**. The advanced options will be shown by default if there are advanced settings active already.\n\nTip\n\nAdvanced broker options are accessible only when advanced mode is enabled (see user settings), or when advanced broker settings are configured already.\n#### Alternative client ID\nYou can set a custom MQTT client ID, this can help when debugging. Mind that the client ID must be unique. Leave this settings default if you want Home Assistant to generate a unique ID.\n\n#### Keep alive\nThe time in seconds between sending keep alive messages for this client. The default is 60 seconds. The keep alive setting should be at least 15 seconds.\n\n#### Broker certificate validation\nTo enable a secure connection to the broker, the broker certificate should be validated. If your broker uses a trusted certificate, then choose **Auto**. This validates the broker certificate against the bundled certificate authority (CA) certificates. If a self-signed certificate is used, select **Custom**. A custom PEM- or DER-encoded CA certificate can be uploaded. Select **Next** to show the control to upload the CA certificate. If the server certificate does not match the hostname then validation will fail. To allow a connection without the verification of the hostname, turn the **Ignore broker certificate validation** switch on.\n\n#### MQTT Protocol\nThe MQTT protocol setting defaults to version `3.1.1`. If your MQTT broker supports MQTT version 5 you can set the protocol setting to `5`.\n\n#### Securing the connection\nWith a secure broker connection, it is possible to use a client certificate for authentication. To set the client certificate and private key, turn on the option **Use a client certificate** and select **Next** to reveal file upload controls. A client certificate and the corresponding private key must be uploaded together. Both client certificate and private key must be either PEM- or DER-encoded. If the private key is encrypted with a password, ensure you supply the correct password when uploading the client certificate and key files.\n\n#### Using WebSockets as transport\nYou can select `websockets` as the transport method if your MQTT broker supports it. When you select `websockets` and select **Next**, you will be able to add a WebSockets path (default is `\/`) and WebSockets headers (optional). The target WebSockets URI `ws:\/\/{broker}:{port}{ws_path}` is built with the `broker`, `port`, and `ws_path` (WebSocket path) settings. To configure the WebSocket’s headers, supply a valid JSON dictionary string. For example, `{ \"Authorization\": \"token\" , \"x-header\": \"some header\"}`. The default transport method is `tcp`. The WebSockets transport can be secured using TLS and optionally using user credentials or a client certificate.\n\nNote\n\nA configured client certificate will only be active if broker certificate validation is enabled.\n## Configure MQTT options\nTo change the options, follow these steps:\n\n1. Go to **[Settings \\> Devices & services](https:\/\/my.home-assistant.io\/redirect\/integrations)**.\n2. Select the MQTT integration.\n3. Select **Configure**, then **Re-configure MQTT**.\n4. To open the MQTT options page, select **Next**.\n### Change MQTT discovery options\nThe MQTT discovery options can be changed by following these steps:\n\n1. Go to [**Settings** \\> **Devices & services**](https:\/\/my.home-assistant.io\/redirect\/integrations).\n2. Find the MQTT integration and select it.\n3. To open the MQTT discovery options page, select the **Configure MQTT Options** button.\n### Discovery options\nMQTT discovery is enabled by default. Discovery can be turned off. The prefix for the discovery topic (default `homeassistant`) can be changed here as well. See also [MQTT Discovery section](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#mqtt-discovery)\n\n### Birth and last will messages\nHome Assistant’s MQTT integration supports so-called Birth and Last Will and Testament (LWT) messages. The former is used to send a message after the service has started, and the latter is used to notify other clients about a disconnected client. Note that the LWT message will be sent both in case of a clean disconnect (for example, Home Assistant shutting down) and in case of an unclean disconnect (for example, Home Assistant crashing or losing its network connection).\n\nIf a disabled entity is enabled and added after 30 seconds, the MQTT integration will be reloaded and will cause all discovered MQTT entities to be unloaded. When MQTT starts up, all existing MQTT devices, entities, tags, and device triggers, will be unavailable until a discovery message is received and processed. A device or service that exposes the MQTT discovery should subscribe to the Birth message and use this as a trigger to send the [discovery payload](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-payload). To avoid high IO loads on the MQTT broker, adding some random delay in sending the discovery payload is recommended.\n\nAlternative approaches:\n\n- Retaining the [discovery payload](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-payload): This will store the discovery payload at the MQTT broker, and offer it to the MQTT integration as soon as it subscribes for MQTT discovery. When there are a lot of entities, this can cause high IO loads.\n- Periodically resending the discovery payload: This can cause some delay, or a lot of IO if there are a lot of MQTT discovery messages.\n\nBy default, Home Assistant sends `online` and `offline` to `homeassistant\/status`.\n\nMQTT Birth and Last Will messages can be customized or disabled from the UI. To do this, select **Configure** on the integration page in the UI, then **Re-configure MQTT**, and then **Next**.\n\n## Testing your setup\nThe `mosquitto` broker package ships command line tools (often as `*-clients` package) to send and receive MQTT messages. For sending test messages to a broker running on `localhost`, you can use [`mosquitto_pub`](https:\/\/mosquitto.org\/man\/mosquitto_pub-1.html), check the example below:\n\n```\nmosquitto_pub -h 127.0.0.1 -t homeassistant\/switch\/1\/on -m \"Switch is ON\"\n```\nBash\n\nCopy\n\nAnother way to send MQTT messages manually is to use the **MQTT** integration in the frontend. Select **Settings** on the left menu, select **Devices & services**, and select **Configure** in the **Mosquitto broker** tile. Enter something similar to the example below into the **topic** field under **Publish a packet** and select **Publish**.\n\n1. Go to **[Settings \\> Devices & services](https:\/\/my.home-assistant.io\/redirect\/integrations)**.\n2. Select the Mosquitto broker integration, then select **Configure**.\n3. Enter something similar to the example below into the **topic** field under **Publish a packet**. Select **Publish**.\n\n```\nhomeassistant\/switch\/1\/power\n```\nBash\n\nCopy\n\nand in the Payload field\n\n```\nON\n```\nBash\n\nCopy\n\nIn the **Listen to a topic** field, type `#` to see everything, or `homeassistant\/switch\/#` to just follow a published topic, then select **Start listening**. The messages should appear similar to the text below:\n\n```\nMessage 23 received on homeassistant\/switch\/1\/power\/stat\/POWER at 12:16 PM:\nON\nQoS: 0 - Retain: false\nMessage 22 received on homeassistant\/switch\/1\/power\/stat\/RESULT at 12:16 PM:\n{\n    \"POWER\": \"ON\"\n}\nQoS: 0 - Retain: false\n```\nBash\n\nCopy\n\nFor reading all messages sent on the topic `homeassistant` to a broker running on localhost:\n\n```\nmosquitto_sub -h 127.0.0.1 -v -t \"homeassistant\/#\"\n```\nBash\n\nCopy\n## Naming of MQTT Entities\nFor every configured MQTT entity Home Assistant automatically assigns a unique `entity_id`. If the `unique_id` option is configured, you can change the `entity_id` after creation, and the changes are stored in the Entity Registry. The `entity_id` is generated when an item is loaded the first time.\n\nIf the `default_entity_id` option is set, then this will be used to generate the `entity_id`. If, for example, we have configured a `sensor`, and we have set `default_entity_id` to `sensor.test`, then Home Assistant will try to assign `sensor.test` as `entity_id`. If `sensor.test` already exists, Home Assistant will append a suffix to make it unique, for example, `sensor.test_2`.\n\nThis means any MQTT entity which is part of a device will [automatically have its `friendly_name` attribute prefixed with the device name](https:\/\/developers.home-assistant.io\/docs\/core\/entity\/#has_entity_name-true-mandatory-for-new-integrations)\n\nUnnamed `binary_sensor`, `button`, `number`, and `sensor` entities will now be named by their device class instead of being named “MQTT binary sensor” and similar. It’s allowed to set an MQTT entity’s name to `None` (use `null` in YAML) to mark it as the main feature of a device.\n\nNote that on each MQTT entity, the `has_entity_name` attribute will be set to `True`. More details [can be found here](https:\/\/developers.home-assistant.io\/docs\/core\/entity\/#has_entity_name-true-mandatory-for-new-integrations).\n\n## Grouping entities\nIf the MQTT entity represents a group of other entities, the member entities can be made visible in the UI by setting the list of unique IDs of the member entities in the `group` configuration option of the entity group:\n\ngroup\n\nA list of unique IDs of the member entities. Set this if the entity represents a group entity. Note that the member entities must be already configured before the member entities will become visible in the UI at the moment a group entity is loaded.\n## MQTT Discovery\nThe discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](https:\/\/www.home-assistant.io\/integrations\/http\/#binary-sensor) and the [HTTP sensor](https:\/\/www.home-assistant.io\/integrations\/http\/#sensor). To prevent multiple identical entries if a device reconnects, a unique identifier is necessary. Two parts are required on the device side: The configuration topic, and the device configuration as payload.\n\nMQTT discovery is enabled by default, but can be disabled. The prefix for the discovery topic (default `homeassistant`) can be changed. See the [MQTT Options sections](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configure-mqtt-options)\n\nNote\n\nDocumentation on the MQTT components that support MQTT discovery [can be found here](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configuration-via-mqtt-discovery).\n### Discovery messages\nMQTT discovery supports two types of discovery messages:\n\n- [Device discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#device-discovery-payload), which allows you to include several components in a single discovery message\n- [Single component discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#single-component-discovery-payload), where you publish a separate discovery message for each component\n\nIf you use a device with multiple components, it is recommended to use MQTT device discovery. It reduces the number of messages sent, and allows you to send the device information only once.\n\n#### Discovery topic\nThe discovery topic needs to follow a specific format:\n\n```\n<discovery_prefix>\/<component>\/[<node_id>\/]<object_id>\/config\n```\nText\n\nCopy\n\n- `<discovery_prefix>`: The Discovery Prefix defaults to `homeassistant` and this prefix can be [changed](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-options).\n- `<component>`: One of the supported MQTT integrations, for example, `binary_sensor`, or `device` in case of device discovery.\n- `<node_id>`: (*Optional*): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. The ID of the node must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen).\n- `<object_id>`: The ID of the device. This allows for separate topics for each device. The ID of the device must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen).\n\n> **Note:** The `<object_id>` in the topic does not influence the resulting `entity_id`; use `default_entity_id` if you need to control the `entity_id`. The `<node_id>` is optional, and can be used by clients to subscribe to their own (command) topics by using one wildcard topic like `<discovery_prefix>\/+\/<node_id>\/+\/set`.\n\nBest practice for entities with a `unique_id` is to set `<object_id>` to the `unique_id` and omit the `<node_id>`.\n\n#### Device discovery payload\nA device can send a discovery payload to expose all components for a device. The `<component>` part in the discovery topic must be set to `device`.\n\nAs an alternative, it is also possible for a device [to send a discovery payload for each component](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#single-component-discovery-payload) it wants to set up.\n\nThe shared options at the root level of the JSON message must include:\n\n- `device` mapping (abbreviated as `dev`)\n- `origin` mapping (abbreviated as `o`)\n\nThese mappings are mandatory and cannot be overridden at the entity\/component level.\n\nSupported shared options are:\n\n- The `availability` [options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#using-availability-topics).\n- The `origin` (required) [options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#adding-information-about-the-origin-of-a-discovery-message)\n- `command_topic`\n- `state_topic`\n- `qos`\n- `encoding`\n\nThe component specific options are placed as mappings under the `components` key (abbreviated as `cmps`) like:\n\n```\n{\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  },\n  \"cmps\": {\n    \"some_unique_component_id1\": {\n      \"p\": \"sensor\",\n      \"device_class\":\"temperature\",\n      \"unit_of_measurement\":\"°C\",\n      \"value_template\":\"{{ value_json.temperature}}\",\n      \"unique_id\":\"temp01ae_t\"\n    },\n    \"some_unique_id2\": {\n      \"p\": \"sensor\",\n      \"device_class\":\"humidity\",\n      \"unit_of_measurement\":\"%\",\n      \"value_template\":\"{{ value_json.humidity}}\",\n      \"unique_id\":\"temp01ae_h\"\n    }\n  },\n  \"state_topic\":\"sensorBedroom\/state\",\n  \"qos\": 2\n}\n```\nJSON\n\nCopy\n\nNote\n\nTo see what each abbreviation stands for, refer to the [list of supported abbreviations in MQTT discovery messages](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#supported-abbreviations-in-mqtt-discovery-messages).\n\nThe components id’s under the `components` (`cmps`) key, are used as part of the discovery identification. A `platform` (`p`) config option is required for each component config that is added to identify the component platform. Also required is a `unique_id` for entity-based components.\n\nTo remove the components, publish an empty (retained) string payload to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it.\n\nAn empty config can be published as an update to remove a single component from the device discovery. Note that adding the `platform` (`p`) option is still required.\n\n```\n{\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  },\n  \"cmps\": {\n    \"some_unique_component_id1\": {\n      \"p\": \"sensor\",\n      \"device_class\":\"temperature\",\n      \"unit_of_measurement\":\"°C\",\n      \"value_template\":\"{{ value_json.temperature}}\",\n      \"unique_id\":\"temp01ae_t\"\n    },\n    \"some_unique_id2\": {\n      \"p\": \"sensor\"\n    }\n  },\n  \"state_topic\":\"sensorBedroom\/state\",\n  \"qos\": 2\n}\n```\nJSON\n\nCopy\n\nThis will explicitly remove the humidity sensor and its entry.\n\nAfter removing a component, you should send another update with the removed component omitted from the configuration. This ensures that Home Assistant has the most up-to-date device configuration. For example:\n\n```\n{\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  },\n  \"cmps\": {\n    \"some_unique_component_id1\": {\n      \"p\": \"sensor\",\n      \"device_class\":\"temperature\",\n      \"unit_of_measurement\":\"°C\",\n      \"value_template\":\"{{ value_json.temperature}}\",\n      \"unique_id\":\"temp01ae_t\"\n    }\n  },\n  \"state_topic\":\"sensorBedroom\/state\",\n  \"qos\": 2\n}\n```\nJSON\n\nCopy\n\nA component config part in a device discovery payload must have the `platform` (`p`) option set with the name of the `component` and also must have at least one component specific config option. Entity components must have set the `unique_id` option and have a `device` context.\n\n##### Migration from single component to device discovery\nTo allow a smooth migration from single component discovery to device discovery:\n\n1. Ensure all entities have a `unique_id` and a `device` context.\n2. Move the `object_id` inside the discovery payload, if that is available, or use a unique ID or the component.\n3. Consider using the previous `node_id` as the new `object_id` of the device discovery topic.\n4. Ensure the `unique_id` matches and the `device` context has the correct identifiers.\n5. Send the following payload to all existing single component discovery topics: `{\"migrate_discovery\": true }`. This will unload the discovered item, but its settings will be retained.\n6. Switch the discovery topic to the device discovery topic and include all the component configurations.\n7. Clean up the single component discovery messages with an empty payload.\n\nDuring the migration steps, INFO messages will be logged to inform you about the progress of the migration.\n\nImportant\n\nConsider testing the migration process in a non-production environment before applying it to a live system.\n#### Discovery migration example with a device automation and a sensor\n**Step 1: Original single component discovery configurations:**\n\nDiscovery topic single: `homeassistant\/device_automation\/0AFFD2\/bla1\/config` Discovery id: `0AFFD2 bla1` *(both `0AFFD2` and `bla1` from the discovery topic)* Discovery payload single:\n\n```\n{\n  \"device\": {\n    \"identifiers\": [\"0AFFD2\"],\n    \"name\": \"Test device\"\n  },\n  \"o\": {\n    \"name\": \"foobar\"\n  },\n  \"automation_type\": \"trigger\",\n  \"payload\": \"short_press\",\n  \"topic\": \"foobar\/triggers\/button1\",\n  \"type\": \"button_short_press\",\n  \"subtype\": \"button_1\"\n}\n```\nJSON\n\nCopy\n\nDiscovery topic single: `homeassistant\/sensor\/0AFFD2\/bla2\/config` Discovery id: `0AFFD2 bla2` *(both `0AFFD2` and `bla2` from the discovery topic)* Discovery payload single:\n\n```\n{\n  \"device\": {\n    \"identifiers\": [\"0AFFD2\"],\n    \"name\": \"Test device\"\n  },\n  \"o\": {\n    \"name\": \"foobar\"\n  },\n  \"state_topic\": \"foobar\/sensor\/sensor1\",\n  \"unique_id\": \"bla_sensor001\"\n}\n```\nJSON\n\nCopy\n\n**Step 2: Initiate migration by publishing to both discovery topics:**\n\nWhen these single component discovery payloads are processed, and we want to initiate migration to device discovery, we need to publish …\n\n```\n{\"migrate_discovery\": true }\n```\nJSON\n\nCopy\n\n… to both discovery topics …\n\n- `homeassistant\/device_automation\/0AFFD2\/bla1\/config`\n- `homeassistant\/sensor\/0AFFD2\/bla2\/config`\n\nImportant\n\nCheck the logs to ensure this step is executed correctly.\n\n**Step 3: Publish the new device discovery configuration:**\n\nDiscovery topic device: `homeassistant\/device\/0AFFD2\/config` Discovery id: `0AFFD2 bla` *(`0AFFD2`from discovery topic, `bla`: The key under `cmps` in the discovery payload)* Discovery payload device:\n\n```\n{\n  \"device\": {\n    \"identifiers\": [\n      \"0AFFD2\"\n    ]\n  },\n  \"o\": {\n    \"name\": \"foobar\"\n  },\n  \"cmps\": {\n    \"bla1\": {\n      \"p\": \"device_automation\",\n      \"automation_type\": \"trigger\",\n      \"payload\": \"short_press\",\n      \"topic\": \"foobar\/triggers\/button1\",\n      \"type\": \"button_short_press\",\n      \"subtype\": \"button_1\"\n    },\n    \"bla2\": {\n      \"p\": \"sensor\",\n      \"state_topic\": \"foobar\/sensor\/sensor1\",\n      \"unique_id\": \"bla_sensor001\"\n    }\n  }\n}\n```\nJSON\n\nCopy\n\nImportant\n\nCheck the logs to ensure the migration was successful.\n\n**Step 4: Clean up after successful migration:**\n\nAfter the logs show a successful migration, the single component discovery topics can be cleaned up safely by publishing an empty payload to them. The logs should indicate if the discovery migration was successful.\n\n**Optional: Rolling back the migration:**\n\nTo rollback publish …\n\n```\n{\"migrate_discovery\": true }\n```\nJSON\n\nCopy\n\nTo the device discovery topic(s). After that, re-publish the single component discovery payloads. At last, clean up the device discovery payloads by publishing an empty payload.\n\nCheck the logs for every step.\n\n#### Single component discovery payload\nWhen using single component discovery messages, the `<component>` part in the discovery topic must be one of the supported MQTT platforms.\n\nThe options in the payload are only used to set up one specific component. If a device contains multiple components, it is recommended to use [device discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#device-discovery-payload) instead.\n\nMQTT entities can share device configuration, meaning one entity can include the full device configuration and other entities can link to that device by only setting mandatory fields.\n\nImportant\n\nThe mandatory fields were previously limited to at least one of `connection` and `identifiers`, but have now been extended to at least one of `connection` and `identifiers` as well as the `name`.\n\nExample discovery payload:\n\n```\n{\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  },\n  \"device_class\":\"temperature\",\n  \"unit_of_measurement\":\"°C\",\n  \"value_template\":\"{{ value_json.temperature}}\",\n  \"unique_id\":\"temp01ae_t\",\n  \"state_topic\":\"sensorBedroom\/state\",\n  \"qos\": 2\n}\n```\nJSON\n\nCopy\n\nTo remove the component, publish an empty string to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it.\n\nFor more examples [see](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-examples-with-component-discovery).\n\n#### Discovery payload\nThe payload must be a serialized JSON dictionary and will be checked like an entry in your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\\[Learn more\\]](https:\/\/www.home-assistant.io\/docs\/configuration\/) file if a new device is added, with the exception that unknown configuration keys are allowed but ignored. This means that missing variables will be filled with the integration’s default values. All configuration variables which are *required* must be present in the payload. The reason for allowing unknown documentation keys is allow some backwards compatibility, software generating MQTT discovery messages can then be used with older Home Assistant versions which will simply ignore new features.\n\nA discovery payload can be sent with a retain flag set. In that case, the discovery message will be stored at the MQTT broker and processed automatically when the MQTT integrations start. This method removes the need for it to be resent. A better approach, though, is for the software generating MQTT discovery messages to send discovery payload(s) when the MQTT integration sends the [Birth message](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#birth-and-last-will-messages).\n\nSubsequent messages on a topic where a valid payload has been received will be handled as a configuration update, and a configuration update with an empty payload will cause a previously discovered device to be deleted.\n\nA base topic `~` may be defined in the payload to conserve memory when the same topic base is used multiple times. In the value of configuration variables ending with `_topic`, `~` will be replaced with the base topic, if the `~` occurs at the beginning or end of the value.\n\nConfiguration variable names in the discovery payload may be abbreviated to conserve memory when sending a discovery message from memory constrained devices.\n\nIt is recommended to add information about the origin of MQTT entities by including the `origin` option (abbreviated as `o`) in the discovery payload. For device discovery, this information is required. The origin details will be logged in the core event log when an item is discovered or updated. Adding origin information helps with troubleshooting and provides valuable context about the source of MQTT messages in your Home Assistant setup.\n\nNote: These options also support abbreviations, as shown in the table below.\n\nname\n\nThe name of the application that is the origin of the discovered MQTT item. (Required)\n\nsw\\_version\n\nSoftware version of the application that supplies the discovered MQTT item.\n\nsupport\\_url\n\nSupport URL of the application that supplies the discovered MQTT item.\n#### Supported abbreviations in MQTT discovery messages\nSupported abbreviations\n\n```\n'act_t':               'action_topic',\n'act_tpl':             'action_template',\n'atype':               'automation_type',\n'aux_cmd_t':           'aux_command_topic',\n'aux_stat_t':          'aux_state_topic',\n'aux_stat_tpl':        'aux_state_template',\n'av_tones':            'available_tones',\n'avty':                'availability',\n'avty_mode':           'availability_mode',\n'avty_t':              'availability_topic',\n'avty_tpl':            'availability_template',\n'away_mode_cmd_t':     'away_mode_command_topic',\n'away_mode_stat_t':    'away_mode_state_topic',\n'away_mode_stat_tpl':  'away_mode_state_template',\n'b_tpl':               'blue_template',\n'bri_cmd_t':           'brightness_command_topic',\n'bri_cmd_tpl':         'brightness_command_template',\n'bri_scl':             'brightness_scale',\n'bri_stat_t':          'brightness_state_topic',\n'bri_tpl':             'brightness_template',\n'bri_val_tpl':         'brightness_value_template',\n'clr_temp_cmd_tpl':    'color_temp_command_template',\n'clr_temp_cmd_t':      'color_temp_command_topic',\n'clr_temp_k':           'color_temp_kelvin',\n'clr_temp_stat_t':     'color_temp_state_topic',\n'clr_temp_tpl':        'color_temp_template',\n'clr_temp_val_tpl':    'color_temp_value_template',\n'clrm_stat_t':         'color_mode_state_topic',\n'clrm_val_tpl':        'color_mode_value_template',\n'cmd_off_tpl':         'command_off_template',\n'cmd_on_tpl':          'command_on_template',\n'cmd_t':               'command_topic',\n'cmd_tpl':             'command_template',\n'cmps':                'components',\n'cod_arm_req':         'code_arm_required',\n'cod_dis_req':         'code_disarm_required',\n'cod_trig_req':        'code_trigger_required',\n'cont_type':           'content_type',\n'curr_temp_t':         'current_temperature_topic',\n'curr_temp_tpl':       'current_temperature_template',\n'def_ent_id':          'default_entity_id',\n'dev':                 'device',\n'dev_cla':             'device_class',\n'dir_cmd_t':           'direction_command_topic',\n'dir_cmd_tpl':         'direction_command_template',\n'dir_stat_t':          'direction_state_topic',\n'dir_val_tpl':         'direction_value_template',\n'dsp_prc':             'display_precision',\n'e':                   'encoding',\n'en':                  'enabled_by_default',\n'ent_cat':             'entity_category',\n'ent_pic':             'entity_picture',\n'evt_typ':             'event_types',\n'exp_aft':             'expire_after',\n'fanspd_lst':          'fan_speed_list',\n'flsh':                'flash',\n'flsh_tlng':           'flash_time_long',\n'flsh_tsht':           'flash_time_short',\n'fx_cmd_t':            'effect_command_topic',\n'fx_cmd_tpl':          'effect_command_template',\n'fx_list':             'effect_list',\n'fx_stat_t':           'effect_state_topic',\n'fx_tpl':              'effect_template',\n'fx_val_tpl':          'effect_value_template',\n'fan_mode_cmd_t':      'fan_mode_command_topic',\n'fan_mode_cmd_tpl':    'fan_mode_command_template',\n'fan_mode_stat_t':     'fan_mode_state_topic',\n'fan_mode_stat_tpl':   'fan_mode_state_template',\n'frc_upd':             'force_update',\n'g_tpl':               'green_template',\n'grp':                 'group',\n'hs_cmd_t':            'hs_command_topic',\n'hs_cmd_tpl':          'hs_command_template',\n'hs_stat_t':           'hs_state_topic',\n'hs_val_tpl':          'hs_value_template',\n'ic':                  'icon',\n'img_e':               'image_encoding',\n'img_t':               'image_topic',\n'init':                'initial',\n'hum_cmd_t':           'target_humidity_command_topic',\n'hum_cmd_tpl':         'target_humidity_command_template',\n'hum_stat_t':          'target_humidity_state_topic',\n'hum_state_tpl':       'target_humidity_state_template',\n'json_attr':           'json_attributes',\n'json_attr_t':         'json_attributes_topic',\n'json_attr_tpl':       'json_attributes_template',\n'l_ver_t':             'latest_version_topic',\n'l_ver_tpl':           'latest_version_template',\n'lrst_t':              'last_reset_topic',\n'lrst_val_tpl':        'last_reset_value_template',\n'max':                 'max',\n'max_hum':             'max_humidity',\n'max_k':               'max_kelvin',\n'max_mirs':            'max_mireds',\n'max_temp':            'max_temp',\n'migr_discvry':        'migrate_discovery',\n'min':                 'min',\n'min_hum':             'min_humidity',\n'min_k':               'min_kelvin',\n'min_mirs':            'min_mireds',\n'min_temp':            'min_temp',\n'mode':                'mode',\n'mode_cmd_t':          'mode_command_topic',\n'mode_cmd_tpl':        'mode_command_template',\n'mode_stat_t':         'mode_state_topic',\n'mode_stat_tpl':       'mode_state_template',\n'modes':               'modes',\n'name':                'name',\n'o':                   'origin',\n'off_dly':             'off_delay',\n'on_cmd_type':         'on_command_type',\n'ops':                 'options',\n'opt':                 'optimistic',\n'osc_cmd_t':           'oscillation_command_topic',\n'osc_cmd_tpl':         'oscillation_command_template',\n'osc_stat_t':          'oscillation_state_topic',\n'osc_val_tpl':         'oscillation_value_template',\n'p':                   'platform',\n'pct_cmd_t':           'percentage_command_topic',\n'pct_cmd_tpl':         'percentage_command_template',\n'pct_stat_t':          'percentage_state_topic',\n'pct_val_tpl':         'percentage_value_template',\n'pl':                  'payload',\n'pl_arm_away':         'payload_arm_away',\n'pl_arm_custom_b':     'payload_arm_custom_bypass',\n'pl_arm_home':         'payload_arm_home',\n'pl_arm_nite':         'payload_arm_night',\n'pl_arm_vacation':     'payload_arm_vacation',\n'pl_avail':            'payload_available',\n'pl_cln_sp':           'payload_clean_spot',\n'pl_cls':              'payload_close',\n'pl_dir_fwd':          'payload_direction_forward',\n'pl_dir_rev':          'payload_direction_reverse',\n'pl_disarm':           'payload_disarm',\n'pl_home':             'payload_home',\n'pl_inst':             'payload_install',\n'pl_loc':              'payload_locate',\n'pl_lock':             'payload_lock',\n'pl_not_avail':        'payload_not_available',\n'pl_not_home':         'payload_not_home',\n'pl_off':              'payload_off',\n'pl_on':               'payload_on',\n'pl_open':             'payload_open',\n'pl_osc_off':          'payload_oscillation_off',\n'pl_osc_on':           'payload_oscillation_on',\n'pl_paus':             'payload_pause',\n'pl_prs':              'payload_press',\n'pl_ret':              'payload_return_to_base',\n'pl_rst':              'payload_reset',\n'pl_rst_hum':          'payload_reset_humidity',\n'pl_rst_mode':         'payload_reset_mode',\n'pl_rst_pct':          'payload_reset_percentage',\n'pl_rst_pr_mode':      'payload_reset_preset_mode',\n'pl_stop':             'payload_stop',\n'pl_stop_tilt':        'payload_stop_tilt',\n'pl_stpa':             'payload_start_pause',\n'pl_strt':             'payload_start',\n'pl_toff':             'payload_turn_off',\n'pl_ton':              'payload_turn_on',\n'pl_trig':             'payload_trigger',\n'pl_unlk':             'payload_unlock',\n'pos':                 'reports_position',\n'pos_clsd':            'position_closed',\n'pos_open':            'position_open',\n'pr_mode_cmd_t':       'preset_mode_command_topic',\n'pr_mode_cmd_tpl':     'preset_mode_command_template',\n'pr_mode_stat_t':      'preset_mode_state_topic',\n'pr_mode_val_tpl':     'preset_mode_value_template',\n'pr_modes':            'preset_modes',\n'ptrn':                'pattern',\n'r_tpl':               'red_template',\n'rel_s':               'release_summary',\n'rel_u':               'release_url',\n'ret':                 'retain',\n'rgb_cmd_t':           'rgb_command_topic',\n'rgb_cmd_tpl':         'rgb_command_template',\n'rgb_stat_t':          'rgb_state_topic',\n'rgb_val_tpl':         'rgb_value_template',\n'rgbw_cmd_t':          'rgbw_command_topic',\n'rgbw_cmd_tpl':        'rgbw_command_template',\n'rgbw_stat_t':         'rgbw_state_topic',\n'rgbw_val_tpl':        'rgbw_value_template',\n'rgbww_cmd_t':         'rgbww_command_topic',\n'rgbww_cmd_tpl':       'rgbww_command_template',\n'rgbww_stat_t':        'rgbww_state_topic',\n'rgbww_val_tpl':       'rgbww_value_template',\n'send_cmd_t':          'send_command_topic',\n'send_if_off':         'send_if_off',\n'set_fan_spd_t':       'set_fan_speed_topic',\n'set_pos_t':           'set_position_topic',\n'set_pos_tpl':         'set_position_template',\n'pos_t':               'position_topic',\n'pos_tpl':             'position_template',\n'spd_rng_min':         'speed_range_min',\n'spd_rng_max':         'speed_range_max',\n'src_type':            'source_type',\n'stat_cla':            'state_class',\n'stat_closing':        'state_closing',\n'stat_clsd':           'state_closed',\n'stat_jam':            'state_jammed',\n'stat_locked':         'state_locked',\n'stat_locking':        'state_locking',\n'stat_off':            'state_off',\n'stat_on':             'state_on',\n'stat_open':           'state_open',\n'stat_opening':        'state_opening',\n'stat_stopped':        'state_stopped',\n'stat_unlocked':       'state_unlocked',\n'stat_unlocking':      'state_unlocking',\n'stat_t':              'state_topic',\n'stat_tpl':            'state_template',\n'stat_val_tpl':        'state_value_template',\n'step':                'step',\n'stype':               'subtype',\n'sug_dsp_prc':         'suggested_display_precision',\n'sup_clrm':            'supported_color_modes',\n'sup_dur':             'support_duration',\n'sup_vol':             'support_volume_set',\n'sup_feat':            'supported_features',\n'swing_mode_cmd_t':    'swing_mode_command_topic',\n'swing_mode_cmd_tpl':  'swing_mode_command_template',\n'swing_mode_stat_t':   'swing_mode_state_topic',\n'swing_mode_stat_tpl': 'swing_mode_state_template',\n't':                   'topic',\n'temp_cmd_t':          'temperature_command_topic',\n'temp_cmd_tpl':        'temperature_command_template',\n'temp_hi_cmd_t':       'temperature_high_command_topic',\n'temp_hi_cmd_tpl':     'temperature_high_command_template',\n'temp_hi_stat_t':      'temperature_high_state_topic',\n'temp_hi_stat_tpl':    'temperature_high_state_template',\n'temp_lo_cmd_t':       'temperature_low_command_topic',\n'temp_lo_cmd_tpl':     'temperature_low_command_template',\n'temp_lo_stat_t':      'temperature_low_state_topic',\n'temp_lo_stat_tpl':    'temperature_low_state_template',\n'temp_stat_t':         'temperature_state_topic',\n'temp_stat_tpl':       'temperature_state_template',\n'temp_unit':           'temperature_unit',\n'tilt_clsd_val':       'tilt_closed_value',\n'tilt_cmd_t':          'tilt_command_topic',\n'tilt_cmd_tpl':        'tilt_command_template',\n'tilt_max':            'tilt_max',\n'tilt_min':            'tilt_min',\n'tilt_opnd_val':       'tilt_opened_value',\n'tilt_opt':            'tilt_optimistic',\n'tilt_status_t':       'tilt_status_topic',\n'tilt_status_tpl':     'tilt_status_template',\n'tit':                 'title',\n'trns':                'transition',\n'uniq_id':             'unique_id',\n'unit_of_meas':        'unit_of_measurement',\n'url_t':               'url_topic',\n'url_tpl':             'url_template',\n'val_tpl':             'value_template',\n'whit_cmd_t':          'white_command_topic',\n'whit_scl':            'white_scale',\n'xy_cmd_t':            'xy_command_topic',\n'xy_cmd_tpl':          'xy_command_template',\n'xy_stat_t':           'xy_state_topic',\n'xy_val_tpl':          'xy_value_template',\n```\nTxt\n\nCopy\n\nSupported abbreviations for device registry configuration\n\n```\n'cu':                  'configuration_url',\n'cns':                 'connections',\n'ids':                 'identifiers',\n'name':                'name',\n'mf':                  'manufacturer',\n'mdl':                 'model',\n'mdl_id':              'model_id',\n'hw':                  'hw_version',\n'sw':                  'sw_version',\n'sa':                  'suggested_area',\n'sn':                  'serial_number',\n```\nTxt\n\nCopy\n\nSupported abbreviations for origin info\n\n```\n'name':                'name',\n'sw':                  'sw_version',\n'url':                 'support_url',\n```\nTxt\n\nCopy\n### Discovery messages and availability\nWhen MQTT discovery is set up, and a device or service sends a discovery message, an MQTT entity, tag, or device automation will be set up directly after receiving the message. When Home Assistant is restarting, discovered MQTT items with a unique ID will be unavailable until a new discovery message is received. MQTT items without a unique ID will not be added at startup. So a device or service using MQTT discovery must make sure a configuration message is offered after the **MQTT** integration has been (re)started. There are two common approaches to make sure the discovered items are set up at startup:\n\n1. Using Birth and Will messages to trigger setup\n2. Using retained messages\n\nFinally, it is a best practice to publish your device or service availability status.\n\n#### Use the Birth and Will messages to trigger discovery\nWhen the **MQTT** integration starts, a birth message is published at `homeassistant\/status` by default. A device or service connected to the shared `mqtt` broker can subscribe to this topic and use an `online` message to trigger discovery messages. See also the [birth and last will messages](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#birth-and-last-will-messages) section. After the configs have been published, the state topics will need an update, so they need to be republished.\n\n#### Using retained config messages\nAn alternative method for a device or service is to publish discovery messages with a `retain` flag. This will make sure discovery messages are replayed when the **MQTT** integration connects to the broker. After the configs have been published, the state topics will need an update.\n\n#### Using retained state messages\nState updates also need to be re-published after a config as been processed. This can also be done by publishing `retained` messages. As soon as a config is received (or replayed from a retained message), the setup will subscribe any state topics. If a retained message is available at a state topic, this message will be replayed so that the state can be restored for this topic.\n\nWarning\n\nA disadvantage of using retained messages is that these messages retain at the broker, even when the device or service stops working. They are retained even after the system or broker has been restarted. Retained messages can create ghost entities that keep coming back.   \n  \n Especially when you have many entities, (unneeded) discovery messages can cause excessive system load. For this reason, use discovery messages with caution.\n### Using Availability topics\nA device or service can announce its availability by publishing a Birth message and set a Will message at the broker. When the device or service loses connection to the broker, the broker will publish the Will message. This allows the **MQTT** integration to make an entity unavailable.\n\nPlatform specific availability settings are available for `mqtt` entity platforms only.\n\nPlatform specific availability settings\n\n#### Configuration Variables\n[Looking for your configuration file?](https:\/\/www.home-assistant.io\/docs\/configuration\/)\n\navailability list (Optional)\n\nA list of MQTT topics subscribed to receive availability (online\/offline) updates. Must not be used together with `availability_topic`.\n\npayload\\_available string (Optional, default: online)\n\nThe payload that represents the available state.\n\npayload\\_not\\_available string (Optional, default: offline)\n\nThe payload that represents the unavailable state.\n\ntopic string Required\n\nAn MQTT topic subscribed to receive availability (online\/offline) updates.\n\nvalue\\_template [template](https:\/\/www.home-assistant.io\/docs\/configuration\/templating\/) (Optional)\n\nDefines a [template](https:\/\/www.home-assistant.io\/docs\/templating\/where-to-use\/#mqtt) to extract a device’s availability from the `topic`. To determine the device’s availability, the result of this template will be compared to `payload_available` and `payload_not_available`.\n\navailability\\_topic string (Optional)\n\nThe MQTT topic subscribed to receive availability (online\/offline) updates. Must not be used together with `availability`.\n\navailability\\_mode string (Optional, default: latest)\n\nWhen `availability` is configured, this controls the conditions needed to set the entity to `available`. Valid entries are `all`, `any`, and `latest`. If set to `all`, `payload_available` must be received on all configured availability topics before the entity is marked as online. If set to `any`, `payload_available` must be received on at least one configured availability topic before the entity is marked as online. If set to `latest`, the last `payload_available` or `payload_not_available` received on any configured availability topic controls the availability.\n\navailability\\_template [template](https:\/\/www.home-assistant.io\/docs\/configuration\/templating\/) (Optional)\n\nDefines a [template](https:\/\/www.home-assistant.io\/docs\/templating\/where-to-use\/#mqtt) to extract device’s availability from the `availability_topic`. To determine the devices’s availability result of this template will be compared to `payload_available` and `payload_not_available`.\n\npayload\\_available string (Optional, default: online)\n\nThe payload that represents the available state.\n\npayload\\_not\\_available string (Optional, default: offline)\n\nThe payload that represents the unavailable state.\n### Discovery examples with component discovery\n#### Motion detection (binary sensor)\nA motion detection device which can be represented by a [binary sensor](https:\/\/www.home-assistant.io\/integrations\/binary_sensor.mqtt\/) for your garden would send its configuration as JSON payload to the Configuration topic. After the first message to `config`, then the MQTT messages sent to the state topic will update the state in Home Assistant.\n\n- Configuration topic: `homeassistant\/binary_sensor\/garden\/config`\n- State topic: `homeassistant\/binary_sensor\/garden\/state`\n- Configuration payload with derived device name:\n\n```\n{\n   \"name\":null,\n   \"device_class\":\"motion\",\n   \"state_topic\":\"homeassistant\/binary_sensor\/garden\/state\",\n   \"unique_id\":\"motion01ad\",\n   \"device\":{\n      \"identifiers\":[\n         \"01ad\"\n      ],\n      \"name\":\"Garden\"\n   }\n}\n```\nJSON\n\nCopy\n\n- Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts.\n\nIt is also a good idea to add a `unique_id` to allow changes to the entity and a `device` mapping so we can group all sensors of a device together. We can set “name” to `null` if we want to inherit the device name for the entity. If we set an entity name, the `friendly_name` will be a combination of the device and entity name. If `name` is left away and a `device_class` is set, the entity name part will be derived from the `device_class`.\n\n- Example configuration payload with no name set and derived `device_class` name:\n\n```\n{\n   \"name\":null,\n   \"device_class\":\"motion\",\n   \"state_topic\":\"homeassistant\/binary_sensor\/garden\/state\",\n   \"unique_id\":\"motion01ad\",\n   \"device\":{\n      \"identifiers\":[\n         \"01ad\"\n      ],\n      \"name\":\"Garden\"\n   }\n}\n```\nJSON\n\nCopy\n\nIf no name is set, a default name will be set by MQTT ([see the MQTT platform documentation](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#mqtt-discovery)).\n\nTo create a new sensor manually and with the name set to `null` to derive the device name “Garden”:\n\n```\nmosquitto_pub -r -h 127.0.0.1 -p 1883 -t \"homeassistant\/binary_sensor\/garden\/config\" -m '{\"name\": null, \"device_class\": \"motion\", \"state_topic\": \"homeassistant\/binary_sensor\/garden\/state\", \"unique_id\": \"motion01ad\", \"device\": {\"identifiers\": [\"01ad\"], \"name\": \"Garden\" }}'\n```\nBash\n\nCopy\n\nUpdate the state:\n\n```\nmosquitto_pub -h 127.0.0.1 -p 1883 -t \"homeassistant\/binary_sensor\/garden\/state\" -m ON\n```\nBash\n\nCopy\n\nDelete the sensor by sending an empty message.\n\n```\nmosquitto_pub -h 127.0.0.1 -p 1883 -t \"homeassistant\/binary_sensor\/garden\/config\" -m ''\n```\nBash\n\nCopy\n\nFor more details, refer to the [MQTT testing section](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#testing-your-setup).\n\n#### Sensors\nSetting up a sensor with multiple measurement values requires multiple consecutive configuration topic submissions.\n\n- Configuration topic no1: `homeassistant\/sensor\/sensorBedroomT\/config`\n- Configuration payload no1:\n\n```\n{\n   \"device_class\":\"temperature\",\n   \"state_topic\":\"homeassistant\/sensor\/sensorBedroom\/state\",\n   \"unit_of_measurement\":\"°C\",\n   \"value_template\":\"{{ value_json.temperature}}\",\n   \"unique_id\":\"temp01ae\",\n   \"device\":{\n      \"identifiers\":[\n          \"bedroom01ae\"\n      ],\n      \"name\":\"Bedroom\",\n      \"manufacturer\": \"Example sensors Ltd.\",\n      \"model\": \"Example Sensor\",\n      \"model_id\": \"K9\",\n      \"serial_number\": \"12AE3010545\",\n      \"hw_version\": \"1.01a\",\n      \"sw_version\": \"2024.1.0\",\n      \"configuration_url\": \"<https:\/\/example.com\/sensor_portal\/config>\"\n   }\n}\n```\nJSON\n\nCopy\n\n- Configuration topic no2: `homeassistant\/sensor\/sensorBedroomH\/config`\n- Configuration payload no2:\n\n```\n{\n   \"device_class\":\"humidity\",\n   \"state_topic\":\"homeassistant\/sensor\/sensorBedroom\/state\",\n   \"unit_of_measurement\":\"%\",\n   \"value_template\":\"{{ value_json.humidity}}\",\n   \"unique_id\":\"hum01ae\",\n   \"device\":{\n      \"identifiers\":[\n         \"bedroom01ae\"\n      ]\n   }\n}\n```\nJSON\n\nCopy\n\nThe sensor [`identifiers` or `connections`](https:\/\/www.home-assistant.io\/integrations\/sensor.mqtt\/#device) option allows to set up multiple entities that share the same device.\n\nNote\n\nIf a device configuration is shared, then it is not needed to add all device details to the other entity configs. It is enough to add shared identifiers or connections to the device mapping for the other entity config payloads.\n\nA common state payload that can be parsed with the `value_template` in the sensor configs:\n\n```\n{\n   \"temperature\":23.20,\n   \"humidity\":43.70\n}\n```\nJSON\n\nCopy\n#### Entities with command topics\nSetting up a light or switch is similar but requires a `command_topic` as mentioned in the [MQTT switch documentation](https:\/\/www.home-assistant.io\/integrations\/switch.mqtt\/).\n\n- Configuration topic: `homeassistant\/switch\/irrigation\/config`\n- State topic: `homeassistant\/switch\/irrigation\/state`\n- Command topic: `homeassistant\/switch\/irrigation\/set`\n- Payload:\n\n```\n{\n   \"name\":\"Irrigation\",\n   \"command_topic\":\"homeassistant\/switch\/irrigation\/set\",\n   \"state_topic\":\"homeassistant\/switch\/irrigation\/state\",\n   \"unique_id\":\"irr01ad\",\n   \"device\":{\n      \"identifiers\":[\n         \"garden01ad\"\n      ],\n      \"name\":\"Garden\"\n   }\n}\n```\nJSON\n\nCopy\n\n- Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts.\n\n```\nmosquitto_pub -r -h 127.0.0.1 -p 1883 -t \"homeassistant\/switch\/irrigation\/config\" \\\n  -m '{\"name\": \"Irrigation\", \"command_topic\": \"homeassistant\/switch\/irrigation\/set\", \"state_topic\": \"homeassistant\/switch\/irrigation\/state\", \"unique_id\": \"irr01ad\", \"device\": {\"identifiers\": [\"garden01ad\"], \"name\": \"Garden\" }}'\n```\nBash\n\nCopy\n\nSet the state:\n\n```\nmosquitto_pub -h 127.0.0.1 -p 1883 -t \"homeassistant\/switch\/irrigation\/set\" -m ON\n```\nBash\n\nCopy\n#### Using abbreviations and base topic\nSetting up a switch using topic prefix and abbreviated configuration variable names to reduce payload length.\n\n- Configuration topic: `homeassistant\/switch\/irrigation\/config`\n- Command topic: `homeassistant\/switch\/irrigation\/set`\n- State topic: `homeassistant\/switch\/irrigation\/state`\n- Configuration payload:\n\n```\n{\n   \"~\":\"homeassistant\/switch\/irrigation\",\n   \"name\":\"garden\",\n   \"cmd_t\":\"~\/set\",\n   \"stat_t\":\"~\/state\"\n}\n```\nJSON\n\nCopy\n\nNote\n\nTo see what each abbreviation stands for, refer to the [list of supported abbreviations in MQTT discovery messages](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#supported-abbreviations-in-mqtt-discovery-messages).\n#### Another example using abbreviations topic name and base topic\nSetting up a [light that takes JSON payloads](https:\/\/www.home-assistant.io\/integrations\/light.mqtt\/#json-schema), with abbreviated configuration variable names:\n\n- Configuration topic: `homeassistant\/light\/kitchen\/config`\n- Command topic: `homeassistant\/light\/kitchen\/set`\n- State topic: `homeassistant\/light\/kitchen\/state`\n- Example state payload: `{\"state\": \"ON\", \"brightness\": 255}`\n- Configuration payload:\n  ```\n  {\n  \"~\": \"homeassistant\/light\/kitchen\",\n  \"name\": \"Kitchen\",\n  \"uniq_id\": \"kitchen_light\",\n  \"cmd_t\": \"~\/set\",\n  \"stat_t\": \"~\/state\",\n  \"schema\": \"json\",\n  \"brightness\": true\n}\n  ```\n  JSON\n  \n  Copy\n#### Example with using abbreviated Device and Origin info in discovery messages\n```\n{\n  \"~\": \"homeassistant\/light\/kitchen\",\n  \"name\": null,\n  \"uniq_id\": \"kitchen_light\",\n  \"cmd_t\": \"~\/set\",\n  \"stat_t\": \"~\/state\",\n  \"schema\": \"json\",\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"mdl_id\": \"ABC123\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  }\n}\n```\nJSON\n\nCopy\n### Support by third-party tools\nThe following software has built-in support for MQTT discovery:\n\n- [anpr2mqtt](https:\/\/anpr2mqtt.rhizomatics.org.uk\/)\n- [ArduinoHA](https:\/\/github.com\/dawidchyrzynski\/arduino-home-assistant)\n- [Arilux AL-LC0X LED controllers](https:\/\/github.com\/smrtnt\/Arilux_AL-LC0X)\n- [ble2mqtt](https:\/\/github.com\/devbis\/ble2mqtt)\n- [diematic\\_server](https:\/\/github.com\/IgnacioHR\/diematic_server)\n- [digitalstrom-mqtt](https:\/\/github.com\/gaetancollaud\/digitalstrom-mqtt)\n- [ebusd](https:\/\/github.com\/john30\/ebusd)\n- [ecowitt2mqtt](https:\/\/github.com\/bachya\/ecowitt2mqtt)\n- [EMS-ESP32 (and EMS-ESP)](https:\/\/github.com\/emsesp\/EMS-ESP32)\n- [ESPHome](https:\/\/esphome.io\/)\n- [ESPurna](https:\/\/github.com\/xoseperez\/espurna)\n- [go-iotdevice](https:\/\/github.com\/koestler\/go-iotdevice)\n- [HASS.Agent](https:\/\/github.com\/LAB02-Research\/HASS.Agent)\n- [IOTLink](https:\/\/iotlink.gitlab.io\/) (starting with 2.0.0)\n- [MiFlora MQTT Daemon](https:\/\/github.com\/ThomDietrich\/miflora-mqtt-daemon)\n- [MyElectricalData](https:\/\/github.com\/MyElectricalData\/myelectricaldata_import#english)\n- [MqDockerUp](https:\/\/github.com\/MichelFR\/MqDockerUp)\n- [Nuki Hub](https:\/\/github.com\/technyon\/nuki_hub)\n- [Nuki Smart Lock 3.0 Pro](https:\/\/support.nuki.io\/hc\/articles\/12947926779409-MQTT-support), [more info](https:\/\/developer.nuki.io\/t\/mqtt-api-specification-v1-3\/17626)\n- [OpenMQTTGateway](https:\/\/github.com\/1technophile\/OpenMQTTGateway)\n- [OTGateway](https:\/\/github.com\/Laxilef\/OTGateway)\n- [rethink](https:\/\/github.com\/anszom\/rethink)\n- [room-assistant](https:\/\/github.com\/mKeRix\/room-assistant) (starting with 1.1.0)\n- [SmartHome](https:\/\/github.com\/roncoa\/SmartHome)\n- [SpeedTest-CLI MQTT](https:\/\/github.com\/adorobis\/speedtest-CLI2mqtt)\n- [SwitchBot-MQTT-BLE-ESP32](https:\/\/github.com\/devWaves\/SwitchBot-MQTT-BLE-ESP32)\n- [Tasmota](https:\/\/github.com\/arendst\/Tasmota) (starting with 5.11.1e, development halted)\n- [TeddyCloud](https:\/\/github.com\/toniebox-reverse-engineering\/teddycloud)\n- [Teleinfo MQTT](https:\/\/fmartinou.github.io\/teleinfo2mqtt) (starting with 3.0.0)\n- [Tydom2MQTT](https:\/\/tydom2mqtt.github.io\/tydom2mqtt\/)\n- [Updates2MQTT](https:\/\/updates2mqtt.rhizomatics.org.uk\/)\n- [What’s up Docker?](https:\/\/fmartinou.github.io\/whats-up-docker\/) (starting with 3.5.0)\n- [WyzeSense2MQTT](https:\/\/github.com\/raetha\/wyzesense2mqtt)\n- [Xiaomi DaFang Hacks](https:\/\/github.com\/EliasKotlyar\/Xiaomi-Dafang-Hacks)\n- [Zehnder Comfoair RS232 MQTT](https:\/\/github.com\/adorobis\/hacomfoairmqtt)\n- [Zigbee2MQTT](https:\/\/github.com\/koenkk\/zigbee2mqtt)\n\nThe following software also supports consuming MQTT discovery information that is intended for Home Assistant. Compatibility and features will vary, and not all devices may work.\n\n- [Domoticz](https:\/\/wiki.domoticz.com\/MQTT#Add_hardware_.22MQTT_Auto_Discovery_Client_Gateway.22)\n- [openHAB](https:\/\/www.openhab.org\/addons\/bindings\/mqtt.homeassistant\/)\n## Manual configured MQTT items\nSupport to allow [adding manual items as a subentry via a config flow](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configuration), is work in progress. Not all entity platforms are supported yet.\n\nFor most integrations, it is also possible to manually set up MQTT items in `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\\[Learn more\\]](https:\/\/www.home-assistant.io\/docs\/configuration\/). Read more [about configuration in YAML](https:\/\/www.home-assistant.io\/docs\/configuration\/yaml).\n\nMQTT supports two styles for configuring items in YAML. All configuration items are placed directly under the `mqtt` integration key. Note that you cannot mix these styles. Use the *YAML configuration listed per item* style when in doubt.\n\n### YAML configuration listed per item\nThis method expects all items to be in a YAML list. Each item has a `{domain}` key and the item config is placed directly under the domain key. This method is considered as best practice. In all the examples we use this format.\n\n```\nmqtt:\n  - {domain}:\n      name: \"\"\n      ...\n  - {domain}:\n      name: \"\"\n      ...\n```\nYAML\n\nCopy\n### YAML configuration keyed and bundled by `{domain}`\nAll items are grouped per `{domain}` and where all configs are listed.\n\n```\nmqtt:\n  {domain}:\n    - name: \"\"\n      ...\n    - name: \"\"\n      ...\n```\nYAML\n\nCopy\n\nIf you have a large number of manually configured items, you might want to consider [splitting up the configuration](https:\/\/www.home-assistant.io\/docs\/configuration\/splitting_configuration\/).\n\nNote\n\nDocumentation on the MQTT components that support YAML [can be found here](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configuration-via-yaml).\n## Entity state updates\nEntities receive state updates via MQTT subscriptions. The payloads received on the state topics are processed to determine whether there is a significant change. If a change is detected, the entity will be updated.\n\nNote that MQTT device payloads often contain information for updating multiple entities that subscribe to the same topics. For example, a light status update might include information about link quality. This data can update a link quality sensor but is not used to update the light itself. MQTT filters out entity state updates when there are no changes.\n\n### The last reported state attribute\nBecause MQTT state updates are often repeated frequently, even when no actual changes exist, it is up to the MQTT subscriber to determine whether a status update was received. If the latest update is missed, it might take some time before the next one arrives. If a retained payload exists at the broker, that value will be replayed first, but it will be an update of a previous last state.\n\nMQTT devices often continuously generate numerous state updates. MQTT does not update `last_reported` to avoid impacting system stability unless `force_update` is set. Alternatively, an MQTT sensor can be created to measure the last update.\n\n## Using Templates\nThe MQTT integration supports templating. Read more [about using templates with the MQTT integration](https:\/\/www.home-assistant.io\/docs\/templating\/where-to-use\/#mqtt).\n\n### Examples\n#### REST API\nUsing the [REST API](https:\/\/developers.home-assistant.io\/docs\/api\/rest\/) to send a message to a given topic.\n\n```\n$ curl -X POST \\\n    -H \"Authorization: Bearer ABCDEFGH\" \\\n    -H \"Content-Type: application\/json\" \\\n    -d '{\"payload\": \"Test message from HA\", \"topic\": \"home\/notification\"}' \\\n    <http:\/\/IP_ADDRESS:8123\/api\/services\/mqtt\/publish>\n```\nBash\n\nCopy\n#### Automations\nUse as [`script`](https:\/\/www.home-assistant.io\/integrations\/script\/) in automations.\n\n```\nautomation:\n  alias: \"Send me a message when I get home\"\n  triggers:\n    - trigger: state\n      entity_id: device_tracker.me\n      to: \"home\"\n  actions:\n    - action: script.notify_mqtt\n      data:\n        target: \"me\"\n        message: \"I'm home\"\n\nscript:\n  notify_mqtt:\n    sequence:\n      - action: mqtt.publish\n        data:\n          payload: \"{{ message }}\"\n          topic: \"home\/{{ target }}\"\n          retain: true\n```\nYAML\n\nCopy\n## Publish & Dump actions\nThe MQTT integration will register the `mqtt.publish` action, which allows publishing messages to MQTT topics.\n\n### Action: Publish\nThe `mqtt.publish` action publishes a message to an MQTT topic.\n\n| Data attribute | Optional | Description |\n|---|---|---|\n| `topic` | no | Topic to publish payload to. |\n| `payload` | yes | Payload to publish. Will publish an empty payload when `payload` is omitted. |\n| `evaluate_payload` | yes | If a `bytes` literal in `payload` should be evaluated to publish raw data. (default: false) |\n| `qos` | yes | Quality of Service to use. (default: 0) |\n| `retain` | yes | If message should have the retain flag set. (default: false) |\n\nNote\n\nWhen `payload` is rendered from [template](https:\/\/www.home-assistant.io\/docs\/templating\/where-to-use\/#mqtt) in a YAML script or automation, and the template renders to a `bytes` literal, the outgoing MQTT payload will only be sent as `raw` data, if the `evaluate_payload` option flag is set to `true`.\n\n```\ntopic: homeassistant\/light\/1\/command\npayload: \"ON\"\n```\nYAML\n\nCopy\n\n```\ntopic: homeassistant\/light\/1\/state\npayload: \"{{ states('device_tracker.paulus') }}\"\n```\nYAML\n\nCopy\n\n```\ntopic: \"homeassistant\/light\/{{ states('sensor.light_active') }}\/state\"\npayload: \"{{ states('device_tracker.paulus') }}\"\n```\nYAML\n\nCopy\n\nBe aware that `payload` must be a string. If you want to send JSON using the YAML editor then you need to format\/escape it properly. Like:\n\n```\ntopic: homeassistant\/light\/1\/state\npayload: \"{\\\"Status\\\":\\\"off\\\", \\\"Data\\\":\\\"something\\\"}\"\n```\nYAML\n\nCopy\n\nThe example below shows how to publish a temperature sensor ‘Bathroom Temperature’. The `device_class` is set, so it is not needed to set the “name” option. The entity will inherit the name from the `device_class` set and also support translations. If you set “name” in the payload the entity name will start with the device name.\n\n```\naction: mqtt.publish\ndata:\n  topic: homeassistant\/sensor\/Acurite-986-1R-51778\/config\n  payload: >-\n    {\"device_class\": \"temperature\",\n    \"unit_of_measurement\": \"\\u00b0C\",\n    \"value_template\": \"{{ value | float }}\",\n    \"state_topic\": \"rtl_433\/rtl433\/devices\/Acurite-986\/1R\/51778\/temperature_C\",\n    \"unique_id\": \"Acurite-986-1R-51778-T\",\n    \"device\": {\n    \"identifiers\": \"Acurite-986-1R-51778\",\n    \"name\": \"Bathroom\",\n    \"model\": \"Acurite\",\n    \"model_id\": \"986\",\n    \"manufacturer\": \"rtl_433\" }\n    }\n```\nYAML\n\nCopy\n\nExample of how to use `qos` and `retain`:\n\n```\ntopic: homeassistant\/light\/1\/command\npayload: \"ON\"\nqos: 2\nretain: true\n```\nYAML\n\nCopy\n### Action: Dump\nThe `mqtt.dump` action listens to the specified topic matcher and dumps all received messages within a specific duration into the file `mqtt_dump.txt` in your configuration folder. This is useful when debugging a problem.\n\n| Data attribute | Optional | Description |\n|---|---|---|\n| `topic` | no | Topic to dump. Can contain a wildcard (`#` or `+`). |\n| `duration` | yes | Duration in seconds that we will listen for messages. Default is 5 seconds. |\n\n```\ntopic: zigbee2mqtt\/#\n```\nYAML\n\nCopy\n## Logging\nThe [logger](https:\/\/www.home-assistant.io\/integrations\/logger\/) integration allows the logging of received MQTT messages.\n\n```\n# Example configuration.yaml entry\nlogger:\n  default: warning\n  logs:\n    homeassistant.components.mqtt: debug\n```\nYAML\n\nCopy\n## Event `event_mqtt_reloaded`\nEvent `event_mqtt_reloaded` is fired when Manually configured MQTT entities have been reloaded and entities thus might have changed.\n\nThis event has no additional data.\n\n## Removing the integration\n1. Go to [**Settings** \\> **Devices & services**](https:\/\/my.home-assistant.io\/redirect\/integrations) and select the integration card.\n2. From the list of devices, select the integration instance you want to remove.\n3. Next to the entry, select the three dots\n   menu. Then, select **Delete**.\n\nNote: This action does not remove the [MQTT broker](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#setting-up-a-broker) or its data. If you want to completely remove MQTT:\n\n1. Check your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\\[Learn more\\]](https:\/\/www.home-assistant.io\/docs\/configuration\/) and other YAML files for MQTT-related configurations and remove them\n2. Review your automations and scripts for any MQTT dependencies\n3. Consider backing up your configuration before making these changes\n\n#### **Help us improve our documentation**\nSuggest an edit to this page, or provide\/view feedback for this page.\n\n- [Edit](https:\/\/github.com\/home-assistant\/home-assistant.io\/tree\/current\/source\/_integrations\/mqtt.markdown \"Edit this page\")\n- [Provide feedback](https:\/\/github.com\/home-assistant\/home-assistant.io\/issues\/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fintegrations%2Fmqtt%2F&version=2026.4.1&labels=current,integration%3A%20mqtt \"Provide feedback on this page\")\n- [View pending feedback](https:\/\/github.com\/home-assistant\/home-assistant.io\/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22integration%3A+mqtt%22 \"View pending feedback for this page\")\n\n![](https:\/\/brands.home-assistant.io\/_\/mqtt\/\/logo.png)[![](https:\/\/my.home-assistant.io\/badges\/config_flow_start.svg)](https:\/\/my.home-assistant.io\/redirect\/config_flow_start?domain=mqtt)\n\nThe MQTT service was introduced in Home Assistant pre 0.7, and it's used by  [48%](https:\/\/analytics.home-assistant.io\/integrations \"Open analytics.home-assistant.io\") of the active installations.\n\nIts IoT class is [Local Push.](https:\/\/www.home-assistant.io\/blog\/2016\/02\/12\/classifying-the-internet-of-things\/#classifiers)\n\n[🏆 Platinum quality](https:\/\/www.home-assistant.io\/docs\/quality_scale\/#-platinum)\n\n[View source on GitHub](https:\/\/github.com\/home-assistant\/core\/tree\/dev\/homeassistant\/components\/mqtt)\n\n[View known issues](https:\/\/github.com\/home-assistant\/core\/issues?q=is%3Aissue+label%3A%22integration%3A+mqtt%22)\n\n[View feature requests](https:\/\/github.com\/orgs\/home-assistant\/discussions?discussions_q=label%3A%22integration%3A+mqtt%22)\n\n## Integration owners\nWe are incredibly grateful to the following contributors who currently maintain this integration:\n\n[![@emontnemery](https:\/\/avatars.githubusercontent.com\/emontnemery?size=96) @emontnemery](https:\/\/github.com\/emontnemery)  \n[![@jbouwh](https:\/\/avatars.githubusercontent.com\/jbouwh?size=96) @jbouwh](https:\/\/github.com\/jbouwh)  \n[![@bdraco](https:\/\/avatars.githubusercontent.com\/bdraco?size=96) @bdraco](https:\/\/github.com\/bdraco)\n\n## Categories\n- [Hub](https:\/\/www.home-assistant.io\/integrations\/#hub)\n- [Update](https:\/\/www.home-assistant.io\/integrations\/#update)\n\n## On this page\n- [Configuration](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configuration)\n- [Setting up a broker](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#setting-up-a-broker)\n- [Broker configuration](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#broker-configuration)\n  - [Advanced broker configuration](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#advanced-broker-configuration)\n- [Configure MQTT options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configure-mqtt-options)\n  - [Change MQTT discovery options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#change-mqtt-discovery-options)\n  - [Discovery options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-options)\n  - [Birth and last will messages](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#birth-and-last-will-messages)\n- [Testing your setup](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#testing-your-setup)\n- [Naming of MQTT Entities](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#naming-of-mqtt-entities)\n- [Grouping entities](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#grouping-entities)\n- [MQTT Discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#mqtt-discovery)\n  - [Discovery messages](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-messages)\n  - [Discovery messages and availability](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-messages-and-availability)\n  - [Using Availability topics](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#using-availability-topics)\n  - [Discovery examples with component discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-examples-with-component-discovery)\n  - [Support by third-party tools](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#support-by-third-party-tools)\n- [Manual configured MQTT items](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#manual-configured-mqtt-items)\n  - [YAML configuration listed per item](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#yaml-configuration-listed-per-item)\n  - [YAML configuration keyed and bundled by {domain}](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#yaml-configuration-keyed-and-bundled-by-domain)\n- [Entity state updates](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#entity-state-updates)\n  - [The last reported state attribute](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#the-last-reported-state-attribute)\n- [Using Templates](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#using-templates)\n  - [Examples](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#examples)\n- [Publish & Dump actions](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#publish--dump-actions)\n  - [Action: Publish](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#action-publish)\n  - [Action: Dump](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#action-dump)\n- [Logging](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#logging)\n- [Event event\\_mqtt\\_reloaded](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#event-event_mqtt_reloaded)\n- [Removing the integration](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#removing-the-integration)\n\nBack to top\n\n![Home Assistant](https:\/\/www.home-assistant.io\/images\/footer-logo-text.svg)\n\nHome Assistant is a project from the [Open Home Foundation](https:\/\/www.openhomefoundation.org\/), sponsored by [Nabu Casa](https:\/\/www.nabucasa.com\/).\n\n### Join us and contribute\\!\n- [GitHub repo](https:\/\/github.com\/home-assistant\/)\n- [Developers Portal](https:\/\/developers.home-assistant.io\/)\n- [Design Portal](https:\/\/design.home-assistant.io\/)\n- [Data Science Portal](https:\/\/data.home-assistant.io\/)\n- [Community Forum](https:\/\/community.home-assistant.io\/)\n- [Creator Network](https:\/\/creators.home-assistant.io\/)\n- [Works With Home Assistant](https:\/\/works-with.home-assistant.io\/)\n- [Our community](https:\/\/www.home-assistant.io\/community)\n- [Reporting issues](https:\/\/www.home-assistant.io\/help\/reporting_issues\/)\n### System status\n- [Integration Alerts](https:\/\/alerts.home-assistant.io\/)\n- [Security Alerts](https:\/\/www.home-assistant.io\/security\/)\n- [System Status](https:\/\/status.home-assistant.io\/)\n\n### Companion apps\n- [iOS and Apple devices](https:\/\/apps.apple.com\/app\/id1099568401)\n- [Android and Wear OS](https:\/\/play.google.com\/store\/apps\/details?id=io.homeassistant.companion.android)\n- [...and more\\!](https:\/\/companion.home-assistant.io\/)\n### Support us\n- [Merch store](https:\/\/store.openhomefoundation.org\/)\n- [Home Assistant Cloud](https:\/\/www.home-assistant.io\/cloud\/)\n### Governance\n- [Privacy Notices](https:\/\/www.home-assistant.io\/privacy\/)\n- [Contributor License Agreement](https:\/\/www.home-assistant.io\/developers\/cla\/)\n- [Terms of Service](https:\/\/www.home-assistant.io\/tos\/)\n- [Code of Conduct](https:\/\/www.home-assistant.io\/code_of_conduct\/)\n- [Credits](https:\/\/www.home-assistant.io\/developers\/credits\/)\n- [License](https:\/\/www.home-assistant.io\/developers\/license\/)\n\n### Follow us\n[Sign up for our newsletter](https:\/\/newsletter.openhomefoundation.org\/#\/portal)\n\nFor partnership inquiries please check out [Works With Home Assistant](https:\/\/works-with.home-assistant.io\/). For media, [email our team](mailto:media@openhomefoundation.org). For other questions, you can [contact support](mailto:hello@home-assistant.io) (No technical support!)\n\nWebsite powered by [Jekyll](https:\/\/jekyllrb.com\/)  \n Originally based on the [Oscailte theme](https:\/\/github.com\/coogie\/oscailte)\n\n[![Deploys by Netlify Badge](https:\/\/www.home-assistant.io\/images\/frontpage\/netlify.svg)](https:\/\/www.netlify.com\/)","attrs_readable_markdown":"MQTT (aka MQ Telemetry Transport) is a machine-to-machine or “Internet of Things” connectivity protocol on top of TCP\/IP. It allows extremely lightweight publish\/subscribe messaging transport.\n\n## Configuration\nTo add the **MQTT** service to your Home Assistant instance, use this My button:\n\n[![](https:\/\/my.home-assistant.io\/badges\/config_flow_start.svg)](https:\/\/my.home-assistant.io\/redirect\/config_flow_start?domain=mqtt)\n\nManual configuration steps\n\nIf the above My button doesn’t work, you can also perform the following steps manually:\n\n- Browse to your Home Assistant instance.\n- Go to **[Settings \\> Devices & services](https:\/\/my.home-assistant.io\/redirect\/integrations)**.\n- In the bottom right corner, select the **[Add Integration](https:\/\/my.home-assistant.io\/redirect\/config_flow_start?domain=mqtt)** button.\n- From the list, select **MQTT**.\n- Follow the instructions on screen to complete the setup.\n\nMQTT devices and entities can be set up through [MQTT discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#mqtt-discovery) or [added manually](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#manual-configured-mqtt-items) via YAML or subentries.\n\nConfiguration of MQTT components via MQTT discovery\n\nConfiguration of MQTT components via YAML\n\nYour first step to get MQTT and Home Assistant working is to choose a broker.\n\nThe easiest option is to install the official Mosquitto Broker app for Home Assistant (formerly known as Mosquitto Broker add-on). You can choose to set up and configure this app automatically when you set up the MQTT integration. Home Assistant will automatically generate and assign a safe username and password, and no further attention is required. This also works if you have already set up this app yourself in advance. You can set up additional logins for your MQTT devices and services using the [Mosquitto app configuration](https:\/\/my.home-assistant.io\/redirect\/supervisor_addon\/?addon=core_mosquitto).\n\nImportant\n\nWhen MQTT is set up with the official Mosquitto MQTT broker app, the broker’s credentials are generated and kept secret. If the official Mosquitto MQTT broker needs to be re-installed, make sure you save a copy of the app user options, like the additional logins. After re-installing the app, the MQTT integration will automatically update the new password for the re-installed broker. It will then reconnect automatically.\n\nAlternatively, you can use a different MQTT broker that you configure yourself, ensuring it is compatible with Home Assistant.\n\n## Setting up a broker\nWhile public MQTT brokers are available, the easiest and most private option is running your own.\n\nThe recommended setup method is to use the [Mosquitto MQTT broker app](https:\/\/github.com\/home-assistant\/hassio-addons\/blob\/master\/mosquitto\/DOCS.md).\n\nWarning\n\nNeither ActiveMQ MQTT broker nor the RabbitMQ MQTT Plugin are supported, use a known working broker like Mosquitto instead. There are [at least two](https:\/\/issues.apache.org\/jira\/browse\/AMQ-6360) [issues](https:\/\/issues.apache.org\/jira\/browse\/AMQ-6575) with the ActiveMQ MQTT broker which break MQTT message retention.\n## Broker configuration\nMQTT broker settings are configured when the MQTT integration is first set up and can be changed later if needed.\n\nAdd the MQTT integration, then provide your broker’s hostname (or IP address) and port and (if required) the username and password that Home Assistant should use. To change the settings later, follow these steps:\n\n1. Go to **[Settings \\> Devices & services](https:\/\/my.home-assistant.io\/redirect\/integrations)**.\n2. Select the MQTT integration.\n3. Reconfigure the MQTT broker settings via [**Settings** \\> **Devices & services**](https:\/\/my.home-assistant.io\/redirect\/integrations), select\n   , and select **Reconfigure**.\n\nMQTT subentries can also be reconfigured. Additional entities can be added, or an entity can be removed from the sub entry. Each MQTT subentry holds one MQTT device. The MQTT device must have at least one entity.\n\nImportant\n\nIf you experience an error message like `Failed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed`, then turn on `Advanced options` and set [Broker certificate validation](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#broker-certificate-validation) to `Auto`.\n### Advanced broker configuration\nAdvanced broker configuration options include setting a custom client ID, setting a client certificate and key for authentication, and enabling TLS validation of the broker’s certificate for secure connection. To access the advanced settings, open the MQTT broker settings, switch on **Advanced options**, and select **Next**. The advanced options will be shown by default if there are advanced settings active already.\n\nTip\n\nAdvanced broker options are accessible only when advanced mode is enabled (see user settings), or when advanced broker settings are configured already.\n#### Alternative client ID\nYou can set a custom MQTT client ID, this can help when debugging. Mind that the client ID must be unique. Leave this settings default if you want Home Assistant to generate a unique ID.\n\n#### Keep alive\nThe time in seconds between sending keep alive messages for this client. The default is 60 seconds. The keep alive setting should be at least 15 seconds.\n\n#### Broker certificate validation\nTo enable a secure connection to the broker, the broker certificate should be validated. If your broker uses a trusted certificate, then choose **Auto**. This validates the broker certificate against the bundled certificate authority (CA) certificates. If a self-signed certificate is used, select **Custom**. A custom PEM- or DER-encoded CA certificate can be uploaded. Select **Next** to show the control to upload the CA certificate. If the server certificate does not match the hostname then validation will fail. To allow a connection without the verification of the hostname, turn the **Ignore broker certificate validation** switch on.\n\n#### MQTT Protocol\nThe MQTT protocol setting defaults to version `3.1.1`. If your MQTT broker supports MQTT version 5 you can set the protocol setting to `5`.\n\n#### Securing the connection\nWith a secure broker connection, it is possible to use a client certificate for authentication. To set the client certificate and private key, turn on the option **Use a client certificate** and select **Next** to reveal file upload controls. A client certificate and the corresponding private key must be uploaded together. Both client certificate and private key must be either PEM- or DER-encoded. If the private key is encrypted with a password, ensure you supply the correct password when uploading the client certificate and key files.\n\n#### Using WebSockets as transport\nYou can select `websockets` as the transport method if your MQTT broker supports it. When you select `websockets` and select **Next**, you will be able to add a WebSockets path (default is `\/`) and WebSockets headers (optional). The target WebSockets URI `ws:\/\/{broker}:{port}{ws_path}` is built with the `broker`, `port`, and `ws_path` (WebSocket path) settings. To configure the WebSocket’s headers, supply a valid JSON dictionary string. For example, `{ \"Authorization\": \"token\" , \"x-header\": \"some header\"}`. The default transport method is `tcp`. The WebSockets transport can be secured using TLS and optionally using user credentials or a client certificate.\n\nNote\n\nA configured client certificate will only be active if broker certificate validation is enabled.\n## Configure MQTT options\nTo change the options, follow these steps:\n\n1. Go to **[Settings \\> Devices & services](https:\/\/my.home-assistant.io\/redirect\/integrations)**.\n2. Select the MQTT integration.\n3. Select **Configure**, then **Re-configure MQTT**.\n4. To open the MQTT options page, select **Next**.\n### Change MQTT discovery options\nThe MQTT discovery options can be changed by following these steps:\n\n1. Go to [**Settings** \\> **Devices & services**](https:\/\/my.home-assistant.io\/redirect\/integrations).\n2. Find the MQTT integration and select it.\n3. To open the MQTT discovery options page, select the **Configure MQTT Options** button.\n### Discovery options\nMQTT discovery is enabled by default. Discovery can be turned off. The prefix for the discovery topic (default `homeassistant`) can be changed here as well. See also [MQTT Discovery section](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#mqtt-discovery)\n\n### Birth and last will messages\nHome Assistant’s MQTT integration supports so-called Birth and Last Will and Testament (LWT) messages. The former is used to send a message after the service has started, and the latter is used to notify other clients about a disconnected client. Note that the LWT message will be sent both in case of a clean disconnect (for example, Home Assistant shutting down) and in case of an unclean disconnect (for example, Home Assistant crashing or losing its network connection).\n\nIf a disabled entity is enabled and added after 30 seconds, the MQTT integration will be reloaded and will cause all discovered MQTT entities to be unloaded. When MQTT starts up, all existing MQTT devices, entities, tags, and device triggers, will be unavailable until a discovery message is received and processed. A device or service that exposes the MQTT discovery should subscribe to the Birth message and use this as a trigger to send the [discovery payload](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-payload). To avoid high IO loads on the MQTT broker, adding some random delay in sending the discovery payload is recommended.\n\nAlternative approaches:\n\n- Retaining the [discovery payload](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-payload): This will store the discovery payload at the MQTT broker, and offer it to the MQTT integration as soon as it subscribes for MQTT discovery. When there are a lot of entities, this can cause high IO loads.\n- Periodically resending the discovery payload: This can cause some delay, or a lot of IO if there are a lot of MQTT discovery messages.\n\nBy default, Home Assistant sends `online` and `offline` to `homeassistant\/status`.\n\nMQTT Birth and Last Will messages can be customized or disabled from the UI. To do this, select **Configure** on the integration page in the UI, then **Re-configure MQTT**, and then **Next**.\n\n## Testing your setup\nThe `mosquitto` broker package ships command line tools (often as `*-clients` package) to send and receive MQTT messages. For sending test messages to a broker running on `localhost`, you can use [`mosquitto_pub`](https:\/\/mosquitto.org\/man\/mosquitto_pub-1.html), check the example below:\n\n```\nmosquitto_pub -h 127.0.0.1 -t homeassistant\/switch\/1\/on -m \"Switch is ON\"\n```\nBash\n\nAnother way to send MQTT messages manually is to use the **MQTT** integration in the frontend. Select **Settings** on the left menu, select **Devices & services**, and select **Configure** in the **Mosquitto broker** tile. Enter something similar to the example below into the **topic** field under **Publish a packet** and select **Publish**.\n\n1. Go to **[Settings \\> Devices & services](https:\/\/my.home-assistant.io\/redirect\/integrations)**.\n2. Select the Mosquitto broker integration, then select **Configure**.\n3. Enter something similar to the example below into the **topic** field under **Publish a packet**. Select **Publish**.\n\n```\nhomeassistant\/switch\/1\/power\n```\nBash\n\nand in the Payload field\n\n```\nON\n```\nBash\n\nIn the **Listen to a topic** field, type `#` to see everything, or `homeassistant\/switch\/#` to just follow a published topic, then select **Start listening**. The messages should appear similar to the text below:\n\n```\nMessage 23 received on homeassistant\/switch\/1\/power\/stat\/POWER at 12:16 PM:\nON\nQoS: 0 - Retain: false\nMessage 22 received on homeassistant\/switch\/1\/power\/stat\/RESULT at 12:16 PM:\n{\n    \"POWER\": \"ON\"\n}\nQoS: 0 - Retain: false\n```\nBash\n\nFor reading all messages sent on the topic `homeassistant` to a broker running on localhost:\n\n```\nmosquitto_sub -h 127.0.0.1 -v -t \"homeassistant\/#\"\n```\nBash\n## Naming of MQTT Entities\nFor every configured MQTT entity Home Assistant automatically assigns a unique `entity_id`. If the `unique_id` option is configured, you can change the `entity_id` after creation, and the changes are stored in the Entity Registry. The `entity_id` is generated when an item is loaded the first time.\n\nIf the `default_entity_id` option is set, then this will be used to generate the `entity_id`. If, for example, we have configured a `sensor`, and we have set `default_entity_id` to `sensor.test`, then Home Assistant will try to assign `sensor.test` as `entity_id`. If `sensor.test` already exists, Home Assistant will append a suffix to make it unique, for example, `sensor.test_2`.\n\nThis means any MQTT entity which is part of a device will [automatically have its `friendly_name` attribute prefixed with the device name](https:\/\/developers.home-assistant.io\/docs\/core\/entity\/#has_entity_name-true-mandatory-for-new-integrations)\n\nUnnamed `binary_sensor`, `button`, `number`, and `sensor` entities will now be named by their device class instead of being named “MQTT binary sensor” and similar. It’s allowed to set an MQTT entity’s name to `None` (use `null` in YAML) to mark it as the main feature of a device.\n\nNote that on each MQTT entity, the `has_entity_name` attribute will be set to `True`. More details [can be found here](https:\/\/developers.home-assistant.io\/docs\/core\/entity\/#has_entity_name-true-mandatory-for-new-integrations).\n\n## Grouping entities\nIf the MQTT entity represents a group of other entities, the member entities can be made visible in the UI by setting the list of unique IDs of the member entities in the `group` configuration option of the entity group:\n\ngroup\n\nA list of unique IDs of the member entities. Set this if the entity represents a group entity. Note that the member entities must be already configured before the member entities will become visible in the UI at the moment a group entity is loaded.\n## MQTT Discovery\nThe discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](https:\/\/www.home-assistant.io\/integrations\/http\/#binary-sensor) and the [HTTP sensor](https:\/\/www.home-assistant.io\/integrations\/http\/#sensor). To prevent multiple identical entries if a device reconnects, a unique identifier is necessary. Two parts are required on the device side: The configuration topic, and the device configuration as payload.\n\nMQTT discovery is enabled by default, but can be disabled. The prefix for the discovery topic (default `homeassistant`) can be changed. See the [MQTT Options sections](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configure-mqtt-options)\n\nNote\n\nDocumentation on the MQTT components that support MQTT discovery [can be found here](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configuration-via-mqtt-discovery).\n### Discovery messages\nMQTT discovery supports two types of discovery messages:\n\n- [Device discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#device-discovery-payload), which allows you to include several components in a single discovery message\n- [Single component discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#single-component-discovery-payload), where you publish a separate discovery message for each component\n\nIf you use a device with multiple components, it is recommended to use MQTT device discovery. It reduces the number of messages sent, and allows you to send the device information only once.\n\n#### Discovery topic\nThe discovery topic needs to follow a specific format:\n\n```\n<discovery_prefix>\/<component>\/[<node_id>\/]<object_id>\/config\n```\nText\n\n- `<discovery_prefix>`: The Discovery Prefix defaults to `homeassistant` and this prefix can be [changed](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-options).\n- `<component>`: One of the supported MQTT integrations, for example, `binary_sensor`, or `device` in case of device discovery.\n- `<node_id>`: (*Optional*): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. The ID of the node must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen).\n- `<object_id>`: The ID of the device. This allows for separate topics for each device. The ID of the device must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen).\n\n> **Note:** The `<object_id>` in the topic does not influence the resulting `entity_id`; use `default_entity_id` if you need to control the `entity_id`. The `<node_id>` is optional, and can be used by clients to subscribe to their own (command) topics by using one wildcard topic like `<discovery_prefix>\/+\/<node_id>\/+\/set`.\n\nBest practice for entities with a `unique_id` is to set `<object_id>` to the `unique_id` and omit the `<node_id>`.\n\n#### Device discovery payload\nA device can send a discovery payload to expose all components for a device. The `<component>` part in the discovery topic must be set to `device`.\n\nAs an alternative, it is also possible for a device [to send a discovery payload for each component](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#single-component-discovery-payload) it wants to set up.\n\nThe shared options at the root level of the JSON message must include:\n\n- `device` mapping (abbreviated as `dev`)\n- `origin` mapping (abbreviated as `o`)\n\nThese mappings are mandatory and cannot be overridden at the entity\/component level.\n\nSupported shared options are:\n\n- The `availability` [options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#using-availability-topics).\n- The `origin` (required) [options](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#adding-information-about-the-origin-of-a-discovery-message)\n- `command_topic`\n- `state_topic`\n- `qos`\n- `encoding`\n\nThe component specific options are placed as mappings under the `components` key (abbreviated as `cmps`) like:\n\n```\n{\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  },\n  \"cmps\": {\n    \"some_unique_component_id1\": {\n      \"p\": \"sensor\",\n      \"device_class\":\"temperature\",\n      \"unit_of_measurement\":\"°C\",\n      \"value_template\":\"{{ value_json.temperature}}\",\n      \"unique_id\":\"temp01ae_t\"\n    },\n    \"some_unique_id2\": {\n      \"p\": \"sensor\",\n      \"device_class\":\"humidity\",\n      \"unit_of_measurement\":\"%\",\n      \"value_template\":\"{{ value_json.humidity}}\",\n      \"unique_id\":\"temp01ae_h\"\n    }\n  },\n  \"state_topic\":\"sensorBedroom\/state\",\n  \"qos\": 2\n}\n```\nJSON\n\nNote\n\nThe components id’s under the `components` (`cmps`) key, are used as part of the discovery identification. A `platform` (`p`) config option is required for each component config that is added to identify the component platform. Also required is a `unique_id` for entity-based components.\n\nTo remove the components, publish an empty (retained) string payload to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it.\n\nAn empty config can be published as an update to remove a single component from the device discovery. Note that adding the `platform` (`p`) option is still required.\n\n```\n{\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  },\n  \"cmps\": {\n    \"some_unique_component_id1\": {\n      \"p\": \"sensor\",\n      \"device_class\":\"temperature\",\n      \"unit_of_measurement\":\"°C\",\n      \"value_template\":\"{{ value_json.temperature}}\",\n      \"unique_id\":\"temp01ae_t\"\n    },\n    \"some_unique_id2\": {\n      \"p\": \"sensor\"\n    }\n  },\n  \"state_topic\":\"sensorBedroom\/state\",\n  \"qos\": 2\n}\n```\nJSON\n\nThis will explicitly remove the humidity sensor and its entry.\n\nAfter removing a component, you should send another update with the removed component omitted from the configuration. This ensures that Home Assistant has the most up-to-date device configuration. For example:\n\n```\n{\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  },\n  \"cmps\": {\n    \"some_unique_component_id1\": {\n      \"p\": \"sensor\",\n      \"device_class\":\"temperature\",\n      \"unit_of_measurement\":\"°C\",\n      \"value_template\":\"{{ value_json.temperature}}\",\n      \"unique_id\":\"temp01ae_t\"\n    }\n  },\n  \"state_topic\":\"sensorBedroom\/state\",\n  \"qos\": 2\n}\n```\nJSON\n\nA component config part in a device discovery payload must have the `platform` (`p`) option set with the name of the `component` and also must have at least one component specific config option. Entity components must have set the `unique_id` option and have a `device` context.\n\n##### Migration from single component to device discovery\nTo allow a smooth migration from single component discovery to device discovery:\n\n1. Ensure all entities have a `unique_id` and a `device` context.\n2. Move the `object_id` inside the discovery payload, if that is available, or use a unique ID or the component.\n3. Consider using the previous `node_id` as the new `object_id` of the device discovery topic.\n4. Ensure the `unique_id` matches and the `device` context has the correct identifiers.\n5. Send the following payload to all existing single component discovery topics: `{\"migrate_discovery\": true }`. This will unload the discovered item, but its settings will be retained.\n6. Switch the discovery topic to the device discovery topic and include all the component configurations.\n7. Clean up the single component discovery messages with an empty payload.\n\nDuring the migration steps, INFO messages will be logged to inform you about the progress of the migration.\n\nImportant\n\nConsider testing the migration process in a non-production environment before applying it to a live system.\n#### Discovery migration example with a device automation and a sensor\n**Step 1: Original single component discovery configurations:**\n\nDiscovery topic single: `homeassistant\/device_automation\/0AFFD2\/bla1\/config` Discovery id: `0AFFD2 bla1` *(both `0AFFD2` and `bla1` from the discovery topic)* Discovery payload single:\n\n```\n{\n  \"device\": {\n    \"identifiers\": [\"0AFFD2\"],\n    \"name\": \"Test device\"\n  },\n  \"o\": {\n    \"name\": \"foobar\"\n  },\n  \"automation_type\": \"trigger\",\n  \"payload\": \"short_press\",\n  \"topic\": \"foobar\/triggers\/button1\",\n  \"type\": \"button_short_press\",\n  \"subtype\": \"button_1\"\n}\n```\nJSON\n\nDiscovery topic single: `homeassistant\/sensor\/0AFFD2\/bla2\/config` Discovery id: `0AFFD2 bla2` *(both `0AFFD2` and `bla2` from the discovery topic)* Discovery payload single:\n\n```\n{\n  \"device\": {\n    \"identifiers\": [\"0AFFD2\"],\n    \"name\": \"Test device\"\n  },\n  \"o\": {\n    \"name\": \"foobar\"\n  },\n  \"state_topic\": \"foobar\/sensor\/sensor1\",\n  \"unique_id\": \"bla_sensor001\"\n}\n```\nJSON\n\n**Step 2: Initiate migration by publishing to both discovery topics:**\n\nWhen these single component discovery payloads are processed, and we want to initiate migration to device discovery, we need to publish …\n\n```\n{\"migrate_discovery\": true }\n```\nJSON\n\n… to both discovery topics …\n\n- `homeassistant\/device_automation\/0AFFD2\/bla1\/config`\n- `homeassistant\/sensor\/0AFFD2\/bla2\/config`\n\nImportant\n\nCheck the logs to ensure this step is executed correctly.\n\n**Step 3: Publish the new device discovery configuration:**\n\nDiscovery topic device: `homeassistant\/device\/0AFFD2\/config` Discovery id: `0AFFD2 bla` *(`0AFFD2`from discovery topic, `bla`: The key under `cmps` in the discovery payload)* Discovery payload device:\n\n```\n{\n  \"device\": {\n    \"identifiers\": [\n      \"0AFFD2\"\n    ]\n  },\n  \"o\": {\n    \"name\": \"foobar\"\n  },\n  \"cmps\": {\n    \"bla1\": {\n      \"p\": \"device_automation\",\n      \"automation_type\": \"trigger\",\n      \"payload\": \"short_press\",\n      \"topic\": \"foobar\/triggers\/button1\",\n      \"type\": \"button_short_press\",\n      \"subtype\": \"button_1\"\n    },\n    \"bla2\": {\n      \"p\": \"sensor\",\n      \"state_topic\": \"foobar\/sensor\/sensor1\",\n      \"unique_id\": \"bla_sensor001\"\n    }\n  }\n}\n```\nJSON\n\nImportant\n\nCheck the logs to ensure the migration was successful.\n\n**Step 4: Clean up after successful migration:**\n\nAfter the logs show a successful migration, the single component discovery topics can be cleaned up safely by publishing an empty payload to them. The logs should indicate if the discovery migration was successful.\n\n**Optional: Rolling back the migration:**\n\nTo rollback publish …\n\n```\n{\"migrate_discovery\": true }\n```\nJSON\n\nTo the device discovery topic(s). After that, re-publish the single component discovery payloads. At last, clean up the device discovery payloads by publishing an empty payload.\n\nCheck the logs for every step.\n\n#### Single component discovery payload\nWhen using single component discovery messages, the `<component>` part in the discovery topic must be one of the supported MQTT platforms.\n\nThe options in the payload are only used to set up one specific component. If a device contains multiple components, it is recommended to use [device discovery](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#device-discovery-payload) instead.\n\nMQTT entities can share device configuration, meaning one entity can include the full device configuration and other entities can link to that device by only setting mandatory fields.\n\nImportant\n\nThe mandatory fields were previously limited to at least one of `connection` and `identifiers`, but have now been extended to at least one of `connection` and `identifiers` as well as the `name`.\n\nExample discovery payload:\n\n```\n{\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  },\n  \"device_class\":\"temperature\",\n  \"unit_of_measurement\":\"°C\",\n  \"value_template\":\"{{ value_json.temperature}}\",\n  \"unique_id\":\"temp01ae_t\",\n  \"state_topic\":\"sensorBedroom\/state\",\n  \"qos\": 2\n}\n```\nJSON\n\nTo remove the component, publish an empty string to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it.\n\nFor more examples [see](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#discovery-examples-with-component-discovery).\n\n#### Discovery payload\nThe payload must be a serialized JSON dictionary and will be checked like an entry in your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\\[Learn more\\]](https:\/\/www.home-assistant.io\/docs\/configuration\/) file if a new device is added, with the exception that unknown configuration keys are allowed but ignored. This means that missing variables will be filled with the integration’s default values. All configuration variables which are *required* must be present in the payload. The reason for allowing unknown documentation keys is allow some backwards compatibility, software generating MQTT discovery messages can then be used with older Home Assistant versions which will simply ignore new features.\n\nA discovery payload can be sent with a retain flag set. In that case, the discovery message will be stored at the MQTT broker and processed automatically when the MQTT integrations start. This method removes the need for it to be resent. A better approach, though, is for the software generating MQTT discovery messages to send discovery payload(s) when the MQTT integration sends the [Birth message](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#birth-and-last-will-messages).\n\nSubsequent messages on a topic where a valid payload has been received will be handled as a configuration update, and a configuration update with an empty payload will cause a previously discovered device to be deleted.\n\nA base topic `~` may be defined in the payload to conserve memory when the same topic base is used multiple times. In the value of configuration variables ending with `_topic`, `~` will be replaced with the base topic, if the `~` occurs at the beginning or end of the value.\n\nConfiguration variable names in the discovery payload may be abbreviated to conserve memory when sending a discovery message from memory constrained devices.\n\nIt is recommended to add information about the origin of MQTT entities by including the `origin` option (abbreviated as `o`) in the discovery payload. For device discovery, this information is required. The origin details will be logged in the core event log when an item is discovered or updated. Adding origin information helps with troubleshooting and provides valuable context about the source of MQTT messages in your Home Assistant setup.\n\nNote: These options also support abbreviations, as shown in the table below.\n\nname\n\nThe name of the application that is the origin of the discovered MQTT item. (Required)\n\nsw\\_version\n\nSoftware version of the application that supplies the discovered MQTT item.\n\nsupport\\_url\n\nSupport URL of the application that supplies the discovered MQTT item.\n#### Supported abbreviations in MQTT discovery messages\nSupported abbreviations\n\n```\n'act_t':               'action_topic',\n'act_tpl':             'action_template',\n'atype':               'automation_type',\n'aux_cmd_t':           'aux_command_topic',\n'aux_stat_t':          'aux_state_topic',\n'aux_stat_tpl':        'aux_state_template',\n'av_tones':            'available_tones',\n'avty':                'availability',\n'avty_mode':           'availability_mode',\n'avty_t':              'availability_topic',\n'avty_tpl':            'availability_template',\n'away_mode_cmd_t':     'away_mode_command_topic',\n'away_mode_stat_t':    'away_mode_state_topic',\n'away_mode_stat_tpl':  'away_mode_state_template',\n'b_tpl':               'blue_template',\n'bri_cmd_t':           'brightness_command_topic',\n'bri_cmd_tpl':         'brightness_command_template',\n'bri_scl':             'brightness_scale',\n'bri_stat_t':          'brightness_state_topic',\n'bri_tpl':             'brightness_template',\n'bri_val_tpl':         'brightness_value_template',\n'clr_temp_cmd_tpl':    'color_temp_command_template',\n'clr_temp_cmd_t':      'color_temp_command_topic',\n'clr_temp_k':           'color_temp_kelvin',\n'clr_temp_stat_t':     'color_temp_state_topic',\n'clr_temp_tpl':        'color_temp_template',\n'clr_temp_val_tpl':    'color_temp_value_template',\n'clrm_stat_t':         'color_mode_state_topic',\n'clrm_val_tpl':        'color_mode_value_template',\n'cmd_off_tpl':         'command_off_template',\n'cmd_on_tpl':          'command_on_template',\n'cmd_t':               'command_topic',\n'cmd_tpl':             'command_template',\n'cmps':                'components',\n'cod_arm_req':         'code_arm_required',\n'cod_dis_req':         'code_disarm_required',\n'cod_trig_req':        'code_trigger_required',\n'cont_type':           'content_type',\n'curr_temp_t':         'current_temperature_topic',\n'curr_temp_tpl':       'current_temperature_template',\n'def_ent_id':          'default_entity_id',\n'dev':                 'device',\n'dev_cla':             'device_class',\n'dir_cmd_t':           'direction_command_topic',\n'dir_cmd_tpl':         'direction_command_template',\n'dir_stat_t':          'direction_state_topic',\n'dir_val_tpl':         'direction_value_template',\n'dsp_prc':             'display_precision',\n'e':                   'encoding',\n'en':                  'enabled_by_default',\n'ent_cat':             'entity_category',\n'ent_pic':             'entity_picture',\n'evt_typ':             'event_types',\n'exp_aft':             'expire_after',\n'fanspd_lst':          'fan_speed_list',\n'flsh':                'flash',\n'flsh_tlng':           'flash_time_long',\n'flsh_tsht':           'flash_time_short',\n'fx_cmd_t':            'effect_command_topic',\n'fx_cmd_tpl':          'effect_command_template',\n'fx_list':             'effect_list',\n'fx_stat_t':           'effect_state_topic',\n'fx_tpl':              'effect_template',\n'fx_val_tpl':          'effect_value_template',\n'fan_mode_cmd_t':      'fan_mode_command_topic',\n'fan_mode_cmd_tpl':    'fan_mode_command_template',\n'fan_mode_stat_t':     'fan_mode_state_topic',\n'fan_mode_stat_tpl':   'fan_mode_state_template',\n'frc_upd':             'force_update',\n'g_tpl':               'green_template',\n'grp':                 'group',\n'hs_cmd_t':            'hs_command_topic',\n'hs_cmd_tpl':          'hs_command_template',\n'hs_stat_t':           'hs_state_topic',\n'hs_val_tpl':          'hs_value_template',\n'ic':                  'icon',\n'img_e':               'image_encoding',\n'img_t':               'image_topic',\n'init':                'initial',\n'hum_cmd_t':           'target_humidity_command_topic',\n'hum_cmd_tpl':         'target_humidity_command_template',\n'hum_stat_t':          'target_humidity_state_topic',\n'hum_state_tpl':       'target_humidity_state_template',\n'json_attr':           'json_attributes',\n'json_attr_t':         'json_attributes_topic',\n'json_attr_tpl':       'json_attributes_template',\n'l_ver_t':             'latest_version_topic',\n'l_ver_tpl':           'latest_version_template',\n'lrst_t':              'last_reset_topic',\n'lrst_val_tpl':        'last_reset_value_template',\n'max':                 'max',\n'max_hum':             'max_humidity',\n'max_k':               'max_kelvin',\n'max_mirs':            'max_mireds',\n'max_temp':            'max_temp',\n'migr_discvry':        'migrate_discovery',\n'min':                 'min',\n'min_hum':             'min_humidity',\n'min_k':               'min_kelvin',\n'min_mirs':            'min_mireds',\n'min_temp':            'min_temp',\n'mode':                'mode',\n'mode_cmd_t':          'mode_command_topic',\n'mode_cmd_tpl':        'mode_command_template',\n'mode_stat_t':         'mode_state_topic',\n'mode_stat_tpl':       'mode_state_template',\n'modes':               'modes',\n'name':                'name',\n'o':                   'origin',\n'off_dly':             'off_delay',\n'on_cmd_type':         'on_command_type',\n'ops':                 'options',\n'opt':                 'optimistic',\n'osc_cmd_t':           'oscillation_command_topic',\n'osc_cmd_tpl':         'oscillation_command_template',\n'osc_stat_t':          'oscillation_state_topic',\n'osc_val_tpl':         'oscillation_value_template',\n'p':                   'platform',\n'pct_cmd_t':           'percentage_command_topic',\n'pct_cmd_tpl':         'percentage_command_template',\n'pct_stat_t':          'percentage_state_topic',\n'pct_val_tpl':         'percentage_value_template',\n'pl':                  'payload',\n'pl_arm_away':         'payload_arm_away',\n'pl_arm_custom_b':     'payload_arm_custom_bypass',\n'pl_arm_home':         'payload_arm_home',\n'pl_arm_nite':         'payload_arm_night',\n'pl_arm_vacation':     'payload_arm_vacation',\n'pl_avail':            'payload_available',\n'pl_cln_sp':           'payload_clean_spot',\n'pl_cls':              'payload_close',\n'pl_dir_fwd':          'payload_direction_forward',\n'pl_dir_rev':          'payload_direction_reverse',\n'pl_disarm':           'payload_disarm',\n'pl_home':             'payload_home',\n'pl_inst':             'payload_install',\n'pl_loc':              'payload_locate',\n'pl_lock':             'payload_lock',\n'pl_not_avail':        'payload_not_available',\n'pl_not_home':         'payload_not_home',\n'pl_off':              'payload_off',\n'pl_on':               'payload_on',\n'pl_open':             'payload_open',\n'pl_osc_off':          'payload_oscillation_off',\n'pl_osc_on':           'payload_oscillation_on',\n'pl_paus':             'payload_pause',\n'pl_prs':              'payload_press',\n'pl_ret':              'payload_return_to_base',\n'pl_rst':              'payload_reset',\n'pl_rst_hum':          'payload_reset_humidity',\n'pl_rst_mode':         'payload_reset_mode',\n'pl_rst_pct':          'payload_reset_percentage',\n'pl_rst_pr_mode':      'payload_reset_preset_mode',\n'pl_stop':             'payload_stop',\n'pl_stop_tilt':        'payload_stop_tilt',\n'pl_stpa':             'payload_start_pause',\n'pl_strt':             'payload_start',\n'pl_toff':             'payload_turn_off',\n'pl_ton':              'payload_turn_on',\n'pl_trig':             'payload_trigger',\n'pl_unlk':             'payload_unlock',\n'pos':                 'reports_position',\n'pos_clsd':            'position_closed',\n'pos_open':            'position_open',\n'pr_mode_cmd_t':       'preset_mode_command_topic',\n'pr_mode_cmd_tpl':     'preset_mode_command_template',\n'pr_mode_stat_t':      'preset_mode_state_topic',\n'pr_mode_val_tpl':     'preset_mode_value_template',\n'pr_modes':            'preset_modes',\n'ptrn':                'pattern',\n'r_tpl':               'red_template',\n'rel_s':               'release_summary',\n'rel_u':               'release_url',\n'ret':                 'retain',\n'rgb_cmd_t':           'rgb_command_topic',\n'rgb_cmd_tpl':         'rgb_command_template',\n'rgb_stat_t':          'rgb_state_topic',\n'rgb_val_tpl':         'rgb_value_template',\n'rgbw_cmd_t':          'rgbw_command_topic',\n'rgbw_cmd_tpl':        'rgbw_command_template',\n'rgbw_stat_t':         'rgbw_state_topic',\n'rgbw_val_tpl':        'rgbw_value_template',\n'rgbww_cmd_t':         'rgbww_command_topic',\n'rgbww_cmd_tpl':       'rgbww_command_template',\n'rgbww_stat_t':        'rgbww_state_topic',\n'rgbww_val_tpl':       'rgbww_value_template',\n'send_cmd_t':          'send_command_topic',\n'send_if_off':         'send_if_off',\n'set_fan_spd_t':       'set_fan_speed_topic',\n'set_pos_t':           'set_position_topic',\n'set_pos_tpl':         'set_position_template',\n'pos_t':               'position_topic',\n'pos_tpl':             'position_template',\n'spd_rng_min':         'speed_range_min',\n'spd_rng_max':         'speed_range_max',\n'src_type':            'source_type',\n'stat_cla':            'state_class',\n'stat_closing':        'state_closing',\n'stat_clsd':           'state_closed',\n'stat_jam':            'state_jammed',\n'stat_locked':         'state_locked',\n'stat_locking':        'state_locking',\n'stat_off':            'state_off',\n'stat_on':             'state_on',\n'stat_open':           'state_open',\n'stat_opening':        'state_opening',\n'stat_stopped':        'state_stopped',\n'stat_unlocked':       'state_unlocked',\n'stat_unlocking':      'state_unlocking',\n'stat_t':              'state_topic',\n'stat_tpl':            'state_template',\n'stat_val_tpl':        'state_value_template',\n'step':                'step',\n'stype':               'subtype',\n'sug_dsp_prc':         'suggested_display_precision',\n'sup_clrm':            'supported_color_modes',\n'sup_dur':             'support_duration',\n'sup_vol':             'support_volume_set',\n'sup_feat':            'supported_features',\n'swing_mode_cmd_t':    'swing_mode_command_topic',\n'swing_mode_cmd_tpl':  'swing_mode_command_template',\n'swing_mode_stat_t':   'swing_mode_state_topic',\n'swing_mode_stat_tpl': 'swing_mode_state_template',\n't':                   'topic',\n'temp_cmd_t':          'temperature_command_topic',\n'temp_cmd_tpl':        'temperature_command_template',\n'temp_hi_cmd_t':       'temperature_high_command_topic',\n'temp_hi_cmd_tpl':     'temperature_high_command_template',\n'temp_hi_stat_t':      'temperature_high_state_topic',\n'temp_hi_stat_tpl':    'temperature_high_state_template',\n'temp_lo_cmd_t':       'temperature_low_command_topic',\n'temp_lo_cmd_tpl':     'temperature_low_command_template',\n'temp_lo_stat_t':      'temperature_low_state_topic',\n'temp_lo_stat_tpl':    'temperature_low_state_template',\n'temp_stat_t':         'temperature_state_topic',\n'temp_stat_tpl':       'temperature_state_template',\n'temp_unit':           'temperature_unit',\n'tilt_clsd_val':       'tilt_closed_value',\n'tilt_cmd_t':          'tilt_command_topic',\n'tilt_cmd_tpl':        'tilt_command_template',\n'tilt_max':            'tilt_max',\n'tilt_min':            'tilt_min',\n'tilt_opnd_val':       'tilt_opened_value',\n'tilt_opt':            'tilt_optimistic',\n'tilt_status_t':       'tilt_status_topic',\n'tilt_status_tpl':     'tilt_status_template',\n'tit':                 'title',\n'trns':                'transition',\n'uniq_id':             'unique_id',\n'unit_of_meas':        'unit_of_measurement',\n'url_t':               'url_topic',\n'url_tpl':             'url_template',\n'val_tpl':             'value_template',\n'whit_cmd_t':          'white_command_topic',\n'whit_scl':            'white_scale',\n'xy_cmd_t':            'xy_command_topic',\n'xy_cmd_tpl':          'xy_command_template',\n'xy_stat_t':           'xy_state_topic',\n'xy_val_tpl':          'xy_value_template',\n```\nTxt\n\nSupported abbreviations for device registry configuration\n\n```\n'cu':                  'configuration_url',\n'cns':                 'connections',\n'ids':                 'identifiers',\n'name':                'name',\n'mf':                  'manufacturer',\n'mdl':                 'model',\n'mdl_id':              'model_id',\n'hw':                  'hw_version',\n'sw':                  'sw_version',\n'sa':                  'suggested_area',\n'sn':                  'serial_number',\n```\nTxt\n\nSupported abbreviations for origin info\n\n```\n'name':                'name',\n'sw':                  'sw_version',\n'url':                 'support_url',\n```\nTxt\n### Discovery messages and availability\nWhen MQTT discovery is set up, and a device or service sends a discovery message, an MQTT entity, tag, or device automation will be set up directly after receiving the message. When Home Assistant is restarting, discovered MQTT items with a unique ID will be unavailable until a new discovery message is received. MQTT items without a unique ID will not be added at startup. So a device or service using MQTT discovery must make sure a configuration message is offered after the **MQTT** integration has been (re)started. There are two common approaches to make sure the discovered items are set up at startup:\n\n1. Using Birth and Will messages to trigger setup\n2. Using retained messages\n\nFinally, it is a best practice to publish your device or service availability status.\n\n#### Use the Birth and Will messages to trigger discovery\nWhen the **MQTT** integration starts, a birth message is published at `homeassistant\/status` by default. A device or service connected to the shared `mqtt` broker can subscribe to this topic and use an `online` message to trigger discovery messages. See also the [birth and last will messages](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#birth-and-last-will-messages) section. After the configs have been published, the state topics will need an update, so they need to be republished.\n\n#### Using retained config messages\nAn alternative method for a device or service is to publish discovery messages with a `retain` flag. This will make sure discovery messages are replayed when the **MQTT** integration connects to the broker. After the configs have been published, the state topics will need an update.\n\n#### Using retained state messages\nState updates also need to be re-published after a config as been processed. This can also be done by publishing `retained` messages. As soon as a config is received (or replayed from a retained message), the setup will subscribe any state topics. If a retained message is available at a state topic, this message will be replayed so that the state can be restored for this topic.\n\nWarning\n\nA disadvantage of using retained messages is that these messages retain at the broker, even when the device or service stops working. They are retained even after the system or broker has been restarted. Retained messages can create ghost entities that keep coming back.\n\nEspecially when you have many entities, (unneeded) discovery messages can cause excessive system load. For this reason, use discovery messages with caution.\n### Using Availability topics\nA device or service can announce its availability by publishing a Birth message and set a Will message at the broker. When the device or service loses connection to the broker, the broker will publish the Will message. This allows the **MQTT** integration to make an entity unavailable.\n\nPlatform specific availability settings are available for `mqtt` entity platforms only.\n\nPlatform specific availability settings\n\n#### Configuration Variables\navailability list (Optional)\n\nA list of MQTT topics subscribed to receive availability (online\/offline) updates. Must not be used together with `availability_topic`.\n\npayload\\_available string (Optional, default: online)\n\nThe payload that represents the available state.\n\npayload\\_not\\_available string (Optional, default: offline)\n\nThe payload that represents the unavailable state.\n\ntopic string Required\n\nAn MQTT topic subscribed to receive availability (online\/offline) updates.\n\nvalue\\_template [template](https:\/\/www.home-assistant.io\/docs\/configuration\/templating\/) (Optional)\n\nDefines a [template](https:\/\/www.home-assistant.io\/docs\/templating\/where-to-use\/#mqtt) to extract a device’s availability from the `topic`. To determine the device’s availability, the result of this template will be compared to `payload_available` and `payload_not_available`.\n\navailability\\_topic string (Optional)\n\nThe MQTT topic subscribed to receive availability (online\/offline) updates. Must not be used together with `availability`.\n\navailability\\_mode string (Optional, default: latest)\n\nWhen `availability` is configured, this controls the conditions needed to set the entity to `available`. Valid entries are `all`, `any`, and `latest`. If set to `all`, `payload_available` must be received on all configured availability topics before the entity is marked as online. If set to `any`, `payload_available` must be received on at least one configured availability topic before the entity is marked as online. If set to `latest`, the last `payload_available` or `payload_not_available` received on any configured availability topic controls the availability.\n\navailability\\_template [template](https:\/\/www.home-assistant.io\/docs\/configuration\/templating\/) (Optional)\n\nDefines a [template](https:\/\/www.home-assistant.io\/docs\/templating\/where-to-use\/#mqtt) to extract device’s availability from the `availability_topic`. To determine the devices’s availability result of this template will be compared to `payload_available` and `payload_not_available`.\n\npayload\\_available string (Optional, default: online)\n\nThe payload that represents the available state.\n\npayload\\_not\\_available string (Optional, default: offline)\n\nThe payload that represents the unavailable state.\n### Discovery examples with component discovery\n#### Motion detection (binary sensor)\nA motion detection device which can be represented by a [binary sensor](https:\/\/www.home-assistant.io\/integrations\/binary_sensor.mqtt\/) for your garden would send its configuration as JSON payload to the Configuration topic. After the first message to `config`, then the MQTT messages sent to the state topic will update the state in Home Assistant.\n\n- Configuration topic: `homeassistant\/binary_sensor\/garden\/config`\n- State topic: `homeassistant\/binary_sensor\/garden\/state`\n- Configuration payload with derived device name:\n\n```\n{\n   \"name\":null,\n   \"device_class\":\"motion\",\n   \"state_topic\":\"homeassistant\/binary_sensor\/garden\/state\",\n   \"unique_id\":\"motion01ad\",\n   \"device\":{\n      \"identifiers\":[\n         \"01ad\"\n      ],\n      \"name\":\"Garden\"\n   }\n}\n```\nJSON\n\n- Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts.\n\nIt is also a good idea to add a `unique_id` to allow changes to the entity and a `device` mapping so we can group all sensors of a device together. We can set “name” to `null` if we want to inherit the device name for the entity. If we set an entity name, the `friendly_name` will be a combination of the device and entity name. If `name` is left away and a `device_class` is set, the entity name part will be derived from the `device_class`.\n\n- Example configuration payload with no name set and derived `device_class` name:\n\n```\n{\n   \"name\":null,\n   \"device_class\":\"motion\",\n   \"state_topic\":\"homeassistant\/binary_sensor\/garden\/state\",\n   \"unique_id\":\"motion01ad\",\n   \"device\":{\n      \"identifiers\":[\n         \"01ad\"\n      ],\n      \"name\":\"Garden\"\n   }\n}\n```\nJSON\n\nIf no name is set, a default name will be set by MQTT ([see the MQTT platform documentation](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#mqtt-discovery)).\n\nTo create a new sensor manually and with the name set to `null` to derive the device name “Garden”:\n\n```\nmosquitto_pub -r -h 127.0.0.1 -p 1883 -t \"homeassistant\/binary_sensor\/garden\/config\" -m '{\"name\": null, \"device_class\": \"motion\", \"state_topic\": \"homeassistant\/binary_sensor\/garden\/state\", \"unique_id\": \"motion01ad\", \"device\": {\"identifiers\": [\"01ad\"], \"name\": \"Garden\" }}'\n```\nBash\n\nUpdate the state:\n\n```\nmosquitto_pub -h 127.0.0.1 -p 1883 -t \"homeassistant\/binary_sensor\/garden\/state\" -m ON\n```\nBash\n\nDelete the sensor by sending an empty message.\n\n```\nmosquitto_pub -h 127.0.0.1 -p 1883 -t \"homeassistant\/binary_sensor\/garden\/config\" -m ''\n```\nBash\n\nFor more details, refer to the [MQTT testing section](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#testing-your-setup).\n\n#### Sensors\nSetting up a sensor with multiple measurement values requires multiple consecutive configuration topic submissions.\n\n- Configuration topic no1: `homeassistant\/sensor\/sensorBedroomT\/config`\n- Configuration payload no1:\n\n```\n{\n   \"device_class\":\"temperature\",\n   \"state_topic\":\"homeassistant\/sensor\/sensorBedroom\/state\",\n   \"unit_of_measurement\":\"°C\",\n   \"value_template\":\"{{ value_json.temperature}}\",\n   \"unique_id\":\"temp01ae\",\n   \"device\":{\n      \"identifiers\":[\n          \"bedroom01ae\"\n      ],\n      \"name\":\"Bedroom\",\n      \"manufacturer\": \"Example sensors Ltd.\",\n      \"model\": \"Example Sensor\",\n      \"model_id\": \"K9\",\n      \"serial_number\": \"12AE3010545\",\n      \"hw_version\": \"1.01a\",\n      \"sw_version\": \"2024.1.0\",\n      \"configuration_url\": \"<https:\/\/example.com\/sensor_portal\/config>\"\n   }\n}\n```\nJSON\n\n- Configuration topic no2: `homeassistant\/sensor\/sensorBedroomH\/config`\n- Configuration payload no2:\n\n```\n{\n   \"device_class\":\"humidity\",\n   \"state_topic\":\"homeassistant\/sensor\/sensorBedroom\/state\",\n   \"unit_of_measurement\":\"%\",\n   \"value_template\":\"{{ value_json.humidity}}\",\n   \"unique_id\":\"hum01ae\",\n   \"device\":{\n      \"identifiers\":[\n         \"bedroom01ae\"\n      ]\n   }\n}\n```\nJSON\n\nThe sensor [`identifiers` or `connections`](https:\/\/www.home-assistant.io\/integrations\/sensor.mqtt\/#device) option allows to set up multiple entities that share the same device.\n\nNote\n\nIf a device configuration is shared, then it is not needed to add all device details to the other entity configs. It is enough to add shared identifiers or connections to the device mapping for the other entity config payloads.\n\nA common state payload that can be parsed with the `value_template` in the sensor configs:\n\n```\n{\n   \"temperature\":23.20,\n   \"humidity\":43.70\n}\n```\nJSON\n#### Entities with command topics\nSetting up a light or switch is similar but requires a `command_topic` as mentioned in the [MQTT switch documentation](https:\/\/www.home-assistant.io\/integrations\/switch.mqtt\/).\n\n- Configuration topic: `homeassistant\/switch\/irrigation\/config`\n- State topic: `homeassistant\/switch\/irrigation\/state`\n- Command topic: `homeassistant\/switch\/irrigation\/set`\n- Payload:\n\n```\n{\n   \"name\":\"Irrigation\",\n   \"command_topic\":\"homeassistant\/switch\/irrigation\/set\",\n   \"state_topic\":\"homeassistant\/switch\/irrigation\/state\",\n   \"unique_id\":\"irr01ad\",\n   \"device\":{\n      \"identifiers\":[\n         \"garden01ad\"\n      ],\n      \"name\":\"Garden\"\n   }\n}\n```\nJSON\n\n- Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts.\n\n```\nmosquitto_pub -r -h 127.0.0.1 -p 1883 -t \"homeassistant\/switch\/irrigation\/config\" \\\n  -m '{\"name\": \"Irrigation\", \"command_topic\": \"homeassistant\/switch\/irrigation\/set\", \"state_topic\": \"homeassistant\/switch\/irrigation\/state\", \"unique_id\": \"irr01ad\", \"device\": {\"identifiers\": [\"garden01ad\"], \"name\": \"Garden\" }}'\n```\nBash\n\nSet the state:\n\n```\nmosquitto_pub -h 127.0.0.1 -p 1883 -t \"homeassistant\/switch\/irrigation\/set\" -m ON\n```\nBash\n#### Using abbreviations and base topic\nSetting up a switch using topic prefix and abbreviated configuration variable names to reduce payload length.\n\n- Configuration topic: `homeassistant\/switch\/irrigation\/config`\n- Command topic: `homeassistant\/switch\/irrigation\/set`\n- State topic: `homeassistant\/switch\/irrigation\/state`\n- Configuration payload:\n\n```\n{\n   \"~\":\"homeassistant\/switch\/irrigation\",\n   \"name\":\"garden\",\n   \"cmd_t\":\"~\/set\",\n   \"stat_t\":\"~\/state\"\n}\n```\nJSON\n\nNote\n\n#### Another example using abbreviations topic name and base topic\nSetting up a [light that takes JSON payloads](https:\/\/www.home-assistant.io\/integrations\/light.mqtt\/#json-schema), with abbreviated configuration variable names:\n\n- Configuration topic: `homeassistant\/light\/kitchen\/config`\n- Command topic: `homeassistant\/light\/kitchen\/set`\n- State topic: `homeassistant\/light\/kitchen\/state`\n- Example state payload: `{\"state\": \"ON\", \"brightness\": 255}`\n- Configuration payload:\n  ```\n  {\n  \"~\": \"homeassistant\/light\/kitchen\",\n  \"name\": \"Kitchen\",\n  \"uniq_id\": \"kitchen_light\",\n  \"cmd_t\": \"~\/set\",\n  \"stat_t\": \"~\/state\",\n  \"schema\": \"json\",\n  \"brightness\": true\n}\n  ```\n  JSON\n#### Example with using abbreviated Device and Origin info in discovery messages\n```\n{\n  \"~\": \"homeassistant\/light\/kitchen\",\n  \"name\": null,\n  \"uniq_id\": \"kitchen_light\",\n  \"cmd_t\": \"~\/set\",\n  \"stat_t\": \"~\/state\",\n  \"schema\": \"json\",\n  \"dev\": {\n    \"ids\": \"ea334450945afc\",\n    \"name\": \"Kitchen\",\n    \"mf\": \"Bla electronics\",\n    \"mdl\": \"xya\",\n    \"mdl_id\": \"ABC123\",\n    \"sw\": \"1.0\",\n    \"sn\": \"ea334450945afc\",\n    \"hw\": \"1.0rev2\"\n  },\n  \"o\": {\n    \"name\":\"bla2mqtt\",\n    \"sw\": \"2.1\",\n    \"url\": \"<https:\/\/bla2mqtt.example.com\/support>\"\n  }\n}\n```\nJSON\n### Support by third-party tools\nThe following software has built-in support for MQTT discovery:\n\n- [anpr2mqtt](https:\/\/anpr2mqtt.rhizomatics.org.uk\/)\n- [ArduinoHA](https:\/\/github.com\/dawidchyrzynski\/arduino-home-assistant)\n- [Arilux AL-LC0X LED controllers](https:\/\/github.com\/smrtnt\/Arilux_AL-LC0X)\n- [ble2mqtt](https:\/\/github.com\/devbis\/ble2mqtt)\n- [diematic\\_server](https:\/\/github.com\/IgnacioHR\/diematic_server)\n- [digitalstrom-mqtt](https:\/\/github.com\/gaetancollaud\/digitalstrom-mqtt)\n- [ebusd](https:\/\/github.com\/john30\/ebusd)\n- [ecowitt2mqtt](https:\/\/github.com\/bachya\/ecowitt2mqtt)\n- [EMS-ESP32 (and EMS-ESP)](https:\/\/github.com\/emsesp\/EMS-ESP32)\n- [ESPHome](https:\/\/esphome.io\/)\n- [ESPurna](https:\/\/github.com\/xoseperez\/espurna)\n- [go-iotdevice](https:\/\/github.com\/koestler\/go-iotdevice)\n- [HASS.Agent](https:\/\/github.com\/LAB02-Research\/HASS.Agent)\n- [IOTLink](https:\/\/iotlink.gitlab.io\/) (starting with 2.0.0)\n- [MiFlora MQTT Daemon](https:\/\/github.com\/ThomDietrich\/miflora-mqtt-daemon)\n- [MyElectricalData](https:\/\/github.com\/MyElectricalData\/myelectricaldata_import#english)\n- [MqDockerUp](https:\/\/github.com\/MichelFR\/MqDockerUp)\n- [Nuki Hub](https:\/\/github.com\/technyon\/nuki_hub)\n- [Nuki Smart Lock 3.0 Pro](https:\/\/support.nuki.io\/hc\/articles\/12947926779409-MQTT-support), [more info](https:\/\/developer.nuki.io\/t\/mqtt-api-specification-v1-3\/17626)\n- [OpenMQTTGateway](https:\/\/github.com\/1technophile\/OpenMQTTGateway)\n- [OTGateway](https:\/\/github.com\/Laxilef\/OTGateway)\n- [rethink](https:\/\/github.com\/anszom\/rethink)\n- [room-assistant](https:\/\/github.com\/mKeRix\/room-assistant) (starting with 1.1.0)\n- [SmartHome](https:\/\/github.com\/roncoa\/SmartHome)\n- [SpeedTest-CLI MQTT](https:\/\/github.com\/adorobis\/speedtest-CLI2mqtt)\n- [SwitchBot-MQTT-BLE-ESP32](https:\/\/github.com\/devWaves\/SwitchBot-MQTT-BLE-ESP32)\n- [Tasmota](https:\/\/github.com\/arendst\/Tasmota) (starting with 5.11.1e, development halted)\n- [TeddyCloud](https:\/\/github.com\/toniebox-reverse-engineering\/teddycloud)\n- [Teleinfo MQTT](https:\/\/fmartinou.github.io\/teleinfo2mqtt) (starting with 3.0.0)\n- [Tydom2MQTT](https:\/\/tydom2mqtt.github.io\/tydom2mqtt\/)\n- [Updates2MQTT](https:\/\/updates2mqtt.rhizomatics.org.uk\/)\n- [What’s up Docker?](https:\/\/fmartinou.github.io\/whats-up-docker\/) (starting with 3.5.0)\n- [WyzeSense2MQTT](https:\/\/github.com\/raetha\/wyzesense2mqtt)\n- [Xiaomi DaFang Hacks](https:\/\/github.com\/EliasKotlyar\/Xiaomi-Dafang-Hacks)\n- [Zehnder Comfoair RS232 MQTT](https:\/\/github.com\/adorobis\/hacomfoairmqtt)\n- [Zigbee2MQTT](https:\/\/github.com\/koenkk\/zigbee2mqtt)\n\nThe following software also supports consuming MQTT discovery information that is intended for Home Assistant. Compatibility and features will vary, and not all devices may work.\n\n- [Domoticz](https:\/\/wiki.domoticz.com\/MQTT#Add_hardware_.22MQTT_Auto_Discovery_Client_Gateway.22)\n- [openHAB](https:\/\/www.openhab.org\/addons\/bindings\/mqtt.homeassistant\/)\n## Manual configured MQTT items\nSupport to allow [adding manual items as a subentry via a config flow](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#configuration), is work in progress. Not all entity platforms are supported yet.\n\nFor most integrations, it is also possible to manually set up MQTT items in `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\\[Learn more\\]](https:\/\/www.home-assistant.io\/docs\/configuration\/). Read more [about configuration in YAML](https:\/\/www.home-assistant.io\/docs\/configuration\/yaml).\n\nMQTT supports two styles for configuring items in YAML. All configuration items are placed directly under the `mqtt` integration key. Note that you cannot mix these styles. Use the *YAML configuration listed per item* style when in doubt.\n\n### YAML configuration listed per item\nThis method expects all items to be in a YAML list. Each item has a `{domain}` key and the item config is placed directly under the domain key. This method is considered as best practice. In all the examples we use this format.\n\n```\nmqtt:\n  - {domain}:\n      name: \"\"\n      ...\n  - {domain}:\n      name: \"\"\n      ...\n```\nYAML\n### YAML configuration keyed and bundled by `{domain}`\nAll items are grouped per `{domain}` and where all configs are listed.\n\n```\nmqtt:\n  {domain}:\n    - name: \"\"\n      ...\n    - name: \"\"\n      ...\n```\nYAML\n\nIf you have a large number of manually configured items, you might want to consider [splitting up the configuration](https:\/\/www.home-assistant.io\/docs\/configuration\/splitting_configuration\/).\n\n## Entity state updates\nEntities receive state updates via MQTT subscriptions. The payloads received on the state topics are processed to determine whether there is a significant change. If a change is detected, the entity will be updated.\n\nNote that MQTT device payloads often contain information for updating multiple entities that subscribe to the same topics. For example, a light status update might include information about link quality. This data can update a link quality sensor but is not used to update the light itself. MQTT filters out entity state updates when there are no changes.\n\n### The last reported state attribute\nBecause MQTT state updates are often repeated frequently, even when no actual changes exist, it is up to the MQTT subscriber to determine whether a status update was received. If the latest update is missed, it might take some time before the next one arrives. If a retained payload exists at the broker, that value will be replayed first, but it will be an update of a previous last state.\n\nMQTT devices often continuously generate numerous state updates. MQTT does not update `last_reported` to avoid impacting system stability unless `force_update` is set. Alternatively, an MQTT sensor can be created to measure the last update.\n\n## Using Templates\nThe MQTT integration supports templating. Read more [about using templates with the MQTT integration](https:\/\/www.home-assistant.io\/docs\/templating\/where-to-use\/#mqtt).\n\n### Examples\n#### REST API\nUsing the [REST API](https:\/\/developers.home-assistant.io\/docs\/api\/rest\/) to send a message to a given topic.\n\n#### Automations\nUse as [`script`](https:\/\/www.home-assistant.io\/integrations\/script\/) in automations.\n\n```\nautomation:\n  alias: \"Send me a message when I get home\"\n  triggers:\n    - trigger: state\n      entity_id: device_tracker.me\n      to: \"home\"\n  actions:\n    - action: script.notify_mqtt\n      data:\n        target: \"me\"\n        message: \"I'm home\"\n\nscript:\n  notify_mqtt:\n    sequence:\n      - action: mqtt.publish\n        data:\n          payload: \"{{ message }}\"\n          topic: \"home\/{{ target }}\"\n          retain: true\n```\nYAML\n## Publish & Dump actions\nThe MQTT integration will register the `mqtt.publish` action, which allows publishing messages to MQTT topics.\n\n### Action: Publish\nThe `mqtt.publish` action publishes a message to an MQTT topic.\n\n| Data attribute | Optional | Description |\n|---|---|---|\n| `topic` | no | Topic to publish payload to. |\n| `payload` | yes | Payload to publish. Will publish an empty payload when `payload` is omitted. |\n| `evaluate_payload` | yes | If a `bytes` literal in `payload` should be evaluated to publish raw data. (default: false) |\n| `qos` | yes | Quality of Service to use. (default: 0) |\n| `retain` | yes | If message should have the retain flag set. (default: false) |\n\nNote\n\nWhen `payload` is rendered from [template](https:\/\/www.home-assistant.io\/docs\/templating\/where-to-use\/#mqtt) in a YAML script or automation, and the template renders to a `bytes` literal, the outgoing MQTT payload will only be sent as `raw` data, if the `evaluate_payload` option flag is set to `true`.\n\n```\ntopic: homeassistant\/light\/1\/command\npayload: \"ON\"\n```\nYAML\n\n```\ntopic: homeassistant\/light\/1\/state\npayload: \"{{ states('device_tracker.paulus') }}\"\n```\nYAML\n\n```\ntopic: \"homeassistant\/light\/{{ states('sensor.light_active') }}\/state\"\npayload: \"{{ states('device_tracker.paulus') }}\"\n```\nYAML\n\nBe aware that `payload` must be a string. If you want to send JSON using the YAML editor then you need to format\/escape it properly. Like:\n\n```\ntopic: homeassistant\/light\/1\/state\npayload: \"{\\\"Status\\\":\\\"off\\\", \\\"Data\\\":\\\"something\\\"}\"\n```\nYAML\n\nThe example below shows how to publish a temperature sensor ‘Bathroom Temperature’. The `device_class` is set, so it is not needed to set the “name” option. The entity will inherit the name from the `device_class` set and also support translations. If you set “name” in the payload the entity name will start with the device name.\n\n```\naction: mqtt.publish\ndata:\n  topic: homeassistant\/sensor\/Acurite-986-1R-51778\/config\n  payload: >-\n    {\"device_class\": \"temperature\",\n    \"unit_of_measurement\": \"\\u00b0C\",\n    \"value_template\": \"{{ value | float }}\",\n    \"state_topic\": \"rtl_433\/rtl433\/devices\/Acurite-986\/1R\/51778\/temperature_C\",\n    \"unique_id\": \"Acurite-986-1R-51778-T\",\n    \"device\": {\n    \"identifiers\": \"Acurite-986-1R-51778\",\n    \"name\": \"Bathroom\",\n    \"model\": \"Acurite\",\n    \"model_id\": \"986\",\n    \"manufacturer\": \"rtl_433\" }\n    }\n```\nYAML\n\nExample of how to use `qos` and `retain`:\n\n```\ntopic: homeassistant\/light\/1\/command\npayload: \"ON\"\nqos: 2\nretain: true\n```\nYAML\n### Action: Dump\nThe `mqtt.dump` action listens to the specified topic matcher and dumps all received messages within a specific duration into the file `mqtt_dump.txt` in your configuration folder. This is useful when debugging a problem.\n\n| Data attribute | Optional | Description |\n|---|---|---|\n| `topic` | no | Topic to dump. Can contain a wildcard (`#` or `+`). |\n| `duration` | yes | Duration in seconds that we will listen for messages. Default is 5 seconds. |\n\n```\ntopic: zigbee2mqtt\/#\n```\nYAML\n## Logging\nThe [logger](https:\/\/www.home-assistant.io\/integrations\/logger\/) integration allows the logging of received MQTT messages.\n\n```\n# Example configuration.yaml entry\nlogger:\n  default: warning\n  logs:\n    homeassistant.components.mqtt: debug\n```\nYAML\n## Event `event_mqtt_reloaded`\nEvent `event_mqtt_reloaded` is fired when Manually configured MQTT entities have been reloaded and entities thus might have changed.\n\nThis event has no additional data.\n\n## Removing the integration\n1. Go to [**Settings** \\> **Devices & services**](https:\/\/my.home-assistant.io\/redirect\/integrations) and select the integration card.\n2. From the list of devices, select the integration instance you want to remove.\n3. Next to the entry, select the three dots\n   menu. Then, select **Delete**.\n\nNote: This action does not remove the [MQTT broker](https:\/\/www.home-assistant.io\/integrations\/mqtt\/#setting-up-a-broker) or its data. If you want to completely remove MQTT:\n\n1. Check your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\\[Learn more\\]](https:\/\/www.home-assistant.io\/docs\/configuration\/) and other YAML files for MQTT-related configurations and remove them\n2. Review your automations and scripts for any MQTT dependencies\n3. Consider backing up your configuration before making these changes\n\n#### **Help us improve our documentation**\nSuggest an edit to this page, or provide\/view feedback for this page.\n\n- [Edit](https:\/\/github.com\/home-assistant\/home-assistant.io\/tree\/current\/source\/_integrations\/mqtt.markdown \"Edit this page\")\n- [Provide feedback](https:\/\/github.com\/home-assistant\/home-assistant.io\/issues\/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fintegrations%2Fmqtt%2F&version=2026.4.1&labels=current,integration%3A%20mqtt \"Provide feedback on this page\")\n- [View pending feedback](https:\/\/github.com\/home-assistant\/home-assistant.io\/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22integration%3A+mqtt%22 \"View pending feedback for this page\")","meta_canonical":null}

3. Robots.txt Check

Query:

Response:

4. Spam/Ban Check

Query:

Response:

5. Seen Status Check

ℹ️ Skipped - page is already crawled

📄

INDEXABLE

✅

CRAWLED

6 hours ago

🤖

ROBOTS ALLOWED

Page Info Filters

Filter	Status	Condition	Details
HTTP status	PASS	`download_http_code = 200`	HTTP 200
Age cutoff	PASS	`download_stamp > now() - 6 MONTH`	0 months ago
History drop	PASS	`isNull(history_drop_reason)`	No drop reason
Spam/ban	PASS	`fh_dont_index != 1 AND ml_spam_score = 0`	ml_spam_score=0
Canonical	PASS	`meta_canonical IS NULL OR = '' OR = src_unparsed`	Not set

Page Details

Property	Value
URL	https://www.home-assistant.io/integrations/mqtt/
Last Crawled	2026-04-11 01:35:54 (6 hours ago)
First Indexed	2019-10-02 00:41:57 (6 years ago)
HTTP Status Code	200
Meta Title	MQTT - Home Assistant
Meta Description	Instructions on how to setup MQTT within Home Assistant.
Meta Canonical	null
Boilerpipe Text	MQTT (aka MQ Telemetry Transport) is a machine-to-machine or “Internet of Things” connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport. Configuration To add the MQTT service to your Home Assistant instance, use this My button: Manual configuration steps If the above My button doesn’t work, you can also perform the following steps manually: Browse to your Home Assistant instance. Go to Settings > Devices & services . In the bottom right corner, select the Add Integration button. From the list, select MQTT . Follow the instructions on screen to complete the setup. MQTT devices and entities can be set up through MQTT discovery or added manually via YAML or subentries. Configuration of MQTT components via MQTT discovery Configuration of MQTT components via YAML Your first step to get MQTT and Home Assistant working is to choose a broker. The easiest option is to install the official Mosquitto Broker app for Home Assistant (formerly known as Mosquitto Broker add-on). You can choose to set up and configure this app automatically when you set up the MQTT integration. Home Assistant will automatically generate and assign a safe username and password, and no further attention is required. This also works if you have already set up this app yourself in advance. You can set up additional logins for your MQTT devices and services using the Mosquitto app configuration . Important When MQTT is set up with the official Mosquitto MQTT broker app, the broker’s credentials are generated and kept secret. If the official Mosquitto MQTT broker needs to be re-installed, make sure you save a copy of the app user options, like the additional logins. After re-installing the app, the MQTT integration will automatically update the new password for the re-installed broker. It will then reconnect automatically. Alternatively, you can use a different MQTT broker that you configure yourself, ensuring it is compatible with Home Assistant. Setting up a broker While public MQTT brokers are available, the easiest and most private option is running your own. The recommended setup method is to use the Mosquitto MQTT broker app . Warning Neither ActiveMQ MQTT broker nor the RabbitMQ MQTT Plugin are supported, use a known working broker like Mosquitto instead. There are at least two issues with the ActiveMQ MQTT broker which break MQTT message retention. Broker configuration MQTT broker settings are configured when the MQTT integration is first set up and can be changed later if needed. Add the MQTT integration, then provide your broker’s hostname (or IP address) and port and (if required) the username and password that Home Assistant should use. To change the settings later, follow these steps: Go to Settings > Devices & services . Select the MQTT integration. Reconfigure the MQTT broker settings via Settings > Devices & services , select , and select Reconfigure . MQTT subentries can also be reconfigured. Additional entities can be added, or an entity can be removed from the sub entry. Each MQTT subentry holds one MQTT device. The MQTT device must have at least one entity. Important If you experience an error message like Failed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed , then turn on Advanced options and set Broker certificate validation to Auto . Advanced broker configuration Advanced broker configuration options include setting a custom client ID, setting a client certificate and key for authentication, and enabling TLS validation of the broker’s certificate for secure connection. To access the advanced settings, open the MQTT broker settings, switch on Advanced options , and select Next . The advanced options will be shown by default if there are advanced settings active already. Tip Advanced broker options are accessible only when advanced mode is enabled (see user settings), or when advanced broker settings are configured already. Alternative client ID You can set a custom MQTT client ID, this can help when debugging. Mind that the client ID must be unique. Leave this settings default if you want Home Assistant to generate a unique ID. Keep alive The time in seconds between sending keep alive messages for this client. The default is 60 seconds. The keep alive setting should be at least 15 seconds. Broker certificate validation To enable a secure connection to the broker, the broker certificate should be validated. If your broker uses a trusted certificate, then choose Auto . This validates the broker certificate against the bundled certificate authority (CA) certificates. If a self-signed certificate is used, select Custom . A custom PEM- or DER-encoded CA certificate can be uploaded. Select Next to show the control to upload the CA certificate. If the server certificate does not match the hostname then validation will fail. To allow a connection without the verification of the hostname, turn the Ignore broker certificate validation switch on. MQTT Protocol The MQTT protocol setting defaults to version 3.1.1 . If your MQTT broker supports MQTT version 5 you can set the protocol setting to 5 . Securing the connection With a secure broker connection, it is possible to use a client certificate for authentication. To set the client certificate and private key, turn on the option Use a client certificate and select Next to reveal file upload controls. A client certificate and the corresponding private key must be uploaded together. Both client certificate and private key must be either PEM- or DER-encoded. If the private key is encrypted with a password, ensure you supply the correct password when uploading the client certificate and key files. Using WebSockets as transport You can select websockets as the transport method if your MQTT broker supports it. When you select websockets and select Next , you will be able to add a WebSockets path (default is / ) and WebSockets headers (optional). The target WebSockets URI ws://{broker}:{port}{ws_path} is built with the broker , port , and ws_path (WebSocket path) settings. To configure the WebSocket’s headers, supply a valid JSON dictionary string. For example, { "Authorization": "token" , "x-header": "some header"} . The default transport method is tcp . The WebSockets transport can be secured using TLS and optionally using user credentials or a client certificate. Note A configured client certificate will only be active if broker certificate validation is enabled. Configure MQTT options To change the options, follow these steps: Go to Settings > Devices & services . Select the MQTT integration. Select Configure , then Re-configure MQTT . To open the MQTT options page, select Next . Change MQTT discovery options The MQTT discovery options can be changed by following these steps: Go to Settings > Devices & services . Find the MQTT integration and select it. To open the MQTT discovery options page, select the Configure MQTT Options button. Discovery options MQTT discovery is enabled by default. Discovery can be turned off. The prefix for the discovery topic (default homeassistant ) can be changed here as well. See also MQTT Discovery section Birth and last will messages Home Assistant’s MQTT integration supports so-called Birth and Last Will and Testament (LWT) messages. The former is used to send a message after the service has started, and the latter is used to notify other clients about a disconnected client. Note that the LWT message will be sent both in case of a clean disconnect (for example, Home Assistant shutting down) and in case of an unclean disconnect (for example, Home Assistant crashing or losing its network connection). If a disabled entity is enabled and added after 30 seconds, the MQTT integration will be reloaded and will cause all discovered MQTT entities to be unloaded. When MQTT starts up, all existing MQTT devices, entities, tags, and device triggers, will be unavailable until a discovery message is received and processed. A device or service that exposes the MQTT discovery should subscribe to the Birth message and use this as a trigger to send the discovery payload . To avoid high IO loads on the MQTT broker, adding some random delay in sending the discovery payload is recommended. Alternative approaches: Retaining the discovery payload : This will store the discovery payload at the MQTT broker, and offer it to the MQTT integration as soon as it subscribes for MQTT discovery. When there are a lot of entities, this can cause high IO loads. Periodically resending the discovery payload: This can cause some delay, or a lot of IO if there are a lot of MQTT discovery messages. By default, Home Assistant sends online and offline to homeassistant/status . MQTT Birth and Last Will messages can be customized or disabled from the UI. To do this, select Configure on the integration page in the UI, then Re-configure MQTT , and then Next . Testing your setup The mosquitto broker package ships command line tools (often as *-clients package) to send and receive MQTT messages. For sending test messages to a broker running on localhost , you can use mosquitto_pub , check the example below: mosquitto_pub -h 127.0 .0.1 -t homeassistant/switch/1/on -m "Switch is ON" Bash Another way to send MQTT messages manually is to use the MQTT integration in the frontend. Select Settings on the left menu, select Devices & services , and select Configure in the Mosquitto broker tile. Enter something similar to the example below into the topic field under Publish a packet and select Publish . Go to Settings > Devices & services . Select the Mosquitto broker integration, then select Configure . Enter something similar to the example below into the topic field under Publish a packet . Select Publish . homeassistant/switch/1/power Bash and in the Payload field ON Bash In the Listen to a topic field, type # to see everything, or homeassistant/switch/# to just follow a published topic, then select Start listening . The messages should appear similar to the text below: Message 23 received on homeassistant/switch/1/power/stat/POWER at 12 :16 PM: ON QoS: 0 - Retain: false Message 22 received on homeassistant/switch/1/power/stat/RESULT at 12 :16 PM: { "POWER" : "ON" } QoS: 0 - Retain: false Bash For reading all messages sent on the topic homeassistant to a broker running on localhost: mosquitto_sub -h 127.0 .0.1 -v -t "homeassistant/#" Bash Naming of MQTT Entities For every configured MQTT entity Home Assistant automatically assigns a unique entity_id . If the unique_id option is configured, you can change the entity_id after creation, and the changes are stored in the Entity Registry. The entity_id is generated when an item is loaded the first time. If the default_entity_id option is set, then this will be used to generate the entity_id . If, for example, we have configured a sensor , and we have set default_entity_id to sensor.test , then Home Assistant will try to assign sensor.test as entity_id . If sensor.test already exists, Home Assistant will append a suffix to make it unique, for example, sensor.test_2 . This means any MQTT entity which is part of a device will automatically have its friendly_name attribute prefixed with the device name Unnamed binary_sensor , button , number , and sensor entities will now be named by their device class instead of being named “MQTT binary sensor” and similar. It’s allowed to set an MQTT entity’s name to None (use null in YAML) to mark it as the main feature of a device. Note that on each MQTT entity, the has_entity_name attribute will be set to True . More details can be found here . Grouping entities If the MQTT entity represents a group of other entities, the member entities can be made visible in the UI by setting the list of unique IDs of the member entities in the group configuration option of the entity group: group A list of unique IDs of the member entities. Set this if the entity represents a group entity. Note that the member entities must be already configured before the member entities will become visible in the UI at the moment a group entity is loaded. MQTT Discovery The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the HTTP binary sensor and the HTTP sensor . To prevent multiple identical entries if a device reconnects, a unique identifier is necessary. Two parts are required on the device side: The configuration topic, and the device configuration as payload. MQTT discovery is enabled by default, but can be disabled. The prefix for the discovery topic (default homeassistant ) can be changed. See the MQTT Options sections Note Documentation on the MQTT components that support MQTT discovery can be found here . Discovery messages MQTT discovery supports two types of discovery messages: Device discovery , which allows you to include several components in a single discovery message Single component discovery , where you publish a separate discovery message for each component If you use a device with multiple components, it is recommended to use MQTT device discovery. It reduces the number of messages sent, and allows you to send the device information only once. Discovery topic The discovery topic needs to follow a specific format: <discovery_prefix>/<component>/[<node_id>/]<object_id>/config Text <discovery_prefix> : The Discovery Prefix defaults to homeassistant and this prefix can be changed . <component> : One of the supported MQTT integrations, for example, binary_sensor , or device in case of device discovery. <node_id> : ( Optional ): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. The ID of the node must only consist of characters from the character class [a-zA-Z0-9_-] (alphanumerics, underscore and hyphen). <object_id> : The ID of the device. This allows for separate topics for each device. The ID of the device must only consist of characters from the character class [a-zA-Z0-9_-] (alphanumerics, underscore and hyphen). Note: The <object_id> in the topic does not influence the resulting entity_id ; use default_entity_id if you need to control the entity_id . The <node_id> is optional, and can be used by clients to subscribe to their own (command) topics by using one wildcard topic like <discovery_prefix>/+/<node_id>/+/set . Best practice for entities with a unique_id is to set <object_id> to the unique_id and omit the <node_id> . Device discovery payload A device can send a discovery payload to expose all components for a device. The <component> part in the discovery topic must be set to device . As an alternative, it is also possible for a device to send a discovery payload for each component it wants to set up. The shared options at the root level of the JSON message must include: device mapping (abbreviated as dev ) origin mapping (abbreviated as o ) These mappings are mandatory and cannot be overridden at the entity/component level. Supported shared options are: The availability options . The origin (required) options command_topic state_topic qos encoding The component specific options are placed as mappings under the components key (abbreviated as cmps ) like: { "dev" : { "ids" : "ea334450945afc" , "name" : "Kitchen" , "mf" : "Bla electronics" , "mdl" : "xya" , "sw" : "1.0" , "sn" : "ea334450945afc" , "hw" : "1.0rev2" } , "o" : { "name" : "bla2mqtt" , "sw" : "2.1" , "url" : " https://bla2mqtt.example.com/support " } , "cmps" : { "some_unique_component_id1" : { "p" : "sensor" , "device_class" : "temperature" , "unit_of_measurement" : "°C" , "value_template" : "{{ value_json.temperature}}" , "unique_id" : "temp01ae_t" } , "some_unique_id2" : { "p" : "sensor" , "device_class" : "humidity" , "unit_of_measurement" : "%" , "value_template" : "{{ value_json.humidity}}" , "unique_id" : "temp01ae_h" } } , "state_topic" : "sensorBedroom/state" , "qos" : 2 } JSON Note The components id’s under the components ( cmps ) key, are used as part of the discovery identification. A platform ( p ) config option is required for each component config that is added to identify the component platform. Also required is a unique_id for entity-based components. To remove the components, publish an empty (retained) string payload to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it. An empty config can be published as an update to remove a single component from the device discovery. Note that adding the platform ( p ) option is still required. { "dev" : { "ids" : "ea334450945afc" , "name" : "Kitchen" , "mf" : "Bla electronics" , "mdl" : "xya" , "sw" : "1.0" , "sn" : "ea334450945afc" , "hw" : "1.0rev2" } , "o" : { "name" : "bla2mqtt" , "sw" : "2.1" , "url" : " https://bla2mqtt.example.com/support " } , "cmps" : { "some_unique_component_id1" : { "p" : "sensor" , "device_class" : "temperature" , "unit_of_measurement" : "°C" , "value_template" : "{{ value_json.temperature}}" , "unique_id" : "temp01ae_t" } , "some_unique_id2" : { "p" : "sensor" } } , "state_topic" : "sensorBedroom/state" , "qos" : 2 } JSON This will explicitly remove the humidity sensor and its entry. After removing a component, you should send another update with the removed component omitted from the configuration. This ensures that Home Assistant has the most up-to-date device configuration. For example: { "dev" : { "ids" : "ea334450945afc" , "name" : "Kitchen" , "mf" : "Bla electronics" , "mdl" : "xya" , "sw" : "1.0" , "sn" : "ea334450945afc" , "hw" : "1.0rev2" } , "o" : { "name" : "bla2mqtt" , "sw" : "2.1" , "url" : " https://bla2mqtt.example.com/support " } , "cmps" : { "some_unique_component_id1" : { "p" : "sensor" , "device_class" : "temperature" , "unit_of_measurement" : "°C" , "value_template" : "{{ value_json.temperature}}" , "unique_id" : "temp01ae_t" } } , "state_topic" : "sensorBedroom/state" , "qos" : 2 } JSON A component config part in a device discovery payload must have the platform ( p ) option set with the name of the component and also must have at least one component specific config option. Entity components must have set the unique_id option and have a device context. Migration from single component to device discovery To allow a smooth migration from single component discovery to device discovery: Ensure all entities have a unique_id and a device context. Move the object_id inside the discovery payload, if that is available, or use a unique ID or the component. Consider using the previous node_id as the new object_id of the device discovery topic. Ensure the unique_id matches and the device context has the correct identifiers. Send the following payload to all existing single component discovery topics: {"migrate_discovery": true } . This will unload the discovered item, but its settings will be retained. Switch the discovery topic to the device discovery topic and include all the component configurations. Clean up the single component discovery messages with an empty payload. During the migration steps, INFO messages will be logged to inform you about the progress of the migration. Important Consider testing the migration process in a non-production environment before applying it to a live system. Discovery migration example with a device automation and a sensor Step 1: Original single component discovery configurations: Discovery topic single: homeassistant/device_automation/0AFFD2/bla1/config Discovery id: 0AFFD2 bla1 (both 0AFFD2 and bla1 from the discovery topic) Discovery payload single: { "device" : { "identifiers" : [ "0AFFD2" ] , "name" : "Test device" } , "o" : { "name" : "foobar" } , "automation_type" : "trigger" , "payload" : "short_press" , "topic" : "foobar/triggers/button1" , "type" : "button_short_press" , "subtype" : "button_1" } JSON Discovery topic single: homeassistant/sensor/0AFFD2/bla2/config Discovery id: 0AFFD2 bla2 (both 0AFFD2 and bla2 from the discovery topic) Discovery payload single: { "device" : { "identifiers" : [ "0AFFD2" ] , "name" : "Test device" } , "o" : { "name" : "foobar" } , "state_topic" : "foobar/sensor/sensor1" , "unique_id" : "bla_sensor001" } JSON Step 2: Initiate migration by publishing to both discovery topics: When these single component discovery payloads are processed, and we want to initiate migration to device discovery, we need to publish … { "migrate_discovery" : true } JSON … to both discovery topics … homeassistant/device_automation/0AFFD2/bla1/config homeassistant/sensor/0AFFD2/bla2/config Important Check the logs to ensure this step is executed correctly. Step 3: Publish the new device discovery configuration: Discovery topic device: homeassistant/device/0AFFD2/config Discovery id: 0AFFD2 bla ( 0AFFD2 from discovery topic, bla : The key under cmps in the discovery payload) Discovery payload device: { "device" : { "identifiers" : [ "0AFFD2" ] } , "o" : { "name" : "foobar" } , "cmps" : { "bla1" : { "p" : "device_automation" , "automation_type" : "trigger" , "payload" : "short_press" , "topic" : "foobar/triggers/button1" , "type" : "button_short_press" , "subtype" : "button_1" } , "bla2" : { "p" : "sensor" , "state_topic" : "foobar/sensor/sensor1" , "unique_id" : "bla_sensor001" } } } JSON Important Check the logs to ensure the migration was successful. Step 4: Clean up after successful migration: After the logs show a successful migration, the single component discovery topics can be cleaned up safely by publishing an empty payload to them. The logs should indicate if the discovery migration was successful. Optional: Rolling back the migration: To rollback publish … { "migrate_discovery" : true } JSON To the device discovery topic(s). After that, re-publish the single component discovery payloads. At last, clean up the device discovery payloads by publishing an empty payload. Check the logs for every step. Single component discovery payload When using single component discovery messages, the <component> part in the discovery topic must be one of the supported MQTT platforms. The options in the payload are only used to set up one specific component. If a device contains multiple components, it is recommended to use device discovery instead. MQTT entities can share device configuration, meaning one entity can include the full device configuration and other entities can link to that device by only setting mandatory fields. Important The mandatory fields were previously limited to at least one of connection and identifiers , but have now been extended to at least one of connection and identifiers as well as the name . Example discovery payload: { "dev" : { "ids" : "ea334450945afc" , "name" : "Kitchen" , "mf" : "Bla electronics" , "mdl" : "xya" , "sw" : "1.0" , "sn" : "ea334450945afc" , "hw" : "1.0rev2" } , "o" : { "name" : "bla2mqtt" , "sw" : "2.1" , "url" : " https://bla2mqtt.example.com/support " } , "device_class" : "temperature" , "unit_of_measurement" : "°C" , "value_template" : "{{ value_json.temperature}}" , "unique_id" : "temp01ae_t" , "state_topic" : "sensorBedroom/state" , "qos" : 2 } JSON To remove the component, publish an empty string to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it. For more examples see . Discovery payload The payload must be a serialized JSON dictionary and will be checked like an entry in your configuration.yaml The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file if a new device is added, with the exception that unknown configuration keys are allowed but ignored. This means that missing variables will be filled with the integration’s default values. All configuration variables which are required must be present in the payload. The reason for allowing unknown documentation keys is allow some backwards compatibility, software generating MQTT discovery messages can then be used with older Home Assistant versions which will simply ignore new features. A discovery payload can be sent with a retain flag set. In that case, the discovery message will be stored at the MQTT broker and processed automatically when the MQTT integrations start. This method removes the need for it to be resent. A better approach, though, is for the software generating MQTT discovery messages to send discovery payload(s) when the MQTT integration sends the Birth message . Subsequent messages on a topic where a valid payload has been received will be handled as a configuration update, and a configuration update with an empty payload will cause a previously discovered device to be deleted. A base topic ~ may be defined in the payload to conserve memory when the same topic base is used multiple times. In the value of configuration variables ending with _topic , ~ will be replaced with the base topic, if the ~ occurs at the beginning or end of the value. Configuration variable names in the discovery payload may be abbreviated to conserve memory when sending a discovery message from memory constrained devices. It is recommended to add information about the origin of MQTT entities by including the origin option (abbreviated as o ) in the discovery payload. For device discovery, this information is required. The origin details will be logged in the core event log when an item is discovered or updated. Adding origin information helps with troubleshooting and provides valuable context about the source of MQTT messages in your Home Assistant setup. Note: These options also support abbreviations, as shown in the table below. name The name of the application that is the origin of the discovered MQTT item. (Required) sw_version Software version of the application that supplies the discovered MQTT item. support_url Support URL of the application that supplies the discovered MQTT item. Supported abbreviations in MQTT discovery messages Supported abbreviations 'act_t': 'action_topic', 'act_tpl': 'action_template', 'atype': 'automation_type', 'aux_cmd_t': 'aux_command_topic', 'aux_stat_t': 'aux_state_topic', 'aux_stat_tpl': 'aux_state_template', 'av_tones': 'available_tones', 'avty': 'availability', 'avty_mode': 'availability_mode', 'avty_t': 'availability_topic', 'avty_tpl': 'availability_template', 'away_mode_cmd_t': 'away_mode_command_topic', 'away_mode_stat_t': 'away_mode_state_topic', 'away_mode_stat_tpl': 'away_mode_state_template', 'b_tpl': 'blue_template', 'bri_cmd_t': 'brightness_command_topic', 'bri_cmd_tpl': 'brightness_command_template', 'bri_scl': 'brightness_scale', 'bri_stat_t': 'brightness_state_topic', 'bri_tpl': 'brightness_template', 'bri_val_tpl': 'brightness_value_template', 'clr_temp_cmd_tpl': 'color_temp_command_template', 'clr_temp_cmd_t': 'color_temp_command_topic', 'clr_temp_k': 'color_temp_kelvin', 'clr_temp_stat_t': 'color_temp_state_topic', 'clr_temp_tpl': 'color_temp_template', 'clr_temp_val_tpl': 'color_temp_value_template', 'clrm_stat_t': 'color_mode_state_topic', 'clrm_val_tpl': 'color_mode_value_template', 'cmd_off_tpl': 'command_off_template', 'cmd_on_tpl': 'command_on_template', 'cmd_t': 'command_topic', 'cmd_tpl': 'command_template', 'cmps': 'components', 'cod_arm_req': 'code_arm_required', 'cod_dis_req': 'code_disarm_required', 'cod_trig_req': 'code_trigger_required', 'cont_type': 'content_type', 'curr_temp_t': 'current_temperature_topic', 'curr_temp_tpl': 'current_temperature_template', 'def_ent_id': 'default_entity_id', 'dev': 'device', 'dev_cla': 'device_class', 'dir_cmd_t': 'direction_command_topic', 'dir_cmd_tpl': 'direction_command_template', 'dir_stat_t': 'direction_state_topic', 'dir_val_tpl': 'direction_value_template', 'dsp_prc': 'display_precision', 'e': 'encoding', 'en': 'enabled_by_default', 'ent_cat': 'entity_category', 'ent_pic': 'entity_picture', 'evt_typ': 'event_types', 'exp_aft': 'expire_after', 'fanspd_lst': 'fan_speed_list', 'flsh': 'flash', 'flsh_tlng': 'flash_time_long', 'flsh_tsht': 'flash_time_short', 'fx_cmd_t': 'effect_command_topic', 'fx_cmd_tpl': 'effect_command_template', 'fx_list': 'effect_list', 'fx_stat_t': 'effect_state_topic', 'fx_tpl': 'effect_template', 'fx_val_tpl': 'effect_value_template', 'fan_mode_cmd_t': 'fan_mode_command_topic', 'fan_mode_cmd_tpl': 'fan_mode_command_template', 'fan_mode_stat_t': 'fan_mode_state_topic', 'fan_mode_stat_tpl': 'fan_mode_state_template', 'frc_upd': 'force_update', 'g_tpl': 'green_template', 'grp': 'group', 'hs_cmd_t': 'hs_command_topic', 'hs_cmd_tpl': 'hs_command_template', 'hs_stat_t': 'hs_state_topic', 'hs_val_tpl': 'hs_value_template', 'ic': 'icon', 'img_e': 'image_encoding', 'img_t': 'image_topic', 'init': 'initial', 'hum_cmd_t': 'target_humidity_command_topic', 'hum_cmd_tpl': 'target_humidity_command_template', 'hum_stat_t': 'target_humidity_state_topic', 'hum_state_tpl': 'target_humidity_state_template', 'json_attr': 'json_attributes', 'json_attr_t': 'json_attributes_topic', 'json_attr_tpl': 'json_attributes_template', 'l_ver_t': 'latest_version_topic', 'l_ver_tpl': 'latest_version_template', 'lrst_t': 'last_reset_topic', 'lrst_val_tpl': 'last_reset_value_template', 'max': 'max', 'max_hum': 'max_humidity', 'max_k': 'max_kelvin', 'max_mirs': 'max_mireds', 'max_temp': 'max_temp', 'migr_discvry': 'migrate_discovery', 'min': 'min', 'min_hum': 'min_humidity', 'min_k': 'min_kelvin', 'min_mirs': 'min_mireds', 'min_temp': 'min_temp', 'mode': 'mode', 'mode_cmd_t': 'mode_command_topic', 'mode_cmd_tpl': 'mode_command_template', 'mode_stat_t': 'mode_state_topic', 'mode_stat_tpl': 'mode_state_template', 'modes': 'modes', 'name': 'name', 'o': 'origin', 'off_dly': 'off_delay', 'on_cmd_type': 'on_command_type', 'ops': 'options', 'opt': 'optimistic', 'osc_cmd_t': 'oscillation_command_topic', 'osc_cmd_tpl': 'oscillation_command_template', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', 'p': 'platform', 'pct_cmd_t': 'percentage_command_topic', 'pct_cmd_tpl': 'percentage_command_template', 'pct_stat_t': 'percentage_state_topic', 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', 'pl_arm_away': 'payload_arm_away', 'pl_arm_custom_b': 'payload_arm_custom_bypass', 'pl_arm_home': 'payload_arm_home', 'pl_arm_nite': 'payload_arm_night', 'pl_arm_vacation': 'payload_arm_vacation', 'pl_avail': 'payload_available', 'pl_cln_sp': 'payload_clean_spot', 'pl_cls': 'payload_close', 'pl_dir_fwd': 'payload_direction_forward', 'pl_dir_rev': 'payload_direction_reverse', 'pl_disarm': 'payload_disarm', 'pl_home': 'payload_home', 'pl_inst': 'payload_install', 'pl_loc': 'payload_locate', 'pl_lock': 'payload_lock', 'pl_not_avail': 'payload_not_available', 'pl_not_home': 'payload_not_home', 'pl_off': 'payload_off', 'pl_on': 'payload_on', 'pl_open': 'payload_open', 'pl_osc_off': 'payload_oscillation_off', 'pl_osc_on': 'payload_oscillation_on', 'pl_paus': 'payload_pause', 'pl_prs': 'payload_press', 'pl_ret': 'payload_return_to_base', 'pl_rst': 'payload_reset', 'pl_rst_hum': 'payload_reset_humidity', 'pl_rst_mode': 'payload_reset_mode', 'pl_rst_pct': 'payload_reset_percentage', 'pl_rst_pr_mode': 'payload_reset_preset_mode', 'pl_stop': 'payload_stop', 'pl_stop_tilt': 'payload_stop_tilt', 'pl_stpa': 'payload_start_pause', 'pl_strt': 'payload_start', 'pl_toff': 'payload_turn_off', 'pl_ton': 'payload_turn_on', 'pl_trig': 'payload_trigger', 'pl_unlk': 'payload_unlock', 'pos': 'reports_position', 'pos_clsd': 'position_closed', 'pos_open': 'position_open', 'pr_mode_cmd_t': 'preset_mode_command_topic', 'pr_mode_cmd_tpl': 'preset_mode_command_template', 'pr_mode_stat_t': 'preset_mode_state_topic', 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', 'ptrn': 'pattern', 'r_tpl': 'red_template', 'rel_s': 'release_summary', 'rel_u': 'release_url', 'ret': 'retain', 'rgb_cmd_t': 'rgb_command_topic', 'rgb_cmd_tpl': 'rgb_command_template', 'rgb_stat_t': 'rgb_state_topic', 'rgb_val_tpl': 'rgb_value_template', 'rgbw_cmd_t': 'rgbw_command_topic', 'rgbw_cmd_tpl': 'rgbw_command_template', 'rgbw_stat_t': 'rgbw_state_topic', 'rgbw_val_tpl': 'rgbw_value_template', 'rgbww_cmd_t': 'rgbww_command_topic', 'rgbww_cmd_tpl': 'rgbww_command_template', 'rgbww_stat_t': 'rgbww_state_topic', 'rgbww_val_tpl': 'rgbww_value_template', 'send_cmd_t': 'send_command_topic', 'send_if_off': 'send_if_off', 'set_fan_spd_t': 'set_fan_speed_topic', 'set_pos_t': 'set_position_topic', 'set_pos_tpl': 'set_position_template', 'pos_t': 'position_topic', 'pos_tpl': 'position_template', 'spd_rng_min': 'speed_range_min', 'spd_rng_max': 'speed_range_max', 'src_type': 'source_type', 'stat_cla': 'state_class', 'stat_closing': 'state_closing', 'stat_clsd': 'state_closed', 'stat_jam': 'state_jammed', 'stat_locked': 'state_locked', 'stat_locking': 'state_locking', 'stat_off': 'state_off', 'stat_on': 'state_on', 'stat_open': 'state_open', 'stat_opening': 'state_opening', 'stat_stopped': 'state_stopped', 'stat_unlocked': 'state_unlocked', 'stat_unlocking': 'state_unlocking', 'stat_t': 'state_topic', 'stat_tpl': 'state_template', 'stat_val_tpl': 'state_value_template', 'step': 'step', 'stype': 'subtype', 'sug_dsp_prc': 'suggested_display_precision', 'sup_clrm': 'supported_color_modes', 'sup_dur': 'support_duration', 'sup_vol': 'support_volume_set', 'sup_feat': 'supported_features', 'swing_mode_cmd_t': 'swing_mode_command_topic', 'swing_mode_cmd_tpl': 'swing_mode_command_template', 'swing_mode_stat_t': 'swing_mode_state_topic', 'swing_mode_stat_tpl': 'swing_mode_state_template', 't': 'topic', 'temp_cmd_t': 'temperature_command_topic', 'temp_cmd_tpl': 'temperature_command_template', 'temp_hi_cmd_t': 'temperature_high_command_topic', 'temp_hi_cmd_tpl': 'temperature_high_command_template', 'temp_hi_stat_t': 'temperature_high_state_topic', 'temp_hi_stat_tpl': 'temperature_high_state_template', 'temp_lo_cmd_t': 'temperature_low_command_topic', 'temp_lo_cmd_tpl': 'temperature_low_command_template', 'temp_lo_stat_t': 'temperature_low_state_topic', 'temp_lo_stat_tpl': 'temperature_low_state_template', 'temp_stat_t': 'temperature_state_topic', 'temp_stat_tpl': 'temperature_state_template', 'temp_unit': 'temperature_unit', 'tilt_clsd_val': 'tilt_closed_value', 'tilt_cmd_t': 'tilt_command_topic', 'tilt_cmd_tpl': 'tilt_command_template', 'tilt_max': 'tilt_max', 'tilt_min': 'tilt_min', 'tilt_opnd_val': 'tilt_opened_value', 'tilt_opt': 'tilt_optimistic', 'tilt_status_t': 'tilt_status_topic', 'tilt_status_tpl': 'tilt_status_template', 'tit': 'title', 'trns': 'transition', 'uniq_id': 'unique_id', 'unit_of_meas': 'unit_of_measurement', 'url_t': 'url_topic', 'url_tpl': 'url_template', 'val_tpl': 'value_template', 'whit_cmd_t': 'white_command_topic', 'whit_scl': 'white_scale', 'xy_cmd_t': 'xy_command_topic', 'xy_cmd_tpl': 'xy_command_template', 'xy_stat_t': 'xy_state_topic', 'xy_val_tpl': 'xy_value_template', Txt Supported abbreviations for device registry configuration 'cu': 'configuration_url', 'cns': 'connections', 'ids': 'identifiers', 'name': 'name', 'mf': 'manufacturer', 'mdl': 'model', 'mdl_id': 'model_id', 'hw': 'hw_version', 'sw': 'sw_version', 'sa': 'suggested_area', 'sn': 'serial_number', Txt Supported abbreviations for origin info 'name': 'name', 'sw': 'sw_version', 'url': 'support_url', Txt Discovery messages and availability When MQTT discovery is set up, and a device or service sends a discovery message, an MQTT entity, tag, or device automation will be set up directly after receiving the message. When Home Assistant is restarting, discovered MQTT items with a unique ID will be unavailable until a new discovery message is received. MQTT items without a unique ID will not be added at startup. So a device or service using MQTT discovery must make sure a configuration message is offered after the MQTT integration has been (re)started. There are two common approaches to make sure the discovered items are set up at startup: Using Birth and Will messages to trigger setup Using retained messages Finally, it is a best practice to publish your device or service availability status. Use the Birth and Will messages to trigger discovery When the MQTT integration starts, a birth message is published at homeassistant/status by default. A device or service connected to the shared mqtt broker can subscribe to this topic and use an online message to trigger discovery messages. See also the birth and last will messages section. After the configs have been published, the state topics will need an update, so they need to be republished. Using retained config messages An alternative method for a device or service is to publish discovery messages with a retain flag. This will make sure discovery messages are replayed when the MQTT integration connects to the broker. After the configs have been published, the state topics will need an update. Using retained state messages State updates also need to be re-published after a config as been processed. This can also be done by publishing retained messages. As soon as a config is received (or replayed from a retained message), the setup will subscribe any state topics. If a retained message is available at a state topic, this message will be replayed so that the state can be restored for this topic. Warning A disadvantage of using retained messages is that these messages retain at the broker, even when the device or service stops working. They are retained even after the system or broker has been restarted. Retained messages can create ghost entities that keep coming back. Especially when you have many entities, (unneeded) discovery messages can cause excessive system load. For this reason, use discovery messages with caution. Using Availability topics A device or service can announce its availability by publishing a Birth message and set a Will message at the broker. When the device or service loses connection to the broker, the broker will publish the Will message. This allows the MQTT integration to make an entity unavailable. Platform specific availability settings are available for mqtt entity platforms only. Platform specific availability settings Configuration Variables availability list ( Optional ) A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with availability_topic . payload_available string ( Optional , default: online ) The payload that represents the available state. payload_not_available string ( Optional , default: offline ) The payload that represents the unavailable state. topic string Required An MQTT topic subscribed to receive availability (online/offline) updates. value_template template ( Optional ) Defines a template to extract a device’s availability from the topic . To determine the device’s availability, the result of this template will be compared to payload_available and payload_not_available . availability_topic string ( Optional ) The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with availability . availability_mode string ( Optional , default: latest ) When availability is configured, this controls the conditions needed to set the entity to available . Valid entries are all , any , and latest . If set to all , payload_available must be received on all configured availability topics before the entity is marked as online. If set to any , payload_available must be received on at least one configured availability topic before the entity is marked as online. If set to latest , the last payload_available or payload_not_available received on any configured availability topic controls the availability. availability_template template ( Optional ) Defines a template to extract device’s availability from the availability_topic . To determine the devices’s availability result of this template will be compared to payload_available and payload_not_available . payload_available string ( Optional , default: online ) The payload that represents the available state. payload_not_available string ( Optional , default: offline ) The payload that represents the unavailable state. Discovery examples with component discovery Motion detection (binary sensor) A motion detection device which can be represented by a binary sensor for your garden would send its configuration as JSON payload to the Configuration topic. After the first message to config , then the MQTT messages sent to the state topic will update the state in Home Assistant. Configuration topic: homeassistant/binary_sensor/garden/config State topic: homeassistant/binary_sensor/garden/state Configuration payload with derived device name: { "name" : null , "device_class" : "motion" , "state_topic" : "homeassistant/binary_sensor/garden/state" , "unique_id" : "motion01ad" , "device" : { "identifiers" : [ "01ad" ] , "name" : "Garden" } } JSON Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts. It is also a good idea to add a unique_id to allow changes to the entity and a device mapping so we can group all sensors of a device together. We can set “name” to null if we want to inherit the device name for the entity. If we set an entity name, the friendly_name will be a combination of the device and entity name. If name is left away and a device_class is set, the entity name part will be derived from the device_class . Example configuration payload with no name set and derived device_class name: { "name" : null , "device_class" : "motion" , "state_topic" : "homeassistant/binary_sensor/garden/state" , "unique_id" : "motion01ad" , "device" : { "identifiers" : [ "01ad" ] , "name" : "Garden" } } JSON If no name is set, a default name will be set by MQTT ( see the MQTT platform documentation ). To create a new sensor manually and with the name set to null to derive the device name “Garden”: mosquitto_pub -r -h 127.0 .0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": null, "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state", "unique_id": "motion01ad", "device": {"identifiers": ["01ad"], "name": "Garden" }}' Bash Update the state: mosquitto_pub -h 127.0 .0.1 -p 1883 -t "homeassistant/binary_sensor/garden/state" -m ON Bash Delete the sensor by sending an empty message. mosquitto_pub -h 127.0 .0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '' Bash For more details, refer to the MQTT testing section . Sensors Setting up a sensor with multiple measurement values requires multiple consecutive configuration topic submissions. Configuration topic no1: homeassistant/sensor/sensorBedroomT/config Configuration payload no1: { "device_class" : "temperature" , "state_topic" : "homeassistant/sensor/sensorBedroom/state" , "unit_of_measurement" : "°C" , "value_template" : "{{ value_json.temperature}}" , "unique_id" : "temp01ae" , "device" : { "identifiers" : [ "bedroom01ae" ] , "name" : "Bedroom" , "manufacturer" : "Example sensors Ltd." , "model" : "Example Sensor" , "model_id" : "K9" , "serial_number" : "12AE3010545" , "hw_version" : "1.01a" , "sw_version" : "2024.1.0" , "configuration_url" : " https://example.com/sensor_portal/config " } } JSON Configuration topic no2: homeassistant/sensor/sensorBedroomH/config Configuration payload no2: { "device_class" : "humidity" , "state_topic" : "homeassistant/sensor/sensorBedroom/state" , "unit_of_measurement" : "%" , "value_template" : "{{ value_json.humidity}}" , "unique_id" : "hum01ae" , "device" : { "identifiers" : [ "bedroom01ae" ] } } JSON The sensor identifiers or connections option allows to set up multiple entities that share the same device. Note If a device configuration is shared, then it is not needed to add all device details to the other entity configs. It is enough to add shared identifiers or connections to the device mapping for the other entity config payloads. A common state payload that can be parsed with the value_template in the sensor configs: { "temperature" : 23.20 , "humidity" : 43.70 } JSON Entities with command topics Setting up a light or switch is similar but requires a command_topic as mentioned in the MQTT switch documentation . Configuration topic: homeassistant/switch/irrigation/config State topic: homeassistant/switch/irrigation/state Command topic: homeassistant/switch/irrigation/set Payload: { "name" : "Irrigation" , "command_topic" : "homeassistant/switch/irrigation/set" , "state_topic" : "homeassistant/switch/irrigation/state" , "unique_id" : "irr01ad" , "device" : { "identifiers" : [ "garden01ad" ] , "name" : "Garden" } } JSON Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts. mosquitto_pub -r -h 127.0 .0.1 -p 1883 -t "homeassistant/switch/irrigation/config" \ -m '{"name": "Irrigation", "command_topic": "homeassistant/switch/irrigation/set", "state_topic": "homeassistant/switch/irrigation/state", "unique_id": "irr01ad", "device": {"identifiers": ["garden01ad"], "name": "Garden" }}' Bash Set the state: mosquitto_pub -h 127.0 .0.1 -p 1883 -t "homeassistant/switch/irrigation/set" -m ON Bash Using abbreviations and base topic Setting up a switch using topic prefix and abbreviated configuration variable names to reduce payload length. Configuration topic: homeassistant/switch/irrigation/config Command topic: homeassistant/switch/irrigation/set State topic: homeassistant/switch/irrigation/state Configuration payload: { "~" : "homeassistant/switch/irrigation" , "name" : "garden" , "cmd_t" : "~/set" , "stat_t" : "~/state" } JSON Note Another example using abbreviations topic name and base topic Setting up a light that takes JSON payloads , with abbreviated configuration variable names: Configuration topic: homeassistant/light/kitchen/config Command topic: homeassistant/light/kitchen/set State topic: homeassistant/light/kitchen/state Example state payload: {"state": "ON", "brightness": 255} Configuration payload: { "~" : "homeassistant/light/kitchen" , "name" : "Kitchen" , "uniq_id" : "kitchen_light" , "cmd_t" : "~/set" , "stat_t" : "~/state" , "schema" : "json" , "brightness" : true } JSON Example with using abbreviated Device and Origin info in discovery messages { "~" : "homeassistant/light/kitchen" , "name" : null , "uniq_id" : "kitchen_light" , "cmd_t" : "~/set" , "stat_t" : "~/state" , "schema" : "json" , "dev" : { "ids" : "ea334450945afc" , "name" : "Kitchen" , "mf" : "Bla electronics" , "mdl" : "xya" , "mdl_id" : "ABC123" , "sw" : "1.0" , "sn" : "ea334450945afc" , "hw" : "1.0rev2" } , "o" : { "name" : "bla2mqtt" , "sw" : "2.1" , "url" : " https://bla2mqtt.example.com/support " } } JSON Support by third-party tools The following software has built-in support for MQTT discovery: anpr2mqtt ArduinoHA Arilux AL-LC0X LED controllers ble2mqtt diematic_server digitalstrom-mqtt ebusd ecowitt2mqtt EMS-ESP32 (and EMS-ESP) ESPHome ESPurna go-iotdevice HASS.Agent IOTLink (starting with 2.0.0) MiFlora MQTT Daemon MyElectricalData MqDockerUp Nuki Hub Nuki Smart Lock 3.0 Pro , more info OpenMQTTGateway OTGateway rethink room-assistant (starting with 1.1.0) SmartHome SpeedTest-CLI MQTT SwitchBot-MQTT-BLE-ESP32 Tasmota (starting with 5.11.1e, development halted) TeddyCloud Teleinfo MQTT (starting with 3.0.0) Tydom2MQTT Updates2MQTT What’s up Docker? (starting with 3.5.0) WyzeSense2MQTT Xiaomi DaFang Hacks Zehnder Comfoair RS232 MQTT Zigbee2MQTT The following software also supports consuming MQTT discovery information that is intended for Home Assistant. Compatibility and features will vary, and not all devices may work. Domoticz openHAB Manual configured MQTT items Support to allow adding manual items as a subentry via a config flow , is work in progress. Not all entity platforms are supported yet. For most integrations, it is also possible to manually set up MQTT items in configuration.yaml The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] . Read more about configuration in YAML . MQTT supports two styles for configuring items in YAML. All configuration items are placed directly under the mqtt integration key. Note that you cannot mix these styles. Use the YAML configuration listed per item style when in doubt. YAML configuration listed per item This method expects all items to be in a YAML list. Each item has a {domain} key and the item config is placed directly under the domain key. This method is considered as best practice. In all the examples we use this format. mqtt : - { domain } : name : "" ... - { domain } : name : "" ... YAML YAML configuration keyed and bundled by {domain} All items are grouped per {domain} and where all configs are listed. mqtt : { domain } : - name : "" ... - name : "" ... YAML If you have a large number of manually configured items, you might want to consider splitting up the configuration . Entity state updates Entities receive state updates via MQTT subscriptions. The payloads received on the state topics are processed to determine whether there is a significant change. If a change is detected, the entity will be updated. Note that MQTT device payloads often contain information for updating multiple entities that subscribe to the same topics. For example, a light status update might include information about link quality. This data can update a link quality sensor but is not used to update the light itself. MQTT filters out entity state updates when there are no changes. The last reported state attribute Because MQTT state updates are often repeated frequently, even when no actual changes exist, it is up to the MQTT subscriber to determine whether a status update was received. If the latest update is missed, it might take some time before the next one arrives. If a retained payload exists at the broker, that value will be replayed first, but it will be an update of a previous last state. MQTT devices often continuously generate numerous state updates. MQTT does not update last_reported to avoid impacting system stability unless force_update is set. Alternatively, an MQTT sensor can be created to measure the last update. Using Templates The MQTT integration supports templating. Read more about using templates with the MQTT integration . Examples REST API Using the REST API to send a message to a given topic. Automations Use as script in automations. automation : alias : "Send me a message when I get home" triggers : - trigger : state entity_id : device_tracker.me to : "home" actions : - action : script.notify_mqtt data : target : "me" message : "I'm home" script : notify_mqtt : sequence : - action : mqtt.publish data : payload : " {{ message }} " topic : "home/ {{ target }} " retain : true YAML Publish & Dump actions The MQTT integration will register the mqtt.publish action, which allows publishing messages to MQTT topics. Action: Publish The mqtt.publish action publishes a message to an MQTT topic. Data attribute Optional Description topic no Topic to publish payload to. payload yes Payload to publish. Will publish an empty payload when payload is omitted. evaluate_payload yes If a bytes literal in payload should be evaluated to publish raw data. (default: false) qos yes Quality of Service to use. (default: 0) retain yes If message should have the retain flag set. (default: false) Note When payload is rendered from template in a YAML script or automation, and the template renders to a bytes literal, the outgoing MQTT payload will only be sent as raw data, if the evaluate_payload option flag is set to true . topic : homeassistant/light/1/command payload : "ON" YAML topic : homeassistant/light/1/state payload : " {{ states ( 'device_tracker.paulus' ) }} " YAML topic : "homeassistant/light/ {{ states ( 'sensor.light_active' ) }} /state" payload : " {{ states ( 'device_tracker.paulus' ) }} " YAML Be aware that payload must be a string. If you want to send JSON using the YAML editor then you need to format/escape it properly. Like: topic : homeassistant/light/1/state payload : "{\"Status\":\"off\", \"Data\":\"something\"}" YAML The example below shows how to publish a temperature sensor ‘Bathroom Temperature’. The device_class is set, so it is not needed to set the “name” option. The entity will inherit the name from the device_class set and also support translations. If you set “name” in the payload the entity name will start with the device name. action : mqtt.publish data : topic : homeassistant/sensor/Acurite - 986 - 1R - 51778/config payload : > - { "device_class" : "temperature" , "unit_of_measurement" : "\u00b0C" , "value_template" : " {{ value \| float }} " , "state_topic" : "rtl_433/rtl433/devices/Acurite-986/1R/51778/temperature_C" , "unique_id" : "Acurite-986-1R-51778-T" , "device" : { "identifiers" : "Acurite-986-1R-51778" , "name" : "Bathroom" , "model" : "Acurite" , "model_id" : "986" , "manufacturer" : "rtl_433" } } YAML Example of how to use qos and retain : topic : homeassistant/light/1/command payload : "ON" qos : 2 retain : true YAML Action: Dump The mqtt.dump action listens to the specified topic matcher and dumps all received messages within a specific duration into the file mqtt_dump.txt in your configuration folder. This is useful when debugging a problem. Data attribute Optional Description topic no Topic to dump. Can contain a wildcard ( # or + ). duration yes Duration in seconds that we will listen for messages. Default is 5 seconds. topic : zigbee2mqtt/ # YAML Logging The logger integration allows the logging of received MQTT messages. # Example configuration.yaml entry logger : default : warning logs : homeassistant.components.mqtt : debug YAML Event event_mqtt_reloaded Event event_mqtt_reloaded is fired when Manually configured MQTT entities have been reloaded and entities thus might have changed. This event has no additional data. Removing the integration Go to Settings > Devices & services and select the integration card. From the list of devices, select the integration instance you want to remove. Next to the entry, select the three dots menu. Then, select Delete . Note: This action does not remove the MQTT broker or its data. If you want to completely remove MQTT: Check your configuration.yaml The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] and other YAML files for MQTT-related configurations and remove them Review your automations and scripts for any MQTT dependencies Consider backing up your configuration before making these changes Help us improve our documentation Suggest an edit to this page, or provide/view feedback for this page. Edit Provide feedback View pending feedback
Markdown	[2026\.4.1](https://www.home-assistant.io/blog/2026/04/01/release-20264/ "Latest version 2026.4.1 released April 3, 2026") - [Getting started](https://www.home-assistant.io/installation/) - [Documentation](https://www.home-assistant.io/docs/) - [Installation](https://www.home-assistant.io/installation/) - [Automations](https://www.home-assistant.io/docs/automation/) - [Dashboards](https://www.home-assistant.io/dashboards/) - [Voice assistants](https://www.home-assistant.io/voice_control/) - [Device organization](https://www.home-assistant.io/docs/organizing/) - [Energy management](https://www.home-assistant.io/docs/energy/) - [Templating](https://www.home-assistant.io/docs/templating/) - [Advanced configuration](https://www.home-assistant.io/docs/configuration/) - [Our hardware](https://www.home-assistant.io/integrations/mqtt/) - [Home Assistant Green](https://www.home-assistant.io/green/) - [Connect ZBT-2](https://www.home-assistant.io/connect/zbt-2/) - [Connect ZWA-2](https://www.home-assistant.io/connect/zwa-2/) - [Voice Preview Edition](https://www.home-assistant.io/voice-pe/) - [Integrations](https://www.home-assistant.io/integrations/) - [Blog](https://www.home-assistant.io/blog/) - [Need help?](https://www.home-assistant.io/help/) - Search ```K` On this page Configuration - [Configuration](https://www.home-assistant.io/integrations/mqtt/#configuration) - [Setting up a broker](https://www.home-assistant.io/integrations/mqtt/#setting-up-a-broker) - [Broker configuration](https://www.home-assistant.io/integrations/mqtt/#broker-configuration) - [Advanced broker configuration](https://www.home-assistant.io/integrations/mqtt/#advanced-broker-configuration) - [Configure MQTT options](https://www.home-assistant.io/integrations/mqtt/#configure-mqtt-options) - [Change MQTT discovery options](https://www.home-assistant.io/integrations/mqtt/#change-mqtt-discovery-options) - [Discovery options](https://www.home-assistant.io/integrations/mqtt/#discovery-options) - [Birth and last will messages](https://www.home-assistant.io/integrations/mqtt/#birth-and-last-will-messages) - [Testing your setup](https://www.home-assistant.io/integrations/mqtt/#testing-your-setup) - [Naming of MQTT Entities](https://www.home-assistant.io/integrations/mqtt/#naming-of-mqtt-entities) - [Grouping entities](https://www.home-assistant.io/integrations/mqtt/#grouping-entities) - [MQTT Discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) - [Discovery messages](https://www.home-assistant.io/integrations/mqtt/#discovery-messages) - [Discovery messages and availability](https://www.home-assistant.io/integrations/mqtt/#discovery-messages-and-availability) - [Using Availability topics](https://www.home-assistant.io/integrations/mqtt/#using-availability-topics) - [Discovery examples with component discovery](https://www.home-assistant.io/integrations/mqtt/#discovery-examples-with-component-discovery) - [Support by third-party tools](https://www.home-assistant.io/integrations/mqtt/#support-by-third-party-tools) - [Manual configured MQTT items](https://www.home-assistant.io/integrations/mqtt/#manual-configured-mqtt-items) - [YAML configuration listed per item](https://www.home-assistant.io/integrations/mqtt/#yaml-configuration-listed-per-item) - [YAML configuration keyed and bundled by {domain}](https://www.home-assistant.io/integrations/mqtt/#yaml-configuration-keyed-and-bundled-by-domain) - [Entity state updates](https://www.home-assistant.io/integrations/mqtt/#entity-state-updates) - [The last reported state attribute](https://www.home-assistant.io/integrations/mqtt/#the-last-reported-state-attribute) - [Using Templates](https://www.home-assistant.io/integrations/mqtt/#using-templates) - [Examples](https://www.home-assistant.io/integrations/mqtt/#examples) - [Publish & Dump actions](https://www.home-assistant.io/integrations/mqtt/#publish--dump-actions) - [Action: Publish](https://www.home-assistant.io/integrations/mqtt/#action-publish) - [Action: Dump](https://www.home-assistant.io/integrations/mqtt/#action-dump) - [Logging](https://www.home-assistant.io/integrations/mqtt/#logging) - [Event event\_mqtt\_reloaded](https://www.home-assistant.io/integrations/mqtt/#event-event_mqtt_reloaded) - [Removing the integration](https://www.home-assistant.io/integrations/mqtt/#removing-the-integration) [Home](https://www.home-assistant.io/) ▸ [Integrations](https://www.home-assistant.io/integrations/) # MQTT MQTT (aka MQ Telemetry Transport) is a machine-to-machine or “Internet of Things” connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport. ## Configuration To add the MQTT service to your Home Assistant instance, use this My button: [![](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start?domain=mqtt) Manual configuration steps If the above My button doesn’t work, you can also perform the following steps manually: - Browse to your Home Assistant instance. - Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). - In the bottom right corner, select the [Add Integration](https://my.home-assistant.io/redirect/config_flow_start?domain=mqtt) button. - From the list, select MQTT. - Follow the instructions on screen to complete the setup. MQTT devices and entities can be set up through [MQTT discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) or [added manually](https://www.home-assistant.io/integrations/mqtt/#manual-configured-mqtt-items) via YAML or subentries. Configuration of MQTT components via MQTT discovery - [Alarm control panel](https://www.home-assistant.io/integrations/alarm_control_panel.mqtt/) - [Binary sensor](https://www.home-assistant.io/integrations/binary_sensor.mqtt/) - [Button](https://www.home-assistant.io/integrations/button.mqtt/) - [Camera](https://www.home-assistant.io/integrations/camera.mqtt/) - [Cover](https://www.home-assistant.io/integrations/cover.mqtt/) - [Climate (HVAC)](https://www.home-assistant.io/integrations/climate.mqtt/) - [Device tracker](https://www.home-assistant.io/integrations/device_tracker.mqtt/) - [Device trigger](https://www.home-assistant.io/integrations/device_trigger.mqtt/) - [Event](https://www.home-assistant.io/integrations/event.mqtt/) - [Fan](https://www.home-assistant.io/integrations/fan.mqtt/) - [Humidifier](https://www.home-assistant.io/integrations/humidifier.mqtt/) - [Image](https://www.home-assistant.io/integrations/image.mqtt/) - [Lawn mower](https://www.home-assistant.io/integrations/lawn_mower.mqtt/) - [Light](https://www.home-assistant.io/integrations/light.mqtt/) - [Lock](https://www.home-assistant.io/integrations/lock.mqtt/) - [Notify](https://www.home-assistant.io/integrations/notify.mqtt/) - [Number](https://www.home-assistant.io/integrations/number.mqtt/) - [Scene](https://www.home-assistant.io/integrations/scene.mqtt/) - [Select](https://www.home-assistant.io/integrations/select.mqtt/) - [Sensor](https://www.home-assistant.io/integrations/sensor.mqtt/) - [Siren](https://www.home-assistant.io/integrations/siren.mqtt/) - [Switch](https://www.home-assistant.io/integrations/switch.mqtt/) - [Update](https://www.home-assistant.io/integrations/update.mqtt/) - [Tag scanner](https://www.home-assistant.io/integrations/tag.mqtt/) - [Text](https://www.home-assistant.io/integrations/text.mqtt/) - [Vacuum](https://www.home-assistant.io/integrations/vacuum.mqtt/) - [Valve](https://www.home-assistant.io/integrations/valve.mqtt/) - [Water heater](https://www.home-assistant.io/integrations/water_heater.mqtt/) Configuration of MQTT components via YAML - [Alarm control panel](https://www.home-assistant.io/integrations/alarm_control_panel.mqtt/) - [Binary sensor](https://www.home-assistant.io/integrations/binary_sensor.mqtt/) - [Button](https://www.home-assistant.io/integrations/button.mqtt/) - [Camera](https://www.home-assistant.io/integrations/camera.mqtt/) - [Climate (HVAC)](https://www.home-assistant.io/integrations/climate.mqtt/) - [Cover](https://www.home-assistant.io/integrations/cover.mqtt/) - [Device tracker](https://www.home-assistant.io/integrations/device_tracker.mqtt/) - [Event](https://www.home-assistant.io/integrations/event.mqtt/) - [Fan](https://www.home-assistant.io/integrations/fan.mqtt/) - [Humidifier](https://www.home-assistant.io/integrations/humidifier.mqtt/) - [Image](https://www.home-assistant.io/integrations/image.mqtt/) - [Lawn mower](https://www.home-assistant.io/integrations/lawn_mower.mqtt/) - [Light](https://www.home-assistant.io/integrations/light.mqtt/) - [Lock](https://www.home-assistant.io/integrations/lock.mqtt/) - [Notify](https://www.home-assistant.io/integrations/notify.mqtt/) - [Number](https://www.home-assistant.io/integrations/number.mqtt/) - [Scene](https://www.home-assistant.io/integrations/scene.mqtt/) - [Select](https://www.home-assistant.io/integrations/select.mqtt/) - [Sensor](https://www.home-assistant.io/integrations/sensor.mqtt/) - [Siren](https://www.home-assistant.io/integrations/siren.mqtt/) - [Switch](https://www.home-assistant.io/integrations/switch.mqtt/) - [Text](https://www.home-assistant.io/integrations/text.mqtt/) - [Update](https://www.home-assistant.io/integrations/update.mqtt/) - [Vacuum](https://www.home-assistant.io/integrations/vacuum.mqtt/) - [Valve](https://www.home-assistant.io/integrations/valve.mqtt/) - [Water heater](https://www.home-assistant.io/integrations/water_heater.mqtt/) Configuration of MQTT components via Subentries - [Alarm control panel](https://www.home-assistant.io/integrations/alarm_control_panel.mqtt/) - [Binary sensor](https://www.home-assistant.io/integrations/binary_sensor.mqtt/) - [Button](https://www.home-assistant.io/integrations/button.mqtt/) - [Climate (HVAC)](https://www.home-assistant.io/integrations/climate.mqtt/) - [Cover](https://www.home-assistant.io/integrations/cover.mqtt/) - [Fan](https://www.home-assistant.io/integrations/fan.mqtt/) - [Image](https://www.home-assistant.io/integrations/image.mqtt/) - [Light](https://www.home-assistant.io/integrations/light.mqtt/) - [Lock](https://www.home-assistant.io/integrations/lock.mqtt/) - [Notify](https://www.home-assistant.io/integrations/notify.mqtt/) - [Number](https://www.home-assistant.io/integrations/number.mqtt/) - [Select](https://www.home-assistant.io/integrations/select.mqtt/) - [Sensor](https://www.home-assistant.io/integrations/sensor.mqtt/) - [Siren](https://www.home-assistant.io/integrations/siren.mqtt/) - [Switch](https://www.home-assistant.io/integrations/switch.mqtt/) - [Text](https://www.home-assistant.io/integrations/text.mqtt/) - [Valve](https://www.home-assistant.io/integrations/valve.mqtt/) - [Water heater](https://www.home-assistant.io/integrations/water_heater.mqtt/) To add an MQTT device via a Subentry, follow these steps: 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). 2. Select the MQTT integration. 3. Add a subentry via [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations), select , and select Add MQTT device. A device context and one or more entities can be added to the subentry. Your first step to get MQTT and Home Assistant working is to choose a broker. The easiest option is to install the official Mosquitto Broker app for Home Assistant (formerly known as Mosquitto Broker add-on). You can choose to set up and configure this app automatically when you set up the MQTT integration. Home Assistant will automatically generate and assign a safe username and password, and no further attention is required. This also works if you have already set up this app yourself in advance. You can set up additional logins for your MQTT devices and services using the [Mosquitto app configuration](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_mosquitto). Important When MQTT is set up with the official Mosquitto MQTT broker app, the broker’s credentials are generated and kept secret. If the official Mosquitto MQTT broker needs to be re-installed, make sure you save a copy of the app user options, like the additional logins. After re-installing the app, the MQTT integration will automatically update the new password for the re-installed broker. It will then reconnect automatically. Alternatively, you can use a different MQTT broker that you configure yourself, ensuring it is compatible with Home Assistant. ## Setting up a broker While public MQTT brokers are available, the easiest and most private option is running your own. The recommended setup method is to use the [Mosquitto MQTT broker app](https://github.com/home-assistant/hassio-addons/blob/master/mosquitto/DOCS.md). Warning Neither ActiveMQ MQTT broker nor the RabbitMQ MQTT Plugin are supported, use a known working broker like Mosquitto instead. There are [at least two](https://issues.apache.org/jira/browse/AMQ-6360) [issues](https://issues.apache.org/jira/browse/AMQ-6575) with the ActiveMQ MQTT broker which break MQTT message retention. ## Broker configuration MQTT broker settings are configured when the MQTT integration is first set up and can be changed later if needed. Add the MQTT integration, then provide your broker’s hostname (or IP address) and port and (if required) the username and password that Home Assistant should use. To change the settings later, follow these steps: 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). 2. Select the MQTT integration. 3. Reconfigure the MQTT broker settings via [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations), select , and select Reconfigure. MQTT subentries can also be reconfigured. Additional entities can be added, or an entity can be removed from the sub entry. Each MQTT subentry holds one MQTT device. The MQTT device must have at least one entity. Important If you experience an error message like `Failed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed`, then turn on `Advanced options` and set [Broker certificate validation](https://www.home-assistant.io/integrations/mqtt/#broker-certificate-validation) to `Auto`. ### Advanced broker configuration Advanced broker configuration options include setting a custom client ID, setting a client certificate and key for authentication, and enabling TLS validation of the broker’s certificate for secure connection. To access the advanced settings, open the MQTT broker settings, switch on Advanced options, and select Next. The advanced options will be shown by default if there are advanced settings active already. Tip Advanced broker options are accessible only when advanced mode is enabled (see user settings), or when advanced broker settings are configured already. #### Alternative client ID You can set a custom MQTT client ID, this can help when debugging. Mind that the client ID must be unique. Leave this settings default if you want Home Assistant to generate a unique ID. #### Keep alive The time in seconds between sending keep alive messages for this client. The default is 60 seconds. The keep alive setting should be at least 15 seconds. #### Broker certificate validation To enable a secure connection to the broker, the broker certificate should be validated. If your broker uses a trusted certificate, then choose Auto. This validates the broker certificate against the bundled certificate authority (CA) certificates. If a self-signed certificate is used, select Custom. A custom PEM- or DER-encoded CA certificate can be uploaded. Select Next to show the control to upload the CA certificate. If the server certificate does not match the hostname then validation will fail. To allow a connection without the verification of the hostname, turn the Ignore broker certificate validation switch on. #### MQTT Protocol The MQTT protocol setting defaults to version `3.1.1`. If your MQTT broker supports MQTT version 5 you can set the protocol setting to `5`. #### Securing the connection With a secure broker connection, it is possible to use a client certificate for authentication. To set the client certificate and private key, turn on the option Use a client certificate and select Next to reveal file upload controls. A client certificate and the corresponding private key must be uploaded together. Both client certificate and private key must be either PEM- or DER-encoded. If the private key is encrypted with a password, ensure you supply the correct password when uploading the client certificate and key files. #### Using WebSockets as transport You can select `websockets` as the transport method if your MQTT broker supports it. When you select `websockets` and select Next, you will be able to add a WebSockets path (default is `/`) and WebSockets headers (optional). The target WebSockets URI `ws://{broker}:{port}{ws_path}` is built with the `broker`, `port`, and `ws_path` (WebSocket path) settings. To configure the WebSocket’s headers, supply a valid JSON dictionary string. For example, `{ "Authorization": "token" , "x-header": "some header"}`. The default transport method is `tcp`. The WebSockets transport can be secured using TLS and optionally using user credentials or a client certificate. Note A configured client certificate will only be active if broker certificate validation is enabled. ## Configure MQTT options To change the options, follow these steps: 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). 2. Select the MQTT integration. 3. Select Configure, then Re-configure MQTT. 4. To open the MQTT options page, select Next. ### Change MQTT discovery options The MQTT discovery options can be changed by following these steps: 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). 2. Find the MQTT integration and select it. 3. To open the MQTT discovery options page, select the Configure MQTT Options button. ### Discovery options MQTT discovery is enabled by default. Discovery can be turned off. The prefix for the discovery topic (default `homeassistant`) can be changed here as well. See also [MQTT Discovery section](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) ### Birth and last will messages Home Assistant’s MQTT integration supports so-called Birth and Last Will and Testament (LWT) messages. The former is used to send a message after the service has started, and the latter is used to notify other clients about a disconnected client. Note that the LWT message will be sent both in case of a clean disconnect (for example, Home Assistant shutting down) and in case of an unclean disconnect (for example, Home Assistant crashing or losing its network connection). If a disabled entity is enabled and added after 30 seconds, the MQTT integration will be reloaded and will cause all discovered MQTT entities to be unloaded. When MQTT starts up, all existing MQTT devices, entities, tags, and device triggers, will be unavailable until a discovery message is received and processed. A device or service that exposes the MQTT discovery should subscribe to the Birth message and use this as a trigger to send the [discovery payload](https://www.home-assistant.io/integrations/mqtt/#discovery-payload). To avoid high IO loads on the MQTT broker, adding some random delay in sending the discovery payload is recommended. Alternative approaches: - Retaining the [discovery payload](https://www.home-assistant.io/integrations/mqtt/#discovery-payload): This will store the discovery payload at the MQTT broker, and offer it to the MQTT integration as soon as it subscribes for MQTT discovery. When there are a lot of entities, this can cause high IO loads. - Periodically resending the discovery payload: This can cause some delay, or a lot of IO if there are a lot of MQTT discovery messages. By default, Home Assistant sends `online` and `offline` to `homeassistant/status`. MQTT Birth and Last Will messages can be customized or disabled from the UI. To do this, select Configure on the integration page in the UI, then Re-configure MQTT, and then Next. ## Testing your setup The `mosquitto` broker package ships command line tools (often as `-clients` package) to send and receive MQTT messages. For sending test messages to a broker running on `localhost`, you can use [`mosquitto_pub`](https://mosquitto.org/man/mosquitto_pub-1.html), check the example below: ``` mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m "Switch is ON" ``` Bash Copy Another way to send MQTT messages manually is to use the MQTT* integration in the frontend. Select Settings on the left menu, select Devices & services, and select Configure in the Mosquitto broker tile. Enter something similar to the example below into the topic field under Publish a packet and select Publish. 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). 2. Select the Mosquitto broker integration, then select Configure. 3. Enter something similar to the example below into the topic field under Publish a packet. Select Publish. ``` homeassistant/switch/1/power ``` Bash Copy and in the Payload field ``` ON ``` Bash Copy In the Listen to a topic field, type `#` to see everything, or `homeassistant/switch/#` to just follow a published topic, then select Start listening. The messages should appear similar to the text below: ``` Message 23 received on homeassistant/switch/1/power/stat/POWER at 12:16 PM: ON QoS: 0 - Retain: false Message 22 received on homeassistant/switch/1/power/stat/RESULT at 12:16 PM: { "POWER": "ON" } QoS: 0 - Retain: false ``` Bash Copy For reading all messages sent on the topic `homeassistant` to a broker running on localhost: ``` mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#" ``` Bash Copy ## Naming of MQTT Entities For every configured MQTT entity Home Assistant automatically assigns a unique `entity_id`. If the `unique_id` option is configured, you can change the `entity_id` after creation, and the changes are stored in the Entity Registry. The `entity_id` is generated when an item is loaded the first time. If the `default_entity_id` option is set, then this will be used to generate the `entity_id`. If, for example, we have configured a `sensor`, and we have set `default_entity_id` to `sensor.test`, then Home Assistant will try to assign `sensor.test` as `entity_id`. If `sensor.test` already exists, Home Assistant will append a suffix to make it unique, for example, `sensor.test_2`. This means any MQTT entity which is part of a device will [automatically have its `friendly_name` attribute prefixed with the device name](https://developers.home-assistant.io/docs/core/entity/#has_entity_name-true-mandatory-for-new-integrations) Unnamed `binary_sensor`, `button`, `number`, and `sensor` entities will now be named by their device class instead of being named “MQTT binary sensor” and similar. It’s allowed to set an MQTT entity’s name to `None` (use `null` in YAML) to mark it as the main feature of a device. Note that on each MQTT entity, the `has_entity_name` attribute will be set to `True`. More details [can be found here](https://developers.home-assistant.io/docs/core/entity/#has_entity_name-true-mandatory-for-new-integrations). ## Grouping entities If the MQTT entity represents a group of other entities, the member entities can be made visible in the UI by setting the list of unique IDs of the member entities in the `group` configuration option of the entity group: group A list of unique IDs of the member entities. Set this if the entity represents a group entity. Note that the member entities must be already configured before the member entities will become visible in the UI at the moment a group entity is loaded. ## MQTT Discovery The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](https://www.home-assistant.io/integrations/http/#binary-sensor) and the [HTTP sensor](https://www.home-assistant.io/integrations/http/#sensor). To prevent multiple identical entries if a device reconnects, a unique identifier is necessary. Two parts are required on the device side: The configuration topic, and the device configuration as payload. MQTT discovery is enabled by default, but can be disabled. The prefix for the discovery topic (default `homeassistant`) can be changed. See the [MQTT Options sections](https://www.home-assistant.io/integrations/mqtt/#configure-mqtt-options) Note Documentation on the MQTT components that support MQTT discovery [can be found here](https://www.home-assistant.io/integrations/mqtt/#configuration-via-mqtt-discovery). ### Discovery messages MQTT discovery supports two types of discovery messages: - [Device discovery](https://www.home-assistant.io/integrations/mqtt/#device-discovery-payload), which allows you to include several components in a single discovery message - [Single component discovery](https://www.home-assistant.io/integrations/mqtt/#single-component-discovery-payload), where you publish a separate discovery message for each component If you use a device with multiple components, it is recommended to use MQTT device discovery. It reduces the number of messages sent, and allows you to send the device information only once. #### Discovery topic The discovery topic needs to follow a specific format: ``` <discovery_prefix>/<component>/[<node_id>/]<object_id>/config ``` Text Copy - `<discovery_prefix>`: The Discovery Prefix defaults to `homeassistant` and this prefix can be [changed](https://www.home-assistant.io/integrations/mqtt/#discovery-options). - `<component>`: One of the supported MQTT integrations, for example, `binary_sensor`, or `device` in case of device discovery. - `<node_id>`: (Optional): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. The ID of the node must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen). - `<object_id>`: The ID of the device. This allows for separate topics for each device. The ID of the device must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen). > Note: The `<object_id>` in the topic does not influence the resulting `entity_id`; use `default_entity_id` if you need to control the `entity_id`. The `<node_id>` is optional, and can be used by clients to subscribe to their own (command) topics by using one wildcard topic like `<discovery_prefix>/+/<node_id>/+/set`. Best practice for entities with a `unique_id` is to set `<object_id>` to the `unique_id` and omit the `<node_id>`. #### Device discovery payload A device can send a discovery payload to expose all components for a device. The `<component>` part in the discovery topic must be set to `device`. As an alternative, it is also possible for a device [to send a discovery payload for each component](https://www.home-assistant.io/integrations/mqtt/#single-component-discovery-payload) it wants to set up. The shared options at the root level of the JSON message must include: - `device` mapping (abbreviated as `dev`) - `origin` mapping (abbreviated as `o`) These mappings are mandatory and cannot be overridden at the entity/component level. Supported shared options are: - The `availability` [options](https://www.home-assistant.io/integrations/mqtt/#using-availability-topics). - The `origin` (required) [options](https://www.home-assistant.io/integrations/mqtt/#adding-information-about-the-origin-of-a-discovery-message) - `command_topic` - `state_topic` - `qos` - `encoding` The component specific options are placed as mappings under the `components` key (abbreviated as `cmps`) like: ``` { "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" }, "cmps": { "some_unique_component_id1": { "p": "sensor", "device_class":"temperature", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae_t" }, "some_unique_id2": { "p": "sensor", "device_class":"humidity", "unit_of_measurement":"%", "value_template":"{{ value_json.humidity}}", "unique_id":"temp01ae_h" } }, "state_topic":"sensorBedroom/state", "qos": 2 } ``` JSON Copy Note To see what each abbreviation stands for, refer to the [list of supported abbreviations in MQTT discovery messages](https://www.home-assistant.io/integrations/mqtt/#supported-abbreviations-in-mqtt-discovery-messages). The components id’s under the `components` (`cmps`) key, are used as part of the discovery identification. A `platform` (`p`) config option is required for each component config that is added to identify the component platform. Also required is a `unique_id` for entity-based components. To remove the components, publish an empty (retained) string payload to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it. An empty config can be published as an update to remove a single component from the device discovery. Note that adding the `platform` (`p`) option is still required. ``` { "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" }, "cmps": { "some_unique_component_id1": { "p": "sensor", "device_class":"temperature", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae_t" }, "some_unique_id2": { "p": "sensor" } }, "state_topic":"sensorBedroom/state", "qos": 2 } ``` JSON Copy This will explicitly remove the humidity sensor and its entry. After removing a component, you should send another update with the removed component omitted from the configuration. This ensures that Home Assistant has the most up-to-date device configuration. For example: ``` { "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" }, "cmps": { "some_unique_component_id1": { "p": "sensor", "device_class":"temperature", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae_t" } }, "state_topic":"sensorBedroom/state", "qos": 2 } ``` JSON Copy A component config part in a device discovery payload must have the `platform` (`p`) option set with the name of the `component` and also must have at least one component specific config option. Entity components must have set the `unique_id` option and have a `device` context. ##### Migration from single component to device discovery To allow a smooth migration from single component discovery to device discovery: 1. Ensure all entities have a `unique_id` and a `device` context. 2. Move the `object_id` inside the discovery payload, if that is available, or use a unique ID or the component. 3. Consider using the previous `node_id` as the new `object_id` of the device discovery topic. 4. Ensure the `unique_id` matches and the `device` context has the correct identifiers. 5. Send the following payload to all existing single component discovery topics: `{"migrate_discovery": true }`. This will unload the discovered item, but its settings will be retained. 6. Switch the discovery topic to the device discovery topic and include all the component configurations. 7. Clean up the single component discovery messages with an empty payload. During the migration steps, INFO messages will be logged to inform you about the progress of the migration. Important Consider testing the migration process in a non-production environment before applying it to a live system. #### Discovery migration example with a device automation and a sensor Step 1: Original single component discovery configurations: Discovery topic single: `homeassistant/device_automation/0AFFD2/bla1/config` Discovery id: `0AFFD2 bla1` (both `0AFFD2` and `bla1` from the discovery topic) Discovery payload single: ``` { "device": { "identifiers": ["0AFFD2"], "name": "Test device" }, "o": { "name": "foobar" }, "automation_type": "trigger", "payload": "short_press", "topic": "foobar/triggers/button1", "type": "button_short_press", "subtype": "button_1" } ``` JSON Copy Discovery topic single: `homeassistant/sensor/0AFFD2/bla2/config` Discovery id: `0AFFD2 bla2` (both `0AFFD2` and `bla2` from the discovery topic) Discovery payload single: ``` { "device": { "identifiers": ["0AFFD2"], "name": "Test device" }, "o": { "name": "foobar" }, "state_topic": "foobar/sensor/sensor1", "unique_id": "bla_sensor001" } ``` JSON Copy Step 2: Initiate migration by publishing to both discovery topics: When these single component discovery payloads are processed, and we want to initiate migration to device discovery, we need to publish … ``` {"migrate_discovery": true } ``` JSON Copy … to both discovery topics … - `homeassistant/device_automation/0AFFD2/bla1/config` - `homeassistant/sensor/0AFFD2/bla2/config` Important Check the logs to ensure this step is executed correctly. Step 3: Publish the new device discovery configuration: Discovery topic device: `homeassistant/device/0AFFD2/config` Discovery id: `0AFFD2 bla` (`0AFFD2`from discovery topic, `bla`: The key under `cmps` in the discovery payload) Discovery payload device: ``` { "device": { "identifiers": [ "0AFFD2" ] }, "o": { "name": "foobar" }, "cmps": { "bla1": { "p": "device_automation", "automation_type": "trigger", "payload": "short_press", "topic": "foobar/triggers/button1", "type": "button_short_press", "subtype": "button_1" }, "bla2": { "p": "sensor", "state_topic": "foobar/sensor/sensor1", "unique_id": "bla_sensor001" } } } ``` JSON Copy Important Check the logs to ensure the migration was successful. Step 4: Clean up after successful migration: After the logs show a successful migration, the single component discovery topics can be cleaned up safely by publishing an empty payload to them. The logs should indicate if the discovery migration was successful. Optional: Rolling back the migration: To rollback publish … ``` {"migrate_discovery": true } ``` JSON Copy To the device discovery topic(s). After that, re-publish the single component discovery payloads. At last, clean up the device discovery payloads by publishing an empty payload. Check the logs for every step. #### Single component discovery payload When using single component discovery messages, the `<component>` part in the discovery topic must be one of the supported MQTT platforms. The options in the payload are only used to set up one specific component. If a device contains multiple components, it is recommended to use [device discovery](https://www.home-assistant.io/integrations/mqtt/#device-discovery-payload) instead. MQTT entities can share device configuration, meaning one entity can include the full device configuration and other entities can link to that device by only setting mandatory fields. Important The mandatory fields were previously limited to at least one of `connection` and `identifiers`, but have now been extended to at least one of `connection` and `identifiers` as well as the `name`. Example discovery payload: ``` { "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" }, "device_class":"temperature", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae_t", "state_topic":"sensorBedroom/state", "qos": 2 } ``` JSON Copy To remove the component, publish an empty string to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it. For more examples [see](https://www.home-assistant.io/integrations/mqtt/#discovery-examples-with-component-discovery). #### Discovery payload The payload must be a serialized JSON dictionary and will be checked like an entry in your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file if a new device is added, with the exception that unknown configuration keys are allowed but ignored. This means that missing variables will be filled with the integration’s default values. All configuration variables which are required must be present in the payload. The reason for allowing unknown documentation keys is allow some backwards compatibility, software generating MQTT discovery messages can then be used with older Home Assistant versions which will simply ignore new features. A discovery payload can be sent with a retain flag set. In that case, the discovery message will be stored at the MQTT broker and processed automatically when the MQTT integrations start. This method removes the need for it to be resent. A better approach, though, is for the software generating MQTT discovery messages to send discovery payload(s) when the MQTT integration sends the [Birth message](https://www.home-assistant.io/integrations/mqtt/#birth-and-last-will-messages). Subsequent messages on a topic where a valid payload has been received will be handled as a configuration update, and a configuration update with an empty payload will cause a previously discovered device to be deleted. A base topic `~` may be defined in the payload to conserve memory when the same topic base is used multiple times. In the value of configuration variables ending with `_topic`, `~` will be replaced with the base topic, if the `~` occurs at the beginning or end of the value. Configuration variable names in the discovery payload may be abbreviated to conserve memory when sending a discovery message from memory constrained devices. It is recommended to add information about the origin of MQTT entities by including the `origin` option (abbreviated as `o`) in the discovery payload. For device discovery, this information is required. The origin details will be logged in the core event log when an item is discovered or updated. Adding origin information helps with troubleshooting and provides valuable context about the source of MQTT messages in your Home Assistant setup. Note: These options also support abbreviations, as shown in the table below. name The name of the application that is the origin of the discovered MQTT item. (Required) sw\_version Software version of the application that supplies the discovered MQTT item. support\_url Support URL of the application that supplies the discovered MQTT item. #### Supported abbreviations in MQTT discovery messages Supported abbreviations ``` 'act_t': 'action_topic', 'act_tpl': 'action_template', 'atype': 'automation_type', 'aux_cmd_t': 'aux_command_topic', 'aux_stat_t': 'aux_state_topic', 'aux_stat_tpl': 'aux_state_template', 'av_tones': 'available_tones', 'avty': 'availability', 'avty_mode': 'availability_mode', 'avty_t': 'availability_topic', 'avty_tpl': 'availability_template', 'away_mode_cmd_t': 'away_mode_command_topic', 'away_mode_stat_t': 'away_mode_state_topic', 'away_mode_stat_tpl': 'away_mode_state_template', 'b_tpl': 'blue_template', 'bri_cmd_t': 'brightness_command_topic', 'bri_cmd_tpl': 'brightness_command_template', 'bri_scl': 'brightness_scale', 'bri_stat_t': 'brightness_state_topic', 'bri_tpl': 'brightness_template', 'bri_val_tpl': 'brightness_value_template', 'clr_temp_cmd_tpl': 'color_temp_command_template', 'clr_temp_cmd_t': 'color_temp_command_topic', 'clr_temp_k': 'color_temp_kelvin', 'clr_temp_stat_t': 'color_temp_state_topic', 'clr_temp_tpl': 'color_temp_template', 'clr_temp_val_tpl': 'color_temp_value_template', 'clrm_stat_t': 'color_mode_state_topic', 'clrm_val_tpl': 'color_mode_value_template', 'cmd_off_tpl': 'command_off_template', 'cmd_on_tpl': 'command_on_template', 'cmd_t': 'command_topic', 'cmd_tpl': 'command_template', 'cmps': 'components', 'cod_arm_req': 'code_arm_required', 'cod_dis_req': 'code_disarm_required', 'cod_trig_req': 'code_trigger_required', 'cont_type': 'content_type', 'curr_temp_t': 'current_temperature_topic', 'curr_temp_tpl': 'current_temperature_template', 'def_ent_id': 'default_entity_id', 'dev': 'device', 'dev_cla': 'device_class', 'dir_cmd_t': 'direction_command_topic', 'dir_cmd_tpl': 'direction_command_template', 'dir_stat_t': 'direction_state_topic', 'dir_val_tpl': 'direction_value_template', 'dsp_prc': 'display_precision', 'e': 'encoding', 'en': 'enabled_by_default', 'ent_cat': 'entity_category', 'ent_pic': 'entity_picture', 'evt_typ': 'event_types', 'exp_aft': 'expire_after', 'fanspd_lst': 'fan_speed_list', 'flsh': 'flash', 'flsh_tlng': 'flash_time_long', 'flsh_tsht': 'flash_time_short', 'fx_cmd_t': 'effect_command_topic', 'fx_cmd_tpl': 'effect_command_template', 'fx_list': 'effect_list', 'fx_stat_t': 'effect_state_topic', 'fx_tpl': 'effect_template', 'fx_val_tpl': 'effect_value_template', 'fan_mode_cmd_t': 'fan_mode_command_topic', 'fan_mode_cmd_tpl': 'fan_mode_command_template', 'fan_mode_stat_t': 'fan_mode_state_topic', 'fan_mode_stat_tpl': 'fan_mode_state_template', 'frc_upd': 'force_update', 'g_tpl': 'green_template', 'grp': 'group', 'hs_cmd_t': 'hs_command_topic', 'hs_cmd_tpl': 'hs_command_template', 'hs_stat_t': 'hs_state_topic', 'hs_val_tpl': 'hs_value_template', 'ic': 'icon', 'img_e': 'image_encoding', 'img_t': 'image_topic', 'init': 'initial', 'hum_cmd_t': 'target_humidity_command_topic', 'hum_cmd_tpl': 'target_humidity_command_template', 'hum_stat_t': 'target_humidity_state_topic', 'hum_state_tpl': 'target_humidity_state_template', 'json_attr': 'json_attributes', 'json_attr_t': 'json_attributes_topic', 'json_attr_tpl': 'json_attributes_template', 'l_ver_t': 'latest_version_topic', 'l_ver_tpl': 'latest_version_template', 'lrst_t': 'last_reset_topic', 'lrst_val_tpl': 'last_reset_value_template', 'max': 'max', 'max_hum': 'max_humidity', 'max_k': 'max_kelvin', 'max_mirs': 'max_mireds', 'max_temp': 'max_temp', 'migr_discvry': 'migrate_discovery', 'min': 'min', 'min_hum': 'min_humidity', 'min_k': 'min_kelvin', 'min_mirs': 'min_mireds', 'min_temp': 'min_temp', 'mode': 'mode', 'mode_cmd_t': 'mode_command_topic', 'mode_cmd_tpl': 'mode_command_template', 'mode_stat_t': 'mode_state_topic', 'mode_stat_tpl': 'mode_state_template', 'modes': 'modes', 'name': 'name', 'o': 'origin', 'off_dly': 'off_delay', 'on_cmd_type': 'on_command_type', 'ops': 'options', 'opt': 'optimistic', 'osc_cmd_t': 'oscillation_command_topic', 'osc_cmd_tpl': 'oscillation_command_template', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', 'p': 'platform', 'pct_cmd_t': 'percentage_command_topic', 'pct_cmd_tpl': 'percentage_command_template', 'pct_stat_t': 'percentage_state_topic', 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', 'pl_arm_away': 'payload_arm_away', 'pl_arm_custom_b': 'payload_arm_custom_bypass', 'pl_arm_home': 'payload_arm_home', 'pl_arm_nite': 'payload_arm_night', 'pl_arm_vacation': 'payload_arm_vacation', 'pl_avail': 'payload_available', 'pl_cln_sp': 'payload_clean_spot', 'pl_cls': 'payload_close', 'pl_dir_fwd': 'payload_direction_forward', 'pl_dir_rev': 'payload_direction_reverse', 'pl_disarm': 'payload_disarm', 'pl_home': 'payload_home', 'pl_inst': 'payload_install', 'pl_loc': 'payload_locate', 'pl_lock': 'payload_lock', 'pl_not_avail': 'payload_not_available', 'pl_not_home': 'payload_not_home', 'pl_off': 'payload_off', 'pl_on': 'payload_on', 'pl_open': 'payload_open', 'pl_osc_off': 'payload_oscillation_off', 'pl_osc_on': 'payload_oscillation_on', 'pl_paus': 'payload_pause', 'pl_prs': 'payload_press', 'pl_ret': 'payload_return_to_base', 'pl_rst': 'payload_reset', 'pl_rst_hum': 'payload_reset_humidity', 'pl_rst_mode': 'payload_reset_mode', 'pl_rst_pct': 'payload_reset_percentage', 'pl_rst_pr_mode': 'payload_reset_preset_mode', 'pl_stop': 'payload_stop', 'pl_stop_tilt': 'payload_stop_tilt', 'pl_stpa': 'payload_start_pause', 'pl_strt': 'payload_start', 'pl_toff': 'payload_turn_off', 'pl_ton': 'payload_turn_on', 'pl_trig': 'payload_trigger', 'pl_unlk': 'payload_unlock', 'pos': 'reports_position', 'pos_clsd': 'position_closed', 'pos_open': 'position_open', 'pr_mode_cmd_t': 'preset_mode_command_topic', 'pr_mode_cmd_tpl': 'preset_mode_command_template', 'pr_mode_stat_t': 'preset_mode_state_topic', 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', 'ptrn': 'pattern', 'r_tpl': 'red_template', 'rel_s': 'release_summary', 'rel_u': 'release_url', 'ret': 'retain', 'rgb_cmd_t': 'rgb_command_topic', 'rgb_cmd_tpl': 'rgb_command_template', 'rgb_stat_t': 'rgb_state_topic', 'rgb_val_tpl': 'rgb_value_template', 'rgbw_cmd_t': 'rgbw_command_topic', 'rgbw_cmd_tpl': 'rgbw_command_template', 'rgbw_stat_t': 'rgbw_state_topic', 'rgbw_val_tpl': 'rgbw_value_template', 'rgbww_cmd_t': 'rgbww_command_topic', 'rgbww_cmd_tpl': 'rgbww_command_template', 'rgbww_stat_t': 'rgbww_state_topic', 'rgbww_val_tpl': 'rgbww_value_template', 'send_cmd_t': 'send_command_topic', 'send_if_off': 'send_if_off', 'set_fan_spd_t': 'set_fan_speed_topic', 'set_pos_t': 'set_position_topic', 'set_pos_tpl': 'set_position_template', 'pos_t': 'position_topic', 'pos_tpl': 'position_template', 'spd_rng_min': 'speed_range_min', 'spd_rng_max': 'speed_range_max', 'src_type': 'source_type', 'stat_cla': 'state_class', 'stat_closing': 'state_closing', 'stat_clsd': 'state_closed', 'stat_jam': 'state_jammed', 'stat_locked': 'state_locked', 'stat_locking': 'state_locking', 'stat_off': 'state_off', 'stat_on': 'state_on', 'stat_open': 'state_open', 'stat_opening': 'state_opening', 'stat_stopped': 'state_stopped', 'stat_unlocked': 'state_unlocked', 'stat_unlocking': 'state_unlocking', 'stat_t': 'state_topic', 'stat_tpl': 'state_template', 'stat_val_tpl': 'state_value_template', 'step': 'step', 'stype': 'subtype', 'sug_dsp_prc': 'suggested_display_precision', 'sup_clrm': 'supported_color_modes', 'sup_dur': 'support_duration', 'sup_vol': 'support_volume_set', 'sup_feat': 'supported_features', 'swing_mode_cmd_t': 'swing_mode_command_topic', 'swing_mode_cmd_tpl': 'swing_mode_command_template', 'swing_mode_stat_t': 'swing_mode_state_topic', 'swing_mode_stat_tpl': 'swing_mode_state_template', 't': 'topic', 'temp_cmd_t': 'temperature_command_topic', 'temp_cmd_tpl': 'temperature_command_template', 'temp_hi_cmd_t': 'temperature_high_command_topic', 'temp_hi_cmd_tpl': 'temperature_high_command_template', 'temp_hi_stat_t': 'temperature_high_state_topic', 'temp_hi_stat_tpl': 'temperature_high_state_template', 'temp_lo_cmd_t': 'temperature_low_command_topic', 'temp_lo_cmd_tpl': 'temperature_low_command_template', 'temp_lo_stat_t': 'temperature_low_state_topic', 'temp_lo_stat_tpl': 'temperature_low_state_template', 'temp_stat_t': 'temperature_state_topic', 'temp_stat_tpl': 'temperature_state_template', 'temp_unit': 'temperature_unit', 'tilt_clsd_val': 'tilt_closed_value', 'tilt_cmd_t': 'tilt_command_topic', 'tilt_cmd_tpl': 'tilt_command_template', 'tilt_max': 'tilt_max', 'tilt_min': 'tilt_min', 'tilt_opnd_val': 'tilt_opened_value', 'tilt_opt': 'tilt_optimistic', 'tilt_status_t': 'tilt_status_topic', 'tilt_status_tpl': 'tilt_status_template', 'tit': 'title', 'trns': 'transition', 'uniq_id': 'unique_id', 'unit_of_meas': 'unit_of_measurement', 'url_t': 'url_topic', 'url_tpl': 'url_template', 'val_tpl': 'value_template', 'whit_cmd_t': 'white_command_topic', 'whit_scl': 'white_scale', 'xy_cmd_t': 'xy_command_topic', 'xy_cmd_tpl': 'xy_command_template', 'xy_stat_t': 'xy_state_topic', 'xy_val_tpl': 'xy_value_template', ``` Txt Copy Supported abbreviations for device registry configuration ``` 'cu': 'configuration_url', 'cns': 'connections', 'ids': 'identifiers', 'name': 'name', 'mf': 'manufacturer', 'mdl': 'model', 'mdl_id': 'model_id', 'hw': 'hw_version', 'sw': 'sw_version', 'sa': 'suggested_area', 'sn': 'serial_number', ``` Txt Copy Supported abbreviations for origin info ``` 'name': 'name', 'sw': 'sw_version', 'url': 'support_url', ``` Txt Copy ### Discovery messages and availability When MQTT discovery is set up, and a device or service sends a discovery message, an MQTT entity, tag, or device automation will be set up directly after receiving the message. When Home Assistant is restarting, discovered MQTT items with a unique ID will be unavailable until a new discovery message is received. MQTT items without a unique ID will not be added at startup. So a device or service using MQTT discovery must make sure a configuration message is offered after the MQTT integration has been (re)started. There are two common approaches to make sure the discovered items are set up at startup: 1. Using Birth and Will messages to trigger setup 2. Using retained messages Finally, it is a best practice to publish your device or service availability status. #### Use the Birth and Will messages to trigger discovery When the MQTT integration starts, a birth message is published at `homeassistant/status` by default. A device or service connected to the shared `mqtt` broker can subscribe to this topic and use an `online` message to trigger discovery messages. See also the [birth and last will messages](https://www.home-assistant.io/integrations/mqtt/#birth-and-last-will-messages) section. After the configs have been published, the state topics will need an update, so they need to be republished. #### Using retained config messages An alternative method for a device or service is to publish discovery messages with a `retain` flag. This will make sure discovery messages are replayed when the MQTT integration connects to the broker. After the configs have been published, the state topics will need an update. #### Using retained state messages State updates also need to be re-published after a config as been processed. This can also be done by publishing `retained` messages. As soon as a config is received (or replayed from a retained message), the setup will subscribe any state topics. If a retained message is available at a state topic, this message will be replayed so that the state can be restored for this topic. Warning A disadvantage of using retained messages is that these messages retain at the broker, even when the device or service stops working. They are retained even after the system or broker has been restarted. Retained messages can create ghost entities that keep coming back. Especially when you have many entities, (unneeded) discovery messages can cause excessive system load. For this reason, use discovery messages with caution. ### Using Availability topics A device or service can announce its availability by publishing a Birth message and set a Will message at the broker. When the device or service loses connection to the broker, the broker will publish the Will message. This allows the MQTT integration to make an entity unavailable. Platform specific availability settings are available for `mqtt` entity platforms only. Platform specific availability settings #### Configuration Variables [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) availability list (Optional) A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`. payload\_available string (Optional, default: online) The payload that represents the available state. payload\_not\_available string (Optional, default: offline) The payload that represents the unavailable state. topic string Required An MQTT topic subscribed to receive availability (online/offline) updates. value\_template [template](https://www.home-assistant.io/docs/configuration/templating/) (Optional) Defines a [template](https://www.home-assistant.io/docs/templating/where-to-use/#mqtt) to extract a device’s availability from the `topic`. To determine the device’s availability, the result of this template will be compared to `payload_available` and `payload_not_available`. availability\_topic string (Optional) The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. availability\_mode string (Optional, default: latest) When `availability` is configured, this controls the conditions needed to set the entity to `available`. Valid entries are `all`, `any`, and `latest`. If set to `all`, `payload_available` must be received on all configured availability topics before the entity is marked as online. If set to `any`, `payload_available` must be received on at least one configured availability topic before the entity is marked as online. If set to `latest`, the last `payload_available` or `payload_not_available` received on any configured availability topic controls the availability. availability\_template [template](https://www.home-assistant.io/docs/configuration/templating/) (Optional) Defines a [template](https://www.home-assistant.io/docs/templating/where-to-use/#mqtt) to extract device’s availability from the `availability_topic`. To determine the devices’s availability result of this template will be compared to `payload_available` and `payload_not_available`. payload\_available string (Optional, default: online) The payload that represents the available state. payload\_not\_available string (Optional, default: offline) The payload that represents the unavailable state. ### Discovery examples with component discovery #### Motion detection (binary sensor) A motion detection device which can be represented by a [binary sensor](https://www.home-assistant.io/integrations/binary_sensor.mqtt/) for your garden would send its configuration as JSON payload to the Configuration topic. After the first message to `config`, then the MQTT messages sent to the state topic will update the state in Home Assistant. - Configuration topic: `homeassistant/binary_sensor/garden/config` - State topic: `homeassistant/binary_sensor/garden/state` - Configuration payload with derived device name: ``` { "name":null, "device_class":"motion", "state_topic":"homeassistant/binary_sensor/garden/state", "unique_id":"motion01ad", "device":{ "identifiers":[ "01ad" ], "name":"Garden" } } ``` JSON Copy - Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts. It is also a good idea to add a `unique_id` to allow changes to the entity and a `device` mapping so we can group all sensors of a device together. We can set “name” to `null` if we want to inherit the device name for the entity. If we set an entity name, the `friendly_name` will be a combination of the device and entity name. If `name` is left away and a `device_class` is set, the entity name part will be derived from the `device_class`. - Example configuration payload with no name set and derived `device_class` name: ``` { "name":null, "device_class":"motion", "state_topic":"homeassistant/binary_sensor/garden/state", "unique_id":"motion01ad", "device":{ "identifiers":[ "01ad" ], "name":"Garden" } } ``` JSON Copy If no name is set, a default name will be set by MQTT ([see the MQTT platform documentation](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery)). To create a new sensor manually and with the name set to `null` to derive the device name “Garden”: ``` mosquitto_pub -r -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": null, "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state", "unique_id": "motion01ad", "device": {"identifiers": ["01ad"], "name": "Garden" }}' ``` Bash Copy Update the state: ``` mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/state" -m ON ``` Bash Copy Delete the sensor by sending an empty message. ``` mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '' ``` Bash Copy For more details, refer to the [MQTT testing section](https://www.home-assistant.io/integrations/mqtt/#testing-your-setup). #### Sensors Setting up a sensor with multiple measurement values requires multiple consecutive configuration topic submissions. - Configuration topic no1: `homeassistant/sensor/sensorBedroomT/config` - Configuration payload no1: ``` { "device_class":"temperature", "state_topic":"homeassistant/sensor/sensorBedroom/state", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae", "device":{ "identifiers":[ "bedroom01ae" ], "name":"Bedroom", "manufacturer": "Example sensors Ltd.", "model": "Example Sensor", "model_id": "K9", "serial_number": "12AE3010545", "hw_version": "1.01a", "sw_version": "2024.1.0", "configuration_url": "<https://example.com/sensor_portal/config>" } } ``` JSON Copy - Configuration topic no2: `homeassistant/sensor/sensorBedroomH/config` - Configuration payload no2: ``` { "device_class":"humidity", "state_topic":"homeassistant/sensor/sensorBedroom/state", "unit_of_measurement":"%", "value_template":"{{ value_json.humidity}}", "unique_id":"hum01ae", "device":{ "identifiers":[ "bedroom01ae" ] } } ``` JSON Copy The sensor [`identifiers` or `connections`](https://www.home-assistant.io/integrations/sensor.mqtt/#device) option allows to set up multiple entities that share the same device. Note If a device configuration is shared, then it is not needed to add all device details to the other entity configs. It is enough to add shared identifiers or connections to the device mapping for the other entity config payloads. A common state payload that can be parsed with the `value_template` in the sensor configs: ``` { "temperature":23.20, "humidity":43.70 } ``` JSON Copy #### Entities with command topics Setting up a light or switch is similar but requires a `command_topic` as mentioned in the [MQTT switch documentation](https://www.home-assistant.io/integrations/switch.mqtt/). - Configuration topic: `homeassistant/switch/irrigation/config` - State topic: `homeassistant/switch/irrigation/state` - Command topic: `homeassistant/switch/irrigation/set` - Payload: ``` { "name":"Irrigation", "command_topic":"homeassistant/switch/irrigation/set", "state_topic":"homeassistant/switch/irrigation/state", "unique_id":"irr01ad", "device":{ "identifiers":[ "garden01ad" ], "name":"Garden" } } ``` JSON Copy - Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts. ``` mosquitto_pub -r -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/config" \ -m '{"name": "Irrigation", "command_topic": "homeassistant/switch/irrigation/set", "state_topic": "homeassistant/switch/irrigation/state", "unique_id": "irr01ad", "device": {"identifiers": ["garden01ad"], "name": "Garden" }}' ``` Bash Copy Set the state: ``` mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/set" -m ON ``` Bash Copy #### Using abbreviations and base topic Setting up a switch using topic prefix and abbreviated configuration variable names to reduce payload length. - Configuration topic: `homeassistant/switch/irrigation/config` - Command topic: `homeassistant/switch/irrigation/set` - State topic: `homeassistant/switch/irrigation/state` - Configuration payload: ``` { "~":"homeassistant/switch/irrigation", "name":"garden", "cmd_t":"~/set", "stat_t":"~/state" } ``` JSON Copy Note To see what each abbreviation stands for, refer to the [list of supported abbreviations in MQTT discovery messages](https://www.home-assistant.io/integrations/mqtt/#supported-abbreviations-in-mqtt-discovery-messages). #### Another example using abbreviations topic name and base topic Setting up a [light that takes JSON payloads](https://www.home-assistant.io/integrations/light.mqtt/#json-schema), with abbreviated configuration variable names: - Configuration topic: `homeassistant/light/kitchen/config` - Command topic: `homeassistant/light/kitchen/set` - State topic: `homeassistant/light/kitchen/state` - Example state payload: `{"state": "ON", "brightness": 255}` - Configuration payload: ``` { "~": "homeassistant/light/kitchen", "name": "Kitchen", "uniq_id": "kitchen_light", "cmd_t": "~/set", "stat_t": "~/state", "schema": "json", "brightness": true } ``` JSON Copy #### Example with using abbreviated Device and Origin info in discovery messages ``` { "~": "homeassistant/light/kitchen", "name": null, "uniq_id": "kitchen_light", "cmd_t": "~/set", "stat_t": "~/state", "schema": "json", "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "mdl_id": "ABC123", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" } } ``` JSON Copy ### Support by third-party tools The following software has built-in support for MQTT discovery: - [anpr2mqtt](https://anpr2mqtt.rhizomatics.org.uk/) - [ArduinoHA](https://github.com/dawidchyrzynski/arduino-home-assistant) - [Arilux AL-LC0X LED controllers](https://github.com/smrtnt/Arilux_AL-LC0X) - [ble2mqtt](https://github.com/devbis/ble2mqtt) - [diematic\_server](https://github.com/IgnacioHR/diematic_server) - [digitalstrom-mqtt](https://github.com/gaetancollaud/digitalstrom-mqtt) - [ebusd](https://github.com/john30/ebusd) - [ecowitt2mqtt](https://github.com/bachya/ecowitt2mqtt) - [EMS-ESP32 (and EMS-ESP)](https://github.com/emsesp/EMS-ESP32) - [ESPHome](https://esphome.io/) - [ESPurna](https://github.com/xoseperez/espurna) - [go-iotdevice](https://github.com/koestler/go-iotdevice) - [HASS.Agent](https://github.com/LAB02-Research/HASS.Agent) - [IOTLink](https://iotlink.gitlab.io/) (starting with 2.0.0) - [MiFlora MQTT Daemon](https://github.com/ThomDietrich/miflora-mqtt-daemon) - [MyElectricalData](https://github.com/MyElectricalData/myelectricaldata_import#english) - [MqDockerUp](https://github.com/MichelFR/MqDockerUp) - [Nuki Hub](https://github.com/technyon/nuki_hub) - [Nuki Smart Lock 3.0 Pro](https://support.nuki.io/hc/articles/12947926779409-MQTT-support), [more info](https://developer.nuki.io/t/mqtt-api-specification-v1-3/17626) - [OpenMQTTGateway](https://github.com/1technophile/OpenMQTTGateway) - [OTGateway](https://github.com/Laxilef/OTGateway) - [rethink](https://github.com/anszom/rethink) - [room-assistant](https://github.com/mKeRix/room-assistant) (starting with 1.1.0) - [SmartHome](https://github.com/roncoa/SmartHome) - [SpeedTest-CLI MQTT](https://github.com/adorobis/speedtest-CLI2mqtt) - [SwitchBot-MQTT-BLE-ESP32](https://github.com/devWaves/SwitchBot-MQTT-BLE-ESP32) - [Tasmota](https://github.com/arendst/Tasmota) (starting with 5.11.1e, development halted) - [TeddyCloud](https://github.com/toniebox-reverse-engineering/teddycloud) - [Teleinfo MQTT](https://fmartinou.github.io/teleinfo2mqtt) (starting with 3.0.0) - [Tydom2MQTT](https://tydom2mqtt.github.io/tydom2mqtt/) - [Updates2MQTT](https://updates2mqtt.rhizomatics.org.uk/) - [What’s up Docker?](https://fmartinou.github.io/whats-up-docker/) (starting with 3.5.0) - [WyzeSense2MQTT](https://github.com/raetha/wyzesense2mqtt) - [Xiaomi DaFang Hacks](https://github.com/EliasKotlyar/Xiaomi-Dafang-Hacks) - [Zehnder Comfoair RS232 MQTT](https://github.com/adorobis/hacomfoairmqtt) - [Zigbee2MQTT](https://github.com/koenkk/zigbee2mqtt) The following software also supports consuming MQTT discovery information that is intended for Home Assistant. Compatibility and features will vary, and not all devices may work. - [Domoticz](https://wiki.domoticz.com/MQTT#Add_hardware_.22MQTT_Auto_Discovery_Client_Gateway.22) - [openHAB](https://www.openhab.org/addons/bindings/mqtt.homeassistant/) ## Manual configured MQTT items Support to allow [adding manual items as a subentry via a config flow](https://www.home-assistant.io/integrations/mqtt/#configuration), is work in progress. Not all entity platforms are supported yet. For most integrations, it is also possible to manually set up MQTT items in `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/). Read more [about configuration in YAML](https://www.home-assistant.io/docs/configuration/yaml). MQTT supports two styles for configuring items in YAML. All configuration items are placed directly under the `mqtt` integration key. Note that you cannot mix these styles. Use the YAML configuration listed per item style when in doubt. ### YAML configuration listed per item This method expects all items to be in a YAML list. Each item has a `{domain}` key and the item config is placed directly under the domain key. This method is considered as best practice. In all the examples we use this format. ``` mqtt: - {domain}: name: "" ... - {domain}: name: "" ... ``` YAML Copy ### YAML configuration keyed and bundled by `{domain}` All items are grouped per `{domain}` and where all configs are listed. ``` mqtt: {domain}: - name: "" ... - name: "" ... ``` YAML Copy If you have a large number of manually configured items, you might want to consider [splitting up the configuration](https://www.home-assistant.io/docs/configuration/splitting_configuration/). Note Documentation on the MQTT components that support YAML [can be found here](https://www.home-assistant.io/integrations/mqtt/#configuration-via-yaml). ## Entity state updates Entities receive state updates via MQTT subscriptions. The payloads received on the state topics are processed to determine whether there is a significant change. If a change is detected, the entity will be updated. Note that MQTT device payloads often contain information for updating multiple entities that subscribe to the same topics. For example, a light status update might include information about link quality. This data can update a link quality sensor but is not used to update the light itself. MQTT filters out entity state updates when there are no changes. ### The last reported state attribute Because MQTT state updates are often repeated frequently, even when no actual changes exist, it is up to the MQTT subscriber to determine whether a status update was received. If the latest update is missed, it might take some time before the next one arrives. If a retained payload exists at the broker, that value will be replayed first, but it will be an update of a previous last state. MQTT devices often continuously generate numerous state updates. MQTT does not update `last_reported` to avoid impacting system stability unless `force_update` is set. Alternatively, an MQTT sensor can be created to measure the last update. ## Using Templates The MQTT integration supports templating. Read more [about using templates with the MQTT integration](https://www.home-assistant.io/docs/templating/where-to-use/#mqtt). ### Examples #### REST API Using the [REST API](https://developers.home-assistant.io/docs/api/rest/) to send a message to a given topic. ``` $ curl -X POST \ -H "Authorization: Bearer ABCDEFGH" \ -H "Content-Type: application/json" \ -d '{"payload": "Test message from HA", "topic": "home/notification"}' \ <http://IP_ADDRESS:8123/api/services/mqtt/publish> ``` Bash Copy #### Automations Use as [`script`](https://www.home-assistant.io/integrations/script/) in automations. ``` automation: alias: "Send me a message when I get home" triggers: - trigger: state entity_id: device_tracker.me to: "home" actions: - action: script.notify_mqtt data: target: "me" message: "I'm home" script: notify_mqtt: sequence: - action: mqtt.publish data: payload: "{{ message }}" topic: "home/{{ target }}" retain: true ``` YAML Copy ## Publish & Dump actions The MQTT integration will register the `mqtt.publish` action, which allows publishing messages to MQTT topics. ### Action: Publish The `mqtt.publish` action publishes a message to an MQTT topic. \| Data attribute \| Optional \| Description \| \|---\|---\|---\| \| `topic` \| no \| Topic to publish payload to. \| \| `payload` \| yes \| Payload to publish. Will publish an empty payload when `payload` is omitted. \| \| `evaluate_payload` \| yes \| If a `bytes` literal in `payload` should be evaluated to publish raw data. (default: false) \| \| `qos` \| yes \| Quality of Service to use. (default: 0) \| \| `retain` \| yes \| If message should have the retain flag set. (default: false) \| Note When `payload` is rendered from [template](https://www.home-assistant.io/docs/templating/where-to-use/#mqtt) in a YAML script or automation, and the template renders to a `bytes` literal, the outgoing MQTT payload will only be sent as `raw` data, if the `evaluate_payload` option flag is set to `true`. ``` topic: homeassistant/light/1/command payload: "ON" ``` YAML Copy ``` topic: homeassistant/light/1/state payload: "{{ states('device_tracker.paulus') }}" ``` YAML Copy ``` topic: "homeassistant/light/{{ states('sensor.light_active') }}/state" payload: "{{ states('device_tracker.paulus') }}" ``` YAML Copy Be aware that `payload` must be a string. If you want to send JSON using the YAML editor then you need to format/escape it properly. Like: ``` topic: homeassistant/light/1/state payload: "{\"Status\":\"off\", \"Data\":\"something\"}" ``` YAML Copy The example below shows how to publish a temperature sensor ‘Bathroom Temperature’. The `device_class` is set, so it is not needed to set the “name” option. The entity will inherit the name from the `device_class` set and also support translations. If you set “name” in the payload the entity name will start with the device name. ``` action: mqtt.publish data: topic: homeassistant/sensor/Acurite-986-1R-51778/config payload: >- {"device_class": "temperature", "unit_of_measurement": "\u00b0C", "value_template": "{{ value \| float }}", "state_topic": "rtl_433/rtl433/devices/Acurite-986/1R/51778/temperature_C", "unique_id": "Acurite-986-1R-51778-T", "device": { "identifiers": "Acurite-986-1R-51778", "name": "Bathroom", "model": "Acurite", "model_id": "986", "manufacturer": "rtl_433" } } ``` YAML Copy Example of how to use `qos` and `retain`: ``` topic: homeassistant/light/1/command payload: "ON" qos: 2 retain: true ``` YAML Copy ### Action: Dump The `mqtt.dump` action listens to the specified topic matcher and dumps all received messages within a specific duration into the file `mqtt_dump.txt` in your configuration folder. This is useful when debugging a problem. \| Data attribute \| Optional \| Description \| \|---\|---\|---\| \| `topic` \| no \| Topic to dump. Can contain a wildcard (`#` or `+`). \| \| `duration` \| yes \| Duration in seconds that we will listen for messages. Default is 5 seconds. \| ``` topic: zigbee2mqtt/# ``` YAML Copy ## Logging The [logger](https://www.home-assistant.io/integrations/logger/) integration allows the logging of received MQTT messages. ``` # Example configuration.yaml entry logger: default: warning logs: homeassistant.components.mqtt: debug ``` YAML Copy ## Event `event_mqtt_reloaded` Event `event_mqtt_reloaded` is fired when Manually configured MQTT entities have been reloaded and entities thus might have changed. This event has no additional data. ## Removing the integration 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations) and select the integration card. 2. From the list of devices, select the integration instance you want to remove. 3. Next to the entry, select the three dots menu. Then, select Delete. Note: This action does not remove the [MQTT broker](https://www.home-assistant.io/integrations/mqtt/#setting-up-a-broker) or its data. If you want to completely remove MQTT: 1. Check your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) and other YAML files for MQTT-related configurations and remove them 2. Review your automations and scripts for any MQTT dependencies 3. Consider backing up your configuration before making these changes #### Help us improve our documentation Suggest an edit to this page, or provide/view feedback for this page. - [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/mqtt.markdown "Edit this page") - [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fintegrations%2Fmqtt%2F&version=2026.4.1&labels=current,integration%3A%20mqtt "Provide feedback on this page") - [View pending feedback](https://github.com/home-assistant/home-assistant.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22integration%3A+mqtt%22 "View pending feedback for this page") ![](https://brands.home-assistant.io/_/mqtt//logo.png)[![](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start?domain=mqtt) The MQTT service was introduced in Home Assistant pre 0.7, and it's used by [48%](https://analytics.home-assistant.io/integrations "Open analytics.home-assistant.io") of the active installations. Its IoT class is [Local Push.](https://www.home-assistant.io/blog/2016/02/12/classifying-the-internet-of-things/#classifiers) [🏆 Platinum quality](https://www.home-assistant.io/docs/quality_scale/#-platinum) [View source on GitHub](https://github.com/home-assistant/core/tree/dev/homeassistant/components/mqtt) [View known issues](https://github.com/home-assistant/core/issues?q=is%3Aissue+label%3A%22integration%3A+mqtt%22) [View feature requests](https://github.com/orgs/home-assistant/discussions?discussions_q=label%3A%22integration%3A+mqtt%22) ## Integration owners We are incredibly grateful to the following contributors who currently maintain this integration: [![@emontnemery](https://avatars.githubusercontent.com/emontnemery?size=96) @emontnemery](https://github.com/emontnemery) [![@jbouwh](https://avatars.githubusercontent.com/jbouwh?size=96) @jbouwh](https://github.com/jbouwh) [![@bdraco](https://avatars.githubusercontent.com/bdraco?size=96) @bdraco](https://github.com/bdraco) ## Categories - [Hub](https://www.home-assistant.io/integrations/#hub) - [Update](https://www.home-assistant.io/integrations/#update) ## On this page - [Configuration](https://www.home-assistant.io/integrations/mqtt/#configuration) - [Setting up a broker](https://www.home-assistant.io/integrations/mqtt/#setting-up-a-broker) - [Broker configuration](https://www.home-assistant.io/integrations/mqtt/#broker-configuration) - [Advanced broker configuration](https://www.home-assistant.io/integrations/mqtt/#advanced-broker-configuration) - [Configure MQTT options](https://www.home-assistant.io/integrations/mqtt/#configure-mqtt-options) - [Change MQTT discovery options](https://www.home-assistant.io/integrations/mqtt/#change-mqtt-discovery-options) - [Discovery options](https://www.home-assistant.io/integrations/mqtt/#discovery-options) - [Birth and last will messages](https://www.home-assistant.io/integrations/mqtt/#birth-and-last-will-messages) - [Testing your setup](https://www.home-assistant.io/integrations/mqtt/#testing-your-setup) - [Naming of MQTT Entities](https://www.home-assistant.io/integrations/mqtt/#naming-of-mqtt-entities) - [Grouping entities](https://www.home-assistant.io/integrations/mqtt/#grouping-entities) - [MQTT Discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) - [Discovery messages](https://www.home-assistant.io/integrations/mqtt/#discovery-messages) - [Discovery messages and availability](https://www.home-assistant.io/integrations/mqtt/#discovery-messages-and-availability) - [Using Availability topics](https://www.home-assistant.io/integrations/mqtt/#using-availability-topics) - [Discovery examples with component discovery](https://www.home-assistant.io/integrations/mqtt/#discovery-examples-with-component-discovery) - [Support by third-party tools](https://www.home-assistant.io/integrations/mqtt/#support-by-third-party-tools) - [Manual configured MQTT items](https://www.home-assistant.io/integrations/mqtt/#manual-configured-mqtt-items) - [YAML configuration listed per item](https://www.home-assistant.io/integrations/mqtt/#yaml-configuration-listed-per-item) - [YAML configuration keyed and bundled by {domain}](https://www.home-assistant.io/integrations/mqtt/#yaml-configuration-keyed-and-bundled-by-domain) - [Entity state updates](https://www.home-assistant.io/integrations/mqtt/#entity-state-updates) - [The last reported state attribute](https://www.home-assistant.io/integrations/mqtt/#the-last-reported-state-attribute) - [Using Templates](https://www.home-assistant.io/integrations/mqtt/#using-templates) - [Examples](https://www.home-assistant.io/integrations/mqtt/#examples) - [Publish & Dump actions](https://www.home-assistant.io/integrations/mqtt/#publish--dump-actions) - [Action: Publish](https://www.home-assistant.io/integrations/mqtt/#action-publish) - [Action: Dump](https://www.home-assistant.io/integrations/mqtt/#action-dump) - [Logging](https://www.home-assistant.io/integrations/mqtt/#logging) - [Event event\_mqtt\_reloaded](https://www.home-assistant.io/integrations/mqtt/#event-event_mqtt_reloaded) - [Removing the integration](https://www.home-assistant.io/integrations/mqtt/#removing-the-integration) Back to top ![Home Assistant](https://www.home-assistant.io/images/footer-logo-text.svg) Home Assistant is a project from the [Open Home Foundation](https://www.openhomefoundation.org/), sponsored by [Nabu Casa](https://www.nabucasa.com/). ### Join us and contribute\! - [GitHub repo](https://github.com/home-assistant/) - [Developers Portal](https://developers.home-assistant.io/) - [Design Portal](https://design.home-assistant.io/) - [Data Science Portal](https://data.home-assistant.io/) - [Community Forum](https://community.home-assistant.io/) - [Creator Network](https://creators.home-assistant.io/) - [Works With Home Assistant](https://works-with.home-assistant.io/) - [Our community](https://www.home-assistant.io/community) - [Reporting issues](https://www.home-assistant.io/help/reporting_issues/) ### System status - [Integration Alerts](https://alerts.home-assistant.io/) - [Security Alerts](https://www.home-assistant.io/security/) - [System Status](https://status.home-assistant.io/) ### Companion apps - [iOS and Apple devices](https://apps.apple.com/app/id1099568401) - [Android and Wear OS](https://play.google.com/store/apps/details?id=io.homeassistant.companion.android) - [...and more\!](https://companion.home-assistant.io/) ### Support us - [Merch store](https://store.openhomefoundation.org/) - [Home Assistant Cloud](https://www.home-assistant.io/cloud/) ### Governance - [Privacy Notices](https://www.home-assistant.io/privacy/) - [Contributor License Agreement](https://www.home-assistant.io/developers/cla/) - [Terms of Service](https://www.home-assistant.io/tos/) - [Code of Conduct](https://www.home-assistant.io/code_of_conduct/) - [Credits](https://www.home-assistant.io/developers/credits/) - [License](https://www.home-assistant.io/developers/license/) ### Follow us [Sign up for our newsletter](https://newsletter.openhomefoundation.org/#/portal) For partnership inquiries please check out [Works With Home Assistant](https://works-with.home-assistant.io/). For media, [email our team](mailto:media@openhomefoundation.org). For other questions, you can [contact support](mailto:hello@home-assistant.io) (No technical support!) Website powered by [Jekyll](https://jekyllrb.com/) Originally based on the [Oscailte theme](https://github.com/coogie/oscailte) [![Deploys by Netlify Badge](https://www.home-assistant.io/images/frontpage/netlify.svg)](https://www.netlify.com/)
Readable Markdown	MQTT (aka MQ Telemetry Transport) is a machine-to-machine or “Internet of Things” connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport. ## Configuration To add the MQTT service to your Home Assistant instance, use this My button: [![](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start?domain=mqtt) Manual configuration steps If the above My button doesn’t work, you can also perform the following steps manually: - Browse to your Home Assistant instance. - Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). - In the bottom right corner, select the [Add Integration](https://my.home-assistant.io/redirect/config_flow_start?domain=mqtt) button. - From the list, select MQTT. - Follow the instructions on screen to complete the setup. MQTT devices and entities can be set up through [MQTT discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) or [added manually](https://www.home-assistant.io/integrations/mqtt/#manual-configured-mqtt-items) via YAML or subentries. Configuration of MQTT components via MQTT discovery Configuration of MQTT components via YAML Your first step to get MQTT and Home Assistant working is to choose a broker. The easiest option is to install the official Mosquitto Broker app for Home Assistant (formerly known as Mosquitto Broker add-on). You can choose to set up and configure this app automatically when you set up the MQTT integration. Home Assistant will automatically generate and assign a safe username and password, and no further attention is required. This also works if you have already set up this app yourself in advance. You can set up additional logins for your MQTT devices and services using the [Mosquitto app configuration](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_mosquitto). Important When MQTT is set up with the official Mosquitto MQTT broker app, the broker’s credentials are generated and kept secret. If the official Mosquitto MQTT broker needs to be re-installed, make sure you save a copy of the app user options, like the additional logins. After re-installing the app, the MQTT integration will automatically update the new password for the re-installed broker. It will then reconnect automatically. Alternatively, you can use a different MQTT broker that you configure yourself, ensuring it is compatible with Home Assistant. ## Setting up a broker While public MQTT brokers are available, the easiest and most private option is running your own. The recommended setup method is to use the [Mosquitto MQTT broker app](https://github.com/home-assistant/hassio-addons/blob/master/mosquitto/DOCS.md). Warning Neither ActiveMQ MQTT broker nor the RabbitMQ MQTT Plugin are supported, use a known working broker like Mosquitto instead. There are [at least two](https://issues.apache.org/jira/browse/AMQ-6360) [issues](https://issues.apache.org/jira/browse/AMQ-6575) with the ActiveMQ MQTT broker which break MQTT message retention. ## Broker configuration MQTT broker settings are configured when the MQTT integration is first set up and can be changed later if needed. Add the MQTT integration, then provide your broker’s hostname (or IP address) and port and (if required) the username and password that Home Assistant should use. To change the settings later, follow these steps: 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). 2. Select the MQTT integration. 3. Reconfigure the MQTT broker settings via [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations), select , and select Reconfigure. MQTT subentries can also be reconfigured. Additional entities can be added, or an entity can be removed from the sub entry. Each MQTT subentry holds one MQTT device. The MQTT device must have at least one entity. Important If you experience an error message like `Failed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed`, then turn on `Advanced options` and set [Broker certificate validation](https://www.home-assistant.io/integrations/mqtt/#broker-certificate-validation) to `Auto`. ### Advanced broker configuration Advanced broker configuration options include setting a custom client ID, setting a client certificate and key for authentication, and enabling TLS validation of the broker’s certificate for secure connection. To access the advanced settings, open the MQTT broker settings, switch on Advanced options, and select Next. The advanced options will be shown by default if there are advanced settings active already. Tip Advanced broker options are accessible only when advanced mode is enabled (see user settings), or when advanced broker settings are configured already. #### Alternative client ID You can set a custom MQTT client ID, this can help when debugging. Mind that the client ID must be unique. Leave this settings default if you want Home Assistant to generate a unique ID. #### Keep alive The time in seconds between sending keep alive messages for this client. The default is 60 seconds. The keep alive setting should be at least 15 seconds. #### Broker certificate validation To enable a secure connection to the broker, the broker certificate should be validated. If your broker uses a trusted certificate, then choose Auto. This validates the broker certificate against the bundled certificate authority (CA) certificates. If a self-signed certificate is used, select Custom. A custom PEM- or DER-encoded CA certificate can be uploaded. Select Next to show the control to upload the CA certificate. If the server certificate does not match the hostname then validation will fail. To allow a connection without the verification of the hostname, turn the Ignore broker certificate validation switch on. #### MQTT Protocol The MQTT protocol setting defaults to version `3.1.1`. If your MQTT broker supports MQTT version 5 you can set the protocol setting to `5`. #### Securing the connection With a secure broker connection, it is possible to use a client certificate for authentication. To set the client certificate and private key, turn on the option Use a client certificate and select Next to reveal file upload controls. A client certificate and the corresponding private key must be uploaded together. Both client certificate and private key must be either PEM- or DER-encoded. If the private key is encrypted with a password, ensure you supply the correct password when uploading the client certificate and key files. #### Using WebSockets as transport You can select `websockets` as the transport method if your MQTT broker supports it. When you select `websockets` and select Next, you will be able to add a WebSockets path (default is `/`) and WebSockets headers (optional). The target WebSockets URI `ws://{broker}:{port}{ws_path}` is built with the `broker`, `port`, and `ws_path` (WebSocket path) settings. To configure the WebSocket’s headers, supply a valid JSON dictionary string. For example, `{ "Authorization": "token" , "x-header": "some header"}`. The default transport method is `tcp`. The WebSockets transport can be secured using TLS and optionally using user credentials or a client certificate. Note A configured client certificate will only be active if broker certificate validation is enabled. ## Configure MQTT options To change the options, follow these steps: 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). 2. Select the MQTT integration. 3. Select Configure, then Re-configure MQTT. 4. To open the MQTT options page, select Next. ### Change MQTT discovery options The MQTT discovery options can be changed by following these steps: 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). 2. Find the MQTT integration and select it. 3. To open the MQTT discovery options page, select the Configure MQTT Options button. ### Discovery options MQTT discovery is enabled by default. Discovery can be turned off. The prefix for the discovery topic (default `homeassistant`) can be changed here as well. See also [MQTT Discovery section](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) ### Birth and last will messages Home Assistant’s MQTT integration supports so-called Birth and Last Will and Testament (LWT) messages. The former is used to send a message after the service has started, and the latter is used to notify other clients about a disconnected client. Note that the LWT message will be sent both in case of a clean disconnect (for example, Home Assistant shutting down) and in case of an unclean disconnect (for example, Home Assistant crashing or losing its network connection). If a disabled entity is enabled and added after 30 seconds, the MQTT integration will be reloaded and will cause all discovered MQTT entities to be unloaded. When MQTT starts up, all existing MQTT devices, entities, tags, and device triggers, will be unavailable until a discovery message is received and processed. A device or service that exposes the MQTT discovery should subscribe to the Birth message and use this as a trigger to send the [discovery payload](https://www.home-assistant.io/integrations/mqtt/#discovery-payload). To avoid high IO loads on the MQTT broker, adding some random delay in sending the discovery payload is recommended. Alternative approaches: - Retaining the [discovery payload](https://www.home-assistant.io/integrations/mqtt/#discovery-payload): This will store the discovery payload at the MQTT broker, and offer it to the MQTT integration as soon as it subscribes for MQTT discovery. When there are a lot of entities, this can cause high IO loads. - Periodically resending the discovery payload: This can cause some delay, or a lot of IO if there are a lot of MQTT discovery messages. By default, Home Assistant sends `online` and `offline` to `homeassistant/status`. MQTT Birth and Last Will messages can be customized or disabled from the UI. To do this, select Configure on the integration page in the UI, then Re-configure MQTT, and then Next. ## Testing your setup The `mosquitto` broker package ships command line tools (often as `-clients` package) to send and receive MQTT messages. For sending test messages to a broker running on `localhost`, you can use [`mosquitto_pub`](https://mosquitto.org/man/mosquitto_pub-1.html), check the example below: ``` mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m "Switch is ON" ``` Bash Another way to send MQTT messages manually is to use the MQTT* integration in the frontend. Select Settings on the left menu, select Devices & services, and select Configure in the Mosquitto broker tile. Enter something similar to the example below into the topic field under Publish a packet and select Publish. 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations). 2. Select the Mosquitto broker integration, then select Configure. 3. Enter something similar to the example below into the topic field under Publish a packet. Select Publish. ``` homeassistant/switch/1/power ``` Bash and in the Payload field ``` ON ``` Bash In the Listen to a topic field, type `#` to see everything, or `homeassistant/switch/#` to just follow a published topic, then select Start listening. The messages should appear similar to the text below: ``` Message 23 received on homeassistant/switch/1/power/stat/POWER at 12:16 PM: ON QoS: 0 - Retain: false Message 22 received on homeassistant/switch/1/power/stat/RESULT at 12:16 PM: { "POWER": "ON" } QoS: 0 - Retain: false ``` Bash For reading all messages sent on the topic `homeassistant` to a broker running on localhost: ``` mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#" ``` Bash ## Naming of MQTT Entities For every configured MQTT entity Home Assistant automatically assigns a unique `entity_id`. If the `unique_id` option is configured, you can change the `entity_id` after creation, and the changes are stored in the Entity Registry. The `entity_id` is generated when an item is loaded the first time. If the `default_entity_id` option is set, then this will be used to generate the `entity_id`. If, for example, we have configured a `sensor`, and we have set `default_entity_id` to `sensor.test`, then Home Assistant will try to assign `sensor.test` as `entity_id`. If `sensor.test` already exists, Home Assistant will append a suffix to make it unique, for example, `sensor.test_2`. This means any MQTT entity which is part of a device will [automatically have its `friendly_name` attribute prefixed with the device name](https://developers.home-assistant.io/docs/core/entity/#has_entity_name-true-mandatory-for-new-integrations) Unnamed `binary_sensor`, `button`, `number`, and `sensor` entities will now be named by their device class instead of being named “MQTT binary sensor” and similar. It’s allowed to set an MQTT entity’s name to `None` (use `null` in YAML) to mark it as the main feature of a device. Note that on each MQTT entity, the `has_entity_name` attribute will be set to `True`. More details [can be found here](https://developers.home-assistant.io/docs/core/entity/#has_entity_name-true-mandatory-for-new-integrations). ## Grouping entities If the MQTT entity represents a group of other entities, the member entities can be made visible in the UI by setting the list of unique IDs of the member entities in the `group` configuration option of the entity group: group A list of unique IDs of the member entities. Set this if the entity represents a group entity. Note that the member entities must be already configured before the member entities will become visible in the UI at the moment a group entity is loaded. ## MQTT Discovery The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](https://www.home-assistant.io/integrations/http/#binary-sensor) and the [HTTP sensor](https://www.home-assistant.io/integrations/http/#sensor). To prevent multiple identical entries if a device reconnects, a unique identifier is necessary. Two parts are required on the device side: The configuration topic, and the device configuration as payload. MQTT discovery is enabled by default, but can be disabled. The prefix for the discovery topic (default `homeassistant`) can be changed. See the [MQTT Options sections](https://www.home-assistant.io/integrations/mqtt/#configure-mqtt-options) Note Documentation on the MQTT components that support MQTT discovery [can be found here](https://www.home-assistant.io/integrations/mqtt/#configuration-via-mqtt-discovery). ### Discovery messages MQTT discovery supports two types of discovery messages: - [Device discovery](https://www.home-assistant.io/integrations/mqtt/#device-discovery-payload), which allows you to include several components in a single discovery message - [Single component discovery](https://www.home-assistant.io/integrations/mqtt/#single-component-discovery-payload), where you publish a separate discovery message for each component If you use a device with multiple components, it is recommended to use MQTT device discovery. It reduces the number of messages sent, and allows you to send the device information only once. #### Discovery topic The discovery topic needs to follow a specific format: ``` <discovery_prefix>/<component>/[<node_id>/]<object_id>/config ``` Text - `<discovery_prefix>`: The Discovery Prefix defaults to `homeassistant` and this prefix can be [changed](https://www.home-assistant.io/integrations/mqtt/#discovery-options). - `<component>`: One of the supported MQTT integrations, for example, `binary_sensor`, or `device` in case of device discovery. - `<node_id>`: (Optional): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. The ID of the node must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen). - `<object_id>`: The ID of the device. This allows for separate topics for each device. The ID of the device must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen). > Note: The `<object_id>` in the topic does not influence the resulting `entity_id`; use `default_entity_id` if you need to control the `entity_id`. The `<node_id>` is optional, and can be used by clients to subscribe to their own (command) topics by using one wildcard topic like `<discovery_prefix>/+/<node_id>/+/set`. Best practice for entities with a `unique_id` is to set `<object_id>` to the `unique_id` and omit the `<node_id>`. #### Device discovery payload A device can send a discovery payload to expose all components for a device. The `<component>` part in the discovery topic must be set to `device`. As an alternative, it is also possible for a device [to send a discovery payload for each component](https://www.home-assistant.io/integrations/mqtt/#single-component-discovery-payload) it wants to set up. The shared options at the root level of the JSON message must include: - `device` mapping (abbreviated as `dev`) - `origin` mapping (abbreviated as `o`) These mappings are mandatory and cannot be overridden at the entity/component level. Supported shared options are: - The `availability` [options](https://www.home-assistant.io/integrations/mqtt/#using-availability-topics). - The `origin` (required) [options](https://www.home-assistant.io/integrations/mqtt/#adding-information-about-the-origin-of-a-discovery-message) - `command_topic` - `state_topic` - `qos` - `encoding` The component specific options are placed as mappings under the `components` key (abbreviated as `cmps`) like: ``` { "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" }, "cmps": { "some_unique_component_id1": { "p": "sensor", "device_class":"temperature", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae_t" }, "some_unique_id2": { "p": "sensor", "device_class":"humidity", "unit_of_measurement":"%", "value_template":"{{ value_json.humidity}}", "unique_id":"temp01ae_h" } }, "state_topic":"sensorBedroom/state", "qos": 2 } ``` JSON Note The components id’s under the `components` (`cmps`) key, are used as part of the discovery identification. A `platform` (`p`) config option is required for each component config that is added to identify the component platform. Also required is a `unique_id` for entity-based components. To remove the components, publish an empty (retained) string payload to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it. An empty config can be published as an update to remove a single component from the device discovery. Note that adding the `platform` (`p`) option is still required. ``` { "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" }, "cmps": { "some_unique_component_id1": { "p": "sensor", "device_class":"temperature", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae_t" }, "some_unique_id2": { "p": "sensor" } }, "state_topic":"sensorBedroom/state", "qos": 2 } ``` JSON This will explicitly remove the humidity sensor and its entry. After removing a component, you should send another update with the removed component omitted from the configuration. This ensures that Home Assistant has the most up-to-date device configuration. For example: ``` { "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" }, "cmps": { "some_unique_component_id1": { "p": "sensor", "device_class":"temperature", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae_t" } }, "state_topic":"sensorBedroom/state", "qos": 2 } ``` JSON A component config part in a device discovery payload must have the `platform` (`p`) option set with the name of the `component` and also must have at least one component specific config option. Entity components must have set the `unique_id` option and have a `device` context. ##### Migration from single component to device discovery To allow a smooth migration from single component discovery to device discovery: 1. Ensure all entities have a `unique_id` and a `device` context. 2. Move the `object_id` inside the discovery payload, if that is available, or use a unique ID or the component. 3. Consider using the previous `node_id` as the new `object_id` of the device discovery topic. 4. Ensure the `unique_id` matches and the `device` context has the correct identifiers. 5. Send the following payload to all existing single component discovery topics: `{"migrate_discovery": true }`. This will unload the discovered item, but its settings will be retained. 6. Switch the discovery topic to the device discovery topic and include all the component configurations. 7. Clean up the single component discovery messages with an empty payload. During the migration steps, INFO messages will be logged to inform you about the progress of the migration. Important Consider testing the migration process in a non-production environment before applying it to a live system. #### Discovery migration example with a device automation and a sensor Step 1: Original single component discovery configurations: Discovery topic single: `homeassistant/device_automation/0AFFD2/bla1/config` Discovery id: `0AFFD2 bla1` (both `0AFFD2` and `bla1` from the discovery topic) Discovery payload single: ``` { "device": { "identifiers": ["0AFFD2"], "name": "Test device" }, "o": { "name": "foobar" }, "automation_type": "trigger", "payload": "short_press", "topic": "foobar/triggers/button1", "type": "button_short_press", "subtype": "button_1" } ``` JSON Discovery topic single: `homeassistant/sensor/0AFFD2/bla2/config` Discovery id: `0AFFD2 bla2` (both `0AFFD2` and `bla2` from the discovery topic) Discovery payload single: ``` { "device": { "identifiers": ["0AFFD2"], "name": "Test device" }, "o": { "name": "foobar" }, "state_topic": "foobar/sensor/sensor1", "unique_id": "bla_sensor001" } ``` JSON Step 2: Initiate migration by publishing to both discovery topics: When these single component discovery payloads are processed, and we want to initiate migration to device discovery, we need to publish … ``` {"migrate_discovery": true } ``` JSON … to both discovery topics … - `homeassistant/device_automation/0AFFD2/bla1/config` - `homeassistant/sensor/0AFFD2/bla2/config` Important Check the logs to ensure this step is executed correctly. Step 3: Publish the new device discovery configuration: Discovery topic device: `homeassistant/device/0AFFD2/config` Discovery id: `0AFFD2 bla` (`0AFFD2`from discovery topic, `bla`: The key under `cmps` in the discovery payload) Discovery payload device: ``` { "device": { "identifiers": [ "0AFFD2" ] }, "o": { "name": "foobar" }, "cmps": { "bla1": { "p": "device_automation", "automation_type": "trigger", "payload": "short_press", "topic": "foobar/triggers/button1", "type": "button_short_press", "subtype": "button_1" }, "bla2": { "p": "sensor", "state_topic": "foobar/sensor/sensor1", "unique_id": "bla_sensor001" } } } ``` JSON Important Check the logs to ensure the migration was successful. Step 4: Clean up after successful migration: After the logs show a successful migration, the single component discovery topics can be cleaned up safely by publishing an empty payload to them. The logs should indicate if the discovery migration was successful. Optional: Rolling back the migration: To rollback publish … ``` {"migrate_discovery": true } ``` JSON To the device discovery topic(s). After that, re-publish the single component discovery payloads. At last, clean up the device discovery payloads by publishing an empty payload. Check the logs for every step. #### Single component discovery payload When using single component discovery messages, the `<component>` part in the discovery topic must be one of the supported MQTT platforms. The options in the payload are only used to set up one specific component. If a device contains multiple components, it is recommended to use [device discovery](https://www.home-assistant.io/integrations/mqtt/#device-discovery-payload) instead. MQTT entities can share device configuration, meaning one entity can include the full device configuration and other entities can link to that device by only setting mandatory fields. Important The mandatory fields were previously limited to at least one of `connection` and `identifiers`, but have now been extended to at least one of `connection` and `identifiers` as well as the `name`. Example discovery payload: ``` { "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" }, "device_class":"temperature", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae_t", "state_topic":"sensorBedroom/state", "qos": 2 } ``` JSON To remove the component, publish an empty string to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it. For more examples [see](https://www.home-assistant.io/integrations/mqtt/#discovery-examples-with-component-discovery). #### Discovery payload The payload must be a serialized JSON dictionary and will be checked like an entry in your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file if a new device is added, with the exception that unknown configuration keys are allowed but ignored. This means that missing variables will be filled with the integration’s default values. All configuration variables which are required must be present in the payload. The reason for allowing unknown documentation keys is allow some backwards compatibility, software generating MQTT discovery messages can then be used with older Home Assistant versions which will simply ignore new features. A discovery payload can be sent with a retain flag set. In that case, the discovery message will be stored at the MQTT broker and processed automatically when the MQTT integrations start. This method removes the need for it to be resent. A better approach, though, is for the software generating MQTT discovery messages to send discovery payload(s) when the MQTT integration sends the [Birth message](https://www.home-assistant.io/integrations/mqtt/#birth-and-last-will-messages). Subsequent messages on a topic where a valid payload has been received will be handled as a configuration update, and a configuration update with an empty payload will cause a previously discovered device to be deleted. A base topic `~` may be defined in the payload to conserve memory when the same topic base is used multiple times. In the value of configuration variables ending with `_topic`, `~` will be replaced with the base topic, if the `~` occurs at the beginning or end of the value. Configuration variable names in the discovery payload may be abbreviated to conserve memory when sending a discovery message from memory constrained devices. It is recommended to add information about the origin of MQTT entities by including the `origin` option (abbreviated as `o`) in the discovery payload. For device discovery, this information is required. The origin details will be logged in the core event log when an item is discovered or updated. Adding origin information helps with troubleshooting and provides valuable context about the source of MQTT messages in your Home Assistant setup. Note: These options also support abbreviations, as shown in the table below. name The name of the application that is the origin of the discovered MQTT item. (Required) sw\_version Software version of the application that supplies the discovered MQTT item. support\_url Support URL of the application that supplies the discovered MQTT item. #### Supported abbreviations in MQTT discovery messages Supported abbreviations ``` 'act_t': 'action_topic', 'act_tpl': 'action_template', 'atype': 'automation_type', 'aux_cmd_t': 'aux_command_topic', 'aux_stat_t': 'aux_state_topic', 'aux_stat_tpl': 'aux_state_template', 'av_tones': 'available_tones', 'avty': 'availability', 'avty_mode': 'availability_mode', 'avty_t': 'availability_topic', 'avty_tpl': 'availability_template', 'away_mode_cmd_t': 'away_mode_command_topic', 'away_mode_stat_t': 'away_mode_state_topic', 'away_mode_stat_tpl': 'away_mode_state_template', 'b_tpl': 'blue_template', 'bri_cmd_t': 'brightness_command_topic', 'bri_cmd_tpl': 'brightness_command_template', 'bri_scl': 'brightness_scale', 'bri_stat_t': 'brightness_state_topic', 'bri_tpl': 'brightness_template', 'bri_val_tpl': 'brightness_value_template', 'clr_temp_cmd_tpl': 'color_temp_command_template', 'clr_temp_cmd_t': 'color_temp_command_topic', 'clr_temp_k': 'color_temp_kelvin', 'clr_temp_stat_t': 'color_temp_state_topic', 'clr_temp_tpl': 'color_temp_template', 'clr_temp_val_tpl': 'color_temp_value_template', 'clrm_stat_t': 'color_mode_state_topic', 'clrm_val_tpl': 'color_mode_value_template', 'cmd_off_tpl': 'command_off_template', 'cmd_on_tpl': 'command_on_template', 'cmd_t': 'command_topic', 'cmd_tpl': 'command_template', 'cmps': 'components', 'cod_arm_req': 'code_arm_required', 'cod_dis_req': 'code_disarm_required', 'cod_trig_req': 'code_trigger_required', 'cont_type': 'content_type', 'curr_temp_t': 'current_temperature_topic', 'curr_temp_tpl': 'current_temperature_template', 'def_ent_id': 'default_entity_id', 'dev': 'device', 'dev_cla': 'device_class', 'dir_cmd_t': 'direction_command_topic', 'dir_cmd_tpl': 'direction_command_template', 'dir_stat_t': 'direction_state_topic', 'dir_val_tpl': 'direction_value_template', 'dsp_prc': 'display_precision', 'e': 'encoding', 'en': 'enabled_by_default', 'ent_cat': 'entity_category', 'ent_pic': 'entity_picture', 'evt_typ': 'event_types', 'exp_aft': 'expire_after', 'fanspd_lst': 'fan_speed_list', 'flsh': 'flash', 'flsh_tlng': 'flash_time_long', 'flsh_tsht': 'flash_time_short', 'fx_cmd_t': 'effect_command_topic', 'fx_cmd_tpl': 'effect_command_template', 'fx_list': 'effect_list', 'fx_stat_t': 'effect_state_topic', 'fx_tpl': 'effect_template', 'fx_val_tpl': 'effect_value_template', 'fan_mode_cmd_t': 'fan_mode_command_topic', 'fan_mode_cmd_tpl': 'fan_mode_command_template', 'fan_mode_stat_t': 'fan_mode_state_topic', 'fan_mode_stat_tpl': 'fan_mode_state_template', 'frc_upd': 'force_update', 'g_tpl': 'green_template', 'grp': 'group', 'hs_cmd_t': 'hs_command_topic', 'hs_cmd_tpl': 'hs_command_template', 'hs_stat_t': 'hs_state_topic', 'hs_val_tpl': 'hs_value_template', 'ic': 'icon', 'img_e': 'image_encoding', 'img_t': 'image_topic', 'init': 'initial', 'hum_cmd_t': 'target_humidity_command_topic', 'hum_cmd_tpl': 'target_humidity_command_template', 'hum_stat_t': 'target_humidity_state_topic', 'hum_state_tpl': 'target_humidity_state_template', 'json_attr': 'json_attributes', 'json_attr_t': 'json_attributes_topic', 'json_attr_tpl': 'json_attributes_template', 'l_ver_t': 'latest_version_topic', 'l_ver_tpl': 'latest_version_template', 'lrst_t': 'last_reset_topic', 'lrst_val_tpl': 'last_reset_value_template', 'max': 'max', 'max_hum': 'max_humidity', 'max_k': 'max_kelvin', 'max_mirs': 'max_mireds', 'max_temp': 'max_temp', 'migr_discvry': 'migrate_discovery', 'min': 'min', 'min_hum': 'min_humidity', 'min_k': 'min_kelvin', 'min_mirs': 'min_mireds', 'min_temp': 'min_temp', 'mode': 'mode', 'mode_cmd_t': 'mode_command_topic', 'mode_cmd_tpl': 'mode_command_template', 'mode_stat_t': 'mode_state_topic', 'mode_stat_tpl': 'mode_state_template', 'modes': 'modes', 'name': 'name', 'o': 'origin', 'off_dly': 'off_delay', 'on_cmd_type': 'on_command_type', 'ops': 'options', 'opt': 'optimistic', 'osc_cmd_t': 'oscillation_command_topic', 'osc_cmd_tpl': 'oscillation_command_template', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', 'p': 'platform', 'pct_cmd_t': 'percentage_command_topic', 'pct_cmd_tpl': 'percentage_command_template', 'pct_stat_t': 'percentage_state_topic', 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', 'pl_arm_away': 'payload_arm_away', 'pl_arm_custom_b': 'payload_arm_custom_bypass', 'pl_arm_home': 'payload_arm_home', 'pl_arm_nite': 'payload_arm_night', 'pl_arm_vacation': 'payload_arm_vacation', 'pl_avail': 'payload_available', 'pl_cln_sp': 'payload_clean_spot', 'pl_cls': 'payload_close', 'pl_dir_fwd': 'payload_direction_forward', 'pl_dir_rev': 'payload_direction_reverse', 'pl_disarm': 'payload_disarm', 'pl_home': 'payload_home', 'pl_inst': 'payload_install', 'pl_loc': 'payload_locate', 'pl_lock': 'payload_lock', 'pl_not_avail': 'payload_not_available', 'pl_not_home': 'payload_not_home', 'pl_off': 'payload_off', 'pl_on': 'payload_on', 'pl_open': 'payload_open', 'pl_osc_off': 'payload_oscillation_off', 'pl_osc_on': 'payload_oscillation_on', 'pl_paus': 'payload_pause', 'pl_prs': 'payload_press', 'pl_ret': 'payload_return_to_base', 'pl_rst': 'payload_reset', 'pl_rst_hum': 'payload_reset_humidity', 'pl_rst_mode': 'payload_reset_mode', 'pl_rst_pct': 'payload_reset_percentage', 'pl_rst_pr_mode': 'payload_reset_preset_mode', 'pl_stop': 'payload_stop', 'pl_stop_tilt': 'payload_stop_tilt', 'pl_stpa': 'payload_start_pause', 'pl_strt': 'payload_start', 'pl_toff': 'payload_turn_off', 'pl_ton': 'payload_turn_on', 'pl_trig': 'payload_trigger', 'pl_unlk': 'payload_unlock', 'pos': 'reports_position', 'pos_clsd': 'position_closed', 'pos_open': 'position_open', 'pr_mode_cmd_t': 'preset_mode_command_topic', 'pr_mode_cmd_tpl': 'preset_mode_command_template', 'pr_mode_stat_t': 'preset_mode_state_topic', 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', 'ptrn': 'pattern', 'r_tpl': 'red_template', 'rel_s': 'release_summary', 'rel_u': 'release_url', 'ret': 'retain', 'rgb_cmd_t': 'rgb_command_topic', 'rgb_cmd_tpl': 'rgb_command_template', 'rgb_stat_t': 'rgb_state_topic', 'rgb_val_tpl': 'rgb_value_template', 'rgbw_cmd_t': 'rgbw_command_topic', 'rgbw_cmd_tpl': 'rgbw_command_template', 'rgbw_stat_t': 'rgbw_state_topic', 'rgbw_val_tpl': 'rgbw_value_template', 'rgbww_cmd_t': 'rgbww_command_topic', 'rgbww_cmd_tpl': 'rgbww_command_template', 'rgbww_stat_t': 'rgbww_state_topic', 'rgbww_val_tpl': 'rgbww_value_template', 'send_cmd_t': 'send_command_topic', 'send_if_off': 'send_if_off', 'set_fan_spd_t': 'set_fan_speed_topic', 'set_pos_t': 'set_position_topic', 'set_pos_tpl': 'set_position_template', 'pos_t': 'position_topic', 'pos_tpl': 'position_template', 'spd_rng_min': 'speed_range_min', 'spd_rng_max': 'speed_range_max', 'src_type': 'source_type', 'stat_cla': 'state_class', 'stat_closing': 'state_closing', 'stat_clsd': 'state_closed', 'stat_jam': 'state_jammed', 'stat_locked': 'state_locked', 'stat_locking': 'state_locking', 'stat_off': 'state_off', 'stat_on': 'state_on', 'stat_open': 'state_open', 'stat_opening': 'state_opening', 'stat_stopped': 'state_stopped', 'stat_unlocked': 'state_unlocked', 'stat_unlocking': 'state_unlocking', 'stat_t': 'state_topic', 'stat_tpl': 'state_template', 'stat_val_tpl': 'state_value_template', 'step': 'step', 'stype': 'subtype', 'sug_dsp_prc': 'suggested_display_precision', 'sup_clrm': 'supported_color_modes', 'sup_dur': 'support_duration', 'sup_vol': 'support_volume_set', 'sup_feat': 'supported_features', 'swing_mode_cmd_t': 'swing_mode_command_topic', 'swing_mode_cmd_tpl': 'swing_mode_command_template', 'swing_mode_stat_t': 'swing_mode_state_topic', 'swing_mode_stat_tpl': 'swing_mode_state_template', 't': 'topic', 'temp_cmd_t': 'temperature_command_topic', 'temp_cmd_tpl': 'temperature_command_template', 'temp_hi_cmd_t': 'temperature_high_command_topic', 'temp_hi_cmd_tpl': 'temperature_high_command_template', 'temp_hi_stat_t': 'temperature_high_state_topic', 'temp_hi_stat_tpl': 'temperature_high_state_template', 'temp_lo_cmd_t': 'temperature_low_command_topic', 'temp_lo_cmd_tpl': 'temperature_low_command_template', 'temp_lo_stat_t': 'temperature_low_state_topic', 'temp_lo_stat_tpl': 'temperature_low_state_template', 'temp_stat_t': 'temperature_state_topic', 'temp_stat_tpl': 'temperature_state_template', 'temp_unit': 'temperature_unit', 'tilt_clsd_val': 'tilt_closed_value', 'tilt_cmd_t': 'tilt_command_topic', 'tilt_cmd_tpl': 'tilt_command_template', 'tilt_max': 'tilt_max', 'tilt_min': 'tilt_min', 'tilt_opnd_val': 'tilt_opened_value', 'tilt_opt': 'tilt_optimistic', 'tilt_status_t': 'tilt_status_topic', 'tilt_status_tpl': 'tilt_status_template', 'tit': 'title', 'trns': 'transition', 'uniq_id': 'unique_id', 'unit_of_meas': 'unit_of_measurement', 'url_t': 'url_topic', 'url_tpl': 'url_template', 'val_tpl': 'value_template', 'whit_cmd_t': 'white_command_topic', 'whit_scl': 'white_scale', 'xy_cmd_t': 'xy_command_topic', 'xy_cmd_tpl': 'xy_command_template', 'xy_stat_t': 'xy_state_topic', 'xy_val_tpl': 'xy_value_template', ``` Txt Supported abbreviations for device registry configuration ``` 'cu': 'configuration_url', 'cns': 'connections', 'ids': 'identifiers', 'name': 'name', 'mf': 'manufacturer', 'mdl': 'model', 'mdl_id': 'model_id', 'hw': 'hw_version', 'sw': 'sw_version', 'sa': 'suggested_area', 'sn': 'serial_number', ``` Txt Supported abbreviations for origin info ``` 'name': 'name', 'sw': 'sw_version', 'url': 'support_url', ``` Txt ### Discovery messages and availability When MQTT discovery is set up, and a device or service sends a discovery message, an MQTT entity, tag, or device automation will be set up directly after receiving the message. When Home Assistant is restarting, discovered MQTT items with a unique ID will be unavailable until a new discovery message is received. MQTT items without a unique ID will not be added at startup. So a device or service using MQTT discovery must make sure a configuration message is offered after the MQTT integration has been (re)started. There are two common approaches to make sure the discovered items are set up at startup: 1. Using Birth and Will messages to trigger setup 2. Using retained messages Finally, it is a best practice to publish your device or service availability status. #### Use the Birth and Will messages to trigger discovery When the MQTT integration starts, a birth message is published at `homeassistant/status` by default. A device or service connected to the shared `mqtt` broker can subscribe to this topic and use an `online` message to trigger discovery messages. See also the [birth and last will messages](https://www.home-assistant.io/integrations/mqtt/#birth-and-last-will-messages) section. After the configs have been published, the state topics will need an update, so they need to be republished. #### Using retained config messages An alternative method for a device or service is to publish discovery messages with a `retain` flag. This will make sure discovery messages are replayed when the MQTT integration connects to the broker. After the configs have been published, the state topics will need an update. #### Using retained state messages State updates also need to be re-published after a config as been processed. This can also be done by publishing `retained` messages. As soon as a config is received (or replayed from a retained message), the setup will subscribe any state topics. If a retained message is available at a state topic, this message will be replayed so that the state can be restored for this topic. Warning A disadvantage of using retained messages is that these messages retain at the broker, even when the device or service stops working. They are retained even after the system or broker has been restarted. Retained messages can create ghost entities that keep coming back. Especially when you have many entities, (unneeded) discovery messages can cause excessive system load. For this reason, use discovery messages with caution. ### Using Availability topics A device or service can announce its availability by publishing a Birth message and set a Will message at the broker. When the device or service loses connection to the broker, the broker will publish the Will message. This allows the MQTT integration to make an entity unavailable. Platform specific availability settings are available for `mqtt` entity platforms only. Platform specific availability settings #### Configuration Variables availability list (Optional) A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`. payload\_available string (Optional, default: online) The payload that represents the available state. payload\_not\_available string (Optional, default: offline) The payload that represents the unavailable state. topic string Required An MQTT topic subscribed to receive availability (online/offline) updates. value\_template [template](https://www.home-assistant.io/docs/configuration/templating/) (Optional) Defines a [template](https://www.home-assistant.io/docs/templating/where-to-use/#mqtt) to extract a device’s availability from the `topic`. To determine the device’s availability, the result of this template will be compared to `payload_available` and `payload_not_available`. availability\_topic string (Optional) The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. availability\_mode string (Optional, default: latest) When `availability` is configured, this controls the conditions needed to set the entity to `available`. Valid entries are `all`, `any`, and `latest`. If set to `all`, `payload_available` must be received on all configured availability topics before the entity is marked as online. If set to `any`, `payload_available` must be received on at least one configured availability topic before the entity is marked as online. If set to `latest`, the last `payload_available` or `payload_not_available` received on any configured availability topic controls the availability. availability\_template [template](https://www.home-assistant.io/docs/configuration/templating/) (Optional) Defines a [template](https://www.home-assistant.io/docs/templating/where-to-use/#mqtt) to extract device’s availability from the `availability_topic`. To determine the devices’s availability result of this template will be compared to `payload_available` and `payload_not_available`. payload\_available string (Optional, default: online) The payload that represents the available state. payload\_not\_available string (Optional, default: offline) The payload that represents the unavailable state. ### Discovery examples with component discovery #### Motion detection (binary sensor) A motion detection device which can be represented by a [binary sensor](https://www.home-assistant.io/integrations/binary_sensor.mqtt/) for your garden would send its configuration as JSON payload to the Configuration topic. After the first message to `config`, then the MQTT messages sent to the state topic will update the state in Home Assistant. - Configuration topic: `homeassistant/binary_sensor/garden/config` - State topic: `homeassistant/binary_sensor/garden/state` - Configuration payload with derived device name: ``` { "name":null, "device_class":"motion", "state_topic":"homeassistant/binary_sensor/garden/state", "unique_id":"motion01ad", "device":{ "identifiers":[ "01ad" ], "name":"Garden" } } ``` JSON - Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts. It is also a good idea to add a `unique_id` to allow changes to the entity and a `device` mapping so we can group all sensors of a device together. We can set “name” to `null` if we want to inherit the device name for the entity. If we set an entity name, the `friendly_name` will be a combination of the device and entity name. If `name` is left away and a `device_class` is set, the entity name part will be derived from the `device_class`. - Example configuration payload with no name set and derived `device_class` name: ``` { "name":null, "device_class":"motion", "state_topic":"homeassistant/binary_sensor/garden/state", "unique_id":"motion01ad", "device":{ "identifiers":[ "01ad" ], "name":"Garden" } } ``` JSON If no name is set, a default name will be set by MQTT ([see the MQTT platform documentation](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery)). To create a new sensor manually and with the name set to `null` to derive the device name “Garden”: ``` mosquitto_pub -r -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": null, "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state", "unique_id": "motion01ad", "device": {"identifiers": ["01ad"], "name": "Garden" }}' ``` Bash Update the state: ``` mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/state" -m ON ``` Bash Delete the sensor by sending an empty message. ``` mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '' ``` Bash For more details, refer to the [MQTT testing section](https://www.home-assistant.io/integrations/mqtt/#testing-your-setup). #### Sensors Setting up a sensor with multiple measurement values requires multiple consecutive configuration topic submissions. - Configuration topic no1: `homeassistant/sensor/sensorBedroomT/config` - Configuration payload no1: ``` { "device_class":"temperature", "state_topic":"homeassistant/sensor/sensorBedroom/state", "unit_of_measurement":"°C", "value_template":"{{ value_json.temperature}}", "unique_id":"temp01ae", "device":{ "identifiers":[ "bedroom01ae" ], "name":"Bedroom", "manufacturer": "Example sensors Ltd.", "model": "Example Sensor", "model_id": "K9", "serial_number": "12AE3010545", "hw_version": "1.01a", "sw_version": "2024.1.0", "configuration_url": "<https://example.com/sensor_portal/config>" } } ``` JSON - Configuration topic no2: `homeassistant/sensor/sensorBedroomH/config` - Configuration payload no2: ``` { "device_class":"humidity", "state_topic":"homeassistant/sensor/sensorBedroom/state", "unit_of_measurement":"%", "value_template":"{{ value_json.humidity}}", "unique_id":"hum01ae", "device":{ "identifiers":[ "bedroom01ae" ] } } ``` JSON The sensor [`identifiers` or `connections`](https://www.home-assistant.io/integrations/sensor.mqtt/#device) option allows to set up multiple entities that share the same device. Note If a device configuration is shared, then it is not needed to add all device details to the other entity configs. It is enough to add shared identifiers or connections to the device mapping for the other entity config payloads. A common state payload that can be parsed with the `value_template` in the sensor configs: ``` { "temperature":23.20, "humidity":43.70 } ``` JSON #### Entities with command topics Setting up a light or switch is similar but requires a `command_topic` as mentioned in the [MQTT switch documentation](https://www.home-assistant.io/integrations/switch.mqtt/). - Configuration topic: `homeassistant/switch/irrigation/config` - State topic: `homeassistant/switch/irrigation/state` - Command topic: `homeassistant/switch/irrigation/set` - Payload: ``` { "name":"Irrigation", "command_topic":"homeassistant/switch/irrigation/set", "state_topic":"homeassistant/switch/irrigation/state", "unique_id":"irr01ad", "device":{ "identifiers":[ "garden01ad" ], "name":"Garden" } } ``` JSON - Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts. ``` mosquitto_pub -r -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/config" \ -m '{"name": "Irrigation", "command_topic": "homeassistant/switch/irrigation/set", "state_topic": "homeassistant/switch/irrigation/state", "unique_id": "irr01ad", "device": {"identifiers": ["garden01ad"], "name": "Garden" }}' ``` Bash Set the state: ``` mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/set" -m ON ``` Bash #### Using abbreviations and base topic Setting up a switch using topic prefix and abbreviated configuration variable names to reduce payload length. - Configuration topic: `homeassistant/switch/irrigation/config` - Command topic: `homeassistant/switch/irrigation/set` - State topic: `homeassistant/switch/irrigation/state` - Configuration payload: ``` { "~":"homeassistant/switch/irrigation", "name":"garden", "cmd_t":"~/set", "stat_t":"~/state" } ``` JSON Note #### Another example using abbreviations topic name and base topic Setting up a [light that takes JSON payloads](https://www.home-assistant.io/integrations/light.mqtt/#json-schema), with abbreviated configuration variable names: - Configuration topic: `homeassistant/light/kitchen/config` - Command topic: `homeassistant/light/kitchen/set` - State topic: `homeassistant/light/kitchen/state` - Example state payload: `{"state": "ON", "brightness": 255}` - Configuration payload: ``` { "~": "homeassistant/light/kitchen", "name": "Kitchen", "uniq_id": "kitchen_light", "cmd_t": "~/set", "stat_t": "~/state", "schema": "json", "brightness": true } ``` JSON #### Example with using abbreviated Device and Origin info in discovery messages ``` { "~": "homeassistant/light/kitchen", "name": null, "uniq_id": "kitchen_light", "cmd_t": "~/set", "stat_t": "~/state", "schema": "json", "dev": { "ids": "ea334450945afc", "name": "Kitchen", "mf": "Bla electronics", "mdl": "xya", "mdl_id": "ABC123", "sw": "1.0", "sn": "ea334450945afc", "hw": "1.0rev2" }, "o": { "name":"bla2mqtt", "sw": "2.1", "url": "<https://bla2mqtt.example.com/support>" } } ``` JSON ### Support by third-party tools The following software has built-in support for MQTT discovery: - [anpr2mqtt](https://anpr2mqtt.rhizomatics.org.uk/) - [ArduinoHA](https://github.com/dawidchyrzynski/arduino-home-assistant) - [Arilux AL-LC0X LED controllers](https://github.com/smrtnt/Arilux_AL-LC0X) - [ble2mqtt](https://github.com/devbis/ble2mqtt) - [diematic\_server](https://github.com/IgnacioHR/diematic_server) - [digitalstrom-mqtt](https://github.com/gaetancollaud/digitalstrom-mqtt) - [ebusd](https://github.com/john30/ebusd) - [ecowitt2mqtt](https://github.com/bachya/ecowitt2mqtt) - [EMS-ESP32 (and EMS-ESP)](https://github.com/emsesp/EMS-ESP32) - [ESPHome](https://esphome.io/) - [ESPurna](https://github.com/xoseperez/espurna) - [go-iotdevice](https://github.com/koestler/go-iotdevice) - [HASS.Agent](https://github.com/LAB02-Research/HASS.Agent) - [IOTLink](https://iotlink.gitlab.io/) (starting with 2.0.0) - [MiFlora MQTT Daemon](https://github.com/ThomDietrich/miflora-mqtt-daemon) - [MyElectricalData](https://github.com/MyElectricalData/myelectricaldata_import#english) - [MqDockerUp](https://github.com/MichelFR/MqDockerUp) - [Nuki Hub](https://github.com/technyon/nuki_hub) - [Nuki Smart Lock 3.0 Pro](https://support.nuki.io/hc/articles/12947926779409-MQTT-support), [more info](https://developer.nuki.io/t/mqtt-api-specification-v1-3/17626) - [OpenMQTTGateway](https://github.com/1technophile/OpenMQTTGateway) - [OTGateway](https://github.com/Laxilef/OTGateway) - [rethink](https://github.com/anszom/rethink) - [room-assistant](https://github.com/mKeRix/room-assistant) (starting with 1.1.0) - [SmartHome](https://github.com/roncoa/SmartHome) - [SpeedTest-CLI MQTT](https://github.com/adorobis/speedtest-CLI2mqtt) - [SwitchBot-MQTT-BLE-ESP32](https://github.com/devWaves/SwitchBot-MQTT-BLE-ESP32) - [Tasmota](https://github.com/arendst/Tasmota) (starting with 5.11.1e, development halted) - [TeddyCloud](https://github.com/toniebox-reverse-engineering/teddycloud) - [Teleinfo MQTT](https://fmartinou.github.io/teleinfo2mqtt) (starting with 3.0.0) - [Tydom2MQTT](https://tydom2mqtt.github.io/tydom2mqtt/) - [Updates2MQTT](https://updates2mqtt.rhizomatics.org.uk/) - [What’s up Docker?](https://fmartinou.github.io/whats-up-docker/) (starting with 3.5.0) - [WyzeSense2MQTT](https://github.com/raetha/wyzesense2mqtt) - [Xiaomi DaFang Hacks](https://github.com/EliasKotlyar/Xiaomi-Dafang-Hacks) - [Zehnder Comfoair RS232 MQTT](https://github.com/adorobis/hacomfoairmqtt) - [Zigbee2MQTT](https://github.com/koenkk/zigbee2mqtt) The following software also supports consuming MQTT discovery information that is intended for Home Assistant. Compatibility and features will vary, and not all devices may work. - [Domoticz](https://wiki.domoticz.com/MQTT#Add_hardware_.22MQTT_Auto_Discovery_Client_Gateway.22) - [openHAB](https://www.openhab.org/addons/bindings/mqtt.homeassistant/) ## Manual configured MQTT items Support to allow [adding manual items as a subentry via a config flow](https://www.home-assistant.io/integrations/mqtt/#configuration), is work in progress. Not all entity platforms are supported yet. For most integrations, it is also possible to manually set up MQTT items in `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/). Read more [about configuration in YAML](https://www.home-assistant.io/docs/configuration/yaml). MQTT supports two styles for configuring items in YAML. All configuration items are placed directly under the `mqtt` integration key. Note that you cannot mix these styles. Use the YAML configuration listed per item style when in doubt. ### YAML configuration listed per item This method expects all items to be in a YAML list. Each item has a `{domain}` key and the item config is placed directly under the domain key. This method is considered as best practice. In all the examples we use this format. ``` mqtt: - {domain}: name: "" ... - {domain}: name: "" ... ``` YAML ### YAML configuration keyed and bundled by `{domain}` All items are grouped per `{domain}` and where all configs are listed. ``` mqtt: {domain}: - name: "" ... - name: "" ... ``` YAML If you have a large number of manually configured items, you might want to consider [splitting up the configuration](https://www.home-assistant.io/docs/configuration/splitting_configuration/). ## Entity state updates Entities receive state updates via MQTT subscriptions. The payloads received on the state topics are processed to determine whether there is a significant change. If a change is detected, the entity will be updated. Note that MQTT device payloads often contain information for updating multiple entities that subscribe to the same topics. For example, a light status update might include information about link quality. This data can update a link quality sensor but is not used to update the light itself. MQTT filters out entity state updates when there are no changes. ### The last reported state attribute Because MQTT state updates are often repeated frequently, even when no actual changes exist, it is up to the MQTT subscriber to determine whether a status update was received. If the latest update is missed, it might take some time before the next one arrives. If a retained payload exists at the broker, that value will be replayed first, but it will be an update of a previous last state. MQTT devices often continuously generate numerous state updates. MQTT does not update `last_reported` to avoid impacting system stability unless `force_update` is set. Alternatively, an MQTT sensor can be created to measure the last update. ## Using Templates The MQTT integration supports templating. Read more [about using templates with the MQTT integration](https://www.home-assistant.io/docs/templating/where-to-use/#mqtt). ### Examples #### REST API Using the [REST API](https://developers.home-assistant.io/docs/api/rest/) to send a message to a given topic. #### Automations Use as [`script`](https://www.home-assistant.io/integrations/script/) in automations. ``` automation: alias: "Send me a message when I get home" triggers: - trigger: state entity_id: device_tracker.me to: "home" actions: - action: script.notify_mqtt data: target: "me" message: "I'm home" script: notify_mqtt: sequence: - action: mqtt.publish data: payload: "{{ message }}" topic: "home/{{ target }}" retain: true ``` YAML ## Publish & Dump actions The MQTT integration will register the `mqtt.publish` action, which allows publishing messages to MQTT topics. ### Action: Publish The `mqtt.publish` action publishes a message to an MQTT topic. \| Data attribute \| Optional \| Description \| \|---\|---\|---\| \| `topic` \| no \| Topic to publish payload to. \| \| `payload` \| yes \| Payload to publish. Will publish an empty payload when `payload` is omitted. \| \| `evaluate_payload` \| yes \| If a `bytes` literal in `payload` should be evaluated to publish raw data. (default: false) \| \| `qos` \| yes \| Quality of Service to use. (default: 0) \| \| `retain` \| yes \| If message should have the retain flag set. (default: false) \| Note When `payload` is rendered from [template](https://www.home-assistant.io/docs/templating/where-to-use/#mqtt) in a YAML script or automation, and the template renders to a `bytes` literal, the outgoing MQTT payload will only be sent as `raw` data, if the `evaluate_payload` option flag is set to `true`. ``` topic: homeassistant/light/1/command payload: "ON" ``` YAML ``` topic: homeassistant/light/1/state payload: "{{ states('device_tracker.paulus') }}" ``` YAML ``` topic: "homeassistant/light/{{ states('sensor.light_active') }}/state" payload: "{{ states('device_tracker.paulus') }}" ``` YAML Be aware that `payload` must be a string. If you want to send JSON using the YAML editor then you need to format/escape it properly. Like: ``` topic: homeassistant/light/1/state payload: "{\"Status\":\"off\", \"Data\":\"something\"}" ``` YAML The example below shows how to publish a temperature sensor ‘Bathroom Temperature’. The `device_class` is set, so it is not needed to set the “name” option. The entity will inherit the name from the `device_class` set and also support translations. If you set “name” in the payload the entity name will start with the device name. ``` action: mqtt.publish data: topic: homeassistant/sensor/Acurite-986-1R-51778/config payload: >- {"device_class": "temperature", "unit_of_measurement": "\u00b0C", "value_template": "{{ value \| float }}", "state_topic": "rtl_433/rtl433/devices/Acurite-986/1R/51778/temperature_C", "unique_id": "Acurite-986-1R-51778-T", "device": { "identifiers": "Acurite-986-1R-51778", "name": "Bathroom", "model": "Acurite", "model_id": "986", "manufacturer": "rtl_433" } } ``` YAML Example of how to use `qos` and `retain`: ``` topic: homeassistant/light/1/command payload: "ON" qos: 2 retain: true ``` YAML ### Action: Dump The `mqtt.dump` action listens to the specified topic matcher and dumps all received messages within a specific duration into the file `mqtt_dump.txt` in your configuration folder. This is useful when debugging a problem. \| Data attribute \| Optional \| Description \| \|---\|---\|---\| \| `topic` \| no \| Topic to dump. Can contain a wildcard (`#` or `+`). \| \| `duration` \| yes \| Duration in seconds that we will listen for messages. Default is 5 seconds. \| ``` topic: zigbee2mqtt/# ``` YAML ## Logging The [logger](https://www.home-assistant.io/integrations/logger/) integration allows the logging of received MQTT messages. ``` # Example configuration.yaml entry logger: default: warning logs: homeassistant.components.mqtt: debug ``` YAML ## Event `event_mqtt_reloaded` Event `event_mqtt_reloaded` is fired when Manually configured MQTT entities have been reloaded and entities thus might have changed. This event has no additional data. ## Removing the integration 1. Go to [Settings \> Devices & services](https://my.home-assistant.io/redirect/integrations) and select the integration card. 2. From the list of devices, select the integration instance you want to remove. 3. Next to the entry, select the three dots menu. Then, select Delete. Note: This action does not remove the [MQTT broker](https://www.home-assistant.io/integrations/mqtt/#setting-up-a-broker) or its data. If you want to completely remove MQTT: 1. Check your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) and other YAML files for MQTT-related configurations and remove them 2. Review your automations and scripts for any MQTT dependencies 3. Consider backing up your configuration before making these changes #### Help us improve our documentation Suggest an edit to this page, or provide/view feedback for this page. - [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/mqtt.markdown "Edit this page") - [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fintegrations%2Fmqtt%2F&version=2026.4.1&labels=current,integration%3A%20mqtt "Provide feedback on this page") - [View pending feedback](https://github.com/home-assistant/home-assistant.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22integration%3A+mqtt%22 "View pending feedback for this page")
Shard	77 (laksa)
Root Hash	6959518072785130877
Unparsed URL	io,home-assistant!www,/integrations/mqtt/ s443