WTH Why is it so hard to set up the MQTT add-on?

[kbuck]

I’m a fairly new user, but also technically proficient - but this situation left me feeling pretty foolish.

I set up the MQTT add-on and tried to connect my other service to it, but couldn’t locate the password anywhere. In the integration entry in “Devices & services” (the usual one-stop shop for things like this), it has a temptingly-named “password” field, which sent me down a long/incorrect path for trying to figure out the default MQTT password. Finally, after occasionally coming back to try to figure this out this several times over a couple weeks, I chanced upon the addon page for MQTT and finally noticed the documentation tab at the bottom, which finally lays out this process for setting something up to use MQTT:

1. Enable advanced mode so you can add users.
2. Add a user for use with MQTT.
3. Use the credentials that you just set up to configure the MQTT client.

Off the top of my head, there are a lot of things that could be improved here. Here are some options:

1. It seems crazy that using this add-on means you must enable advanced mode (so that you can add users).
2. The documentation for this process can only be found on the add-on page, not in devices & services. In retrospect, that’s probably because the add-on is setting up a generic MQTT service, but that wasn’t obvious at the time.
3. Along the way, there are many other pieces of documentation that can be found that don’t mention anything about advanced mode or user creation, such as the MQTT integration documentation. (I also realize in retrospect that I should’ve been reading the add-on documentation, not the integration documentation. But perhaps links could be added to both to direct wayward users to the correct docs?)
4. Creating a HA user just to connect something else to MQTT seems really weird in general. I’d rather have a separate set of MQTT-specific users. The HA user creation process left me wondering whether leaked MQTT credentials could give someone access to my entire HA instance. I created a local login-only user for the purpose, and that seems to work, but the MQTT add-on docs didn’t say to do that, so that also leaves me wondering whether I’ll regret that in the near future.

Overall, the process left me wishing I’d set up MQTT separately rather than using the add-on. The maintenance burden would be higher, but it seems like the entire process would have been much more straightforward and I’d have fewer doubts/worries about the ramifications of using a HA user account.

[potelux]

Duplicate?

WTH Why is it so hard to add an MQTT entity that's not autodiscovered?

I find it hard in Home Assistant to create a device & entities for something which is sending MQTT data. Home Assistant MQTT broker has the entity values. A quick ‘create MQTT entity’ and ‘create MQTT device’ with specifying the topic/prefix would be amazing. Similarly, grouping multiple entities as a ‘virtual device’ for cases like RESTful commands used.

[kbuck]

I don’t think so – this is specifically about setting up the add-on, not adding entities. I actually couldn’t get to the point of adding anything because I couldn’t figure out how to grant access to connect to MQTT…

[OldSurferDude]

I have had similar concerns about documentatioon.
Here some of the responses I’ve gotten:

• Read the documentation
• at the bottom of every documentation page is a box for you to be able to change the page
• volunteers work hard on the documentation, give them a break

I quote:

@123

1. Improve reading skills.
2. Devote time for learning new concepts.
3. Don’t assume previous experience offers advantages.
4. Use search and/or hyperlinks to find related content.

Lastly, to keep in mind that hundreds of thousands of productive users have preceded you and they referenced the same documentation (actually, an older, less comprehensive version).

As you can see, there is no fault with the documentation. Carefully understand 3. What 123 is saying here is that HA uses its own conventions.

As in your case, and my experience, too, the documentation is frustrating because it is incomplete.

So put your suggesting in the feedback part of the of the Help us improve our documentation, hope that someone will read it and improve the page and then gird yourself for your next frustrating adventure into the documentation.

OSD

[123 (Taras)]

@OldSurferDude

Carefully understand 3. What 123 is saying here is that HA uses its own conventions.

Irony alert; that’s not at all what I said (or meant).

[potelux]

Dude… Just vote for the WTH and move on

[procrastinator]

This one gets my vote.

I have a working HA core (stuck on 2024.3.3 which is a whole different WTH). When I set that up I had the choice of setting up an integrated broker or a client. I chose client because I already had a working mosquitto installation. Now there’s 7 different MQTT integrations, WTH are they all? No don’t answer that. I really don’t have the time nor energy to learn. MQTT is very simple, stop making it hard.

Recently I started setting up a HAOS (2024.11.3) as that seems to be the only way to do integration development (Another WTH, do it ‘our’ preferred way or do one).

I do not want this new installation to autodiscover all my devices which should be simple, just change the autodiscovery topic and it’ll find nothing. Then as my integration development proceeds I can port the devices over one at a time by moving/copying them from /homeassistant to /testhomeassistant. Except you can’t do that, even checking the advanced options box you don’t get to set the autodiscovery topic during setup. There’s probably a work around but my enthusiasm has already taken a severe beating from the WTH bat, I don’t have the energy to go down a 4 hour rabbit hole of fruitless searching.