Hubitat Elevation MQTT Bridge

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

Original Author: https://hub.docker.com/r/stjohnjohnson/hubitat-mqtt-bridge/

I highly recommend looking at the original github above as it may have more information that I have left out, or removed as it is not relevant. For the time being I have left the links to the docker images and setup to the original as they do work. As I rebuild and customize I will update this README.

This project was spawned by the desire to control hubitat and Hubitat Elevation from within Home Assistant. Since Home Assistant already supports MQTT. The original authors chose to go and build a bridge between hubitat and MQTT and I have borrowed their work.

Architecture

MQTT Events

Events about a device (power, level, switch) are sent to MQTT using the following format:

{PREFACE}/{DEVICE_NAME}/${ATTRIBUTE}

PREFACE is defined as "hubitat" by default in your configuration

For example, my Dimmer Z-Wave Switch is called "Family Room Lights" in Hubitat Elevation. The following topics are published:

# Brightness (0-99)
hubitat/Family Room Lights/level
# Switch State (on|off)
hubitat/Family Room Lights/switch

The Bridge also subscribes to changes in these topics, so that you can update the device via MQTT.

$ mqtt pub -t 'hubitat/Family Room Lights/switch'  -m 'off'
# Light goes off in Hubitat Elevation

Configuration

The bridge has one yaml file for configuration:

---
mqtt:
    # Specify your MQTT Broker URL here
    host: mqtt://localhost
    # Example from CloudMQTT
    # host: mqtt:///m10.cloudmqtt.com:19427

    # Preface for the topics $PREFACE/$DEVICE_NAME/$PROPERTY
    preface: hubitat

    # The write and read suffixes need to be different to be able 
    # to differentiate when state comes from Hubitat Elevation or 
    # when its coming from the physical device/application

    # Suffix for the topics that receive state from Hubitat Elevation $PREFACE/$DEVICE_NAME/$PROPERTY/$STATE_READ_SUFFIX
    # Your physical device or application should subscribe to this topic to get updated status from Hubitat Elevation
    # state_read_suffix: state

    # Suffix for the topics to send state back to Hubitat Elevation $PREFACE/$DEVICE_NAME/$PROPERTY/$STATE_WRITE_SUFFIX
    # your physical device or application should write to this topic to update the state of Hubitat Elevation devices that support setStatus
    # state_write_suffix: set_state

    # Suffix for the command topics $PREFACE/$DEVICE_NAME/$PROPERTY/$COMMAND_SUFFIX
    # command_suffix: cmd

    # Other optional settings from https://www.npmjs.com/package/mqtt#mqttclientstreambuilder-options
    # username: AzureDiamond
    # password: hunter2

    # MQTT retains state changes be default, retain mode can be disabled:
    # retain: false

# Port number to listen on
port: 8080

Installation

There are two ways to use this, Docker (self-contained) or NPM (can run on Raspberry Pi).

Docker

Docker will automatically download the image, but you can "install" it or "update" it via docker pull:

$ docker pull jeubanks/hubitat-mqtt-bridge

To run it (using /opt/mqtt-bridge as your config directory and 8080 as the port):

$ docker run \
    -d \
    --name="mqtt-bridge" \
    -v /opt/mqtt-bridge:/config \
    -p 8080:8080 \
    jeubanks/hubitat-mqtt-bridge

To restart it:

$ docker restart mqtt-bridge

Usage

1. Customize the MQTT host

   $ vi config.yml
   # Restart the service to get the latest changes
   

2. Install the Driver in the Hubitat Web Interface [Drivers Code] using "New Driver"

3. Add the "MQTT Device" device in the [Devices]. Enter MQTT Device (or whatever) for the name. Select "MQTT Bridge" for the type. The other values are up to you.

4. Configure the "MQTT Device" in the [Devices] with the IP Address, Port, and MAC Address of the machine running the Docker container

5. Install the App in [Apps Code] using "New App"

6. Enable the App in [Apps] using "Load New App" and select MQTT Bridge

7. Click MQTT Bridge in the list of Apps

8. At the top of notification (this is to be updated)

9. Configure the devices you want to send to the MQTT Bridge.

10. At the bottom select the MQTT Bridge to send events to.

11. Save

Advanced

Docker Compose

If you want to bundle everything together, you can use Docker Compose.

Just create a file called docker-compose.yml with this contents:

mqtt:
    image: matteocollina/mosca
    ports:
        - 1883:1883

mqttbridge:
    image: jeubanks/hubitat-mqtt-bridge
    volumes:
        - ./mqtt-bridge:/config
    ports:
        - 8080:8080
    links:
        - mqtt

homeassistant:
    image: balloob/home-assistant
    ports:
        - 80:80
    volumes:
        - ./home-assistant:/config
        - /etc/localtime:/etc/localtime:ro
    links:
        - mqtt

This creates a directory called ./mqtt-bridge/ to store configuration for the bridge. It also creates a directory ./home-assistant to store configuration for HA.