MQTT to homebridge (HomeKit) for bloody beginners

[chrstnmr]

After investing hours I want to share what I have learnt. I started as a bloody beginner and I aimed to integrate the pump into HomeKit. This is not a complete guide, but it should provide you the cornerstones, you'll need to do it.

What you already have:

• A working WiFi Remote for Bestway Lay Z SPA
• A working homebridge running on a raspberry pi
• This guide uses Homebridge-mqtt.
• If you are looking for one that uses homebridge-mqttthing, check MQTT Homebridge Integration MQTT Homebridge Integration #109 (Thank you @PierreBier)

What you will need

• Install mosquitto homebridge raspberry (+mosquitto clients application)
• Install NodeRed on your homebridge raspberry
• access to your raspberry terminal (via SSH or directly using a monitor + keyboard)
• patience

Mosquitto

1. Mosquitto is a MQTT broker service. Imagine MQTT like a whiteboard in the center of a public town. The Raspberry Pi is holding this whiteboard and every client can write with different topics on it and read the topics of others. What do we want to achieve: The pump and homebridge should be able to leave each other messages on this whiteboard (MQTT), for example a message for turning off the pump.
2. Mosquitto has two conf files. One in the main folder and one in a subfolder "conf". Do not mix those.
3. Mosquitto is not a web-UI, it is just a service running. It uses port 1883 for standard.
4. You should set login credentials
5. Before continuing make sure this is working. Open three terminals. One is running mosquitto (type "mosquitto -v), one is the publishing terminal (it leaves a test message for others: type "mosquitto_pub -h localhost -t “testtopic” -m 'Hello world' "). The third terminal reads out every message regarding a specific topic (type "mosquitto_sub -h localhost -t 'testtopic') If you want to see ALL messages, type in mosquitto_sub -h localhost -t '#'
6. You should now see the messages you just typed

NodeRed

1. NodeRed is a Web UI and service to connect "tasks" and processes
2. Install NodeRed using the guide on the NodeRed main page
3. You can access it by typing the IP of your raspberry adding the port 1880 to it. for example 192.168.178.1:1880
4. Nodered has tabs for each flow. Imagine a flow like a process in which you have a starting point and you define what happens along the way.
5. I copied an existing NodeRed flow from Daniel Kaiser (https://www.youtube.com/watch?v=PCJ1rTOyxtc&t=132s) https://onedrive.live.com/?authkey=%21AGgISMVWbgJfUgE&cid=66B59267A27B0E9D&id=66B59267A27B0E9D%2149176&parId=66B59267A27B0E9D%21114&o=OneUp
6. Copy the text and click "Import" at the menu at the upper right corner.
7. You should see three tabs now. Each tab is doing something different. The tab 1 and tab 2 are defining the process from pump to homebridge and vice versa. Tab 3 is like a "control panel" with which you can add the pump to HomeKit or delete it from HomeKit (it took me hours to understand that. I will come back later to this)
8. Since Daniel Kaisers homebridge is running on hoobs all the IPs of the purple elements are defined to navigate to the hoobs IP. You have to change this. Double click one and select "Server". Add a new one with the IP of your raspberry. If mosquitto is running on the same raspberry as your homebridge simply type in 127.0.0.1 and port 1883.
9. Save it
10. Repeat this for every purple element.
11. Click deploy (make sure mosquitto is running see step 5 above under mosquitto)

WiFi Remote for Bestway Lay-Z-SPA MQTT Settings

In order to connect all these parts, all parties have to speak the same language under the same "topic" in MQTT

1. open your WiFi Remote using the IP of your ESP-device in your pump (see @visualapproach manual in the readme on how to access your pump via browser)
2. Scroll down to MQTT settings
3. enter the raspberry ip (do not use the localhost 127.0.0.1 since it is a different device!)
4. port 1883
5. your username + password you defined in Mosquitto step 4
6. a client ID of your choice (name it)
7. MQTT base topic "dkspamqtt"
8. Check "Enable MQTT" and save
9. If your main page shows that MQTT is not connected, restart the power (probably also mosquitto and your raspberry. It took me hours here, since I had an connection issue. I tried it without any credentials as I skipped setting credentials. It worked after I set credentials in mosquitto and replugged the pump the next day. Not sure what exactly caused it)

Add the device in HomeKit

1. Open Nodered again (see NodeRed step 3)
2. open the flow (tab) "Geräte verwalten"
3. Notice that the blue elements have a clickable element to their left? This is an Injection element. If you click the clickable area it sends a message to the MQTT broker (your "whiteboard").
4. Start with the lowest and add the Pump by clicking on it. Check whether it is now added to your standard room
5. After this step I lost some hours since I could not add the temperature. My homebridge always got stuck and shut down after Injecting the message to add the temperature. I have no idea what did the trick. But I ended up restarting my raspberry, my pump and all the services.
6. I noticed that Daniel's elements "Pumpe hinzufügen" and "Heizung hinzufügen" are the same. I skipped "Heizung hinzufügen" and edited the service_name. Double click the element "Pumpe hinzufügen" and go to "payload", edit the name to "Poolheizung" (You can choose a different name; I had errors as the name already existed in my interface) Update: I ran into some problems the last days when re-setting it up. I ended up to ignore "Heizung hinzufügen" (as mentioned already) but kept the name "Temperatur" as a service name. It will throw an error but after resetting homebridge it works fine.
7. Save it and deploy.
8. Click the clickable area to inject the message of "Pumpe hinzufügen" and "Blubber hinzufügen". (if something goes wrong you can delete them with "Heizung löschen" und "Pumpe löschen" remember that you change the name of "Pumpe hinzufügen" in step 6 which you need to do in this element as well if you want to delete it)
9. Devices should now be in HomeKit

To be honest, it took me hours to get this working and some errors seem to be solved by random.

If you want to debug, I recommend you to open an terminal and subscribe to '#' to read all messages. Adding a device successful responds a message that contains "ack: true".

I am sure that this is not a complete guide, but I hope this will help some people to finde the correct track when doing this project.

[visualapproach]

@chrstnmr awesome, I added a link to this in the FAQ

[chrstnmr]

Btw. can you add a link to the FAQ in the starting page of this GitHub? I think it is mentioned at the very bottom but not hyperlinked.

[visualapproach]

good idea!

[visualapproach]

Done to the dev branch. (I don't want to mess with several branches because it is difficult to merge sometimes)