Run the whole plant from one page.

Who this guide is for

This documentation covers day-to-day operation for Viewers and Operators, and full system administration for Admins. If you only monitor dashboards and acknowledge alarms, the Using SyncTide chapters are all you need. If you set up devices, users and gateways, continue into Administration.

What SyncTide does

• Ingest — five native protocol drivers plus CSV folder watching, one worker per protocol.
• Watch — threshold, digital, totalizer and operating-curve alarms with per-tag rules.
• Notify — one escalation engine across SMS, email, Telegram and WhatsApp.
• Report — scheduled PDF/Excel exports, per-customer branding, auto-emailed.

Open and log in

1. Open a browser and go to your SyncTide address — http://<host> on the plant LAN (it lands you on the app at /ui and the sign-in screen).
2. Enter your username and password.
3. If multi-factor authentication is enabled on your account, enter the 6-digit code from your authenticator app (or a one-time recovery code).
4. Pick your language — English or Português (Portugal) — from the top bar.

Two-factor authentication (MFA)

SyncTide supports time-based one-time passwords (TOTP). Enrol from My Account → Security: scan the QR code with an authenticator app, confirm a code to switch it on, and store the 10 recovery codes somewhere safe — each works once if you lose your device. Administrators can require MFA for an account; until it's set up, that user is prompted to enrol before reaching any data.

First login & passwords

If you are signing in with a default password, SyncTide forces you to change it before you can continue. Passwords cannot match common defaults such as admin, password or 123456.

The three roles

The asset tree

The asset tree organises every monitored device into a hierarchical category structure. Each device carries a colour-coded status dot:

Click a device name to expand its alarm details. Open alarms appear in a scrollable list (up to five visible at a time).

Acknowledging alarms

Acknowledging tells the system — and your colleagues — that you are aware of a situation. You can acknowledge at three levels:

• Per-alarm — click Ack next to a specific event.
• Per-device — click Ack All on a device to clear all of its alarms at once.
• Global — click Ack All at the top of the asset tree to acknowledge everything.

The interactive map

The map plots devices as coloured dots (green / red / grey). Hover a marker for device details. Devices without coordinates are listed below the map. Free CARTO tiles are used by default; satellite imagery is available when a Mapbox API key is configured.

Summary metrics

The KPI cards show system-wide figures at a glance, with the trend direction versus the previous period:

• Total flow / pressure / power and other site KPIs, each with a sparkline.
• Assets online — how many devices are reporting, and how many carry active alarms.

Filters & time range

Use the filter bar to choose what you're looking at:

• Group — narrow to one or more equipment groups (e.g. Distribution, Intake Station).
• Time interval — presets from 1H to 30D, or a custom range.

For wide date ranges the system automatically aggregates points into hourly or daily buckets to stay responsive; an indicator below the chart shows whether you're viewing raw or aggregated data.

Active alarms

The active-alarm panel lists every open event, ranked by severity, with the measured value and the threshold it breached. Filter by Active, Critical, Warning or All, and acknowledge individually or with Ack all. Acknowledging here stops escalation just as it does on the asset tree.

Data table & export

Below the chart, a table shows the raw measurements behind your current filters. Use the download button to export them as CSV for Excel or other tools.

Building a view

1. Expand the Series tree (Group → Device → Tag) and tick the tags you want.
2. Each tag plots by its natural type — line for instant values, stepped bars for totalizers (Δ per bucket), step for digital on/off.
3. Set the time interval and bucket resolution.
4. Choose an axis mode: Shared, By unit (up to four axes grouped by engineering unit), or Auto-fit to normalise.

Site KPIs & export

When site-wide KPIs are defined they appear at the bottom of the series tree and can be plotted like any other tag. Use Export CSV for the plotted data, or Save view to keep a layout you return to often.

Severity at a glance

Open alarms are ranked by severity so the most important sit at the top:

Acknowledging & escalation

Acknowledge from the Dashboard, the asset tree, or by replying to the notification message itself. When a message includes an ACK token (e.g. Reply ACK-abc123 to acknowledge), you can acknowledge by:

• Replying with the ACK token over SMS or WhatsApp.
• Clicking the acknowledgment link in an email or Telegram message.
• Acknowledging from the platform UI.

Once acknowledged, escalation stops for that alarm event. The alarm itself clears only when the value returns to normal.

Simple reports

Generate a one-off report by choosing a type (Excel summary or raw-data export), one or more devices and tags, and a period (Daily, Monthly, Yearly or a custom range). Click Generate; the file appears in History & Jobs to download.

Template reports

Template reports use pre-designed Excel templates with charts and formatting. Pick a device, tag and template type; SyncTide fills in the data, calculates min / avg / max, and produces a formatted file.

Scheduled reports

Set up reports that generate themselves:

1. Select a report template and device.
2. Choose a frequency — Daily, Monthly or Yearly.
3. Set the run time (HH:MM); for monthly/yearly, set the day of month.
4. Enable the job. It now runs automatically.

Scheduled jobs can be paused, resumed, run immediately, or deleted from History & Jobs.

Viewing & downloading

Every generated report lands in the History & Jobs tab. Click to preview (PDF inline, Excel as a data table) or download the file. A date-range filter helps you find older runs.

Overview

The overview tab summarises active alarm rules, messages sent in the last 24 hours and 7 days, the delivery-rate percentage, gateway status, and recent failures with their error details.

Contacts

Contacts are the people who receive notifications. Each has a name, phone number, email and Telegram chat ID, plus an active/inactive toggle — inactive contacts are skipped. Use the pencil icon to edit, or Add Contact to create one.

Escalation lists

An escalation list sets the order in which contacts are notified during an alarm:

• Each member has a priority level (1 = notified first).
• Members at the same level are notified simultaneously.
• If no one at level N acknowledges within the timeout, SyncTide escalates to level N+1.
• A list can have a parent list — after exhausting its own members, escalation continues through the parent's.

Alarm rules

Alarm rules connect device alarms to escalation lists and define how notifications behave:

Message history

Review every sent message, filtered by status (Pending, Sent, Delivered, Failed, Acknowledged) and date range, and export the list to CSV.

Name & password

• Update your full name.
• Change your password — you'll need your current one to confirm.

Adding a device

Use the Add device expander to register a device with its code, name, alarm category and ingestion protocol (CSV, Modbus TCP, OPC UA, IEC 60870-5-104, MQTT). You can change the protocol later on the Communication tab.

Metadata

The Metadata tab edits the device's name and code, equipment group (used for filtering), model and serial number, latitude/longitude (for the map), and its hierarchical alarm category.

Communication

The Communication tab defines how SyncTide reads each device. Every non-CSV device has its own poll interval (1–86,400 s), and a Test connection button probes the device without saving anything.

Tag mapping

The Tag Mapping tab links raw equipment tags to standardised system tags. Each row maps an equipment tag name to a system tag (standard name + unit), sets a scale factor for unit conversion (default 1.0), and toggles active/inactive.

Monitoring & alarm rules

The Monitoring tab configures alarm detection per device.

Communication timeout. Set how long a device may go without data before it is marked offline (in days, hours and minutes). With Communication Lost Alarm enabled, going stale raises an alarm that auto-clears when data resumes.

Per-tag rules. Each mapped tag can carry up to four threshold alarms (for example High-High / High / Low / Low-Low), and each rule has its own:

• Name & severity — Critical, Warning or Info, shown everywhere the alarm appears.
• Value type — Numeric (threshold), Boolean / digital (true/false edges) or totalizer (window delta).
• Operator — <, <=, =, >, >=, != (numeric).
• Threshold — the setpoint that triggers the alarm.
• Hysteresis (deadband) — once raised, the alarm stays raised until the value crosses the threshold by this margin, so a noisy signal sitting on the limit doesn't flap on and off.

Operating-curve alarms

A curve rule watches the relationship between two tags rather than a single value — like a pump's flow-versus-pressure envelope. Define the expected curve (a set of breakpoints, with extrapolation) plus a tolerance band, and SyncTide alarms when the device drifts outside it — an early signal of wear, cavitation or fouling. Author curves under the Alarms → Curve Rule sub-tab, with a live preview over the last 30 days.

Runtime configuration

• Raw data folder — where CSV files are read from.
• Reports output folder — where generated reports are saved.
• Report templates folder — where Excel templates live.
• Ingestion interval — how often (seconds) SyncTide checks for new CSV files (minimum 15 s).

System tags & virtual tags

System tags are the standardised names (with units) used across every device via tag mapping. Add, edit or deactivate them here.

Virtual tags are derived from a sandboxed expression over tags you already collect — an efficiency, a deviation, a running total. Scope a virtual tag to a single device, or to the whole site to build a cross-device Site KPI. Give a KPI a target value and a tolerance ±%, and SyncTide colours it by deviation and lets you alarm on it like any other tag.

MQTT brokers

Register the MQTT brokers your plant publishes to — host, port, optional username/password and TLS. Once a broker is defined here, MQTT / Sparkplug B devices in Equipment configuration simply pick it and subscribe to a topic. Sparkplug B payloads are decoded automatically.

Alarm categories

Build a hierarchical category tree to organise devices. Create categories with a name, icon and optional parent; devices are assigned to categories in Equipment configuration. Categories drive the asset-tree display and category-scoped alarm rules.

License management

The License tab shows your current entitlement and lets you upload a new .lic file.

Creating & managing users

1. Click Add New User.
2. Enter a username and password.
3. Set the role — Admin, Operator or Viewer.
4. Pick allowed pages (auto-filtered by role) and, optionally, restrict to specific equipment.
5. Click Create.

From the user list you can edit a profile, toggle Active/Inactive, reset a password, or delete an account.

Role permission matrix

Equipment whitelist

Restrict any user to specific equipment:

• By category — they see only devices in the chosen categories (and sub-categories).
• By device — they see only the listed devices.
• Empty whitelist — they see everything.

The whitelist applies across the Dashboard, Reports, Map and every data endpoint.

Security: MFA & the audit log

Two account-security tools sit alongside roles and whitelists:

• Require MFA — force two-factor authentication on an account. The user is prompted to enrol an authenticator app before they can reach any data; see Two-factor authentication.
• Audit log — an admin-only record of who changed what and when (logins, configuration edits, user changes), for traceability and incident review.

Gateway types

To add one: click Add Gateway, choose the type, fill the required fields, mark it Active (and optionally Default), save, then use Test Send to verify connectivity.

Telegram bot setup

1. In Telegram, message @BotFather and send /newbot; follow the prompts.
2. Copy the bot token (format 123456:ABC-DEF…).
3. Add the bot to your group chat and send a message there.
4. Call the getUpdates API to find the chat_id.
5. Configure the gateway with the bot token; use the chat_id as the contact's Telegram Chat ID.

SMTP email setup

For Gmail, use an App Password, not your account password:

1. Google Account → Security → 2-Step Verification → App Passwords.
2. Generate a new app password for Mail.
3. Use smtp.gmail.com, port 587, TLS on, your Gmail as username and the app password.

How escalation flows

When an alarm matches a rule, SyncTide:

1. Queues messages for level-1 contacts in the assigned escalation list, each with an ACK token.
2. If no acknowledgment arrives within the response timeout (default 300 s), escalates to the next level.
3. Continues through every level — including parent-list members — until someone acknowledges or the max level is reached.
4. Honours the cooldown to avoid repeat notifications for the same ongoing alarm.

Live protocols vs. CSV

• Live protocol drivers (Modbus TCP, OPC UA, IEC 60870-5-104, MQTT / Sparkplug B) — SyncTide connects and reads each register / NodeId / topic, polling on an interval or receiving by exception. One worker per protocol means a misbehaving driver can't affect the others.
• CSV ingestion — drop files into the raw-data folder; the ingestion worker imports them on the configured interval.

CSV file format

Delimiters (comma, semicolon, pipe, tab) are auto-detected, as are common timestamp formats including ISO 8601 and DD/MM/YYYY HH:MM:SS.

File placement & folders

Place files in the configured raw-data folder, organised by device using subfolders:

# the folder name becomes the device code
raw_data/DeviceCode_1/file1.csv
raw_data/DeviceCode_2/file2.csv

• Files are tracked by SHA-256 hash — the same file is never imported twice.
• Duplicate measurements (same device + timestamp + tag) are skipped automatically.
• Invalid rows (bad timestamps, non-numeric values) are dropped and logged.
• Devices are created automatically on first file import.

Database backup

SyncTide ships backup helpers — backup_platform.ps1 on Windows and backup_cloud.sh for Docker (pg_dump plus the bind-mounted folders, with rolling retention). To dump the database manually, use PostgreSQL pg_dump and schedule it with Windows Task Scheduler or cron:

pg_dump -U postgres -d synctide > backup_YYYYMMDD.sql

Log files

SyncTide writes rotating logs to the logs/ directory:

Service management

On Windows, SyncTide runs as a set of services — the FastAPI backend (SyncTideBackend, which also serves the web app), one worker per protocol (SyncTideModbus, SyncTideOPCUA, SyncTideIEC104, MQTT), the alarm and ingestion workers, and the SyncTideProxy (Caddy) that puts the app on a clean LAN URL. Manage them with services.msc or PowerShell (Start-Service, Stop-Service, Restart-Service). The supervisor automatically restarts a crashed service, up to five times in a five-minute window. On Linux the same components run as containers (docker compose).

Common issues

Getting support

If something isn't covered here, contact your system administrator with:

• Your username and the page where the issue happens.
• The exact error message, if any.
• The steps to reproduce it.

Role manuals

Operational guides

Markdown references shipped alongside every release — the practical, in-the-field docs.

• Local install — step-by-step setup, service registration, first run.
• PostgreSQL setup — provisioning, roles, connection strings, migrations.
• Recovery — restoring from backup, rolling back a release.
• Operations runbook — triage, log map, error-to-cause table. The 3 AM doc.
• Telegram alerts (admin) and Telegram for recipients.
• Release notes — every version's changelog.