SmartThings MQTT Bridge

System to share and control SmartThings device states in MQTT.

This project was spawned by the desire to control SmartThings from within Home Assistant. Since Home Assistant already supports MQTT, we chose to go and build a bridge between SmartThings and MQTT.

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 "smartthings" by default in your configuration

For example, my Dimmer Z-Wave Lamp is called "Fireplace Lights" in SmartThings. The following topics are published:

# Brightness (0-99)
smartthings/Fireplace Lights/level
# Switch State (on|off)
smartthings/Fireplace Lights/switch

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

$ mqtt pub -t 'smartthings/Fireplace Lights/switch'  -m 'off'
# Light goes off in SmartThings

Configuration

The bridge has one yaml file for configuration. Currently we only have three items you can set:

---
mqtt:
    # Specify your MQTT Broker's hostname or IP address here
    host: mqtt
    # Preface for the topics $PREFACE/$DEVICE_NAME/$PROPERTY
    preface: smartthings

# Port number to listen on
port: 8080

We'll be adding additional fields as this service progresses (mqtt port, username, password, etc).

Usage

1. Run the Docker container

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

2. Customize the MQTT host

   $ vi /opt/mqtt-bridge/config.yml
   $ docker restart mqtt-bridge
   

3. Install the Device Type on the Device Handler IDE

4. Configure the Device Type (via the IDE) with the IP Address, Port, and MAC Address of the machine running the Docker container

5. Install the Smart App on the Smart App IDE

6. Configure the Smart App (via the Native App) with the devices you want to share and the Device Handler you just installed as the bridge

7. Watch as MQTT is populated with events from your devices

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: stjohnjohnson/smartthings-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.