Repository navigation
Plugin automation rules
Builds graphical AND/OR rules over cached provider and OSPy values, sends detailed notifications and optionally performs guarded control actions with incident locking.
| Item | Value |
|---|---|
| Version | 1.1.4 |
| Category | Automation and integrations |
| Author | Martin Pihrt |
| License | GPL-3.0 |
| OSPy |
3.0.354 or newer |
| Python |
3.8 or newer |
| Permissions |
files, email, network, system
|
| Hardware | No dedicated hardware requirement declared |
| Dependencies | Water Meter (optional), Pressure Monitor (optional), Water Tank Monitor (optional), Current Loop Tanks Monitor (optional), Venetian Blind (optional), OSPy package Backup (optional), E-mail Notifications (optional), E-mail Notifications SSL (optional), Telegram Bot (optional) |
| Python/OS packages | None |
| Interfaces | Mobile API v1 |
| Source | Open the plug-in directory |
Builds graphical AND/OR rules over cached provider and OSPy values, sends detailed notifications and optionally performs guarded control actions with incident locking.
Version 1.1.4 makes condition entry type-aware. Boolean states such as manual mode, scheduler state, pressure presence or update availability now offer only the localized is active and is inactive choices and do not display an unused limit field. Numeric values use a numeric limit input, while text and range comparisons retain their appropriate input format. Version 1.1.3 adds concrete provider actions from Venetian Blind 1.2.4, Water Tank Monitor 1.1.1, Current Loop Tanks Monitor 1.1.1 and OSPy Backup 1.0.3. Rules can operate one configured blind, safely release tank regulation, reset the ultrasonic tank's recorded extrema or create a plug-in data backup.
Automation Rules is a graphical, optional consumer of OSPy's read-only ospy.provider.v1 monitoring contract. A rule is displayed as one main card. Its conditions are rows on a desktop and responsive subcards on a narrow screen. Rules can require every condition (AND) or at least one condition (OR).
Each condition selects a running provider, resource, value, comparison and limit. Values and canonical units come from the provider declaration, so the editor does not invent units or perform an extra GPIO/I2C measurement. Missing, stale, disabled or erroneous providers never satisfy a condition and never silently clear an already active incident.
The built-in OSPy Sensors provider also lists every enabled OSPy sensor by its configured name, independently of whether it is a Pihrt or Shelly device. It exposes the selected temperature, contact, motion, moisture, flow, output, power, voltage, humidity or illuminance reading. Pihrt multi-contact and soil devices expose each input separately. An ultrasonic tank sensor exposes its raw distance plus derived water level, fill percentage and configured volume. The adapter reads only the last cached sensor values and never polls hardware.
The built-in Date and time provider exposes the current local ISO date, 24-hour time, weekday, month and day of month. Conditions support in range and outside range comparisons written as start..end, for example 2026-05-01..2026-09-30 or 08:00..18:00. Reversed time ranges such as 22:00..06:00 cross midnight, allowing one time condition to be combined with sensor limits through AND.
The built-in OSPy status provider exposes the scheduler state, manual and scheduled modes, user water-level adjustment, remaining rain-delay seconds, rain-sensor configuration and activity, cached OSPy update availability, cached plug-in update availability and the known plug-in update count. It only reads current local and cached state; evaluating a rule does not start an update check or network request.
Rules support a confirmation duration, repeated-notification interval, recovery notification, severity and these notification channels:
- an OSPy Home popup;
- a browser notification after explicit browser permission;
- E-mail Notifications SSL or E-mail Notifications;
- Telegram Bot authorized chats;
- OSPy Mobile API push notifications.
Test mode is enabled by default. It evaluates rules and records the decisions in a bounded history but does not enqueue local notifications or send anything to external recipients. Test state is separate from live state, so testing cannot consume a later live trigger. The Test saved rule action also never sends.
Browser notifications require an open OSPy page and permission granted through the settings button. Granting permission immediately sends a browser test; a Service Worker fallback covers browsers that reject the direct Notification constructor. Mobile push remains the channel for delivery while the web interface is closed. Every live notification includes the evaluated value, operator and configured limit. Notification history stores rule decisions and delivery status, not credentials or complete provider snapshots.
Version 1.1.0 adds guarded control actions. A rule can stop one or more selected stations, stop all current outputs, disable the scheduler, stop a selected or every running program, turn a specific output off, turn a specific output on for a mandatory duration, change the global water-level adjustment, or call an action explicitly declared by another ospy.provider.v1 plug-in. Add one action row for each selected station or output. Actions normally run only once on the initial trigger; repeated and recovery notifications never repeat or reverse them.
Version 1.1.2 records every output-cycle transition in the bounded action history: initial start, pause, resumed run, failure and final stop with its reason. Water Meter 1.2.1 is the first concrete provider-action implementation and lets an explicitly configured rule reset its accumulated total consumption. Version 1.1.1 lets an output-on action use a bounded cyclic mode. Configure the on duration, the off pause and the maximum total cycling time. The next run starts only while the rule conditions are still available and matched. A false or unavailable condition, disabled rule or automation, test mode, disabled control actions, disabled manual mode, plug-in stop, rule edit or the maximum time limit immediately cancels the cycle and switches its output off. Cycles are held only in runtime memory and therefore never re-energize an output automatically after an OSPy restart. One output cannot be owned by two active cycles. This release requires OSPy 3.0.354 or newer so OSPy must be updated before Automation Rules.
Control execution has a separate global switch that is disabled by default. Test mode simulates every configured action and records the result without changing OSPy, programs, outputs or hardware. Turning an output on additionally requires OSPy manual mode, rejects disabled and master outputs and limits its duration to 1–86400 seconds. Provider actions must be declared by a running provider and implemented through the validated provider-action entry point. Failures are isolated, recorded in history and diagnostics, and do not prevent notifications from being sent.
An optional incident lock keeps a triggered rule active after its conditions return to normal. Only an administrator can acknowledge and unlock it, and unlocking is rejected while any condition is active or unavailable. Unlocking never restores an output, scheduler or water-level setting changed by an action. Existing monitoring and notification plug-ins remain independently usable.
The native mobile API exposes one metrics card per saved rule. Besides enabled state, it reports Ready, Triggered, Conditions active, Unavailable or Automation disabled and marks each individual condition Active, Inactive, Unavailable or Not evaluated. Mobile reads the same cached provider values without changing rule or incident state.
Version 1.1.2 adds complete cycle-transition history and the first concrete provider action through Water Meter 1.2.1. Version 1.1.1 adds bounded output cycling and corrects the minimum compatible OSPy version to 3.0.354. Version 1.1.0 adds guarded OSPy and provider control actions, separate default-off control permission, simulation in test mode, action delivery history, mobile lock/action status and administrator-only incident acknowledgement. Version 1.0.8 initially collapses every saved rule and the New rule card, keeps the rule being saved expanded after redirect and adds a compact localized condition-and-notification summary beside every saved rule name.
Version 1.0.7 adds the built-in OSPy status source, keeps general settings on one readable desktop row and makes saved rule cards collapsible. Rule headers now distinguish Disabled, Ready and Triggered states without presenting the status as a red action button. Version 1.0.6 prioritizes Service Worker notification delivery for Firefox and reports client delivery errors on the settings page instead of ignoring them. Version 1.0.5 adds local date/time range conditions, detailed notification messages and verifiable browser delivery with a Service Worker fallback. Version 1.0.4 adds enabled Pihrt and Shelly OSPy sensors as rule sources while preserving the read-only provider model. Version 1.0.3 displays every Boolean setting and notification channel as the same red/green sliding switch used by other OSPy plug-ins. Hovering over form fields, selectors, switches and action buttons shows a short localized description of the control. General switches are kept directly beside their labels. An explicit confirmed notification test bypasses conditions and timing, sends one real message through the channels currently selected in the rule and records each delivery result without changing incident state. Browser notifications are polled on every authenticated OSPy page. Home popup cards remain restricted to the Home page and are not consumed while the user is viewing another page. Mobile push uses the dedicated automation category when supported by OSPy and includes the stable rule ID, rule name and event in structured notification data. Older OSPy releases continue to classify the same event as other.
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.
Automation Rules evaluates cached measurements supplied by compatible monitoring plug-ins and enabled built-in OSPy sensors, including Pihrt and Shelly devices. Reading a rule never starts an additional hardware measurement.
A rule is one card. Conditions are rows on a desktop and stacked subcards on a narrow screen. Add up to twenty conditions and choose whether all conditions (AND) or at least one condition (OR) must match.
Select the provider, resource and value in this order. The available unit comes from the provider and is filled automatically.
Boolean states, such as manual mode or scheduler enabled, use the is active and is inactive comparisons and do not require a limit. Numeric measurements use a numeric limit. Range comparisons use two values separated by two dots.
The OSPy Sensors provider lists each enabled sensor by name. Ultrasonic tank sensors expose distance, water level, fill percentage and calculated volume. An offline sensor or invalid probe value cannot satisfy a condition.
The Date and time provider exposes the current local date, time, weekday, month and day of month. Use the range operators with start..end, for example 2026-05-01..2026-09-30 or 08:00..18:00. A time range such as 22:00..06:00 automatically crosses midnight.
The OSPy status provider exposes scheduler and operating modes, water-level adjustment, remaining rain delay, rain-sensor state and cached OSPy or plug-in update availability. It never starts an update check or network request.
Saved rules and the New rule card are collapsed when the page is opened. Expand a rule by selecting its heading; after saving, that rule remains expanded. A smaller description beside its name summarizes the conditions, AND or OR matching and notification channels. Disabled means the rule is not evaluated, Ready means no incident is active, and Triggered means a live incident was created after the confirmation time.
The confirmation duration requires the complete condition to remain true before the rule is triggered. The repeat interval sends another notification while the incident remains active; zero disables repetition.
Test mode is enabled by default. It records what would happen but does not display or send notifications. Test saved rule performs one immediate read-only evaluation and also sends nothing. Test notifications ignores conditions and timing and sends one real message through every channel currently enabled in the rule, even while test mode is enabled.
A missing or unhealthy provider cannot match a condition and does not clear an already active incident.
Control actions can stop selected stations, stop every current output, disable the scheduler, stop a selected or every running program, turn a specific output off, turn a specific output on for a required limited duration, change the global water-level adjustment, or call an action declared by another provider. Add a separate action row for every selected station or output.
Control actions have a separate global switch that is disabled by default. Test mode only simulates actions. Live actions run once when an incident is first triggered and are never repeated by reminder notifications or reversed by a recovery notification. Turning an output on requires manual mode and cannot directly start a master or disabled output.
An output-on action can run once or cycle for a bounded time. Cyclic mode alternates the configured run duration and off pause until the maximum cycling time is reached, but only while the rule conditions remain available and matched. A false or unavailable condition, disabled rule or automation, test mode, disabled control actions, disabled manual mode, rule edit, plug-in stop or restart cancels the cycle and leaves the output off. One output cannot be controlled by two cycles at the same time.
The action history records every cycle start, pause, resumed run, failure and final stop, including the reason why a cycle ended. Water Meter 1.2.1 or newer provides the first external action: reset its accumulated total consumption.
Provider actions can also operate a configured Venetian blind, stop Water Tank Monitor or Current Loop Tanks Monitor regulation, reset the ultrasonic tank minimum and maximum, or create an OSPy plug-in data backup. Only actions declared by a running compatible provider are offered.
Lock incident until acknowledged keeps an incident active after its conditions return to normal. Only an administrator can unlock it, and only after every condition is available and no longer active. Unlocking does not restore settings or outputs changed by an action.
The native mobile API shows one card for every saved rule. Each card reports whether automation and the rule are enabled, whether the rule is ready, triggered, waiting on active conditions or unavailable, and whether every individual condition is active, inactive, unavailable or not evaluated. Opening the mobile view reads cached provider values without changing rule or incident state.
Every live notification includes each evaluated value, comparison and configured limit. Home notifications appear in OSPy. Browser notifications require explicit permission and an open OSPy page; the permission button immediately displays a test and uses a Service Worker fallback where required. E-mail and Telegram use their existing configured plug-ins. Push uses paired mobile devices and the configured OSPy push relay.
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.
Start
Reference
Catalog sections