npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

smartthings-mqtt-bridge

v3.0.0

Published

Bridge between SmartThings and an MQTT broker

Downloads

332

Readme

SmartThings MQTT Bridge

System to share and control SmartThings device states in MQTT.

GitHub Tag Docker Pulls Docker Stars Wercker Status Gitter Donate

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

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

    # 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

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

    # Suffix for the topics to send state back to SmartThings $PREFACE/$DEVICE_NAME/$PROPERTY/$STATE_WRITE_SUFFIX
    # your physical device or application should write to this topic to update the state of SmartThings 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 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

  1. Customize the MQTT host

    $ vi config.yml
    # Restart the service to get the latest changes
  2. Install the Device Handler in the Device Handler IDE using "Create via code"

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

  4. Configure the "MQTT Device" in the My Devices 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 using "Create via code"

  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. Via the Native App, select your MQTT device and 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.

Donate

If you use and love our bridge tool, please consider buying us a coffee by sending some Satoshi to 1sBPcBai7gZco6LipPthuyZ5rH4RKx1Bg.

Donate Bitcoin