homebridge-blinds-cmd

Homebridge Blinds Command

HomeKit support for non-smart motorized blinds through command-line scripts.

homebridge-blinds-cmd is a Homebridge plugin that allows you to raise, lower, and get the current position of your window blinds by executing a given command-line or script. It makes a HomeKit window covering accessory available to you that can report status and be controlled entirely through command-line scripts.

Why use this plugin for window blinds support in HomeKit?

These days, there is a decent selection of window blinds available on the market with native HomeKit support. However, there are also blinds systems, such as Somfy, which don't have any meaningful HomeKit support. Add to that the proprietary remote protocols and you're in for a challenge in trying to make window blinds part of your HomeKit smart home.

There are other blinds plugins for Homebridge that are either tailored to specific blinds solutions, or more broadly focused on blinds that can be controlled through HTTP -- and they do a great job if that's what you're seeking. You can certainly do those things with this plugin, though you'll be writing your own scripts to do so. So why use this plugin in particular in this scenario? Well, in some cases you've got complex state conditions you want to reflect in HomeKit.

For instance, let's take the example of a living room with two motorized Somfy shades (I'm picking Somfy for this example because it's what I'm most familiar with, but other brands have similar concepts). In our example, we have a remote control that has three presets configured - one to control the first shade, one to control the second shade, and one to control both simultaneously. Controlling each of the individual shades is an easy enough task for most of the blinds-related Homebridge plugins.

That last scenario though can be tricky. What if you want to expose, for the sake of argument, the three presets described above as three shades in HomeKit. What you'd like is that when you raise or lower that third preset, the one that controls two shades simultaneously, that HomeKit also reflects the updates across those shades. This type of relational mapping between shades and presets can be challenging to make work. That's what this plugin is for. Allowing you to do easy things like controlling an individual shade and providing you the flexibility to implement more complex things, should you choose to do so, in the form of command-line scripts.

Changelog

Changelog starting with v2.0 is available here.

Installation

If you are new to Homebridge, please first read the Homebridge documentation and installation instructions before proceeding.

If you have installed the Homebridge Config UI, you can intall this plugin by going to the Plugins tab and searching for homebridge-blinds-cmd and installing it.

If you prefer to install homebridge-blinds-cmd from the command line, you can do so by executing:

sudo npm install -g homebridge-blinds-cmd

Configuration

I strongly recommend using the Homebridge Config UI rather than editing your config.json directly. It does a good job of showing you all the options and always generating a valid configuration so you don't get stuck on typos or looking for stray commas in your config.json.

For those that prefer configuring things directly, add the accessory in config.json in your home directory inside .homebridge.

   "platforms": [
     {
       "platform": "Blinds Command",
 
       "blinds": [
         {
           "name": "Downstairs Window Blinds",
           "manufacturer": "Somfy",
           "model": "Sonesse",
           "serial": "1234",
           "up": "/path/to/your/raise_blinds_script",
           "down": "/path/to/your/lower_blinds_script",
           "status": "/path/to/your/blinds_state_script",
           "stop": "/path/to/your/stop_blinds_script",
           "transitionInterval": 10,
           "refreshRate": 5
         }
      ]
    }
  ]

Options

• up, down, stop, and status should point to scripts or command lines to run to execute those actions. up and down are required, and all others are optional.
• Setting a stop command in conjunction with a transitionInterval will allow you to simulate partially opening or closing your blinds, enabling scenarios such as asking HomeKit to open the blind to a certain percentage (e.g. Hey Siri, set the blinds to 30%).
• manufacturer, model, and serial are optional settings to allow you to further identify your blinds in HomeKit.
• transitionInterval is an optional setting that allows you to simulate a blind transition movement between open and closed. If it takes 15 seconds for the blinds to open, enter 15 here and homebridge-blinds-cmd will simulate the time it takes to complete that transition in HomeKit. The default is 10 seconds.
• refreshRate will execute the status command at whatever refresh rate you set, in seconds. This is useful when the state of your blinds changes outside of HomeKit, and you want to regularly check it's status.

Script inputs and outputs

homebridge-blinds-cmd expected the following:

• status script: Should output a number from 0 to 100 to inform HomeKit of what the current position of the blind is.

• up, down, or stop script: Must be able to accept an additional argument containing the position that's been requested by the user. For example:

    {
       ...
       "up": "/path/to/raise_blinds_script"
       ...
    }

  All configured scripts (up, down, stop, and status) will be called as /path/to/raise_blinds_script 100, where 100 is whatever position was requested by the end user and passed on to HomeKit. This should enable those who wish to take advantage of situations where you may want to only open a shade half way, to do so. The script should output a number from 0 to 100 to inform HomeKit of what the new position of the blind is.

  In the case of the status script, the value specified by homebridge-blinds-cmd represents the position that the plugin believes the blind is at. For example, if homebridge-blinds-cmd believes the blind is 30% open, it will check for status by executing /path/to/status_script 30. If you believe the number specified by the plugin is correct, you should return the same value: 30 in this case. Whatever value is returned by the status script is what HomeKit will ultimately report.

There are two example scripts to get you started in the scripts folder. They should help you get started whether you're using a Somfy URTSI or a Bond Bridge to control your shades.

Notes

This plugin doesn't query nor have direct knowledge of the actual position of your blinds. Instead, it emulates the position based on your most recent request to raise / lower the blinds (i.e. it remembers what you last asked it to do and reports that back to HomeKit). Some blinds, such as Somfy, don't support querying their specific state. That said, if you do wish to use a specific position, you can do so. It's passed as the last argument to the up and down script configuration options. How you choose to handle it, is up to you. What your plugin should output is the position it wants to HomeKit (e.g. 100 if the blind is fully open).

Additionally, if you specify transitionInterval and stop you'll magically get the ability to move the blind a precise amount. For instance, if you try to open the blind to 20%, homebridge-blinds-cmd will run the up script and then use transitionInterval to figure out how many seconds to allow the blinds to move before running the stop script. The result, if you have transitionInterval correctly calculated for your blinds, should be relatively precise placement of your blinds at home - something that many popular blinds (e.g. Somfy), can't do natively! The sample control script for Bond provides a good example of how to do this.

A sample control script for Somfy is included. This script is provided as an example of what is possible. Your mileage may vary - this script was tested on a Mac and should work on other platforms, best of luck. It assumes the use of a Somfy URTSI attached to an iTach Flex) via serial. The script is fairly robust and allows for multiple URTSI scenarios including multiple URTSIs and shade groups.

I've also used, and currently use, a Bond Bridge. It's a terrific device with builtin support for Somfy RF signals as well as a wide variety of IR and RF formats for shades, ceiling fans, and fireplaces. I highly recommend it as a more robust alternative to the Somfy URTSI, and at a much better price point.

Plugin Development Dashboard

This is mostly of interest to the true developer nerds amongst us.