Repository navigation
Web Interface English
See the complete Mobile API v1 reference, also available in OSPy Help under API.
Normal application communication and push delivery are separate paths. For normal operation, the Android application connects to the local or remote address saved for an installation, verifies HTTPS, authenticates with installation-scoped Mobile API v1 tokens, reads current state and sends permitted commands directly to OSPy. The application displays connection progress and retries recoverable network failures without replacing the saved installation.
For push delivery, OSPy does not wait for the application to connect. A matching event enters a bounded background queue, OSPy signs an installation-scoped HTTPS request to the relay, the relay validates it and asks Firebase Cloud Messaging to wake Android and display the system notification. Tapping the notification opens the related saved installation. Relay or FCM failure is recorded without blocking irrigation.
In Options → Mobile applications, between Users and Security, an administrator configures the HTTPS push relay and enables immediate notifications. Push remains disabled by default, while the editable relay field is prefilled with the official OSPy relay URL. The page uses the same paired-device list as the mobile API and shows each phone's user, role, application version, pairing and last-active times, push status, and last successful or failed delivery. Categories can be selected for station start, station stop, rain, diagnostics, updates and other events. The administrator can send a test, unregister push, or revoke the complete device including its login tokens. An active device must be revoked before its record can be permanently deleted; revoked records can be deleted individually or all together. Signing in again from the same saved Android installation reuses its identity and replaces its tokens instead of adding another row.
OSPy stores neither Firebase keys nor the phone's FCM token. The mobile application registers the FCM token directly with the relay; OSPy receives only an opaque subscription identifier and an installation-scoped signing secret. Signed events are sent through a separate bounded worker, so an unavailable Internet connection or relay cannot delay the scheduler or valves. Push is disabled by default and requires HTTPS. Periodic synchronization while the app is open remains the fallback. See the exact contract in Mobile API v1.
The common OSPy footer contains a direct link to the official Android application in Google Play.
When Diagnostics reports SQLite primary beta readiness: Ready, Options enables SQLite primary (beta) in Settings storage mode. OSPy creates a complete system backup before entering or leaving this mode, commits the verified SQLite and shelve/DBM copies together, and restarts. On the next start it independently verifies SQLite before using it as the settings source; the synchronized shelve/DBM copy remains the immediate fallback. A missing marker, damaged database, checksum or schema mismatch, or invalid setting safely keeps OSPy on shelve/DBM and is reported in Diagnostics. No automatic switch occurs, and returning to Verification is available at any time through the same backup-and-restart procedure.
OSPy installation
Logging in
Home page
Normal - Water Level
Active - Rain Delay
Schedule - Manual
Enabled - Disabled
Stop All Stations
Water balance graph
Suppressed by Rain Delay
Rain sensed
CPU Temp
CPU Usage
Software version
External IP
Working
Diagnostics
Feedback
Programs page
Add a New Program
Program groups
Add group
Rename group
Enable or Disable a group
Copy group
Delete group
Run Now
Edit
Copy
Move to group
Delete All
Enable or Disable a Program
Conflict warnings
Schedule type
Selected days (Simple)
Start time
Duration
Repeat
Repetitions
Pause
Selected days (Advanced)
Schedule
Repeating (Simple)
Water interval
Starting in
Start time
Duration
Repeat
Repetitions
Pause
Repeating (Advanced)
Water interval
Starting in
Schedule
Weekly (Advanced)
Monday-Sunday
Custom
Water interval
Starting in
Day 1 - Day 7
Weekly (Weather based)
Irrigation min
Irrigation max
Run max
Pause ratio
Preferred Execution Moments
Day
Start time
Priority
Add - Delete
No adjustments
Cut-off
Activate Master
Run Once page
Run Now
Reset Time
Plugins page
Manage
Install New Plugin
Custom plug-in (ZIP)
Github (https://github.com/martinpihrt/OSPy-plugins/archive/master.zip)
Disable All
Enable All
Enable check updates
Load changes
Changes
Automatic updates
Log page
Events log
Download log as
Clear Log
Clear Log Email
Options page
System Section
Show Tooltips
Set System name
Select System theme
Clock format
HTTP IP addr
About the port number
HTTP/S port
Show plugins on home
Show sensors on home
Select Language
Show pictures at stations
Weather Section
Use Weather
Weather provider
Stormglass API key
Location
Users Section
Disable security
Admin login name
Current password
New password
Confirm password
Aditional users
Security Section
Form protection
Use HTTPS access
Domain name
Use Own HTTPS access
API CORS allowed origin
Enable API JSONP
Remembered browser logins
Sensors Section
Password for uploading
Station Handling Section
Maximum usage
About Sequential and Concurrent modes
Number of outputs
Pause between stations
Minimum runtime
Configure Master Section
Master station
Master two station
Activate relay
Master start offset
Master stop offset
Master two start offset
Master two stop offset
Rain Sensor Section
Use rain sensor
Normally open
Set rain delay
Rain delay time
Logging Section
Enable run log
Max run entries
Enable email log
Max email entries
Enable events log
Max events entries
Enable debug log
System Restart Section
Restart
Reboot
Shutdown
Default
System Backup Section
Download
Upload
SSL Certificate
Upload
Generate
Stations page
Station
Name
Usage
Precipitation
Capacity
ETo factor
Balance adjustment
Connected
Ignore Rain
Activate Master?
None
Activate Master
Activate Master Two
Activate Master 1/2 by program
Notes
Image
Sensors page
Add a New Sensor
Sensor Parameters
Delete All sensors
Help page
OSPy
Readme
Changelog
Programs
Web Interface Guide - Czech
Web Interface Guide - English
Web Interface Guide - German
Web Interface Guide - Polish
Web Interface Guide - Russian
Web Interface Guide - Serbian
Web Interface Guide - Slovak
API
Readme
Details
Plug-ins
Readme
Usage Statistics
LCD Display
Pressure Monitor
Voice Notification
Pulse Output Test
Button Control
CLI Control
System Watchdog
Voltage and Temperature Monitor
Remote Notifications
System Information
MQTT
Air Temperature and Humidity Monitor
Wind Speed Monitor
Weather-based Rain Delay
Relay Test
UPS Monitor
Water Consumption Counter
SMS Modem
Signaling Examples
Email Notifications
Remote FTP Control
System Update
Water Meter
Energy Meter
Webcam Monitor
Weather-based Water Level Netatmo
Direct 16 Relay Outputs
MQTT Zone Broadcaster
System Debug Information
Weather-based Water Level
Real Time and NTP time
Water Tank
Humidity Monitor
Monthly Water Level
Pressurizer
Ping monitor
Temperature Switch
Pool Heating
E-mail Notifications SSL
Sunrise and Sunset
Photovoltaic Boiler
IP CAM
Modbus stations
CHMI
Proto
Label Maker
IP Scanner
Database Connector
OSPy Backup
MQTT Home Assistant
Shelly Cloud Integration
Current loop tanks monitor
The recommended clean installation uses Raspberry Pi OS or Debian 12 and Python 3.11 or newer. The installer always downloads the stable OSPy master branch. On first start, the login page displays a generated administrator password; change it immediately in Options after signing in.
Login to the Pi using SSH. Type or copy and paste the following command: Remember: Raspberry Pi commands are case sensitive.
wget https://raw.githubusercontent.com/martinpihrt/OSPy/master/ospy_setup.sh
sudo bash ospy_setup.shThe menu separates core requirements from optional MQTT and multimedia packages. Choose /opt or the invoking user's home directory. The installer never deletes, resets or automatically updates an existing Git checkout. It builds the service from the versioned systemd template, starts it and verifies its state; recent service output is shown when startup fails. A reboot is recommended only for I2C or group changes. Open a successful installation on port 8080. The Clean installation Help document contains the detailed safe procedure, manual update and local account recovery instructions.
After clicking the "Logging out" button, the user logs out of the system.
The optional Automation Rules plug-in creates graphical AND/OR rules from cached monitoring plug-in values, enabled Pihrt or Shelly OSPy sensors, local date/time and read-only OSPy operating states. A rule can wait until conditions remain true, repeat an alert and report recovery through Home, browser, e-mail, Telegram or mobile push. A separate default-off control switch enables guarded actions that stop selected stations, all outputs or running programs, disable the scheduler, operate a specific output once or in a bounded run/pause cycle in manual mode, change the global water-level adjustment or call an action explicitly declared by another provider. Action history records every cycle start, pause, resumed run, failure and final stop with its reason. Water Meter 1.2.1 provides the first concrete provider action for explicitly resetting its accumulated counters. Test mode only simulates actions and records results. Optional incident locking requires administrator acknowledgement after all conditions become available and inactive; unlocking never reverses an executed action.
The optional Irrigation Safety plug-in combines actual OSPy station and master-output state with cached Water Meter, Pressure Monitor and tank-monitor values. Each enabled station can have an expected minimum and maximum flow, startup delay and fault-confirmation time. Automatic learning accepts samples only after startup delay and while exactly one station runs, then saves a robust range expanded by a configurable safety margin. Fully configured simultaneous stations use the sum of their ranges. The plug-in can also detect flow without irrigation, unavailable flow, missing pressure and a low or unavailable tank value.
Use Monitor only while commissioning. Active protection can stop all current outputs, switch off the separate master relay, disable the scheduler and keep an incident locked until an administrator acknowledges it after the fault clears. A bounded temporary bypass suppresses control actions but keeps monitoring and notifications active. Safety actions run before asynchronous e-mail or native mobile push delivery. The page refreshes measurements, active stations, learning progress, incidents and bounded history in the background.
Compatible running providers add their own guarded actions. Venetian Blind can open, stop, close or select tilt 1–4; Water Tank Monitor can stop regulation and reset recorded minimum and maximum values; Current Loop Tanks Monitor can stop regulation for one tank or all tanks; and OSPy Backup can create a plug-in data archive.
Two-factor authentication protects the main administrator account with a second verification step after the password. Open Options → Two-factor security → Configure and choose exactly one method: Authenticator application (TOTP), Code sent by e-mail, or Disabled. The two methods cannot be active at the same time.
For TOTP, run python setup.py install once if QR support is reported missing. Scan the displayed QR code with Google Authenticator, Microsoft Authenticator, 2FAS, Aegis, or another TOTP application, then enter its current six-digit code. OSPy activates the secret only after this confirmation. Correct system time is required for TOTP.
E-mail verification is available only while E-mail Notifications SSL is installed, running, and has its SMTP server, account, password, and recipient configured. When enabling it, OSPy sends a confirmation code immediately. Login codes expire after five minutes and are never placed in the plug-in's retry queue.
After enabling either method, save the displayed one-time backup codes in a safe place. Each code can replace the normal second factor once and is then deleted. They are not shown again. Changing or disabling 2FA revokes all remembered browser logins. A remembered browser is trusted only after a complete password and second-factor login. If the phone is lost or e-mail is unavailable, use a backup code; without a backup code, restore a configuration backup or reset the 2FA settings locally on the OSPy device. Logging out
The login page presents a text field for entering a name and password. The default name is admin. During the first installation, a random password will be generated (this password must then be changed to a different password in the settings! On the page - tab "Options page" it is recommended to change the password (or even the name) to your own new password. Enter name, password and click the LOG IN button.
The home page is the main control center of the web interface. This includes:
- Clock showing current time On all pages.
- Navigation bar at the top for moving between pages. The interface is also found on other pages besides the login page.
- A set of buttons for making global changes to system behavior.
- A timeline that provides information about completed and scheduled irrigation events.
- A graph that provides information about irrigation events.
- The footer that is present on all pages (if the user is logged in). The footer contains: CPU Temp, CPU Usage, Software version, External IP, Working.
- Some extensions can inject homepage and add other elements. For example, the astral extension adds graphical representations of sunrise and sunset to the timeline. Extension tank monitor graphic column with volume and amount of water.
A button that allows you to set the "water level" as a percentage of the total run time for all irrigation programs (for programs, increase or decrease their set time).
Rain delay. A button that allows watering to be paused for a specified period of time for all stations except those that have been set to ignore rain on the Stations page.
Schedule - Manual. A button that switches the system between schedule (automatic mode) and manual mode, which allows direct control of stations.
Button for enabling or disabling the running of the OSPy program (when disabled, the scheduler will not run).
The "Stop All Stations" button is used to immediately cancel a running irrigation program or an active station.
For every enabled station used by an irrigation program, the graph at the bottom of Home shows the running water balance. Each day combines evapotranspiration (ETo) adjusted by the station ETo factor, rain unless the station is configured to ignore it, and completed or planned irrigation. Point details distinguish ETo, rain, individual program contributions and the resulting total for historical and forecast days.
When Use Weather is enabled, ETo and rain come from the selected Open-Meteo, CHMI ALADIN or Stormglass provider. A provider API key is required only for Stormglass; Open-Meteo and CHMI must not depend on a legacy Dark Sky key. With weather disabled, the station ETo factor and zero rain are used. If the balance data cannot be loaded, Home shows a visible error and OSPy records the technical details in the log instead of silently leaving an empty chart.
If the rain delay is enabled, "Suppressed by Rain Delay" will be displayed and all stations (except those set to ignore rain on the Stations page) will be blocked for a period of time.
If the rain sensor is activated, "Rain sensed" will be displayed and all stations (except those set to ignore rain on the Stations page) will be blocked.
Raspberry pi processor temperature. The displayed temperature can be switched between C and F.
Raspberry Pi CPU usage. Usage is shown in %.
Link to the project software repository and the revision number of the installed software.
Stable builds checked out from master use the numeric version, for example 3.0.238. Test builds checked out from beta show the same revision with the -beta suffix, for example 3.0.238-beta. Promoting that commit to master removes the suffix without changing the revision number.
Before every update, the System Update plug-in first saves the settings and creates a verified safety backup. It then starts an external watchdog before changing any Git-tracked files. On systemd installations, the watchdog runs in a separate transient service and remains active while OSPy restarts. A detached helper process is used without systemd.
The new OSPy process confirms a successful update only after the scheduler records a fresh heartbeat and the web interface starts accepting connections. If a healthy start is not confirmed within 120 seconds, the watchdog automatically restores the previous commit and original branch and restarts OSPy. If the watchdog cannot be started, the update stops before tracked files are changed. The watchdog result is also available in Diagnostics as part of the System Update plug-in health information.
System Update displays the full commit of the running revision and the exact target commit from the selected channel. It recognizes a verified stable release only as an annotated Git tag named vX.Y.Z whose commit is reachable from origin/master. The annotated tag message is used as the short release notes. Lightweight tags, other names and tags outside master are not offered.
Rolling back to the last verified stable release or manually to an older commit first saves the settings, creates a verified safety backup and starts the same external watchdog as a normal update. A stable rollback switches the working branch to master. The project maintainer creates release tags manually only after successful tests; the plug-in never creates tags itself.
External IP address for the OSPy system (address of your connection provider - router). Tested via pihrt.com.
The time the Raspberry pi system has been running since it was powered on (or restarted).
The Database row also shows the active settings storage and SQLite readiness. This transition release continues to read and write the existing shelve/DBM files. The readiness check uses only a temporary in-memory database and by itself creates no file or data migration. If Python SQLite support is unavailable, OSPy continues using shelve/DBM and reports the reason as passive information rather than a system failure.
After each successful settings save, OSPy creates a verified options.sqlite3 shadow copy next to the active shelve/DBM files. It is written through a temporary file and atomically replaced only after schema, key, value and integrity checks succeed. OSPy never loads settings from the shadow during startup. A synchronization failure leaves the authoritative shelve save intact and appears as a warning in the Database row; a missing shadow waits for the next settings save.
At startup OSPy compares the authoritative shelve values with SHA-256 hashes stored in shadow schema 2. It does not unpickle shadow values during this automatic comparison and never uses them to recover or start OSPy. A matching shadow is marked verified; missing, changed or unexpected keys and checksum or database damage are reported as warnings while shelve remains in use. A schema 1 shadow from the preceding transition phase is not read and is replaced safely on the next settings save.
At startup and after every successful shadow replacement, OSPy performs a dry-run decode only after every key and checksum matches a single read-only snapshot, then applies the normal settings validation to the reconstructed SQLite values. The reconstructed dictionary is discarded and never assigned to the running configuration. Diagnostics reports whether this SQLite read test passed; failure remains a warning and OSPy continues exclusively with the already active shelve settings.
Shadow schema 3 also contains a manifest with the total record count and a checksum over the complete sorted key/checksum list. This independently detects removed or added rows before decoding. OSPy performs and discards a full recovery dry run for both the current SQLite shadow and the previous shadow in the backup directory. Diagnostics reports both results. A failed or unavailable recovery candidate never changes startup selection; shelve/DBM remains authoritative.
At startup OSPy uses the first independently verified SQLite candidate only for a restore rehearsal in an isolated temporary directory. It creates a temporary shelve/DBM database, reopens it, validates every setting, compares the serialized values and then removes the directory. Neither the active database nor the startup settings source is changed. If the current SQLite copy is damaged, the rehearsal may use the verified backup while running settings still load from authoritative shelve. The Database row in Diagnostics reports the result, source and setting count.
OSPy also only simulates the emergency decision that would be made if every shelve/DBM database were invalid. The independently verified current SQLite copy has priority; the verified backup would be selected only if the current copy failed. The selected dictionary is discarded and never assigned to running settings, so this state still does not activate SQLite recovery. Diagnostics reports readiness, the hypothetical source and the setting count.
The experimental Allow emergency SQLite settings recovery option in Settings storage is disabled by default. When enabled, OSPy creates a non-secret atomic activation marker only after independently verifying a schema-3 SQLite copy; the verified copy itself must also contain the enabled option, so neither the marker nor the database authorizes recovery alone. Recovery is attempted only when the current, temporary and backup shelve/DBM databases are all invalid. OSPy prefers current SQLite, falls back to the verified backup, rebuilds and revalidates a shelve database in the temporary directory, and only then loads it. This step does not overwrite the existing current or backup directories, and normal persistence remains shelve/DBM. Disabling removes the marker before writing settings. Diagnostics and the startup recovery message identify actual use or failure; review the system and create a backup after recovery.
The experimental Prefer verified SQLite settings reads option in Settings storage is also disabled by default. When enabled, OSPy always loads and validates shelve/DBM first, compares the complete SQLite key and checksum set with that exact authoritative snapshot, and independently decodes and validates every value. Only a complete match assigns the equivalent SQLite dictionary to the running settings. A missing copy, difference, corruption or decode failure keeps the already loaded shelve values without interruption. Writes, directory rotation and backups continue to use shelve/DBM exclusively; SQLite remains a verified shadow. Diagnostics reports whether the path was used, disabled or fell back to shelve.
The experimental Require verified SQLite for settings commits option in Settings storage is disabled by default. When enabled, a new settings directory may replace active data only after both its temporary shelve/DBM database and SQLite copy are written and independently verified. If SQLite is unavailable or writing or verification fails, OSPy removes the complete uncommitted temporary directory, preserves the previous active settings and last-save timestamp, and reports a settings-write problem. Disabling restores compatible shelve-first behavior. A successful strict commit can be read through the verified SQLite path, but shelve/DBM remains the persistence and backup format. Diagnostics reports the active commit policy.
Diagnostics keeps non-authoritative SQLite migration evidence: consecutive successful starts using verified reads and consecutive strict dual-writes. A failure resets only the relevant streak and records its time and reason. The separately and atomically written status file contains no settings and is never used for startup, recovery or storage selection.
During early startup, the interface language is still loaded first from a valid shelve/DBM database. When verified SQLite reads are enabled, the bootstrap compares every key and checksum with that exact shelve snapshot and reads only the lang value from SQLite after a complete match. A missing, older, different or damaged SQLite copy always falls back safely to the shelve language. Checking a missing database does not create an empty file.
The Settings storage mode selector groups the safe transition controls. Compatible keeps shelve/DBM authoritative with SQLite as an optional shadow. Verification enables emergency recovery, verified reads and strict dual-write; it still does not make SQLite the primary database. The individual switches remain available for advanced control, and a mixed combination is automatically labelled Custom advanced settings. Existing installations derive the mode from their saved switches without changing their values.
Diagnostics also evaluates a passive SQLite primary beta readiness gate. Ready requires Verification mode, a verified current shadow, successful read and recovery checks for both current and backup copies, a successful restore rehearsal and emergency-selection dry run, enabled emergency recovery, verified reads and strict dual-write, plus at least five consecutive verified starts and twenty strict writes. Until then Diagnostics shows whether evidence is still being collected or lists the blocking checks. This gate never switches the storage backend automatically; shelve/DBM remains authoritative.
The Diagnostics button in the footer opens an administrator page for checking how OSPy and its plug-ins are using the system.
When Diagnostics reports an error, it opens a red window with the problem, available details, a possible solution and a link to the related page. Administrators can also show the same window on the Home page by enabling Options > Diagnostics > Show diagnostic errors on the home page. This error window has priority over the update notification. Disabling the option affects only the Home page; errors remain visible in Diagnostics.
The page uses collapsible System status, Performance and processes, and Security check sections. Select a dark section bar to expand or collapse it. System status gives each operational area an OK, warning, error or not-configured state. It monitors the scheduler heartbeat, the last successful schedule calculation and next run, output command writes, sensor communication, settings database accessibility, free disk space, enabled plug-in failures, e-mail readiness, weather, internet connectivity and the newest available backup. A successful output write confirms that OSPy sent the requested state to the output driver; it does not claim that a physical relay switched unless hardware feedback is available.
The last Operating system health row runs a failure-contained Linux and root-storage check in the background and caches it for ten minutes. Its overall row uses green OK, yellow Warning and red Critical states, while every detailed check is marked OK, Warning, Critical or Information. It checks the root mount mode, disk space, inodes, a small synchronized write/read probe, accessible EXT4 and SD identity data, Raspberry Pi power throttling, CPU temperature, memory, load, failed systemd services and bounded kernel-log evidence of MMC, I/O, EXT4, read-only remount, panic, lockup and out-of-memory failures. Missing commands or permissions are shown without stopping OSPy. The check never uses sudo and never runs fsck or another repair command on the mounted root filesystem.
The How OSPy works section provides interactive diagrams for programs and scheduling, station-start decisions, master stations, weather, sensors, the plug-in lifecycle, safe updates, settings storage, and backup and restore. A diagram can be zoomed, opened at full width, printed, or downloaded as SVG or PNG. Nodes with a dotted outline open the related OSPy page, and a separate button opens the relevant help. The Mermaid renderer is stored in OSPy and does not require Internet access.
Additional security topics explain the complete protected web-request path, HTTPS and certificates, login with two-factor authentication, sessions with CSRF and remember-me tokens, and API and sensor security. The diagrams distinguish authentication from role authorization and CORS, show brute-force protection, and note that OSPy stores only a hash of the secret part of a long-term login token.
Further diagrams cover irrigation priority and concurrency, rain and water balance, the output-hardware command path, user roles, events and incidents, notification delivery, OSPy startup and shutdown, plug-in permission approval, the complete sensor lifecycle, and safe network exposure. The Clean OSPy installation diagram follows the real guarded installer from Linux and Python checks through the stable master branch, dependencies, SQLite and systemd to the first login and replacement of the generated password.
The Languages row compares every translation catalog with the current template and shows each language's translated percentage and exact missing-string count. A complete translation is green, coverage of at least 80% is yellow, and lower coverage is red. This is information for translation maintainers only: language status does not change overall system health or open the Diagnostics error window.
Security check passively assesses HTTPS, anonymous access, two-factor authentication, sensor API authentication, API CSRF protection, CORS, the sensor password and recommended HTTP response headers. It never displays the sensor password and does not change any setting. The Home network profile treats selected compatibility compromises as warnings, while Internet access requires encrypted, authenticated and restricted access. Every finding explains the current state, a recommendation and a link to the related settings. A reverse proxy may add HTTP security headers after the response leaves OSPy; Diagnostics reports only what OSPy itself can guarantee.
Caught core operational failures appear in System status as separate active problems. Each entry identifies the affected component, occurrence count, latest occurrence, technical cause and a recommended recovery action. A successful retry automatically clears the active problem, while the full traceback remains in the event log. Expected compatibility fallbacks are not reported as failures.
The collapsible Incident history section retains up to 200 recent problems across OSPy restarts. It can filter all, active, resolved and restart-interrupted incidents. Repetition of the same active problem increments its count instead of creating duplicates; the table shows when it opened, last occurred and resolved. History is atomically stored in a validated size-limited JSON file and does not duplicate full tracebacks.
The system summary shows current CPU usage, CPU temperature, system uptime, load average, OSPy process CPU usage, OSPy memory usage, thread count, platform information and the last refresh time.
The plug-in table shows every available plug-in, whether it is running and enabled, its own operational health, current CPU load, total CPU time, thread count, start time, restart count and available actions. A plug-in can optionally provide a health() function returning, for example, {'status': 'ok', 'summary': '...', 'details': '...'}; accepted states are ok, warning, error and unknown. Older plug-ins without this function remain fully compatible and show “not reported”. A failed or timed-out health check does not stop the plug-in or the Diagnostics page. Data refreshes automatically, so the page can be left open while watching system load.
By default, plug-ins are sorted by current CPU load from highest to lowest. Use Sort plugins to switch sorting to plug-in name or total CPU time when you want a stable list or want to find long-running CPU consumers.
The Open action opens the plug-in page. Restart plugin restarts only the selected running plug-in; it does not restart all of OSPy.
If a refresh warning is shown, the last automatic read from the diagnostics API failed or returned a controlled error. Existing data can remain visible until the next successful refresh, and the warning is cleared automatically after a successful refresh.
The Feedback button in the header, to the left of the system name, opens a page for reporting bugs, suggesting improvements and asking questions. The page is available to signed-in administrators and users; the button is hidden on the login page.
Choose Bug report, Feature request or Question, then enter a short title and a detailed description. Continue to GitHub opens a prefilled new GitHub Issue. The user signs in to GitHub, reviews the content and submits it there. OSPy does not store a GitHub access token and does not create an Issue before this confirmation.
The option to include system information is enabled by default and shows an exact preview before submission: the OSPy version and date, architecture, distribution and operating-system version, and Python version. The OSPy system name, operator name, IP addresses and unique usage-statistics identifier are excluded. Clear the option to send only the user's text.
View existing reports opens the project's GitHub Issues. GitHub Discussions opens the project discussions directly and is suitable for general questions and shared ideas. Screenshots and other files can be attached after GitHub opens.
The form uses the existing OSPy login and CSRF protection. When leaving for GitHub, the address of the open OSPy page is not sent as the HTTP referrer.
With the button "Add a New Program" we create a new scheduler program.
Programs can be organized into drop-down groups. Groups are suitable, for example, for separating summer and winter programs, or for a clear division by part of the garden.
The "Add group" button creates a new program group.
The rename group action changes only the group name. Programs assigned to the group will be retained.
A group ON/OFF action enables or disables all programs in that group at once. It is suitable, for example, for seasonal switching of several programs.
The copy action creates a new group and copies all programs from the original group into it. The copied programs are made disabled so they don't run until we check them.
Group deletion requires confirmation. Programs from the deleted group are moved to the default group.
The "Postpone group" button next to "Add a New Program" moves the nearest scheduled run of the whole group once. Select a new date and start time for the first program; a preview of the original and new time range is shown before confirmation. The new start must be later than the original start, must be in the future, and can be set no more than 30 days ahead.
OSPy finds the nearest future run of every enabled program in the group and shifts all these runs by the same time difference. Program order, durations, and relative gaps are preserved. For example, a group scheduled today from 18:00 to 22:00 can be postponed until tomorrow at 07:00; the shifted run will then finish at approximately 11:00.
Postponement does not change the normal program definitions or their later scheduled days. Only the nearest original run is skipped once and its replacement runs at the new time. Postponed programs still respect the scheduler state, rain blocks, the rain sensor, output usage limits, and station delays. The postponement is saved in the settings and survives an OSPy service restart. Only one active postponement is allowed per group.
An active postponement is displayed beside the group as the original time, an arrow, and the new time. Use "Cancel postponement" to remove it. If the original time has not arrived, the normal original run is restored. If the original time has already arrived, it is not started again for safety; only the replacement run is cancelled. A group with an active postponement cannot be deleted; cancel the postponement first. Creating and cancelling a postponement is available only to an administrator and is protected by login and CSRF verification.
With the button "Run Now" we start the program immediately regardless of the time and date of the scheduler.
The "Edit" button is used to modify the parameters of an already created program.
The "Copy" button creates a copy of the selected program. Copy is disabled by default, so we can safely modify it before using it in the scheduler.
A program can be assigned to a group on the program edit page. This only changes its location on the Programs page.
The "Delete All" button removes all existing programs after confirmation.
The "ON/OFF" switch allows the created program to be enabled or disabled in the scheduler.
When saving a program, OSPy checks the allowed programs and looks for overlaps of the scheduled run on the same station/output. If another program is scheduled at the same time, the Programs page will display a notification with the overlap time. This is just a warning, the program will not be automatically blocked or modified.
Scheduler type allows to choose the suitable program type according to our requirement (selected days, repeat, weekly, custom and programs based on weather forecast).
Changing the type changes both the visible fields and the way OSPy builds the schedule. Review all values before saving after changing a type. In graphical schedules, click once to mark the beginning and again to mark the end; use the cross on an existing interval to remove it. Times are interpreted in the local time of the OSPy system.
Every existing recurring program can be further restricted by calendar rules. Allowed months can be selected individually or with spring, summer, autumn, winter and all-year shortcuts. Calendar day parity allows all, odd or even dates, and Days of month accepts selected values from 1 to 31. These rules are combined with the normal weekdays or repeat interval; leaving their default values preserves the original schedule.
Excluded dates accepts one item per line: an exact date (YYYY-MM-DD), an exact inclusive range (YYYY-MM-DD..YYYY-MM-DD) or an annual inclusive range (MM-DD..MM-DD). Annual ranges may cross New Year. A blocked occurrence remains visible in the schedule with its reason. Do not run on public holidays uses the locally installed holiday calendar. OSPy detects the country from the weather location; Options → Weather → Holiday country override can supply another two-letter country code. If the library or country is unavailable, only programs that requested holiday exclusion are safely blocked; OSPy itself and other programs continue running.
The Service outages section on the Programs page creates named global start/end intervals. Overlapping automatic runs are shown as blocked, while Run Now remains available for a deliberate service test. Outages are saved across OSPy restarts.
The Sunrise based and Sunset based program types are available only while the existing Sunrise and Sunset plug-in is enabled, its Astral calculation is active and a valid location is available. The program can start before or after the calculated event with a signed minute offset. An earliest and latest allowed time limit the result; an out-of-window run can be moved to the nearest boundary or skipped. Duration, pause, repetitions, selected weekdays and all calendar rules still apply. OSPy never guesses a fixed time when the plug-in is unavailable and retains the saved program until the provider recovers.
Runs the same simple schedule on each selected weekday. Select one or more weekdays and set the first run below.
The time at which the first run starts on every selected day.
The number of minutes for one run of each selected station.
Enables additional runs on the same selected day after the first run.
The number of additional runs after the first one. For example, 2 produces three runs in total.
The number of minutes between the end of one run and the beginning of the next repetition.
Runs user-drawn intervals on each selected weekday. This type is suitable for several unrelated start and stop times in one day.
Use the 24-hour graphical row to add one or more start/end intervals. The same intervals are copied to every selected weekday.
Runs a simple schedule every configured number of days, anchored to a chosen start date instead of fixed weekdays.
The number of days between active days. 1 means every day, 2 every other day.
The number of days from today to the first active date. 0 starts the cycle today.
The time of the first run on each active day.
The number of minutes for one run of each selected station.
Enables additional runs on the same active day.
The number of additional runs after the first one.
The delay in minutes between repeated runs.
Repeats a graphical daily schedule at a fixed interval of days.
The number of days between executions of the drawn schedule.
The delay in days from today to the date that anchors the repeating cycle.
Draw all start/end intervals for one active day. OSPy repeats this complete set after the selected water interval.
Defines an independent graphical schedule for every weekday and repeats the complete schedule every seven days.
Draw intervals directly in the row for the required weekday. Each day may contain several intervals or remain empty.
Defines an explicit multi-day repeating cycle. Use it when the predefined simple and advanced patterns cannot express the required sequence.
The length of the repeating cycle in days. After the last cycle day, scheduling returns to Day 1.
The number of days from today before Day 1 of the custom cycle begins.
Draw start/end intervals independently on the displayed cycle days. An interval is stored as minutes from the beginning of Day 1.
Plans irrigation from station water balance and the weather forecast. The listed moments are opportunities; OSPy may skip or shorten them when the calculated deficit does not require watering.
The minimum water deficit in millimetres at which irrigation is allowed to start.
The maximum amount in millimetres that may be supplied to a station at one preferred execution moment.
The maximum amount in millimetres that may be supplied continuously before OSPy inserts a pause.
The pause length as a percentage of the preceding continuous run time. For example, 50% adds a pause half as long as the run.
The ordered list of weekly opportunities when weather-based irrigation may run. At least one moment is required.
The weekday of the preferred execution opportunity.
The local time at which OSPy evaluates and may start this opportunity.
The relative preference between opportunities. A higher value makes the moment preferable when watering can be deferred.
Adds another preferred moment or removes the selected row. Deleting every row leaves no opportunity to run.
No modifications will be applied to this program (for example shortening or extending the time)
If the adjusted running time of the program would be shorter than this set time, the program will be skipped (for example, the adjusted running time from the weather forecast extension, or the monthly adjustment of the amount of water and other extensions). The time is set in percentages.
All stations that have the "Activate Master 1/2 by Program" option set will activate Master Station 1/2 according to this assignment in the program. Notification! for stations that have the option "Activate main 1/2 by program" set, the control option "run once" and "manual_on" cannot be used. Only the station will start, not the main station (1 or 2)! This setting is only available if you are using both master stations!
The "Run Once page" page presents a list of allowed stations with a minute and second field for each. This site can be used to test and provide additional irrigation on a one-time basis.
The button activates all selected preset stations.
The button will delete all preset times for all stations.
On the page "Plugins page" we can configure or control all extensions in the OSPy system.
Clicking the "Manage" button will open the extension manager window in OSPy. All available extensions can be turned on, off, installed from repository, etc...
A plug-in uses a plugin.json file containing its name, version, description, author, homepage and license. The manager displays this metadata when available. Backward compatibility is retained for older plug-ins already installed without a manifest, and OSPy reads their name from __init__.py; the rules for new installations are described below.
The manifest may declare dependencies on other plug-ins by directory name in the dependencies list. A required dependency must be installed and enabled. An optional dependency does not block the consumer, but when both plug-ins are enabled OSPy starts the provider first. Shutdown uses the reverse order, and dependency cycles are not started. A bulk installation may provide a required dependency in the same ZIP; installing only the consumer requires its provider to be installed already.
Before activation OSPy checks declared OSPy and Python versions, required Python modules, supported platforms, GPIO/I²C availability and conflicts with enabled plug-ins, GPIO pins or I²C addresses. A blocking problem prevents activation and Enable All skips the affected plug-in. Plug-in management and Diagnostics show details and declared network, file, I²C, GPIO, e-mail, subprocess or system permissions. Permissions inform the administrator; they are not an isolated operating-system sandbox.
Starting with OSPy 3.0.294, an administrator must explicitly approve the permissions declared by a newly installed plug-in before its code can start. The one-time upgrade migration automatically preserves approvals for every plug-in that was already installed, including disabled plug-ins, so updating OSPy does not interrupt existing installations. An unchanged or reduced permission set remains approved; adding a permission blocks manual and automatic updates until the administrator reviews and approves the new set. Revoking approval disables the plug-in. Approval is stored in OSPy as an administrative decision and audit record; it does not create an operating-system sandbox.
New plug-ins can use the shared thread lifecycle and OSPy stop signal. When disabling a plug-in, OSPy first sends the stop signal, calls its existing stop() function and waits up to five seconds for registered threads. Threads that remain alive are reported as an error in Diagnostics and prevent a second copy of the plug-in from starting. Existing plug-ins without this interface remain compatible.
Before import and startup, an automatic static test runs without executing plug-in code or accessing hardware. It checks the directory, __init__.py, Python source syntax and size, the optional manifest and, for manifest-based plug-ins, declared start() and stop() functions; legacy plug-ins without a manifest retain their existing compatibility. Symbolic links are not followed. An error prevents activation and details are available in Plug-in management and Diagnostics. Compatibility, manifest and test information use high-contrast status panels in Plug-in management so they remain readable for both enabled and disabled plug-ins.
Clicking the "Install New Plugin" button opens a window with a remote repository where we can select the available extensions to install on the OSPy system and read general information about the extensions.
Before copying any files, OSPy safely reads plugin.json directly from the downloaded ZIP archive and displays the compatibility state and specific reasons for any problem for each plug-in. An incompatible plug-in cannot be installed or updated manually. A plug-in with warnings remains installable after the warnings are shown. Bulk installation installs compatible plug-ins and skips incompatible ones while reporting the reasons. The same validation applies to custom ZIP files, individual and bulk operations, and updates. A missing, invalid, or oversized plugin.json is an installation error for a new installation; already installed legacy plug-ins without a manifest can continue to run in backward-compatibility mode.
If an I2C plug-in can use one of several alternative addresses, compatibility checking treats the declaration as one selectable resource rather than as all addresses being occupied at once. Repository and custom-ZIP installation is allowed when a distinct address remains available. On activation the plug-in keeps its preferred address or selects a free alternative. Its settings reject an address already used by another enabled plug-in, preserve the previous settings and display the conflict in a red status bar without leaving the page.
OSPy validates the complete ZIP before writing any plug-in file. The archive must contain at least one plug-in directory with __init__.py and a valid UTF-8 plugin.json whose id matches the directory name. A plug-in may also contain Python modules, README.md, templates, static, script, docs, i18n and data. A repository archive may place plug-ins below plugins/; a custom archive may contain a plug-in directly at its top level.
Absolute or parent-directory paths, non-portable names, duplicate paths or plug-in identifiers, symbolic links, special or encrypted entries and damaged archives are rejected. Limits are 64 MiB downloaded ZIP data, 4,096 archive entries, 256 plug-ins, 32 MiB per expanded file, 128 MiB total expanded data and a maximum compression ratio of 200:1. Installation is atomic for each plug-in: files are prepared first, existing data is preserved, and a failed replacement or start restores the previous version.
The extension manager allows you to install your own extension in the OSPy system, which is not published in the remote repository (for example, your personal extension). Using the "browse" button, we select the desired file on our computer to install into the OSPy system. The extension file (zip) must contain the complete structure of the extension (init, templates, i18n, readme, etc.).
The plug-in manager uses the stable master channel by default. An administrator can switch to the test beta channel; the selected channel is visible in management and installation and is used for the list, manual installations, bulk operations and automatic updates. Test versions may contain errors. Switching channels discards the downloaded cache for the previous branch, and the next check loads data from the new branch. Opening an installed plug-in page displays its name and the version read from plugin.json above the plug-in content.
The manager page opens without waiting for GitHub. Repository data is loaded in the background, while the summary at the top shows checking progress, an error, an up-to-date result, or the number and names of available updates. Each update name links directly to the affected plug-in.
Compatibility, permission approval, manifest metadata and the pre-activation test are collapsed under Technical details for each plug-in. A repository check starts automatically only when no repository data is available yet; simply enabling or disabling a plug-in does not repeat it. Approve all permissions stores the currently declared permissions of all installed plug-ins after one confirmation. Update all confirms the displayed source and updates only installed plug-ins for which a new version was detected.
There is a repository of available extensions for the OSPy system at the above location.
Installing or updating an extension runs code from the selected source. OSPy will display the repository URL and ask for confirmation before installing or updating. The Fetch Changes action while contacting the remote repository displays a message about the check in progress.
The button disables all installed extensions.
The button will enable all installed extensions.
When the button is active, the availability of a new version of the extension is automatically checked in the remote repository after an hour. When a new version is available, an "update" message will appear next to the extension.
The button retrieves the latest list of available changes from the remote extension repository.
The button opens an overview of available extension changes and update information.
When the button is active, this extension will automatically be updated when a new compatible version is available. An incompatible new version is not installed automatically, and the manager displays the reason. Warning: OSPy is constantly evolving and if there is a major change in OSPy and the user does not update OSPy, the extension may not work after the update. Always update OSPy first and then all extensions!
Using the page "Log page" we can view all the logs recorded in the OSPy system. The number of records is set on the "Options page" page.
The Events log is an operational and audit history separate from both the station-run log and the technical debug log. It records irrigation interventions and blocked runs, configuration changes, users and security events, system and plug-in operations, and sensor events or conditions. Each record shows the date, time, severity, category, subject, and details. Severity is also distinguished by color: information is blue, success green, warning amber, error red, and critical dark red. Use the Event category selector to show all events or one category. The events.csv export contains Date, Time, Level, Category, Subject, and Status. The existing debug logging and its events.log file are not affected by these controls.
The same audit log records state-changing operations performed through the authenticated API, including station and program control, configuration changes, log clearing, and system actions. Failed API authentication and temporary brute-force blocking appear under Users and security. Routine API reads and each successful Basic authentication are not recorded, preventing high-frequency API traffic from filling the log.
The "Download record as Excel log.csv" link allows you to save the record of the irrigation run as a csv file (Excel program) to your computer.
- The structure of the table is: Date, Start Time, Zone, Duration, Program. Dates are separated by a comma.
- Example: 2019-08-12 05:00:00 Filtering 60:00 Filtering
Link "Download log as Excel log email.csv." allows you to save a record of sent emails to your computer as a csv file (Excel program).
- The structure of the table is: Date, Time, Subject, Body, Status. Dates are separated by a comma.
- Example: 2019-08-12 06:00:04 Sent COTTAGE SYSTEM Finished watering -> Program: Filtration, Station: Filtration, Start: 2019-08-12 05:00:00, Duration: 60:00, Water -> Amount of water in tank: Level: 170 cm (90 %), Ping: 95 cm, Volume: 1.28 m3, Temperature DS1-DS6 -> CELLAR: 21.1 ℃ PUMP: 33.5 ℃ BOILER: 26.6 ℃ INDOOR: 22.1 ℃ WELL: 12.2 ℃
Pressing the "Clear Log" button will delete all records of the irrigation run. The action is non-refundable.
After pressing the "Clear Log Email" button, all records of sent emails will be deleted from the system. The action is non-refundable.
On the page "Options page" we can edit the settings of the entire OSPy system. The page contains several collapsible sections. Click on the bar to open or close the desired section.
- Click the "Show Help" button to show or hide information about each option.
System naming is useful when working with multiple OSPy systems.
- Enter a unique descriptive name for the system.
- Click the "Confirm Changes" button at the bottom of the page to save your changes.
The system name defaults to "OpenSprinkler Pi" and will be displayed in the header of each page for easy system identification.
Specifies the appearance of the GUI. Several themes are available in the list (green mode, black and white mode...)
The 24-hour time option chooses between the international 24-hour format, sometimes referred to as military time, and the 12-hour-AM / PM format.
- Uncheck the box and select 12 hour AM/PM format.
- Click the "Confirm Changes" button at the bottom of the page to save your changes.
You will be redirected to the home page and the clock will be in the selected format.
IP address for the HTTP/S server. IPv4 or IPv6 address (will only appear after reboot.) Default is 0.0.0.0.
The HTTP/S port number is part of the web address. Port 80 is the default number for web pages and as such may not be included when a URL is entered into the browser's address bar. Many web servers use port 80 by default. If you run another server on the same Raspberry Pi as OSPy and use the same port number, a conflict will occur and OSPy may not start. You can avoid the conflict by changing the OSPy port number on the Options page to something else, such as 8080. If you change the port number that OSPy uses, you will need to include that number preceded by a colon in the URL for the OSPy web interface. For example: [URL Raspberry pi]: 8080
The HTTP/S port number is part of the web address. Port 80 is the default number for websites.
- Click in the text box next to the HTTP/S port option.
- Enter the port number you want to use, eg 8080.
- Click the "Confirm Changes" button at the bottom of the page.
You will return to the home page. The system reboots, but no reboot indication is visible in the web interface. Wait at least 60 seconds, then add the new port number to the Pi URL preceded by a colon (:) and try to connect to OSPy again.
If we want to display measured data from the extension (wind, temperature, level...) under the graph on the initial (home page) check the box. If we don't want to display the data from the extension, we uncheck the box.
- Warning: in order for the data to be displayed correctly, it is necessary to have the extension enabled and set correctly.
A plug-in can use showOnTimeline to associate a live value with a specific station. OSPy refreshes it every three seconds beside the status of the running station, including master stations and manual mode. The value disappears after the station stops or the plug-in clears it; display data never changes output control or scheduling.
If we want to display the measured data from the sensors under the graph on the initial (home page), we check the box. If we don't want to display the data from the sensors, we uncheck the box.
- Warning: in order for the data to be displayed correctly, the sensors must be enabled and configured correctly.
By selecting the language, we can change the language used in the web interface.
- Click the down arrow to the right of the language field to display a list of available languages.
- Click on the language you want to use in the interface.
- Click the "Confirm Changes" button at the bottom of the page.
The software restarts and after a few seconds the interface is displayed in the selected language.
Check this box to display station images on the homepage and stations page.
The weather section supplies shared forecast data to OSPy and to plug-ins that adjust watering. Every consumer uses the provider selected in Options, so the service does not need to be configured separately in each plug-in.
Enable or disable weather retrieval from the selected provider.
Open-Meteo automatic model selects a suitable available model without an API key. CHMI ALADIN via Open-Meteo requests the ALADIN model where it is available. Stormglass preserves the original service and requires its own API key. Open-Meteo is intended for non-commercial use under its service terms and OSPy attributes it beside the forecast.
When an older installation is upgraded, a saved Stormglass key keeps Stormglass selected. Installations without a key migrate to Open-Meteo. During a temporary service failure the last valid data remain visible; OSPy does not silently switch to a different provider.
Required only when Stormglass is selected as the provider.
City name or zip code. OpenStreetMap resolves it for the selected weather provider.
Use Select on map to open a touch-friendly map, click the exact weather point, and confirm it. Use device location can place the marker from the browser after the user grants permission. The selected latitude and longitude become the authoritative weather location after Options are saved; editing the text Location field switches back to OpenStreetMap name search. Below the coordinate status, Home shows three forecast cards for now, approximately +3 and +6 hours with local icons, temperature and precipitation. Details identify the data provider and last update time.
Forecast icons cover all WMO weather states, including fog, drizzle, freezing precipitation, rain and snow showers, thunderstorms and hail. Clear, mainly clear and partly cloudy conditions use separate sun or moon variants according to the provider's day/night value.
To increase security, we recommend changing the OSPy system password and username from the default "admin". You can also disable the password requirement if needed.
- Click on the triangle to the left of the bar labeled "Users" to expand the section.
- Check the "Disable security" box only if you have a very good reason to disable password and username protection. The system will no longer require user login. All sections will be accessible.
- Enter your username.
- Enter your current password.
- Enter your new password in the fields marked "New Password" and "Confirm Password".
- Click the "Confirm Changes" button at the bottom of the page.
You will be returned to the home page. Your new password and name will be required the next time you log in.
If the box "Disable security" is checked, we allow anonymous users without a password to access the system.
Enter your username in the text box. This is "admin" on a fresh install.
Enter the current password in the text box.
Enter the new password in the field marked "New password".
In the field marked "Confirm password", enter the same new password as in the field "New password".
The responsive user administration lists the built-in administrator and all additional accounts with their roles, notes, and 2FA status. Administrators can create, edit, delete, or reset 2FA for an additional account. Changing an existing user does not require changing its password; entering a new password replaces it, while an empty field keeps it unchanged.
The built-in administrator continues to use the original OSPy 2FA settings. Every additional account can independently configure TOTP or e-mail verification through Account security in the page header. Existing accounts from older OSPy versions remain valid and start with 2FA disabled. Pairing, backup codes, and remembered-login revocation are isolated to the selected account settings; an administrator can reset another user’s lost 2FA but cannot display its secret or backup codes.
Actions that change settings or system state are in the form token protected web interface. If the page is open for a long time or the browser session times out, reload the page and try again.
In case we have configured the OSPy server for higher data transfer security using an SSL certificate, check the "Use HTTPS access" box. If the option "Use HTTPS access" is checked and the server is not set correctly, OSPy will start as an unsecured http server.
The server-side HTTPS selection is now explicit: the own certificate has priority, otherwise Let’s Encrypt is used; enabling both options no longer causes a silent HTTP fallback.
The certificate is located on the system in the directory '/etc/letsencrypt/live/' domain name '/fullchain.pem' and '/etc/letsencrypt/live/' domain name '/privkey.pem'. The certificate must be manually installed in the system (Linux) using the "Certbot" tool (the use of https will be reflected in OSPy only after OSPy is restarted).
- The certificate service installation procedure can be found in the help "Readme" file or on GitHub.
SSL certificate using Let's Encrypt certificate authority. Certbot (https://certbot.eff.org/) and Let's Encrypt (https://letsencrypt.org/).
sudo apt-get install certbotcertbot --versionsudo certbot certonly --standalone -d your_domain_namesudo certbot renewsudo cp /etc/letsencrypt/live/your.domain.com/fullchain.pem /home/pi/OSPy/sslsudo cp /etc/letsencrypt/live/your.domain.com/privkey.pem /home/pi/OSPy/sslsudo service ospy restartIf "Use custom HTTPS access" is selected in OSPy settings, you need to put file: fullchain.pem and privkey.pem in ssl directory in OSPy location. Warning: OSPy must be restarted.
sudo openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -out fullchain.pem -keyout privkey.pemThe second way is to use the "generate" button in the SSL certificate tab.
This option sets the Access-Control-Allow-Origin header used by the API for clients running in a browser. The value * allows any origin, one origin can be specified for example https://example.com, multiple origins separated by a comma, or leave the field empty and CORS headers will not be sent. It does not replace API authentication; it only determines which web origins are allowed to read API responses.
This option enables the legacy callback parameter for JSONP API responses. Leave it turned off unless it is required by the old integration. Common API clients are supposed to use JSON with CORS.
The login page can remember the browser using a long-term random token stored in a secure cookie. OSPy only stores the hash of this token, not the user's password. Use the Cancel button to delete all saved logins in browsers; affected browsers must log in again with a password.
The sensor section contains settings for security of sensors.
Password for uploading firmware from OSPy to sensor (for all used sensors - the same password must be used in sensor options.)
The "Configure Stations" section contains general settings that affect station scheduling and combining.
Specifies how station runs can overlap. 0 means no usage limit, so stations can run simultaneously if their programs overlap. 1 always means one station at a time, if each station has usage 1. A higher value allows multiple stations to run concurrently, if the sum of their usage does not exceed the set limit.
This setting also affects when the pause between stations is inserted.
- Sequential mode is mainly used when the water source cannot supply multiple branches at the same time. Example: at Maximum Utilization
1and Station Utilization1, Station 3 must finish before Station 4 can start. - Concurrent mode is used when a water source can handle multiple branches at once. Example: at Maximum Utilization
0stations 2, 3 and 4 can run simultaneously if their programs overlap.
Total number of outputs available is 8 outputs plus outputs from expansion boards. The number of outputs can be set higher than the actual number of physical outputs, thereby creating virtual outputs.
Pause inserted between sequentially started stations when the scheduler cannot start them at the same time, in seconds between 0 and 3600. This does not advance the station relative to the master station.
Example: with Maximum Usage 1 and Station Usage 1, a value of 30 will start the next station 30 seconds after the end of the previous station.
Skips the pause between stations if the previous run was shorter than this value, in seconds between 0 and 86400.
Example: with pause 30 and minimum run time 10, a station that only ran for 5 seconds will not force a 30 second pause.
The "Configure Master" section selects master station 1, master station 2, and the time offsets used when master station is activated. The main station is usually a pump or main water supply valve.
The Master Station will only be used for stations that have it set on the Stations page, or for programs that select Master Station 1 or 2 for stations set to "Activate Master 1/2 by Program".
Selection of the first master station, such as a pump or master valve.
Selecting a second master station, for example a second pump or another water source.
If checked, the relay will also be activated as the main output.
Master station 1 power-on time offset from station start, in seconds between -1800 and +1800. Negative values start the master earlier, positive values later.
Example: -10 starts the master station 10 seconds before the station. +10 starts it 10 seconds after the station.
Master station 1 shutdown time offset relative to station end, in seconds between -1800 and +1800. Negative values will shut down the main station sooner, positive values will keep it running longer.
Example: -5 turns off the master station 5 seconds before end of station. +20 turns it off 20 seconds after the end of the station.
Time shift of main station 2 switch-on relative to station start. It works the same as master station start shift, but only for master station 2.
Main station 2 shutdown time offset relative to station end. It works the same as master station shutdown shift, but only for master station 2.
Sets the rain sensor switch type. If you are using a Raspberry Pi and want to connect the rain sensor directly to the GPIO pins, use pins 8 and 6 (gnd).
Check the box "Use sensor" to enable rain sensing.
Check the "Normally open" box if the sensor is normally open without rain, otherwise uncheck the box. Refer to the rain sensor user manual for switch type information.
When the rain sensor is activated, a rain delay is set (this is suitable, for example, for blocking programs for longer than the rain sensor provides).
Rain delay time (in hours), between 0 and 500.
Turn on run logging and set the number of records you want to keep. Turn on logging of sent emails and set the number of records you want to keep.
Check the box "Enable run log". This will turn on logging and turn on the watering history on the timeline on the home page. Record all station runs - note that repetitive writing to the SD card may shorten its life.
Enter the number of entries you want to save in the log. Set a number that covers a reasonable amount of time, such as a week or a month. This will depend on the number of programs and stations you have. There will be one entry each time the station starts. 0 = no limit.
Check the box "Enable email log". This will turn on logging and enable email watering history.
Enter the number of entries you want to save in the log. Set a number that covers a reasonable amount of time, such as a week or a month. This will depend on the number of programs and stations you have. There will be one record for each Email. 0 = no limit.
Enable Event Log (Rain Sensor, Rain Delay, Server, Internet External IP ...)
Number of event records to save to disk, 0 = no limit.
Click "Enable debug log" to save all internal operations in OSPy to a file for better debugging. * Note: * saving data to a file too often can damage the SD card or reduce the capacity of the SD card (storage) after a long time. All operations (including from all extensions) are listed.
The "System Restart" section contains buttons to restart the software, to restart the hardware, to turn off the hardware and to clear all settings to default values.
The "Restart" button only restarts the software. It is a quick forced way to implement changes in software.
The "Reboot" button reboots the Raspberry Pi. This takes longer but will perform a full system reboot.
The "Shutdown" button turns off the power to the Raspberry Pi hardware.
The "Default" button will clear all user settings to a default clean install of OSPy.
- All settings can also be deleted manually in OSPy (we find the ospy/data folder in the system and delete all files in the folder).
If we want to backup all the settings of our OSPy irrigation system or transfer the settings to another OSPy system, we use the button "Download" followed by "Upload".
The "Download" button is used to download a configuration file to the computer for later use or to restore the OSPy system. Not only the database file (options.db) is saved, but also the stations folder where station images are stored. At the same time, the events.log log file (if any) is saved. Everything is stored in a zip file (example: ospy_backup_systemname_4.12.2020_18-40-20.zip). We can easily identify which OSPy system the backup is from. The SSL folder, where the certificate is, is not saved in the backup zip file for security reasons!
The Upload button allows you to insert and restore OSPy (for example, when reinstalling Linux). The uploaded file must be a zip file! The following paths and files must be in the file.
*.zip folder:
ospy-backup.json
ospy/data/default/options.db.*
ospy/data/backup/options.db.*
ospy/data/events.log
ospy/images/stations/station1.png
ospy/images/stations/station1_thumbnail.pngOr other station images in the same format.
New backups contain ospy-backup.json, which records the backup format, OSPy version, creation time and a SHA-256 checksum and size for every file. The archive contains the OSPy settings database, system event data and station images. SSL private keys, plug-in code and Python caches are intentionally excluded; plug-in data directories remain covered by the separate OSPy package Backup plug-in. Before restoration, OSPy rejects invalid ZIP paths, links, encrypted or duplicate entries, excessive size or compression and any file outside ospy/data/ and ospy/images/stations/. The limits are 50,000 entries and 512 MB expanded size; a file larger than 1 MB may not exceed a 200:1 compression ratio, and the configured upload limit may be lower. Every file is verified against the manifest and extracted to a staging directory. OSPy then creates an automatic pre-restore safety backup and atomically replaces the data before restarting. Older OSPy backups without a manifest remain supported as a legacy data-only format and receive the same ZIP path and size checks.
Backup format 2 records the authoritative settings backend, storage mode and SQLite schema. Before archiving live settings, OSPy saves pending changes and blocks concurrent settings writes. The SQLite database is copied through the transactional SQLite Backup API and the snapshot is independently checked for integrity, schema, record manifest and value checksums. Restore repeats this logical validation after extraction and rejects a snapshot whose declared mode, schema or setting count does not match. Format 1 manifest backups and older backups without a manifest remain restorable. Active web sessions are neither backed up nor restored; you must sign in again after restoration. OSPy retains the ten newest system safety backups on the device. They are listed in Options, where a selected archive can be downloaded and then restored with Upload. A system backup contains credentials and security settings, so downloaded archives must be stored securely.
If we have our own certificate for SSL (https) security (fullchain.pem and privkey.pem) we can upload it here using the form.
If we want to generate an SSL certificate, press the "generate" button. A certificate will be generated in the ssl directory. Subsequently, in the settings/security, we check the "own HTTPS" option and then restart OSPy.
The "Upload" button sends the attached files (fullchain.pem and privkey.pem) to the ssl folder in the OSPy directory.
On the page "Stations page" we set station names, properties around the use of the amount of water, control of the main stations.
Automatic numbering to mark stations. For example 1 = station 1, 2 = station 2...
Custom naming of stations for better identification in the system, for example "lawn".
Set concurrency (0) or sequence (>=1) for certain stations. More about concurrency or sequence in the text above in the section "Settings / About sequential and concurrent modes".
The amount of water per hour in mm that will be sprayed by the sprinklers at that station. Used for weather based programs. To measure this value, it is advisable to purchase, for example, a plastic rain gauge.
- Refers to the time required for a given amount of water to infiltrate a specific type of soil. In general, the uptake rate of a lighter textured (sandy) soil is greater than that of a heavier textured (clay) soil. However, sprinkler irrigation with large amounts of water can lead to surface runoff even on sandy soils. The uptake rate of soil under irrigation is affected by many factors such as soil texture, soil structure, compaction, organic matter, stratified soils, soil salts, water quality, sediments in irrigation water, etc.
Amount of water the soil can store above level 0. Used for weather based programs.
- Refers to the amount of soil moisture or water content retained in the soil after the excess water drains and the rate of downward movement is reduced. This usually occurs 2-3 days after rain or irrigation in previous soils with a uniform texture and structure.
Factor used to multiply ETo factor for weather based programs. Use value above 1 in case of sunny/dry soil, use value below 1 for shaded/wet soil.
- Soil type
Soils have different properties that make them unique. Knowing the type of soil you have will help you determine its strengths and weaknesses. While soil is made up of many elements, the place to start is with your soil type. You only need to monitor the composition of the soil particles. OSPy allows users to specify the soil type for each zone (station), allowing for more accurate and efficient watering calculations. Different soil types react differently to water; clayey soils tend to drain, while loamy soils can hold water for long periods, etc. The amount of water contained in the soil after excess water drains off and the ability of the soil to hold water is referred to as field capacity (measured in inches or millimeters).
How to find the approximate proportions of sand, silt and clay? This is a simple test that will give you a general idea of the proportions of sand, silt and clay present in the soil. Put 5 cm of soil in the bottle and fill it with water. Mix the water and soil well, put the bottle aside and do not touch it for an hour. After an hour, the water will become clear and you will see that the larger particles have settled:
- Pieces of organic matter may float on the surface of the water
- There is a layer of clay on top. If the water is still not clear, it is because some of the finer clays are still mixed with the water
- In the middle is a layer of mud
- There is a layer of sand at the bottom
- Measure the depth of sand, silt and clay and estimate their approximate ratio.
The following three types of particles can make up your soil: clay, sand, and silt. Most soils are a combination of these three particles, but the type of particle that dominates dictates many of the properties of your soil. The ratio of these sizes determines the type of soil: clay, loam, clay loam, silt-loam, etc.
- Ideal soil is 40% sand, 40% silt and 20% clay. This mixture is referred to as clay. This takes the best of each type of soil particle. It has good water drainage and allows air to penetrate the soil like sand, but it also retains moisture well and is fertile like silt and clay.
Increase or decrease water balance for weather based programs (if not set to 0).
If we have a station connected (it is physically connected) and we want to use it (it can be seen in the selection in programs, on the home page...), we check "Connected". If we do not use the station and do not want to publish it in the OSPy system, we leave "Connected" unchecked. If a station is used as "main station" or "2 main stations" in the system, it cannot be checked or unchecked (deactivated) in the table. The master station is assigned in the system settings "Settings / master station settings".
If we check "Ignore Rain" for a certain station, the station will be activated according to the program regardless of whether a rain delay is set or whether the rain sensor detects rain. We will use this option, for example, in a greenhouse where it does not rain and we need to water it regularly. or, for example, to start the filtration of the swimming pool, which we also clean regardless of whether it rains.
No master station will be used (if a certain station is activated, the master station will not be activated).
If we require that when a certain station is activated, the main station is also activated (for example, a pump or main valve with water), select the item "ON main?".
If we require that when a certain station is activated, the second main station is also activated (for example, a second pump or another water source), select the item "ON main 2?".
If we want to activate the main station or the second main station, we select the item "Activate Master 1/2 by program" by the program. For the program it is then possible to choose which master station is to be used for this station (example: program 1 controls stations 1-4 and master station 5. Program 2 controls stations 1-4 and the second master station 6).
Notes are used for operating the OSPy system. For example, it can be noted: what type of el. valve, sprinkler, etc. we have used in the system.
After clicking on the window, a page opens where you can upload your own image to the station.
On the "Sensors page" page, we can add or delete sensors that perform different functions in the OSPy system. OSPy currently supports sensors from pihrt.com and shelly.com.
The "Add a New Sensor" button will add a new sensor to the system. Sensor settings are listed below in the "Sensor Parameters" section.
Two types of communication are used for sensors:
- Wireless (radio) - ID radio sensor
- Network (Wi-Fi/LAN) - MAC address, IP address You can choose from different types of sensors:
- Dry Contact
- Leak Detector
- Moisture
- Motion
- Temperature
- Multi sensor contact
- Multisensor leak detector
- Multi sensor humidity
- Multisensor motion
- Multisensor temperature
- Multisensor ultrasound
- Multi-sensor soil moisture
Enable or disable this sensor.
Enter the sensor name. Sensor names must be non-zero and unique.
Select the sensor type.
- Open program(s) Check the desired programs to run.
- Or stop these running stations in the scheduler.
- Closed program(s) Mark the desired programs to run.
- Or stop these running stations in the scheduler.
- Sensitivity (0-100%) Exceeding this level activates the high program(s).
- Stabilization time (mm:ss) After this set time, the detector will not react to a change.
- Low Program(s) Mark the desired programs to run.
- High Program(s) Mark the desired programs to run.
- Low Level (0-100%) Exceeding this level activates the low program(s).
- Low Program(s) Mark the desired programs to run.
- High level (0-100%) When this level is exceeded, the high program(s) will be activated.
- High Program(s) Mark the desired programs to run.
- Program(s) Select the desired programs to run.
- Low level (0-100 °C/°F) When this level is exceeded, the low program(s) will be activated.
- Low Program(s) Mark the desired programs to run.
- High level (0-100 °C/°F) When this level is exceeded, the high program(s) will be activated.
- High Program(s) Mark the desired programs to run. For the temperature, degrees Celsius or degrees Fahrenheit are displayed, depending on how we have set the temperature on the title page (bottom right) (you can change the units by clicking on the temperature).
- Distance from the ultrasonic sensor (top) to the minimum water level in the tank.
- Distance from the ultrasonic sensor (top) to the maximum water level in the tank.
- The minimum water level in the tank (from the bottom of the tank) for the report.
- Cylinder diameter for volume calculation.
- Display in liters or m3.
- Stop stations if minimum water level.
- Delay time (hours).
- Stop stations if the ultrasonic sensor has a fault.
- Stop these stations in the scheduler.
- Maximum water level regulation.
- Maximum maintained water level.
- Maximum running time in activation.
- Minimum maintained water level.
- Output for regulation.
- Probe xx controls the program (select the program you want to influence with probe 1-16 in the list of programs).
- Calibrate xx probe for 100% (enter the voltage level in volts to calibrate the probe at 100% humidity).
- Calibrate xx probe for 0% (enter the voltage level in volts to calibrate the probe at 0% humidity).
Select communication type for sensor.
Enter the sensor ID for your radio sensor. The sensor ID must be non-zero and unique.
- Enter the MAC address of the sensor. Example: aa: bb: cc: dd: ee: ff
- Enter the IP address of the sensor. Example: 192.168.88.10
Enter the sampling time in minutes and seconds (mm:ss).
Enable sample logging.
Enable event logging.
Enable sending Emails when an event occurs. The email notification extension is required for this feature!
Here we can make our notes.
The "Delete All sensors" button will delete all added sensors in the system.
Shelly sensors can be integrated into OSPy using the "shelly cloud integrator" extension in which we connect available devices (either via the shelly.com cloud or in the local network). We can then search for these devices in OSPy in the sensor/search section. In OSPy, we can use measurements of, for example, consumption, voltage, output status, etc.
On the page "Help page" we find documentation for all extensions, system OSPs, system changes, API access, web interface. The floating PDF icon opens a print-ready copy of the currently displayed article without OSPy navigation. Use the browser print dialog to save the article as a PDF file.
Main OSPy documentation, system installation, board connections, licenses.
Changes in the OSPy system or in extensions
Internally, all programs maintain a schedule that can be edited directly (just like a custom program).
The following types of programs have been created for easier handling.
Each program can be one of these types. Finally, each program can also be written as a custom program.
Prog/type_data | 0 | 1 | 2 | 3 | 4 | 5 --:|:-- |:-- |:-- |:-- |:-- | DAYS_SIMPLE |start_time |duration |repeat pause |repeat times |list days to run| REPEAT_SIMPLE |start_time |duration |repeat pause |repeat times |repeat days |start_date DAYS_ADVANCED |list of intervals [start, end]|list days to run| | | | REPEAT_ADVANCED |list of intervals [start, end]|repeat days | | | | WEEKLY_ADVANCED |list of intervals [start, end]| | | | | CUSTOM |list of intervals [start, end]| | | | | WEEKLY_WEATHER | | | | | |
set_days_simple start_min, duration_min, pause_min, repeat_times, [days] set_repeat_simple start_min, duration_min, pause_min, repeat_times, repeat_days, start_date set_days_advanced [schedule], [days] set_repeat_advanced [schedule], repeat_days, start_date set_weekly_advanced [schedule] set_weekly_weather irrigation_min, irrigation_max, run_max, pause_min, pems
Help for the web interface in Czech.
Web interface help in English.
Web interface help in German.
Web interface help in Polish.
Web interface help in Russian.
Web interface help in Serbian.
Help for the web interface in Slovak.
For modern web browsers, it is recommended that the API be built on the CRUD principle using JSON as the data container format.
HTTP/s method mapping.
The current basic structure of a plug-in is:
plugins/
└── plugin_name/
├── data/
├── docs/
├── static/
├── script/
├── templates/
├── __init__.py
├── plugin.json
└── README.md
The directories and README.md are optional. New or updated plug-ins distributed for installation must contain __init__.py and a valid UTF-8 plugin.json whose id matches the directory name. Already installed legacy plug-ins without a manifest remain supported in backward-compatibility mode.
Static files are available below /plugins/plugin_name/static/.... Script files are available below /plugins/plugin_name/script/...; a plug-in page can load its JavaScript to call OSPy APIs and update the display. Every *.md file in docs is shown in Help. README.md, when present, is the first Help entry and may also be used as the plug-in description.
- Usage Statistics (anonymous statistics about OSPy system usage)
- LCD Display (16x2 character LCD display connected via I2C bus)
- Pressure Monitor (monitoring the pressure in the pipeline - pump protection)
- Voice Notification (sound notifications - playing mp3 files)
- Pulse Output Test (output test - used to find a certain valve in the ground)
- Button Control (controlling the OSPy system using 8 buttons - used for manually starting programs)
- CLI Control (remote control of peripherals using URL commands - for example RF sockets)
- System Watchdog (Raspberry Pi system watchdog, if the system freezes, the system will restart)
- Voltage and Temperature Monitor (measurement of voltage and temperature using the I2C bus)
- Remote Notifications (sending data to a remote server using PHP)
- System Information (OSPy and Linux system information)
- Air Temperature and Humidity Monitor (measurement of temperature 6x DS18B20 and humidity DHT11 using I2C bus)
- Wind Speed Monitor (wind speed measurement using I2C bus)
- Weather-based Rain Delay
- Relay Test (tests the relay for the main pump)
- UPS Monitor (monitors system power failure, sends email and shuts down Linux system)
- Water Consumption Counter (virtual water flow meter based on main station run calculation)
- SMS Modem (remote control via SMS and USB modem)
- Signaling Examples (example of "signal" notifications in the OSPy system)
- E-mail Notifications (sending E-mails from the system - some other extensions also use this extension, for example: Wind Speed Monitor, Pressure Monitor, Air Temperature and Humidity Monitor...)
- Remote FTP Control (simplified remote control of OSPy using a server with PHP and FTP)
- System Update (use this extension to easily update the OSPy system from GIThub instead of system commands)
- Water Meter (flow measurement using a water meter with pulse output using the I2C bus)
Water Meter v1.1.1 measures continuously in one-second intervals and refreshes its separate overview every second. The overview shows current l/s, equivalent l/min, current-minute/current-hour/total consumption and a flow graph. Settings control local JSON and optional SQL logging, the displayed source, interval in seconds, zero-flow filtering, and a maximum record count where 0 is unlimited. The optional Home value displays
current l/s (current l/min), and mobile API v1 supplies live cards and bounded history from the selected source. The counter is read explicitly from PCF8583 registers 0x01–0x03; setup and measurement failures close and retry the bus and are shown on the overview. - Energy Meter Energy Meter v1.0.1 monitors any number of Shelly Pro 3EM and Shelly 3EM-63T Gen3 three-phase meters. The default and recommended connection reads a device directly on the local network by IP address or DNS name without cloud or Internet access; a configured and running Shelly Cloud Integration plug-in can alternatively provide cached data. Every meter has a Grid, Solar production, Load or Auxiliary role and its direction can be inverted. The overview separates grid import and export, shows L1–L3 and totals, today, yesterday, month and year, cost, feed-in income, history, graphs and CSV. With Grid and Solar meters it calculates house consumption, self-consumption, energy independence and savings; grid export alone is never labelled as production. Atomically stored counters continue after an OSPy restart and safely recognize a reset or meter replacement. Prices and time tariffs are stored with every interval, history can use local JSON, SQL through Database Connector or both, and data is available on Home, in diagnostics and through the mobile API.
- Webcam Monitor (takes photos from USB webcam)
- Weather-based Water Level Netatmo (setting the amount of water for irrigation from the Netatmo weather station)
- Direct 16 Relay Outputs (using this extension we can control 16 relays (stations) connected directly to the Raspberry Pi, but some other extensions will not be available)
- MQTT (OSPy status reporting using the MQTT protocol, station control via MQTT...)
- system debug information
- Weather-based Water Level (setting the amount of water for irrigation based on the weather forecast)
- Real Time and NTP time (extension that sets system time - Linux and HW RTC time from NTP server, HW RTC uses I2C bus)
- Water Tank (water level measurement using ultrasound - for example in a well using I2C bus)
- Monthly Water Level (setting the amount of water for individual months)
- Pressurizer (pressurizing the pump before starting programs)
- Ping monitor (measuring network outages)
- Temperature Switch (temperature regulator that allows 3 independent zones)
- Pool Heating (pool temperature regulation according to solar heating)
- E-mail reader (control of OSPy using E-mail messages)
- Weather Stations (display values from other extensions in the style of clock hands) version 1.0
- Telegram Bot (communicate with OSPy using telegram.org app)
- Door Opening (opening the door lock or sliding gate)
- Voice Station (sound notifications based on station events - playback of wav and mp3 files)
- Blinds control (this extension sends examples via REST API to Wi-Fi relays from Shelly or similar relays)
- Internet connection speed monitor (response, download, upload)
- E-mail Notifications SSL (sending E-mails from the system - some other extensions also use this extension, for example: Wind Speed Monitor, Pressure Monitor, Air Temperature and Humidity Monitor...) This extension is a more modern variant of the original extension E-mail Notifications (Connection via SSL layer).
- Sunrise and Sunset (calculation of astronomical data such as sunrise and sunset. According to these calculations, it allows programs to be run subsequently).
- PV boiler (boiler heating from the distribution network or PV power plant).
- IP cameras (allows monitoring from IP cameras. As JPEG preview, or GIF image, or MJPEG stream from the camera).
- CHMI (allows you to read the current weather from the CHMI weather radar and set the time delay according to it. At the same time, display the RGB weather status on the HW map).
- Therefore (the default plugin for creating other new plugins. The plugin doesn't do anything fancy, but explains how it works).
- Label Maker (creation of EAN and QR codes).
- IP Scanner (search for IP and MAC in the network).
- Database Connector (connection to the database for storing data from sensors).
- OSPy Backup (data directory backup from all extensions to zip files).
- MQTT Home Assistant (integration into HASS using MQTT).
- Shelly Cloud Integration (retrieving states from the Shelly device manufacturer's cloud).
- Current Loop Tanks Mmonitor (level measurement from 4 sensors).
- Network Ping Monitor (monitoring the availability of 3 devices in the network).
- Weather Dashboard (display values from other extensions in the style of clock hands) version 2.0
- Thermostat
After clicking the "Logging out" button, the user logs out of the system.
OSPy repository · Releases · Plug-ins · Issues · Discussions