[TUTORIAL] Setting up MQTT on Homey for configuring Home Assistant for dashboard purposes

Hi, i would like to share instructions of how to setup MQTT on Homey to make your devices visible in Home Assistant with a Synology NAS. Thanks a lot to @HarriedeGroot for creating the MQTT Hub, @scanno for the MQTT Client (and Broker, which unfortunately will not be included in this tutorial since my setup is on a Synology NAS with Mosquitto as a broker) and @Gustav_Tillback for initially sharing the first steps in creating this setup which will be explained in further detail below

I am no developer or wizzard nor do i state this tutorial is the only or best way to configure MQTT for Home Assistant. I’ve bought my Homey 2019 in February 2019 and ran into MQTT on March 18th for the first time in my life. I just practically followed any instruction i could find on the internet as addition on the above mentioned first steps

The following setup consists of apps on Homey and a so called package on Synology NAS.

What do you need?

  • MQTT Client (Homey app)
  • MQTT Hub (Homey app)
  • Docker (Synology package)
  • Mosquitto (Synology package)

Steps in instruction

  1. Install and configure Home Assistant on Synology NAS in Docker (package)
  2. Install and configure a Mosquitto broker (package) on Synology NAS
  3. Install MQTT client app on Homey and configure it to connect to the broker
    MQTT Client for Homey
  4. Install MQTT Hub app on Homey and configure it for Home Assistant discovery
    MQTT Hub
  5. Set up an integration to the broker in Home Assistant configuration

1. Install and configure Home Assistant on Synology NAS in Docker (package)
Instructions how to install and setup Docker under title ‘Synology NAS’ until the Z-wave USB stick part (halfway page)

2. Install and configure a Mosquitto broker (package) on Synology NAS
Instructions how to install Mosquitto
In the video above a fix is shown when Mosquitto isn’t working with the default configuration. I did not ran into the same problem because this issue probably has been solved since this video is from 2017

3. Install MQTT client app on Homey and configure it to connect to the broker
MQTT Client for installation on Homey
Make sure:

  • you fill in the IP address of your Synology NAS and port 1883
  • disable both checkmarks at ‘using a safe connection with broker (TLS)’ and ‘disable certificate check’
    i already can predict a storm of comments because this probably isn’t a safe way to configure but i don’t have any knowledge to do better so please share your thoughts. With TLS enabled it wouldn’t work anyhow
  • you keep alive set at 60 (don’t know why :sweat_smile:)
  • you keep the rest empty since there is a lack of instructions for a noob like me. If you decide to fill in a username and password make sure you use these same credentials in configuration.yaml at step 5
    Again i would be thankful if someone could share how to appropriately apply username and password in the rest of the setup

4. Install MQTT Hub app on Homey and configure it for Home Assistant discovery
MQTT Hub for installation on Homey
Make sure that:

  • Running is ENABLED
  • Broadcast button will be used later on once the config in Home Assistant has been modified to be able to discover this broadcast by the MQTT Hub

5. Set up an integration to the Mosquitto broker in Home Assistant configuration
The following steps are Home Assistant related and needs to be done in the configuration.yaml file, which can be found in the folder which you’ve created in step 1
For example in <your_folder_name>/config

  • open configuration.yaml

  • add the following:

      broker: <please_fill_in_the_IP_address_of_your_Synology_NAS>
      username: myUsername
      password: myPassword
      discovery: true
      discovery_prefix: homeassistant

YAML is very sensitive to spaces - all lines except mqtt: should have two spaces at the beginning
For username and password fill in the same credentials as for the MQTT Client in step 3

  • save your configuration.yaml file
  • restart the Home Assistant container in Docker
    -Open Docker in Synology NAS
    -look for Container and go to homeassist-home-assistant and click on it
    -on the Action button above choose restart
  • Now it is time to open Home Assistant by entering in your browser http://<your_Synology_IP_address>:8123 where you are prompted for a username and password
  • when Home Assistant opens you need to go back to your MQTT Hub on your Homey and press on the Broadcast button

On the upper right corner (3 dots) you can click and search for ‘Unused entities’ which will show you all the devices connected to Homey

Happy configuring your entities in cards, glance etc.
More info about Home Assistant and edit the user interface can be found here

Good luck and greetings from a noob :slightly_smiling_face:


Definately going to try this. Unfortunately I’m running a WD my cloud at home, so don’t know if that one can be used too. Docker is available for it. Don’t know yet if Mosquito can be installed. I read the thread that it also should work without a personal cloud. If someone have any explanations about that, i would love to see some instructions added to the OP.

You literally just have to add your credentials - as below. (you can use !secret MQTTpassword if you wish)
N.B. YAML is very sensitive to spaces - all lines except mqtt: should have two spaces at the beginning. You might want to emphasise that in your tutorial by popping the YAML into a code block

  broker: <please_fill_in_the_IP_address_of_your_Synology_NAS>
  username: myUsername
  password: myPassword
  discovery: true
  discovery_prefix: homeassistant

If you have Docker available then you should be able to install on that as long as the CPU architecture is supported.

1 Like

Told you!

1 Like

I already mentioned that there is an alternative MQTT broker for Homey by the same developer of the MQTT client.

Yes i have that working. Now running the broker, cliënt and hub succesfully at homey. My struggle now is to install HA. I can’t manage to find good instructions on how to install docker + HA on my wd my cloud nas. Thinking about getting the rasp pi 3+. Seems to be alot easier and way more guides.

I have installed everything (i assume) correctly (HA on RPi, MSQTT on Synology), all devices are discovered by HA, but I can’t switch on/off lights or any other command.
Seems to be only one way direction. If I open a door (or something) I can see the contact alarm in HA, so there is communication from Homey to HA.
Something wrongly configured?


When you got a connection and don’t see the devices, press Broadcast in the MQTT Hub app on the Homey.
Then when you open de MQTT on the HA, you will see al the devices.
Remember, when you restart HA, push Broadcast again on de MQTT Hub app.

Do someone else know how to fix ?

TIP: The broadcast will be executed automatically if the HA birth & last will topics are setup correctly.

Bedankt voor de snelle reactie.
Nu nog even kijken hoe ik de kaarten op het dashboard kan verkleinen

If have got exactly the same problem.
I can see all the devices, if i toggle the state in homey i see the change in realtime
But if i trie to change it in HA it does nothing. It sets the state after 3 seconds to the old state.
I hope it is clear.

Broker tried on a Synology and Homey.
Client and hub on Homey.
HA on Synology and Rassberry.

No luck so far.

I find it amazing that this is a topic that is needed. Why can’t Athom get a working integration to Google home working?? Just had a mail about Alexa and homey in my inbox. Is Amazon giving more kickbacks than Google?

Starting the timer to see how fast the Athom moderators catch this one…

1 Like

This topic is a tutorial and tutorials are necessary to share experiences with every community member with better user experience as a result.

As an inexperienced user i am happy to see people share tutorials so i can learn even more. That’s why i wanted to return the favor and wrote down this extensive tutorial, which is mostly build on apps developed by this community and shows the capabilities of Homey despite this setup isn’t one ‘by the book’.

Despite i can understand your frustration your comment is inappropriate since this tutorial has nothing to do with Google Home.

Maybe there is a positive approach which has more added value motivating people to help you out.

Sorry if I offended you in any way. It’s people like you that keep me from throwing the Homey out in the yard for target practice… My point was really that what you have done should be native to Homey and prioritized by the Homey developers rather than wasting time on mobile phone app frontends…

Also, to understand what I’m after, MQTT, seems to be the only way today to get Google assistant to work with Homey unless you are living in the UK. Alexa does not work att all unless you speak the right language…

This is usually an indication that the MQTT broker is only being updated one way. HA should write the updated state back to the ‘set ‘ topic and MQTT Hub should see that, update the device and publish the new state back to ‘onoff’, ‘dim’ or whatever which HA then sees. However it’s not being updated and so in the HA UI it reverts back to the older published state.

You are using latest version of MQTT Hub aren’t you on v2 Homey ?

Either of you got MQTT Explorer installed ?

I’ve got MQTT Client and Hub on Homey. Broker on my Synology NAS (Mosquitto package) and HASS.io.
I have checked the broker options, but there is not much to configure here…

Not installed MQTT explorer indeed (Is this the missing link? to get MQTT Broker to work both ways?)

Nope, MQTT explorer is just a tool to check which messages are being send. It gives some insights on what might be the problem.

Yes, I’m using the latest updates on my homey device. Client and hub.

I also installed Hass.io on a rassberry and installed the broker on the rasberry.
Explorer installed, but i don’t know where to look for.

The only thing i can think of is the Hub is not working well.
It is driving me crazy.

I’ve installed the broker on as a package under hass.io to remove the Synology as possible cause, but unfortunately the same issue with one way communication (in Hass.io seeing everything but unable to manage the home through the Homey from Hass.io)

Don’t know where to continue trouble shooting

(someone is actually having this operational?.. not that we are working on something which is not operational at all :slight_smile: )

Sounds like the hub/client is not correctly subscribed.

  1. Did you try restarting the MQTT Client & hub apps (via app details; see below)?
  2. Did you try rebooting Homey (keep unplugged for >30 sec.)?

Messages travel: HA > broker > client > hub > Homey.
So if rebooting stuff does not resolve the issue, you need to start debugging where the messages stranded.

  1. Broker: Try MQTT Explorer. Do you see incoming messages from HA when you e.g. switch a light.
  2. MQTT Client: try the log in the app settings. Do you see incoming messages?
  3. Hub: Go to the log tab in app settings and set it to debug. Do you see incoming messages? If not, keep it on debug and restart the Hub (via app details). Go back to the log tab. Maybe the full debug boot log of the Hub will give some additional info.

How-to restart an app: apps > select app > details (cog wheel) > restart app.

1 Like