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:

---
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: smartthings

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

# 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 stjohnjohnson/smartthings-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 \
    stjohnjohnson/smartthings-mqtt-bridge

To restart it:

$ docker restart mqtt-bridge

NPM

To install the module, just use npm:

$ npm install -g smartthings-mqtt-bridge

If you want to run it, you can simply call the binary:

$ smartthings-mqtt-bridge
Starting SmartThings MQTT Bridge - v1.1.3
Loading configuration
No previous configuration found, creating one

Although we recommend using a process manager like PM2:

$ pm2 start smartthings-mqtt-bridge
[PM2] Starting smartthings-mqtt-bridge in fork_mode (1 instance)
[PM2] Done.
┌─────────────────────────┬────┬──────┬───────┬────────┬─────────┬────────┬────────────┬──────────┐
│ App name                │ id │ mode │ pid   │ status │ restart │ uptime │ memory     │ watching │
├─────────────────────────┼────┼──────┼───────┼────────┼─────────┼────────┼────────────┼──────────┤
│ smartthings-mqtt-bridge │ 1  │ fork │ 20715 │ online │ 0       │ 0s     │ 7.523 MB   │ disabled │
└─────────────────────────┴────┴──────┴───────┴────────┴─────────┴────────┴────────────┴──────────┘

$ pm2 logs smartthings-mqtt-bridge
smartthings-mqtt-bridge-1 (out): info: Starting SmartThings MQTT Bridge - v1.1.3
smartthings-mqtt-bridge-1 (out): info: Loading configuration
smartthings-mqtt-bridge-1 (out): info: No previous configuration found, creating one

$ pm2 restart smartthings-mqtt-bridge

Usage

Customize the MQTT host

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

Install the Device Type on the Device Handler IDE
Configure the Device Type (via the IDE) with the IP Address, Port, and MAC Address of the machine running the Docker container
Install the Smart App on the Smart App IDE
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
Watch as MQTT is populated with events from your devices

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: 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.

joelash / smartthings-mqtt-bridge