MQTT

Publishing the readings to a broker of your own and choosing between the five message formats.

The MQTT tab publishes the same readings to any broker. It serves anyone feeding a system other than Home Assistant, or anyone who prefers to feed Home Assistant through their own broker.

As with the native integration, the connection goes from your phone straight to your machine, without passing through our servers.

  1. Enter the broker

    Fill in Broker Address and Port. If the broker requires authentication, fill in User and Password as well.

    Turn Use TLS (SSL) on when the broker is exposed outside your network. Use WebSocket and Base Path serve brokers behind a proxy.

  2. Choose the protocol version

    The MQTT 3.1.1 and MQTT 5.0 buttons select the version. When in doubt, choose 3.1.1, which is the more widely compatible.

  3. Choose the format

    MQTT format sets the shape of the topics and the format of each message. There are five options:

    • Home Assistant Discovery: with automatic discovery, the entities are created on their own, with name, unit and icon.
    • Homie 4.0: follows the Homie convention.
    • Simple topics: one value per topic, with no extra structure. The easiest to consume from a script.
    • Unified JSON: everything in a single message, on the topic you set.
    • ThingsBoard: the ThingsBoard telemetry format.

    Some formats have settings of their own, such as JSON payload (value + timestamp) on simple topics and Include timestamp on ThingsBoard.

  4. Set the topic prefix

    Topic Prefix is the root of everything the app publishes. Set the value at the start and avoid changing it later, because the change leaves the old topics orphaned on the broker.

  5. Test before leaving

    Tap Test Connection. The test confirms the address, the port, TLS and the credentials before you turn transmission on.

  6. Turn transmission on and save

    Turn Enable transmission on, set the Transmission interval and save with the floating button.

If something goes wrong

Check in this order: the address and the port, whether the phone is on a network that reaches the broker, whether Use TLS (SSL) matches what the broker expects, and whether the user and password are right.

Port 1883 usually runs without TLS, and 8883 with TLS. Turning TLS on against a port that does not use it produces a failure with no helpful message.

Choose the Home Assistant Discovery format, the only one with automatic discovery. On the other formats, the entities have to be declared by hand.

For Home Assistant, consider the native integration: it is two-way, publishes events on the bus and needs no broker.

The app asks whether you want to clean the topics of the previous format up. If the answer was to keep them, they stay on the broker until they are removed there.

For Home Assistant, the native integration offers more: it is two-way, publishes events on the bus and needs no broker.

MQTT is the right choice when you already run a broker, when you feed a system that is not Home Assistant, or when you need the data in more than one place at once.

← All guidesIn the FAQ: Home Assistant and MQTT →