homebridge-mqtt-blinds

This is a homebridge plugin to control blinds/shutters via mqtt. 🌞🌚 It can be used with DIY systems or retrofit solutions like Shelly2 and Shelly2.5.

Installation

If you are new to Homebridge, please first read the Homebridge documentation. To install the plugin use:

sudo npm install homebridge-mqtt-blinds -g

Configuration

config.json example (generic)

{
    "bridge": {
        "name": "homebridge",
        "username": "CC:22:3D:E3:CE:30",
        "port": 51826,
        "pin": "031-45-154"
    },
    "accessories": [{
      "accessory": "BlindsMQTT",
      "name": "Living Room Blind",
      "manufacturer": "DIY",
      "model": "Prototype",
      "serialNumberMAC": "01.01.01.01",
      "mqttBrokerUrl": "mqtt://192.168.0.10:1883",
      "mqttUsername": "username",
      "mqttPassword": "password",
      "mqttMainTopic": "myBlind",
      "mqttSetTopics": {
        "targetPosition": "SET/targetPosition"
      },
      "mqttGetTopics": {
        "currentPosition": "GET/currentPosition",
        "positionState": "GET/positionState",
        "targetPosition": "GET/targetPosition"
      },
      "mqttPositionStateValues": ["0", "1", "2"],
      "useManualControls": false
    }
    ],

    "platforms": [
    ]
}

config.json example (for shelly2 devices)

{
    "bridge": {
        "name": "Homebridge",
        "username": "CC:22:3D:E3:CE:30",
        "port": 51826,
        "pin": "031-45-154"
    },
    "accessories": [{
      "accessory": "BlindsMQTT",
      "name": "Living Room Blind",
      "manufacturer": "Allterco",
      "model": "Shelly2",
      "serialNumberMAC": "01.01.01.01",
      "mqttBrokerUrl": "mqtt://192.168.0.10:1883",
      "mqttUsername": "username",
      "mqttPassword": "password",
      "mqttMainTopic": "shellies/shellyswitch-<YOUR_SHELLYID>/roller",
      "mqttSetTopics": {
        "targetPosition": "0/command/pos"
      },
      "mqttGetTopics": {
        "currentPosition": "0/pos",
        "positionState": "0",
        "targetPosition": "0/dummy"
      },
      "mqttPositionStateValues": ["open", "close", "stop"],
      "useManualControls": true
    }
    ],

    "platforms": [
    ]
}

Basic

Variable	Description	Example
accessory	Name of the accessory plugin.	BlindsMQTT
name	Name for your blinds.	Living Room Blind
manufacturer	Manufacturer of your blind	DIY
model	Model of your blind.	Prototype
serialNumberMAC	Serial number of your blind.	01.01.01.01

MQTT

Basics

Variable	Description	Example
mqttBrokerUrl	IP Adress of your MQTT Broker	mqtt://192.168.0.10:1883
mqttUsername	Your MQTT Broker username	username
mqttPassword	Your MQTT Broker password	password
mqttMainTopic	The main topic of your blind	myBlind

Get Topics

Use these variables to set topics to inform the plugin about the current status of your blind. The plugin subscribes these topics.

Variable	Description	Example
currentPosition	Topic to get the current position of your blind. The value has to be between 0-100.	GET/currentPosition
positionState	Topic to get the current position state of your blind. Custom PositionStates messages from your device can be configured with mqttPositionStateValues.	GET/positionState
targetPosition	Topic to get the target position of your blind. The value has to be between 0-100.	GET/targetPosition

Set Topics

Use these variables to define the topic that the plugin uses to control your blind. The plugin will publish on these topics.

Variable	Description	Example
targetPosition	Topic to set the target position of your blind. The value has to be between 0-100.	SET/targetPosition

Position State Values

Use this variable to configure custom payloads for positionState messages for your device.

Variable	Description	Example
mqttPositionStateValues	["DECREASEING_STATE", "INCREASING_STATE", "STOPPED_STATE"]	["open", "close", "stop"] or ["0", "1", "2"]

Manual Controls

Smart Shutters are usually used in parallel with an automation and with manual controls (wall mounted switches). Set "useManualControls"=true if you have manual controls in your setup. This will force to plugin to "simulate" a target position when the manual controls are in use and no real target position is known.

Usage

Build up your blind. Use MQTT to communicate with homebridge. To explain how it works i will use the values of the examples above. For example, if you use the home app to open your blind 100%, the plugin will publish 100 on the topic myBlind/SET/targetPosition. The blind should send the current position on the topic myBlind/GET/currentPosition, the position state on myBlind/GET/positionState an the target position on myBlind/GET/currentPosition.

---

Have fun with this plugin. Let me know if you find a issue.