search

mydevbox / hubitat-mqtt-link

MIT License
26 stars 16 forks source link

readme

Hubitat Elevation MQTT Link

System to share and control Hubitat Elevation device states in MQTT.

MQTT Link is a derivative of MQTT Bridge for Hubitat released by jeubanks who derived it from MQTT Bridge for SmartThings by stjohnjohnson.

Each of the prior MQTT Bridge releases set out to fill a gap in SmartThings and Hubitat as each platform lacked a native MQTT client for which to interface with an MQTT broker. Both releases relied upon a separate, self-hosted nodejs bridge app that ran outside of

the platform and provided both a client to receive MQTT messages and a client to translate those MQTT messages to REST calls which were both platforms offered as integration points.

Since that time the Hubitat platform has introduced an MQTT client capable of interfacing with an MQTT broker without the need for external bridges.

The MQTT Link project builds upon the methods established in the prior works by refactoring the Driver code to utilize the built-in Hubitat MQTT client and to make improvements to the App code.

A big thanks to stjohnjohnson, jeubanks and those to blazed the trails to make this project possible.

MQTT

The MQTT Link apps provide for transit of Hubitat device-specific messages to and from the configured MQTT broker. To remain versatile and lean, no assumptions or impositions were made about the consumers of the published events however, contracts were needed to ensure proper integration with those consumers.

Following are details about the topic format and messages used to communicate to and from the hub devices.

Topics

The MQTT topics apply the following pattern.

Example: hubitat/home-000d/hue-color-lamp-1-738/switch

Messages

Each device has a set of capabilities, attributes and commands that it supports but not every device has support for all three areas. Triggered hub events are converted to a standardized message matching the event that occurred. For example, when light is turned on or off or a door is opened or closed, an MQTT message will be sent to the broker with details about the device and event so that consumers can take the appropriate action.

See the Supported Capabilities section for details on message details for each capability.

Outbound

Messages resulting from hub events mostly report state changes in order to inform subscribers to those events.

Topic: hubitat/home-000d/hue-color-lamp-1-738/switch Message: on

Topic: hubitat/home-000d/hue-color-lamp-1-738/switch Message: off

Inbound

For those devices that support commands, MQTT messages can be authored be downstream consumers so that those commands are executed on the target device.

Topic: hubitat/home-000d/august-pro-z-wave-lock-324/lock Message: lock

Topic: hubitat/home-000d/august-pro-z-wave-lock-324/lock Message: unlock

Last Will

When the client establishes a connection to the broker it sets an default LWT topic to offline and then pushes online shortly thereafter.

In addition to LWT, the client also sends UPTIME, FW and IP containing uptime, current firmware version and IP address of the hub.

hubitat:
    home-000d:
        LWT: online
        FW: 2.2.0.126
        IP: 192.168.1.100
        UPTIME: 82815

Installation & Configuration

MQTT Link consists of both a driver and app. Both must be installed and configured prior to their use.

Driver

The driver app must be installed first because the App depends upon it. The driver connects to the configured MQTT broker and sends out messages when new hub events occur and receives messages from external client events such has those from Home Assistant.

The driver provides a number of commands that are useful for troubleshooting but they are not needed for normal operation of the driver code.

The following commands allow for subscribing and publishing to MQTT topics. The driver automatically prefixes all topics with the following prefix within the code to ensure unique topics for each hub.

/hubitat/{hub-name}-{hub-id}/ e.g. /hubitat/home-893/

Follow the procedure for installing user driver code on Hubitat and enter the following details.

optional

App

The app is responsible for listening to subscribed hub events that it relays to the driver to publish to the MQTT broker. It also listens for inbound messages from the driver that it then translates to a hub event.

Follow the procedure for installing apps code on Hubitat and specify the following details.

Select Devices and Driver

optional

Device Capabilities

Each of the devices chosen on the prior page are listed on this page and include a dropdown containing the capabilities associated with that device. This page also lists the normalized topic for the device.

Supported Capabilities

Following is an inclusive list of device capabilities, attributes and commands recognized by MQTT Link.

Limited access to devices within each of these categories made it impossible to test each combination list. Please report any missing or erroneous details so that they can be corrected within the code.

Hubitat Capabilities List | SmartThings Capabilities List

Release Notes

Update in Release 1.0.0