{"id":13746145,"url":"https://github.com/stjohnjohnson/smartthings-mqtt-bridge","last_synced_at":"2025-04-12T19:50:19.338Z","repository":{"id":57364090,"uuid":"50438488","full_name":"stjohnjohnson/smartthings-mqtt-bridge","owner":"stjohnjohnson","description":"Bridge between SmartThings and MQTT","archived":false,"fork":false,"pushed_at":"2021-06-20T06:34:24.000Z","size":102,"stargazers_count":370,"open_issues_count":108,"forks_count":239,"subscribers_count":48,"default_branch":"master","last_synced_at":"2025-04-12T19:49:57.173Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/stjohnjohnson/smartthings-mqtt-bridge/","language":"Groovy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stjohnjohnson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-26T15:36:25.000Z","updated_at":"2025-01-31T15:14:47.000Z","dependencies_parsed_at":"2022-09-16T22:51:36.661Z","dependency_job_id":null,"html_url":"https://github.com/stjohnjohnson/smartthings-mqtt-bridge","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjohnjohnson%2Fsmartthings-mqtt-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjohnjohnson%2Fsmartthings-mqtt-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjohnjohnson%2Fsmartthings-mqtt-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjohnjohnson%2Fsmartthings-mqtt-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stjohnjohnson","download_url":"https://codeload.github.com/stjohnjohnson/smartthings-mqtt-bridge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625501,"owners_count":21135513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T06:00:47.870Z","updated_at":"2025-04-12T19:50:19.312Z","avatar_url":"https://github.com/stjohnjohnson.png","language":"Groovy","funding_links":[],"categories":["Interfaces","Groovy"],"sub_categories":["Smart Home Hardware Interfaces"],"readme":"# SmartThings MQTT Bridge\n***System to share and control SmartThings device states in MQTT.***\n\n[![GitHub Tag](https://img.shields.io/github/tag/stjohnjohnson/smartthings-mqtt-bridge.svg)](https://github.com/stjohnjohnson/smartthings-mqtt-bridge/releases)\n[![Docker Pulls](https://img.shields.io/docker/pulls/stjohnjohnson/smartthings-mqtt-bridge.svg)](https://hub.docker.com/r/stjohnjohnson/smartthings-mqtt-bridge/)\n[![Docker Stars](https://img.shields.io/docker/stars/stjohnjohnson/smartthings-mqtt-bridge.svg)](https://hub.docker.com/r/stjohnjohnson/smartthings-mqtt-bridge/)\n[![Wercker Status](https://app.wercker.com/status/f2df197ea40f89b7eda771e67b4a4e1e/s/master \"wercker status\")](https://app.wercker.com/project/bykey/f2df197ea40f89b7eda771e67b4a4e1e)\n[![Gitter](https://badges.gitter.im/stjohnjohnson/smartthings-mqtt-bridge.svg)](https://gitter.im/stjohnjohnson/smartthings-mqtt-bridge?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n[![Donate](https://img.shields.io/badge/donate-bitcoin-yellow.svg)](#donate)\n\nThis project was spawned by the desire to [control SmartThings from within Home Assistant][ha-issue].  Since Home Assistant already supports MQTT, we chose to go and build a bridge between SmartThings and MQTT.\n\n# Architecture\n\n![Architecture](https://www.websequencediagrams.com/cgi-bin/cdraw?lz=dGl0bGUgU21hcnRUaGluZ3MgPC0-IE1RVFQgCgpwYXJ0aWNpcGFudCBaV2F2ZSBMaWdodAoKAAcGTW90aW9uIERldGVjdG9yLT5TVCBIdWI6ABEIRXZlbnQgKFotV2F2ZSkKABgGACEFTVFUVEJyaWRnZSBBcHA6IERldmljZSBDaGFuZ2UAMAhHcm9vdnkAMwUAIg4AMxAAOAY6IE1lc3NhADYKSlNPTgAuEABjBi0-AHYLU2VyADkGAHAVUkVTVCkKAB0SAD0GIEJyb2tlcgCBaQk9IHRydWUgKE1RVFQpCgAyBQAcBwBdFgCCSgUgPSAib24iAC4IAFgUAIFaFgCBFhsAgWAWAIJnEwCCESMAgmoIAINWBVR1cm4AgTAHT24AgxcNAINXBQCEGwsAgVYIT24Ag3oJ\u0026s=default)\n\n# MQTT Events\n\nEvents about a device (power, level, switch) are sent to MQTT using the following format:\n\n```\n{PREFACE}/{DEVICE_NAME}/${ATTRIBUTE}\n```\n__PREFACE is defined as \"smartthings\" by default in your configuration__\n\nFor example, my Dimmer Z-Wave Lamp is called \"Fireplace Lights\" in SmartThings.  The following topics are published:\n\n```\n# Brightness (0-99)\nsmartthings/Fireplace Lights/level\n# Switch State (on|off)\nsmartthings/Fireplace Lights/switch\n```\n\nThe Bridge also subscribes to changes in these topics, so that you can update the device via MQTT.\n\n```\n$ mqtt pub -t 'smartthings/Fireplace Lights/switch'  -m 'off'\n# Light goes off in SmartThings\n```\n\n# Configuration\n\nThe bridge has one yaml file for configuration:\n\n```\n---\nmqtt:\n    # Specify your MQTT Broker URL here\n    host: mqtt://localhost\n    # Example from CloudMQTT\n    # host: mqtt:///m10.cloudmqtt.com:19427\n\n    # Preface for the topics $PREFACE/$DEVICE_NAME/$PROPERTY\n    preface: smartthings\n\n    # The write and read suffixes need to be different to be able to differentiate when state comes from SmartThings or when its coming from the physical device/application\n\n    # Suffix for the topics that receive state from SmartThings $PREFACE/$DEVICE_NAME/$PROPERTY/$STATE_READ_SUFFIX\n    # Your physical device or application should subscribe to this topic to get updated status from SmartThings\n    # state_read_suffix: state\n\n    # Suffix for the topics to send state back to SmartThings $PREFACE/$DEVICE_NAME/$PROPERTY/$STATE_WRITE_SUFFIX\n    # your physical device or application should write to this topic to update the state of SmartThings devices that support setStatus\n    # state_write_suffix: set_state\n\n    # Suffix for the command topics $PREFACE/$DEVICE_NAME/$PROPERTY/$COMMAND_SUFFIX\n    # command_suffix: cmd\n\n    # Other optional settings from https://www.npmjs.com/package/mqtt#mqttclientstreambuilder-options\n    # username: AzureDiamond\n    # password: hunter2\n\n    # MQTT retains state changes be default, retain mode can be disabled:\n    # retain: false\n\n# Port number to listen on\nport: 8080\n\n```\n\n# Installation\n\nThere are two ways to use this, Docker (self-contained) or NPM (can run on Raspberry Pi).\n\n## Docker\n\nDocker will automatically download the image, but you can \"install\" it or \"update\" it via `docker pull`:\n```\n$ docker pull stjohnjohnson/smartthings-mqtt-bridge\n```\n\nTo run it (using `/opt/mqtt-bridge` as your config directory and `8080` as the port):\n```\n$ docker run \\\n    -d \\\n    --name=\"mqtt-bridge\" \\\n    -v /opt/mqtt-bridge:/config \\\n    -p 8080:8080 \\\n    stjohnjohnson/smartthings-mqtt-bridge\n```\n\nTo restart it:\n```\n$ docker restart mqtt-bridge\n```\n\n## NPM\n\nTo install the module, just use `npm`:\n```\n$ npm install -g smartthings-mqtt-bridge\n```\n\nIf you want to run it, you can simply call the binary:\n```\n$ smartthings-mqtt-bridge\nStarting SmartThings MQTT Bridge - v1.1.3\nLoading configuration\nNo previous configuration found, creating one\n```\n\nAlthough we recommend using a process manager like [PM2][pm2]:\n```\n$ pm2 start smartthings-mqtt-bridge\n[PM2] Starting smartthings-mqtt-bridge in fork_mode (1 instance)\n[PM2] Done.\n┌─────────────────────────┬────┬──────┬───────┬────────┬─────────┬────────┬────────────┬──────────┐\n│ App name                │ id │ mode │ pid   │ status │ restart │ uptime │ memory     │ watching │\n├─────────────────────────┼────┼──────┼───────┼────────┼─────────┼────────┼────────────┼──────────┤\n│ smartthings-mqtt-bridge │ 1  │ fork │ 20715 │ online │ 0       │ 0s     │ 7.523 MB   │ disabled │\n└─────────────────────────┴────┴──────┴───────┴────────┴─────────┴────────┴────────────┴──────────┘\n\n$ pm2 logs smartthings-mqtt-bridge\nsmartthings-mqtt-bridge-1 (out): info: Starting SmartThings MQTT Bridge - v1.1.3\nsmartthings-mqtt-bridge-1 (out): info: Loading configuration\nsmartthings-mqtt-bridge-1 (out): info: No previous configuration found, creating one\n\n$ pm2 restart smartthings-mqtt-bridge\n```\n\n## Usage\n1. Customize the MQTT host\n    ```\n    $ vi config.yml\n    # Restart the service to get the latest changes\n    ```\n\n2. Install the [Device Handler][dt] in the [Device Handler IDE][ide-dt] using \"Create via code\"\n3. Add the \"MQTT Device\" device in the [My Devices IDE][ide-mydev]. Enter MQTT Device (or whatever) for the name. Select \"MQTT Bridge\" for the type. The other values are up to you.\n4. Configure the \"MQTT Device\" in the [My Devices IDE][ide-mydev] with the IP Address, Port, and MAC Address of the machine running the Docker container\n4. Install the [Smart App][app] on the [Smart App IDE][ide-app] using \"Create via code\"\n5. Configure the Smart App (via the Native App; on Android, this must be the Classic version) with the devices you want to share and the Device Handler you just installed as the bridge\n6. Via the Native App, select your MQTT device and watch as MQTT is populated with events from your devices\n\n## Advanced\n### Docker Compose\n\nIf you want to bundle everything together, you can use [Docker Compose][docker-compose].\n\nJust create a file called `docker-compose.yml` with this contents:\n```yaml\nmqtt:\n    image: matteocollina/mosca\n    ports:\n        - 1883:1883\n\nmqttbridge:\n    image: stjohnjohnson/smartthings-mqtt-bridge\n    volumes:\n        - ./mqtt-bridge:/config\n    ports:\n        - 8080:8080\n    links:\n        - mqtt\n\nhomeassistant:\n    image: balloob/home-assistant\n    ports:\n        - 80:80\n    volumes:\n        - ./home-assistant:/config\n        - /etc/localtime:/etc/localtime:ro\n    links:\n        - mqtt\n```\n\nThis creates a directory called `./mqtt-bridge/` to store configuration for the bridge.  It also creates a directory `./home-assistant` to store configuration for HA.\n\n## Donate\n\nIf you use and love our bridge tool, please consider buying us a coffee by sending some Satoshi to `1sBPcBai7gZco6LipPthuyZ5rH4RKx1Bg`.\n\n[![Donate Bitcoin](http://i.imgur.com/VJomBaC.png)](https://coinbase.com/stjohn)\n\n [dt]: https://github.com/stjohnjohnson/smartthings-mqtt-bridge/blob/master/devicetypes/stj/mqtt-bridge.src/mqtt-bridge.groovy\n [app]: https://github.com/stjohnjohnson/smartthings-mqtt-bridge/blob/master/smartapps/stj/mqtt-bridge.src/mqtt-bridge.groovy\n [ide-dt]: https://graph.api.smartthings.com/ide/devices\n [ide-mydev]: https://graph.api.smartthings.com/device/list\n [ide-app]: https://graph.api.smartthings.com/ide/apps\n [ha-issue]: https://github.com/balloob/home-assistant/issues/604\n [docker-compose]: https://docs.docker.com/compose/\n [pm2]: http://pm2.keymetrics.io/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstjohnjohnson%2Fsmartthings-mqtt-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstjohnjohnson%2Fsmartthings-mqtt-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstjohnjohnson%2Fsmartthings-mqtt-bridge/lists"}