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

[Peter_Kawa]

→ Nederlandstalige versie → klik hier

→ Tutorial with examples of setting up HA from scratch, extended with zwave as example → click me

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

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.

• Also I have added the optional “How to install the HACS store”

For a first impression:

• The installed HA devices in Homey
  

  

• A selection of Homey devices in HA
  

  
  
  .

• • In the device overview, you can see that these devices are present @ HA via the MQTT integration:
    
    

Run the following on Homey:

- MQTT Hub app

Click here

• Install this app:
  https://homey.app/a/nl.hdg.mqtt/
  https://community.homey.app/t/app-pro-mqtt-hub-community-version/113463

• Configuration:
  On the mobile app, go to …More → Apps → MQTT Hub → Cogwheel → App Settings
  Copy the settings from the screen as shown below, and save.

• • For the Pro 2023: in the bottom field “Performance”, set a message delay, in order to avoid app crashes

• Click on image for full view
  
  

  

• The ‘Devices’ tab allows you to exclude devices you don’t want in HA. Fewer devices benefit performance and crash sensitivity.

• • CAUTION to immediately remove devices you add to Homey using the Home Assistant Community app from the Devices list. To avoid loops! ((*) as long as new devices are still automatically added to the list)

• Go to tab ‘Log’, and set the level to “Errors and Warnings”, to reduce log size and performance

- MQTT Client app

Click here

Please install this app:
https://homey.app/a/nl.scanno.mqtt/

• 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
• • • The username + password of the MQTT Client as well as the MQTT Broker must be the same
      
      
      

Run the following on HA:

- Mosquitto Broker and MQTT integration

Click here

Install the broker:

• Go to Add-ons
  

  

• Click the blue button [Add-on Store] …
  

  

• … and then search for Mosquitto broker and install this add-on by clicking on it
  

  

• Configuration:

• • Go to the ‘Configuration’ tab at the top
• • → 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
[space][space]password:[space]password

• • • NOTE: This screen on the screenshot unfortunately wouldn’t save my input, but, via YAML (click on the 3 dots at the top right) it succeeded:
      
      

• Click ‘Save’

• Then go to the ‘Information’ tab at the top

• Turn on ‘Start on startup’ in any case

• Click on ‘START’ at the bottom left of the add-on screen
  

  

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:
  

  

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

• • • If not, click ‘Add integration’ at the bottom right and search for ‘mqtt’, click on the found MQTT integration and add it
      
      

• • Choose MQTT without additions
    
    
• • • Copy the data from the screen below;* *
      → username + password is again the same user + password you used for the MQTT Client and Broker.
      
      

• • • Click ‘Next’ and then ‘Finish’

‘Discovered MQTT integration’ continued:

• Click ‘Configure’ to enable MQTT detection if required, and click ‘Save’ in the screen that follows:
  (Translated: Would you like to configure HomeAssistant to connect to the MQTT-Broker which is presented to you by the Mosquitto Broker add-on “Save”)
  

  
  
  

• Click ‘Finish’
  (The screen says ‘Congrats, config created for Mosquitto Broker’ “Finish”)
  

  

• Click ‘Configure’ again to set up MQTT for the MQTT Broker with your own username + password
  

  

• In this screen, click ‘MQTT RECONFIGURE’
  

  

• Change username + password to matching the user + password you used with the MQTT Client and Broker
  

  

• If all went well, your Homey devices are now being loaded
  Example:
  

  

• A sample of my Homey devices in HA
  

  

• Detail of a plant sensor @ HA, coming from Homey
  

  

Run the following on Homey

- Home Assistant Community app

Click here

Finally, install this app on Homey:
https://homey.app/a/io.home-assistant.community/

• 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
      Example:

• Then, choose the desired type (sensor, switch, light etc.) and enter the desired device name in the search field
• Here is an example with a type ‘button’
  
  

- 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

http://mqtt-explorer.com/

• 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:
  

  

• This is what HA sends to Homey:
  

  

- 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 a totally ‘useless’ option: 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

• Read these ‘necessities’
  https://hacs.xyz/docs/setup/prerequisites
• How to download and install:
  https://hacs.xyz/docs/setup/download

Install a community integration

• Go to the HACS
  

  

• … and look for the brand, e.g. ‘shelly’
  

  

Examples

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

[Krielandor]

Hey,
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?

[Peter_Kawa]

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):

[Krielandor]

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’?”

Yes:

[Peter_Kawa]

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

@Krielandor

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

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

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

@Krielandor

where can I find the logs for the MQTT integration?

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:

Logger

[Krielandor]

Hi Peter, sorry took me a bit.

@Peter_Kawa

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

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?

@Peter_Kawa

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

You mean the Screenshot under the section:

@Peter_Kawa

Run the following on Homey:

- MQTT Hub app

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

@Peter_Kawa

Are you sure you entered the same credentials as you did for MQTT Broker and -Client?

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?

[Krielandor]

News…
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

[Peter_Kawa]

Hello Uwe,

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

@Peter_Kawa

Are you sure you entered the same credentials as you did for MQTT Broker and -Client?

@Krielandor

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

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.

@Krielandor

the MQTT Hub app. I did install the test-version by following your link, that was correct, right?

Correct, I use that version as well.

@Krielandor

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

I can’t see any issues

@Krielandor

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 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…

[Krielandor]

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…

[John_Lykke_Nielsen]

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.

BR,

John

[Peter_Kawa]

Nice to hear! Much appreciated.

@John_Lykke_Nielsen

What is this “HA On-Offline”?

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!

[Daniel_Cruz]

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.

[Peter_Kawa]

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

[Walter_H]

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.

[Peter_Kawa]

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

[Mikael]

@Peter_Kawa

Mosquitto Broker

Solved:
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”
}
]

[Peter_Kawa]

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

[Mikael]

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?

[RonnyW]

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.

[Mikael]

Thanks will try that