Hubitat Integration

 
The Hubitat-Yggio platform integration is a comprehensive solution that connects the Hubitat home automation platform with the Yggio IoT platform. This integration, applicable for Z-Wave, Zigbee and Matter devices, is built around several key components:

• Connector: Establishes a connection between Hubitat and Yggio's MQTT broker, enabling real-time communication between the two platforms.

• Uplink Data-interpreter: Parses MQTT topics from Hubitat and creates corresponding nodes within Yggio, handling a variety of MQTT topics including device events, heartbeat messages, and initialization messages.

• Downlink: Listens for specific MQTT topics from Yggio that represent commands to be executed on Hubitat devices, providing two-way synchronization between the platforms.

• Device Synchronization: Ensures that any changes in device states on Hubitat are reflected in Yggio, and vice versa, allowing for real-time control and status updates of devices in both systems.

• Heartbeat Handling: Manages heartbeat messages, creating and updating a specific node for each heartbeat message received.

This integration leverages Sensative's Hubitat App and Driver, and provides robust, real-time synchronization between Hubitat and Yggio, enhancing user experience and system performance.

Please note that this guide is divided into two main parts: the Hubitat User Interface and the Yggio User Interface. Both parts are interrelated and necessary to get the integration working.

 

Hubitat User Interface

I. Download and Setup Code Files

In this section, we'll download the necessary code files and open them in a text editor. Here's how you do it:

1. Download the App and Driver code files from the following GitHub repository:

   https://github.com/Sensative/hubitat

   Files to download:

   a. Sensative-Yggio-Hubitat-MQTT-App.groovy
   b. Sensative-Yggio-Hubitat-MQTT-driver.groovy

   Open these files in a text editor of your choice.

II. Install the Driver in Hubitat

In this section, we'll install the driver in Hubitat. The driver is a piece of code that allows Hubitat to communicate with the Yggio platform. Here's how you do it:

1. In the Hubitat User Interface, go to Developer Tools -> Drivers Code on the left.
2. Click the New Driver button in the top right corner.
3. Open the Sensative-Yggio-Hubitat-MQTT-driver.groovy file that you downloaded earlier. Copy and paste the code from this file into the editor in Hubitat, then click Save. The driver will be saved under the name "Sensative Yggio MQTT Driver".

III. Install the App code in Hubitat

In this section, we'll install the app in Hubitat. The app is a piece of code that allows Hubitat to interact with the Yggio platform. Here's how you do it:

1. In the Hubitat User Interface, go to Developer Tools -> Apps Code on the left.
2. Click the New App button in the top right corner.
3. Open the Sensative-Yggio-Hubitat-MQTT-App.groovy file that you downloaded earlier. Copy and paste the code from this file into the editor in Hubitat, then click Save. The app will be saved under the name "Sensative Yggio MQTT App".

IV. Create and Configure the Virtual Device

Important: Before proceeding with this step, ensure you have completed sections VI to XI. The details required in this section are either provided by the Yggio Admin or obtained from the steps in sections VI to XI.

In this section, we'll create a virtual device in Hubitat and configure it to connect to the Yggio platform. Here's how you do it:

1. In the Hubitat User Interface, go to Devices on the left.
2. Click the Add Device button in the top right corner.
3. Click the Virtual button.
4. In the Device Information section, under the Type dropdown, type in "Sensative" to filter drivers.
5. Select Sensative Yggio MQTT Driver.
6. Give the device a memorable name, e.g., "Sensative Hubitat-Yggio App Device".
7. Click Save Device.
8. Enter the following mandatory credential details in the Preferences section:
   • Yggio MQTT Broker IP Address
   • Yggio MQTT Broker Port
   • Yggio MQTT Broker Username
   • Yggio MQTT Broker Password
   • Yggio MQTT Broker Basic Credentials ID
9. Click Save Preferences.
10. If it doesn't connect right away, click the Connect button in the User Interface.

---

---

---

---

V. Setup the Sensative Yggio MQTT App

In this section, we'll set up the app in Hubitat. The app allows Hubitat to interact with the Yggio platform. Here's how you do it:

1. In the Hubitat User Interface, go to Apps on the left.
2. Click the Add user app button in the top right corner.
3. Click on Sensative Yggio MQTT App.
4. The configuration page for Sensative Yggio MQTT App will open.
5. In the configuration page, select the device that you created earlier in the Sensative Yggio MQTT Driver section and click the Update button.
6. Select the devices that you want to connect to the Yggio platform and click the Done button. If you add new devices later and want to sync them with the Yggio platform, revisit this section, select the new devices, and click the Done button.

---

---

---

 

Yggio User Interface

VI. Logging into Yggio

In this section, we'll log into the Yggio platform. Logging in allows you to manage your devices and interact with the platform. Here's how you do it:

1. Navigate to the Yggio login page. The URL should have been provided to you by the Yggio Admin.
2. Enter your credentials in the appropriate fields.
3. Click the "Sign In" button.

---

VII. Starting the Swagger Application for API Communication

In this section, we'll start the Swagger application. Swagger is a tool that helps you communicate with the Yggio platform using its API. Here's how you do it:

1. Once logged into Yggio, navigate to the Swagger application.
2. You should now see the Swagger interface. This is where you can interact with the Yggio API.

---

VIII. Authorizing the Yggio Platform

In this section, we'll make sure that Yggio knows who you are and that you have permission to use it. This is called 'authorizing'. Here's how you do it:

1. Navigate to the Authorization section in the Swagger application page.
2. Click on the POST/auth/local dropdown, then click on the Try it out button.
3. In the Request body section, replace the placeholders marked as "string" with your actual login details. These placeholders are located in the fields labeled "username" and "password".
4. Click the Execute button to complete the authorization.
5. You'll see a token (a long string of letters and numbers) in the response. Select this token and copy it. You'll need it later.
6. Click on the Authorize button and a Available authorizations dialog will pop up.
7. Paste the token in the value field and click the Authorize button.
8. Click Close to close the Available authorizations dialog.

---

Authorization response...

---

---

IX. Create a Basic Set Credentials ID

The next step is to create a Basic Set Credentials ID. This ID is used for authentication and ensuring the integrity of MQTT topics.

1. Navigate to the BasicCredentialsSets section in the Swagger application page.
2. Click on the POST/basic-credentials-sets dropdown, then click on the Try it out button.
3. In the Request body section, replace the placeholders marked as "string" with your Yggio login details or a new set of credentials as per your wish. These placeholders are located in the fields labeled "username" and "password". Make a note of the new credentials as these will be needed for configuring the Yggio MQTT Broker Username and Yggio MQTT Broker Password. For more details on this configuration, refer to the section IV. Create and Configure the Virtual Device.
4. Click the Execute button. This will generate a Basic credentials sets Id.
5. In the Response body section, you will see an _id and your username. Save the _id as you will need it for later steps and for configuring the Yggio MQTT Broker Basic Credentials ID. For more details on this configuration, refer to the section IV. Create and Configure the Virtual Device.

---

BasicCredentialsSets response...

X. Establishing a Reserved MQTT Topic

The next step is to create a reserved MQTT topic. This topic is used as a prefix and comprises of the Yggio - Hubitat integration version and the Basic credentials sets Id created earlier.

1. Navigate to the ReservedMqttTopics section in the Swagger application page.
2. Click on the POST/reserved-mqtt-topics dropdown, then click on the Try it out button.
3. In the Request body section, replace the placeholders marked as "string":
   • For the field labeled "topic", replace the "string" with "yggio/hubitat/v1/<your BasicCredentialsSets _id>" (replace <your BasicCredentialsSets _id> with the actual _id you copied earlier).
   • For the field labeled "basicCredentialsSetId", replace the "string" with your actual BasicCredentialsSets _id that you copied when creating the BasicCredentialsSets Id.
4. Click the Execute button.
5. The Response body section will confirm if the Reserved MQTT Topic is created successfully.

---

ReservedMqttTopics response...

XI. Create a Hubitat Connector

The next step is to create the Hubitat Connector which is the crucial component of the integration.

1. Navigate to the Connectors section in the Swagger application page.
2. Click on the POST/connectors dropdown, then click on the Try it out button.
3. In the Request body section, replace the placeholders marked as "string".
   • For the field labeled "name", replace the "string" with a name of your wish.
   • For the field labeled "integration", replace the "string" with "Hubitat". Make sure the spelling is correct.
   • For the field labeled "basicCredentialsSetId", replace the "string" with your actual BasicCredentialsSets _id that you copied when creating the BasicCredentialsSets Id.
   • For the field labeled "hubId", replace the "string" with the Hub UID.
     Hub UID could be found in Hubitat's user interface settings as shown in the accompanying images below.
   • For the field labeled "topic", replace the "string" with "yggio/hubitat/v1/#".
4. Click the Execute button.
5. The Response body section will confirm if the Connector is created successfully.
6. Save the Connector _id for use in Downlink Communication.
   Note: This step will no longer be necessary once Yggio frontend support is implemented.

---

---

---

Add Connectors response...

XII. Populating Preferences in Hubitat with Credentials

Once you have your credentials from the Yggio Admin or from completing sections VI to IX, you can populate the preferences in Hubitat. This will allow Hubitat to communicate with the Yggio platform. Follow the steps in the Create and Configure the Virtual Device section to do this.

XIII. Claiming IoT Nodes: A Work in Progress

To Be Updated(...Not sure how it was done...Swagger Claim nodes seems to be locked)!

XIV. Yggio Dashboard - Viewing Hubitat Devices

After completing the previous steps and successfully syncing your Hubitat devices with Yggio using MQTT communication, you can view your Hubitat devices on the Yggio dashboard. This provides a convenient way to monitor and control your devices.

The first image below shows the Yggio dashboard with the devices that were synced from the Hubitat hub. The second image provides a detailed view of the data for a virtual Z-Wave switch device, showing the current state of the switch as 'on'.

---

XV. Uplink Communication - Example

Uplink communication refers to the communication from Hubitat to Yggio. An example of this would be a device status update from Hubitat being sent to Yggio.

The two images below illustrate this uplink communication. The first image shows the status update when the 'on' button is clicked on the virtual Z-Wave Switch device in the Hubitat interface. This action is reflected in the same device's data on the Yggio side. The second image shows a similar update when the 'off' button is clicked on the virtual Z-Wave Switch device in the Hubitat interface, and how this change is reflected on the Yggio side.

---

XVI. Downlink Communication - Example

Downlink communication refers to the communication from Yggio to Hubitat. An example of this would be a command from Yggio being sent to a device on Hubitat.

The first two images below illustrate how to retrieve the connector Id from the Connectors section in the Swagger application. This might be necessary if you did not copy it in section XI. Create a Hubitat Connector step 6, or if you have lost the connector Id. To do this, you need to

1. Navigate to the Connectors section in the Swagger application page.

2. Click on the GET/connectors dropdown, then click on the Try it out button.

3. In the Request body section, replace the placeholders marked as "string" with "Hubitat" in the integration field.

4. Click the Execute button.

5. From the Response body section, if successful, copy the Connector _id and save it for sending downlink commands.

6. The image marked '6' shows the current state of the virtual Z-Wave switch device on the Hubitat and Yggio side.
   In the Swagger application, you can set up the downlink command in the PUT/connectors/command section. Here's how:

   • For the field labeled "command", the "string" is replaced with "sendDownLink" command.
   • For the field labeled "integrationName", replace the "string" with "Hubitat".
   • For the field labeled "connectorId", replace the "string" with your actual Connector _id that you copied when creating the Hubitat Connector or following the steps 1 to 5 in this section.
   • For the field labeled "data", add the following JSON.

   "data": {
      "mqttTopic": "dp234/off/set",
      "message": ""
   }

   where "mqttTopic" usually follows the format "[device name]/[command name]/set"

   and "message" is the actual payload you want to send.

   Notes for the payload

   Note 1: For commands that do not require parameters (like 'on' and 'off'), you can publish anything as the value for the /set topic. The Sensative Yggio MQTT App ignores this value.

   Note 2: For commands that require multiple parameters, you should separate each parameter with a comma. For example, '80, 25'.

---

Get Connectors response...

---

The image below shows the current 'off' state of the virtual Z-Wave Switch in both Hubitat and Yggio.

---

Send 'on' state downlink command from the Swagger application.

---

New state - 'on' of the virtual Z-Wave Switch reflected in Hubitat and Yggio.

---

Send 'off' state downlink command from the Swagger application.

---

New state - 'off' of the virtual Z-Wave Switch reflected in Hubitat and Yggio.

In this guide, we have walked you through the process of integrating Hubitat with the Yggio platform using MQTT communication. We started by setting up the MQTT broker and configuring the MQTT Bridge app in Hubitat. We then created a virtual device in Hubitat and configured it to communicate with Yggio.

We also discussed the concepts of uplink and downlink communication, with examples showing how device status updates and commands are sent between Hubitat and Yggio.

By following these steps, you should now have a fully functional integration between Hubitat and Yggio, allowing you to monitor and control your Hubitat devices from the Yggio dashboard.