openHAB

This page is part of archived documentation for openHAB 3.1. Go to the current stable version

# Smartify Roller Shutters with openHAB and Shelly

How openHAB and Shelly 2.5 provide an enhance experience when controlling rollers

# Use Case

More and more people have rollers, which are equipped with a motor and button control improving your comfort when operating the shutter.

This use case description covers the following aspects

  • Operate the roller manual as usual - don't loose some of those features when bringing in the Shelly
  • Use openHAB to control the roller (up/down/stop, positioning)
  • Utilize device's position favorites
  • Utilize safety features, which you get for free with the Shelly

The first point is important: SmartHome is nice for us techies, but standard users should have to use the "standard mode", but also the "new world". Therefore a struct requirement: make if "compatible for my wife" and avoid "that sucks, I kill you!". Shutters not opening in the morning don't create fun 😃

One more aspect is some kind of protection to avoid physical damage when something gets wrong. The Shellies provide some interesting features to do.

This use case description might also apply to Venetian Blinds, but I don't have those and can't judge on that. Feel free to adapt the concept and report ideas and experiences to the community (opens new window)

# Technical pre-requisites

To implement this use case you need

  • Roller motor can be attached to the Shelly For this how-to a roller with an electrical motor is required and will be controlled using A/C and a momentary switch. The same solutions works with other switch types (DC/AC, 2 button switch etc.). In this case you need to look into details and user a different Shelly configuration or adapt technical installation. Refer to the Allterco Shelly documentation and make sure to use proper technical installation and wiring. Important: Electrical installation should be performed only be people knowing what they do - failures could harm you!!

  • Shelly 2.5 to control the roller with firmware 1.9.2+ The Shelly 2.5 supports relay and roller operation mode. To prepare this use case you need to upgrade to firmware 1.9.2 (or newer) and perform some setup steps (see below).

  • openHAB 3.0 (or 2.5) with latest version of the binding openHAB is the perfect foundation to combine manual and automated control of the roller. The Shelly binding is available for openHAB 3.0, but still supports version 2.5 (you should at least have 2.5.9). Nevertheless you need to switch to the so called DEV build to benefit from bug fixes and improvements. This version is currently NOT part of the openHAB 3.0 distribution, a PR has been initiated and it will not become part of the 2.5.x distribution, because this only receives bug fixes and the use case utilizes new features in the binding.

# Implementation

# Software pre-requisites

# openHAB version

It's strongly recommended to get on one of the pretty stable openHAB releases

  • The good one: openHAB 2.5.9 or newer
  • The new kid on the block: 3.0 will be release by end of 2020
  • Older versions might worked, but are not covered here.

Refer to the documentation how to upgrade to the current version and where you should watch for necessary adaptions. By the way: There is a good README for the binding, RTFM if you know what I mean 😃 Latest version is always available here (opens new window) as part of the DEV build (see below).

Ideally the upgrade could be performed on a Raspberry with

openhab-cli stop
openhab-cli clean-cache
apt-get update
apt-get upgrade
openhab-cli start

and wait until openHAB has fully initialized and cache has been re-initialized. That's it - pretty simple, but again you might need to do adaptions.

# Device firmware

The binding supports Shelly devices for a long time, also with older firmware releases (beginning with version 1.7). Nevertheless, a lot of issues has been fixed in between as well as new features became available over time. It's recommended to upgrade your roller device to 1.9.2 or newer. 1.9 brings roller position favorites, which are used by this use case (older version works, but you can't use that feature).

See binding's README for more information how to upgrade the firmware.

# Shelly Binding

The Shelly binding is in general included in the openHAB 2.5.x as well as the new 3.0 distribution. However, the so called DEV build is always on a newer feature level and fixing bugs. Due to the fact that we utilize some new features of the binding it also requires the DEV build. Refer to the information how to install the DEV build (check section Resources to get the info where to find this READMEbeta (opens new window))

Important: After installing the new binding release you should delete all Shelly things and run the discovery. No worries, openHAB will restore you channel/item linkings.

# Configuration

# Shelly setup - General

There are some settings required to prepare your Shelly for this use case.

  • Open the Web UI simply by launching 'http://<shelly ip> in the browser, this opens the device's UI
  • Go to Settings:DEVICE TYPE and select Roller-Shutter
  • POWER ON PARAMETERS: "STOP" will make sure that the roller doesn't start moving on a power failure recovery
  • INPUT BUTTONS MODE: This depend on your installed button, if you only have a single one use "One button", if you have 2 buttons or one with 2 positions select "One button"
  • POSITIONING CONTROLS: Enable them to have the controls in the App (UP/STOP/DOWN + relative positions), this helps during installation

For safety reasons you might consider:

  • OPEN/CLOSE WORKING TIME This feature makes sure that the Shelly stops the motor after a certain time even the motor doesn't stop by itself. Start the roller, measure the number of seconds until the shutter stops. Maybe add 2-3 seconds for safe and set the values for both directions in the UI

  • OBSTACLE DETECTION under Safety in the Web UI Shelly 2.5 has an integrated detection on roller obstacles based on measuring the motor power. The detection needs to be enabled, "While Moving" cover open and close. Action Stop makes most sense, you should manually verify the problem.

and there are some more options:

  • MAX POWER PROTECTION A roller should never consume high power - in this case you could assume an electrical problem. Therefore you could configure the Shelly to turn off power when exceeding a certain limit (e.g. 250W - value depend on your roller motor).

  • SWAP INPUTS and REVERSE DIRECTIONS - you could flip operation mode for open/close, this could help in non-standard operations, but could also indicate a wiring problen It also makes sense to give the device a name. Go to Settings:DEVICE NAME and select a symbolic name. This name will also discovered by the binding and added as a suffix to the thing name in the Inbox. It simplifies to identify the roller when you have a ton of Shelly things (believe me).

# Shelly setup - Positioning Favorites

With version 1.9 Allterco introduced an interesting feature called Favorites. Those allow to store up to 4 pre-defined positions in the device, e.g. 15%, 50%, 65%, 98%. Once defined you have kind of a short-cut to bring the roller to that position and those favorites are also supported by the binding (see below).

To use this feature open the device's Web UI and click on Favorites(+) button. You could now specify 4 percentage values between 0% (closed) and 100% (open). Enter the values and try using the button line above the roller control and main UI buttons.

With this configuration your Shelly is ready to be integrated into openHAB.

# Binding/Thing configuration

Once the Shelly is configured you could start the discovery within openHAB. Important: If you want to password protect your Shellys (strong recommendation) you could set a default user/password in the binding settings and avoid to specify those per thing:

  • Open the Binding Configuration in the openHAB UI
  • Set User Id and Password, save
  • Remove all Shellys from the Inbox (if any)
  • and restart the Discovery

Now all Shellys should pop up with the correct device names and types. The binding also adds some information to the Thing Name making the identification easier.

Once you added the device from the Inbox the binding will initialize the device and dynamically create channels depending on the available device/firmware features. This takes about 5-10 seconds. During that time the thing is working, but you might miss channels in the UI - that's normal, try to reload the page after 10sec and boom all there. Go to the channel overview and links the channels you want to use, refer to the README to get more details on channels, type and values.

The only thing to configure are the positioning favorite ids for the roller UP and DOWN commands. Edit the thing configuration and select the ids in the corresponding entry fields. Value 0 means: no favorite, value 1-4 select the position as defined in the Shelly App. There is also a dedicated channel (roller#rollerFav), which accepts this ids and triggers the roller moving to the position (% value) as defined for the matching favorites id.

# Device events

As you might know the binding supports the Allterco Shelly CoIoT protocol. The device supports so called I/O URL Actions, which are kind of a callback to an application for certain events. Whenever possible you should prefer CoIoT events, because they are triggered near realtime and provide way more information compared to the Action URLs. The binding uses those CoIoT updates as triggers, but also to update the channel data. Refer to the README for more information on CoIoT.

# Automation

Beside manual operation the binding provide various options to control the roller from within openHAB rules. For example

  • link channel roller#control and use 'sendCommand(<item>, UP)' to open the shutter or 'sendCommand(<item>, DOWN)' to close it.
  • get status updates from roller operations by observing channel 'roller#state' and 'roller#stopReason', those report an updated status once the operation is completed
  • select a position by sending a number value of 100..0 to channel 'roller#rollerpos'
  • or use the defined favorites by sending favorite id to channel 'roller#rollerFav'
  • you might set a auto-timer, e.g. once the roller is opened close it again after xx minutes by sending a value to the 'roller#autoOn' or 'roller#autoOff' channels
  • you could also get the position of the roller from 'roller#control' (by linking a Number item) or the last status from 'roller#state'. Please note that the device only provides updates only after the roller stops, not during movement so it's not possible to get position updates while the roller is moving.
  • of course you could use time-triggered rules, trigger the shutter depending on sunrise/sunset within openHAB, but also directly on the device

# Extending the Use Case

There are two valuable options, which even extend and improve the user experience.

  • Button-1

Using the described setup you could add a Button-1 to trigger rules, e.g.

  • 1xshort: open roller

  • 2xshort: go to 25% (because disturbs enjoying your morning coffee with your wife or husband)

  • 3xshort: go to 75% (sun is disturbing while watching your TV)

  • long : close shutter (if not done by some automation)

  • Voice control And of course you could utilize openHAB's voice integration, e.g. with Alexa, Siri or Google Home.

  • Scenes There are more of less limits when integrating even more advanced roller control based on openHAB rules. This allows to provide a scene to the user, which does a lot of complex stuff under the hood.

Be welcome to contribute your ideas to the community, this is what creates the difference between openHAB/Shelly setup compared to rollers with button control.

# Resources

There is a bunch of ressources you could browse around openHAB, Shelly or the binding

and the openHAB Community thread specifically for the binding (opens new window)