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.
Events about a device (power, level, switch) are sent to MQTT using the following format:
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
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 # Suffix for the state topics $PREFACE/$DEVICE_NAME/$PROPERTY/$STATE_SUFFIX # state_suffix: 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 # Port number to listen on port: 8080
There are two ways to use this, Docker (self-contained) or NPM (can run on Raspberry Pi).
Docker will automatically download the image, but you can "install" it or "update" it via
$ 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
To install the module, just use
$ 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
Customize the MQTT host
$ vi config.yml # Restart the service to get the latest changes
- Add the "MQTT Device" device in the My Devices IDE. Enter MQTT Device (or whatever) for the name. Select "MQTT Bridge" for the type. The other values are up to you.
- Configure the "MQTT Device" in the My Devices 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 using "Create via code"
- 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
- Via the Native App, select your MQTT device and watch as MQTT is populated with events from your devices
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.
If you use and love our bridge tool, please consider buying us a coffee by sending some Satoshi to
If your still having issues with compose megalithic, I had to change the compose yml like below. This allows traffic outside docker on port 8123 and let's you hit the interface.
- 80:80 - 8123:8123
I just installed arch linux on a lil box to run all this on. Got docker/docker-compose setup. Got the containers setup (all 3 are running and logging.. yay). I setup the Smart App and the Device/Device Handler.
Now, for the potential issues. I setup the preferences for the device so that the ip is to the docker container name, "ha_mqttbridge_1", that didn't seem right, but I saw that one one of the other posts y'all have made about this awesome setup. So basically I can't seem to hit the home assistant UI, and i the bridge isn't talking to smartthings and vice-versa.
Are y'all on the gitter.im channel ever to help with a quick bit of troubleshooting? I'm comfy in CLI-land and mostly with docker (first time using docker-compose, but setup manual docker machines, etc at work).
Thanks! (i'm megalithic on gitter.im/home-assistant)