Repository navigation
Plugin venetian blind
Controls configured Shelly or compatible blinds, including tilt positions, automation rules and mobile actions.
| Item | Value |
|---|---|
| Version | 1.2.8 |
| Category | Energy and building control |
| Author | Martin Pihrt |
| License | GPL-3.0 |
| OSPy |
3.0.211 or newer |
| Python |
3.8 or newer |
| Permissions |
network, files, system
|
| Hardware | No dedicated hardware requirement declared |
| Dependencies | Wind Speed Monitor (optional) |
| Python/OS packages | None |
| Interfaces | provider ospy.provider.v1, Mobile API v1 |
| Source | Open the plug-in directory |
Controls configured Shelly or compatible blinds, including tilt positions, automation rules and mobile actions.
Tested in Python 3+
Version 1.2.8 implements ospy.provider.v1 and exposes every enabled blind as a cached resource with explicit open, stop, close and tilt 1–4 actions for Automation Rules and the native mobile application. Mobile action captions use command verbs instead of state adjectives, while configured tilt labels are preserved. The actions reuse the same validated command path as Mobile API v1.
Mobile action IDs are open, stop, close, tilt1, tilt2, tilt3 and tilt4. Every request supplies {"blind_uid":"..."}; the UID must identify a currently configured enabled blind and plug-in control must be enabled. The four tilt actions retain stable IDs while their visible labels come from the saved blind configuration.
The plug-in includes a plugin.json manifest and reports its worker, configured and reachable blinds, latest status update, command and errors through the OSPy system health interface. Mobile API v1 exposes one native status card for every configured blind, including its current state, position, connection and Shelly profile. It also declares bounded open, stop, close and tilt actions for clients that support per-card manual controls.
This plugin can be used to control blinds and shutters through an API and a hardware module such as a Shelly relay. The blind motor is connected to a Shelly relay or a similar device with separate outputs for the up and down directions. The relay supports control through its local REST or RPC API and can also measure consumption.
Blinds are managed individually through Add blind, Edit and confirmed Delete actions, with a saved card or list view.
The complete structured blind list is stored directly in OSPy PluginOptions; the plug-in does not create a separate configuration JSON file. The selected Gen1/Gen2/Custom profile, host, labels and all four tilt percentages, labels and custom URLs therefore remain persistent after a restart, update or live plug-in replacement. The only plug-in-owned JSON file is the optional operating log.
Boolean settings use the same accessible red and green sliding switches as other OSPy plug-ins without changing the saved option names or their compatibility with existing configurations.
Each blind can use Shelly Gen1, Shelly Gen2 and newer, or Custom REST URLs. Gen1 uses /status, /roller/0?go=open|close|stop and to_pos; Gen2+ uses Cover.GetStatus, Cover.Open, Cover.Close, Cover.Stop and Cover.GoToPosition. Four independently named tilt positions have configurable percentages and optional custom URLs. The reported Shelly position is classified as closed, tilt 1–4, open or an intermediate position.
Testing a saved command keeps the same blind editor open so several directions and tilt positions can be checked without reopening the blind after every command.
Temperature shading reads the selected OSPy sensor from its actual last_read_value channel, compares it directly with the configured limit and operates only inside the permitted time window. Lowering is allowed only after the configured number of consecutive, fresh and unique Wind Monitor measurements is below the safe limit. It is armed only by a transition in which every enabled blind is confirmed fully open.
Wind automation is blocked immediately while Wind Monitor is disabled, stopped, paused by an RS485 device scan or reports an active measurement fault. Pending automatic raising and lowering actions are discarded, and an active automatic lowering program is cancelled. A safety program already started directly by Wind Monitor after sensor failure is not cancelled, allowing it to raise the blinds once. Automatic operation resumes only after Wind Monitor accepts a valid measurement and clears the fault.
Automatic opening and closing are completed only after every enabled and reachable Shelly reports the requested end position. After starting a configured program, the plug-in waits at least 60 seconds and never overlaps an active or queued program. If the target remains unconfirmed while the applicable wind or shading conditions are still satisfied, the program is started again. A temporary loss of the condition pauses retries; confirmation of fully open or fully closed clears the pending target.
Strong-wind protection is active all day and starts after the configured number of unique accepted Wind Monitor measurements reaches or exceeds the wind limit inside the configured minute interval, for example two exceedances during five minutes. It does not reuse the same cached measurement. If at least one enabled blind is closed, tilted, between positions or unreachable, the selected raising programs run; only a confirmed open state from every enabled blind suppresses the action. Pending lowering actions are cancelled first.
An automatic lowering request consumes the armed state but remains pending until every enabled blind is confirmed fully closed. A partial, unchanged or unreachable position therefore causes another attempt after the verification delay while shading conditions remain valid. Once full closure is confirmed, shading is rearmed only after every enabled blind becomes fully open again, whether raised by strong-wind protection or manually.
The plug-in observes active OSPy programs selected for raising and lowering. Programs started manually or through an ESP32 Multi Contact therefore suppress a duplicate automatic start while they are active, while the next valid Shelly position remains the authoritative state.
OSPy retains the last Run-Now program object after its final interval has ended. The plug-in checks the real final interval deadline, releases that completed object and continues its own queue. Temperature shading and strong-wind protection can consequently alternate repeatedly without restarting OSPy.
-
Check Use Control: Enables or disables the plugin.
-
Check Enable logging: Enables or disables logging.
-
Show in footer: Shows plugin data in the footer on the home page.
-
Label for blind: Names the blind for better identification.
-
Command for open blind: Defines a custom command such as
http://192.168.88.213/roller/0?go=open. -
Command for stop blind: Defines a custom command such as
http://192.168.88.213/roller/0?go=stop. -
Command for close blind: Defines a custom command such as
http://192.168.88.213/roller/0?go=close. -
Command for read status: Defines a custom status address such as
http://192.168.88.213/status.
The following notes are generated from the help page shipped with this plug-in. Field names are also explained directly in the OSPy settings page.
This plugin can be used to control blinds and shutters via API and HW module (eg: shelly relays: https://shelly.cloud/products/shelly-25-smart-home-automation-relay/).
The roller shutter motor is connected to a shelly relay, or some other similar. The relay has two outputs (one for the up direction and the other for the down direction). The relay allows control via the REST API. The relay also allows you to measure consumption.
The devices communicate via wifi (for initial communication it can also AP mode), they contain, for example, some relays, a connector for 230V devices, it can be a light bulb or a sensor. The relays (1, 2.5, etc.) are relatively open to tinkering, nor do they oppose alternative software. But the best part is that there is no need for alternative software, because the original software is excellent.
Check Use Control If checked enabled plugin is enabled.
Check Enable logging If checked enabled logging is enabled.
Show in footer Show data from plugin in footer on home page.
Blinds are added, edited and deleted individually. Existing labels and commands are preserved. Complete standard Shelly Gen1 roller URL sets are restored as the Shelly Gen1 profile, while nonstandard commands remain Custom REST URLs. The overview can be saved as cards or a compact list.
After a saved command is tested, the same blind editor remains open so additional directions and tilt positions can be tested immediately.
Enable and disable options use sliding switches. Green means enabled and red means disabled.
Shelly Gen1 uses the roller API and Shelly Gen2 or newer uses the Cover RPC API. Four configurable tilt positions are available in addition to open, stop and closed. The actual position reported by Shelly is the authoritative state.
Automation Rules can explicitly open, stop, close or select tilt position 1 to 4 for an enabled blind through the same command path as the mobile application.
Temperature shading reads the actual value channel of the selected OSPy sensor and runs the selected lowering programs only inside the configured time window, at or above the temperature limit and after the required number of consecutive fresh Wind Monitor measurements is below the safe limit.
Only new accepted Wind Monitor measurements are counted. Strong-wind protection runs after the configured number of limit exceedances occurs inside the selected minute interval, for example two exceedances during five minutes.
Selected programs run sequentially because OSPy has one Run-Now slot. Strong-wind protection has priority and removes pending lowering actions before it starts the raising programs.
Strong wind starts raising unless every enabled blind is reachable and confirmed open. Temperature shading starts lowering unless every enabled blind is reachable and confirmed closed. A closed, open, tilted, intermediate or unreachable state is therefore evaluated conservatively for the requested direction.
Temperature shading is armed only by a transition in which every enabled blind is confirmed fully open. Opening in strong wind and closing for shading remain pending until every enabled Shelly confirms the requested end position. The plug-in waits at least 60 seconds after a program starts, never overlaps an active or queued program, and retries an unconfirmed target while the applicable conditions remain satisfied. After confirmed full closure, all blinds must first become fully open again before a new shading cycle is armed.
Label for blind Naming blinds for better identification.
Command for open blind (eg: http://192.168.88.213/roller/0?go=open).
Command for stop blind (eg: http://192.168.88.213/roller/0?go=open).
Command for close blind (eg: http://192.168.88.213/roller/0?go=close).
Command for read status (eg: http://192.168.88.213/status).
Status returns something similar in json
From the status, this extension processes these returned keys
View of the relay and its connection
Screen from Shelly installed device
Check OSPy → Diagnostics first and remove passwords, tokens, private addresses and other secrets before sharing logs. Report reproducible plug-in problems in the OSPy-plugins issue tracker.