[TUTORIAL][PRO] How to integrate Home Assistant with Homey

Dutch version → click me

It is not very simple to connect Home Assistant (or HA) with Homey when you are new to it,
hence this comprehensive guide.
You can make it work! (At least I hope so :grin: )

When I forgot something, or something is wrong: feel free to point it out.

By default, all Homey devices are available @ HA after a successful connection using MQTT; BUT you need to install the desired HA devices on Homey, just like other devices need to be installed.

For a first impression:

Run the following on Homey:

- MQTT Hub app

Click here

- MQTT Client app

Click here

Please install this app:

  • Configuration:
    On the mobile app, go to …More → Apps → MQTT Client → Configure app
    Enter your data, like the example data in the settings screen screenshot, and save the settings

Run the following on HA:

- Mosquitto Broker and MQTT integration

Click here

Install the broker:

  • … and then search for Mosquitto broker and install this add-on by clicking on it
    Screenshot from 2023-10-23 22-21-54

  • Configuration:

    • Go to the ‘Configuration’ tab at the top
    • :warning: → Enter the user and password similar to those of MQTT Client, with exactly the same number of spaces as in the screenshot below:

[minus sign][space]username:[space]name

Mosquitto Broker and MQTT Integration

To use the Mosquitto broker, go to the integration page and install/configure the integration:

  • Go to Settings → Devices and Services

  • MQTT should now appear there as a discovered integration:
    Screenshot from 2023-03-13 12-15-26

  • If yes: scroll down until " ‘Discovered MQTT integration’ continued" to continue!

      • Click ‘Next’ and then ‘Finish’

‘Discovered MQTT integration’ continued:

Run the following on Homey

- Home Assistant Community app

Click here

Finally, install this app on Homey:

  • Look up the IP address of your HA installation;
  • Add a new device and choose Home Assistant Community
    • Now (only 1-time needed) enter the IP address as URL (http://x.x.x.x:8123) and the so-called ‘longlived token’
      • The manual to create a token can be found on the app page and/or on the forum topic of this app

- Must have tool: MQTT Explorer

Click here

This tool allows you to see what is or isn’t being sent back and forth in MQTT


  • Configuration example, again use the same user + password as with the MQTT Broker & Client, and use the IP address of HA (which runs the broker)

  • MQTT data impression
    This is what Homey sends to HA:
    screenshot from 2023-03-12 20-44-40

  • This is what HA sends to Homey:
    Screenshot from 2023-03-12 20-43-51

- Useful flows

Click here

Broker offline:

You can e.g. also use this trigger to automatically restart HA f.i.

HA offline or back online

If HA has been offline, or Homey, I always had to manually perform a ‘broadcast’ in the MQTT Hub app, otherwise the Homey devices on HA would no longer work. Also, a notification is sent.

(And totally ‘useless’: I also set an AVD’s (advanced virtual device) status to on/offline . It’s called “HA On-Offline”. Also a variable is updated with the status

- Run the following @ HA

Optional: install HACS store

Click here

HACS = Home Assistant Community Store
There are many nice ‘apps’ in this additional store, but it is not supported by HA

Install a community integration


To give an impression of possibilities

My HACS integrations:

Among others iCalender, HVC waste calendar, variable, Nordpool energy prices etc.

My HACS frontend:

This is mainly for ‘spicing up’ my dashboards


what could I be doing wrong?
It seems I set up everything according to the guide, but the MQTT in HA does not find the Homey devices.
The MQTT explorer:

Seems like homey isn’t sending anything?

Could be an account issue. Enter exactly the same credentials for the mqtt broker & -client
Does the mqtt-explorer homey entry, show ‘status=online’?
What does the mqtt client log show?
Same for the broker log

Example mqtt client log:

Broker log (the entries you see here are normal, they’re not issues):

thank you very much for your reply!

The Mosquitto Log looks exactly the same, I checked the username/password combination…

On Homey I got:
MQTT Client v3.0.0

Above the red line: to be sure I changed the password to something else and as expected authentification failed. I changed it back to the correct password, then the log below the red line was created.

MQTT Hub v3.6.1 (Test)
The logs are very quite…

No errors or something, it just states new devices I added yesterday.

On Home Assistant:

Mosquittos log as mentioned above looks the same as yours, where can I find the logs for the MQTT integration?
If I change the password it instantly fails, so it only continues if I use the correct password.
I didn’t find the second config screen in your guide so I didn’t change anything there:

Thank you so much for your time!

Edit: Sorry, forgot to answer your question:
“Does the mqtt-explorer homey entry, show ‘status=online’?”


No problem, Uwe.
MQTT can be a big PITA to configure right…

OK, so Homey should publish it correct so it seems.
The MQTT ‘Homey status = online’ also indicates it should work.

Just to be sure, did you push the MQTT Hub broadcast button already, this forces the devices to be, well, broadcasted :blush:

Did you apply the custom MQTT Hub “communication protocol” settings, as mentioned with screenshot at the MQTT Hub part of the tutorial?

Good question, this seems to be the part where it goes wrong.
Are you sure you entered the same credentials as you did for MQTT Broker and -Client?

About the logging:
When you open the MQTT integration, hit “ebable debug logging” (make sure to turn it off after a while, bcause it can have a negative impact @ HA performance)

Now after, say, 10 to 15 minutes, disable it again
Now go to Settings > System > Logs
Select “Home Assistant Core” at the top right.
Look for MQTT messages

To enable permanent logging:

Hi Peter, sorry took me a bit.

Yes, I clicked that a few times while debugging, but it seems to have no effect at all.
In the Logfile it states “refresh”, but nothing else happens, there are no new messages or something else in the MQTT explorer, so I guess here lies the problem?

You mean the Screenshot under the section:

Right? Yes, I made sure everything looks the same and double checked it now.

maybe I’m blind and you can point out an error :slight_smile:

Yes, if I change the credentials to something else it immediately fails with an error message that no connection could be estabilished.

within the MQTT Log (after disabling the debugging my browser just prompted me to download the .log file) I can not find anything useful. The only errors are when I tried to enter wrong credentials, otherwise its just full of status updates / payloads from my zigbee devices connected to the HA Pi, nothing about homey.

So, I think the error is on the homey side, especially with the MQTT Hub app. I did install the test-version by following your link, that was correct, right? Or should I switch to the older release version?

I realised that the MQTT Hub switched the “Running” switch off, so I reenganged it. The logfiles only stated switch on and running but nothing else. After reloading the homey app the “Running” switch was off again.

I then had the Idea to exclude the devices which are connected to the HA Pi and brought to homey correctly (2 Motion sensors, 1 Bulb and a Dice). After excluding those devices the “Running” switch stays on and now when I press the Broadcast button the log even outputs new information!


so, yeah, the disabled devices are because I disabled them … but then it states Skip - invalid broadcast followed by HomieDecives initialized: false and MQTT Client registered: undefined?

Mhh… hope you have a bright idea :slight_smile:

Hello Uwe,

Just to be sure, didn’t get a confirmation yet about

I meant the credentials you should have entered with the third place you’ll need to logon, MQTT integration as I showed right below my question.

Don’t know if it’s related to the MQTT Hub issues, but one can’t check too much.

Correct, I use that version as well.

I can’t see any issues

I didn’t encounter that behaviour, so

One idea, but a bit of last resort:
Remove the MQTT Hub app,
Reboot Homey,
and then install it again, and enter the custom communication protocol settings again…

So… the devices are synced to HA now.
No Idea why/ what happened, the only thing I did yesterday was deactivate the devices in MQTT Hub which are connected to HA.
Now, over night, everything seems to have sorted out?
The MQTT Explorer now shows 2414 topics, so very busy…

1 Like

Hello Peter,

Thank you for your instructions above, which I followed and got the MQTT connection working fine.

Now I am working on some flows, and have a question in relation to the flow example you have posted. What is this “HA On-Offline”? Is a special app used to create this, or something else? And how do I replicate this?

Thank you very much.




Nice to hear! Much appreciated.

This is an advanced virtual device by the Device Capabilities app.
It can, for instance, do almost anything with the status indicator.
Prior to Homey app v7.2.0 it could not display text as value.
With this device, it was and is possible.

I’ve updated the info with that flow, thx!

Hello @Peter_Kawa,

First of all thank you a lot for these instructions… It really helped me to configure HA and Homey.

All is working well, but just want to give you a small feedback.

After the point that you can see in the image below (Discovered MQTT integration), I didn’t need to do any more steps… Like for example Reconfigure MQTT.

When I selected the discovered integration all was working and the devices being added from Homey in HA.

Thank you.

Thanks! Much appreciated.

Thanks for noticing.
While HA and it’s add-ons / integrations are ever evolving, things can change in time.

On the other hand, I installed it various times from scratch, sometimes things got configured automatically, sometimes not - no clue why :face_with_hand_over_mouth:

I bought the Homey Pro with insanely high expectations and sadly, it isn’t what all the “Social Media influencers” made it out to be. I since picked up a Home Assistant Blue and love it. I decided I wanted to at least integrate the paper weight, err, Homey Pro with the amazing Home Assistant Blue.

I followed your steps and it wasn’t working. It finally hit me, because I am using Starlink, ports are not open at all, which was causing the actual internal IP address to not be able to link up between the two devices/apps. So I changed all the Homey Pro side to my Tailscale VPN IP address and boom it all worked. Just wanted to put this here for others on ISP’s that block all ports.

1 Like

Hmmmmm I don’t get why you complain about the wrong image you got from Homey at this users forum, Walter, we can’t help you man → I’d suggest to let Athom know what you miss, or what you like to see on a Homey, they don’t read your messages in here. Go to Support | Homey

In the Broker i have tried to save password and user like the giude say but it will not save it also when i try to edit the YAML it don´t save it?

This way it works.
logins: [
“username”: “yourMQTT”,
“password”: “yourMQTTpass”

I have no clue what’s going on, I can only say this still works perfectly fine on my setup:

Core: 2024.4.2
Supervisor: 2024.04.0
Operating System: 12.1
Frontend: 20240404.1
Mosquitto broker: 6.4.0

I was adding a new temp sensor and som other devices to the homey but it dont show up in Home Assistant?
What to do to get the new added devices in Homey over to Home Assistant?

Via MQTT Hub?
The devices are shown in MQTT Hub app settings. But it needs an app restart to do the initiaal device sync.
After restarting the MQTT Hub, new devices should appear in HA.

Thanks will try that :slight_smile: