Documentation
Nobody sells a product they cannot learn
In this market, an integrator sells whichever product they can actually learn. Below is the path from a bare server to your first report, the real system requirements, and diagnostic steps for the places people get stuck in the field. A video series is in production; what exists today is written documentation, and we say exactly what that is.
From installation to first report
Six steps. With no hardware on hand you can work through the first three using the Simulation driver; when the PLC arrives you change the connection type only — tags, screens and alarms stay as they are.
1. Installation
IIS, PostgreSQL and a Redis-compatible cache come up on Windows Server, and the SCADA Runtime that polls the field is installed as its own Windows service. You do not have to build on the server — building on your own machine and uploading only the output is the cleaner route.
2. First connection
A connection is a protocol, a transport (TCP or serial) and a poll interval. Protocol-specific fields — unit id, rack/slot, endpoint address — are driven into the form by the protocol schema. With no device on site, pick the Simulation protocol: it behaves like a real connection, produces values, and does not block your progress.
3. First tag
A tag is an address, a data type and a register area. Engineering conversion is defined here with Scale and Offset (y = Scale·x + Offset), along with the unit and a deadband for noisy analogue inputs. Screens and alarms never see the raw register — they see this converted value.
4. First screen
The HMI editor runs in the browser; there is no separate desktop designer to install. You drag a component in, bind it to a tag and set threshold colours. Every save is stored as a revision, so undoing a bad edit does not mean hunting through backups.
5. First alarm
An alarm binds to a tag and carries a condition, a severity, a priority group, a delay and a hysteresis band. The delay stops brief spikes from raising alarms; the hysteresis stops a value oscillating around the threshold from flapping the alarm on and off. Leaving both empty is the most common cause of alarm floods in the field.
6. First report
Reports are built from the trend history written to the historian and can be scheduled out by e-mail. The precondition was set back in step three: history logging must be on for the tag, and the logging interval must suit the resolution the report needs. With logging off, the report comes out empty.
Installation requirements
Production installs run on Windows Server with Plesk and IIS. This is the prerequisite list from our own installation guide, reproduced rather than summarised.
| Component | Version | Required | Note |
|---|---|---|---|
| Operating system | Windows Server 2019 / 2022 | Yes | A Plesk-managed environment is assumed; Plesk handles domains, SSL and IIS. |
| .NET Hosting Bundle | 8.0.x | Yes | Required for IIS to run the ASP.NET Core application. Without it you get HTTP 500.19 / 500.31. |
| PostgreSQL | 16 | Yes | Windows installation, listening on localhost only (5432). |
| Redis-compatible server | Memurai or WSL2 | Yes | Localhost only (6379). There is no official Redis build for Windows, so Memurai is used. |
| Node.js | 20 LTS | No | Build-time only. Not needed if you build on your own machine and upload the output. |
| Browser | Current desktop and mobile versions | Yes | The build targets browsers that are still supported and hold above 0.2% share. We have not measured a specific minimum-version list. |
| SCADA Runtime | Windows service | Yes | This process does the field polling. If it has stopped, tag values will not arrive even with the API up. |
A Docker install is possible but the images are Linux-based, and Plesk on Windows Server does not manage containers. A native IIS install on Windows is not a compromise — it is the recommended path.
The whole configuration is one JSON file
The core configuration of Bella SCADA is text. A single endpoint (GET /api/scada/config/export) downloads connections, devices, tag groups, tags, screens, symbols, alarms and recipes as one JSON bundle. The same bundle goes back in through POST /api/scada/config/import.
Import works as an upsert keyed on id: records already present are updated, new ones are added. Because the GUIDs are preserved, tag-to-alarm and screen-to-symbol relations survive the move. This is the shortest route from a line you built in staging to the same line in production.
The bundle deliberately carries no runtime data: alarm events, trend history, shift records and electronic signatures are not exported. Configuration should be portable; an audit trail should not be. A database backup does not substitute for this and should not — we keep a separate drilled procedure for backup and restore.
The practical consequence: the configuration file can live in version control, two environments can be compared as text, and one commissioned line can be copied to a second site in minutes. A visual diff and selective-promotion interface does not exist yet; today the workflow is download and upload.
What exists today
These documents are written and in use. They are not published on a public portal yet — they ship with the installation or on request. We are not listing documents that are "coming soon", because naming an unwritten document is its own kind of broken link.
| Document | What it covers | Who needs it |
|---|---|---|
| Windows Server + Plesk installation guide | End-to-end production install: architecture, prerequisites, IIS application pool, SSL, service registration, database and build workflow. | The sysadmin performing the install |
| Installation log — demo.bellascada.com | A step-by-step record of a real install on a real server: which decision was taken and why, and where things went wrong. The field counterpart of the guide. | An integrator doing their first install |
| IEC 62443-4-2 compliance map | Security architecture, a component-requirement coverage table, open gaps and a residual risk statement — including one audit finding that was closed. | Anyone bidding on public or critical infrastructure |
| Release integrity verification | How to verify the hashes and signature of a downloaded package, and how to check the component inventory through the SBOM. | Buyers who ask about supply chain security |
| Backup and restore drill | Not how to take a backup, but how to prove it restores: restoring into a scratch database, comparing record counts, and the assets that live outside the database. | The maintenance team taking over operations |
The documents are written in Turkish. English versions do not exist yet; we translate on request for specific projects, but not off the shelf.
Common problems and how to diagnose them
The connection never comes up — status stays Disconnected or Error
Work through it in order. One: is the SCADA Runtime Windows service running? Field polling is done by that process, not the API, so no connection is attempted while it is stopped. Two: is the connection record enabled? A disabled connection is never attempted and simply shows as Disconnected. Three: is the state Disconnected or Error? Disconnected usually means reachability — wrong IP, closed port, firewall. Error means the device answered and refused at protocol level: wrong unit id, wrong rack/slot, failed authentication. Four: build a second connection with the Simulation protocol. If Simulation runs and the real one does not, the problem is between the network and the device, not in the configuration.
The connection is Connected but no tag values arrive
A connected link does not mean the address is right. One: check the tag type — Calculated and Scheduler tags are never polled from the field, and a Calculated tag with a broken expression stays empty. Two: does the address match the register area? Reading a coil address out of the holding register area does not raise an error, it just returns meaningless data. Three: does the data type match the device layout? Word order on 32-bit values is the most common mistake, and it shows up as a number that is wildly too large or too small. Four: the deadband. Set wider than the real range of movement, the value is read but never published, and the screen sits on its first reading. If in doubt, zero the deadband and retry.
The value crosses the threshold but the alarm never fires
One: is the alarm enabled? Two: the threshold is compared against the engineering value, not the raw register. If you defined Scale and Offset, the threshold has to be written in the same unit — a threshold written against raw counts is the hardest alarm fault to spot. Three: the on-delay. If the value crosses the threshold but stays above it for less than the delay, the alarm is never born; watch the live value and count the seconds it holds. Four: hysteresis. It separates the clearing threshold from the raising one, so an oversized hysteresis delays seeing the alarm clear rather than raise — which people report as "the alarm will not go away".
The trend screen is empty although live values are arriving
Live monitoring and the historian are separate paths; one can run while the other is off. One: is history logging enabled on the tag? Important: after the upgrade that introduced this field, existing tags may have had logging silently turned off; this is the first place to check post-upgrade. Two: the logging interval is independent of the poll interval — the field can be read once a second while history is kept once a minute, so a short time window may legitimately contain no points. Three: the query range and the server clock. Four: TimescaleDB compression ships disabled; that costs no data, it only makes long-range queries slower.
The screen loads but the values are frozen
This is almost always the live channel rather than the data source. A screen fetches its opening values over REST and then receives updates over a WebSocket. If refreshing the page updates the value once and then it freezes again, the channel is not being established. A reverse proxy or firewall may be blocking the WebSocket upgrade, and the browser console will show the connection error. If the operator interface and the API sit on different hostnames, make sure they share the same root domain.
Nothing shows up after installation — the panel is empty
A fresh install has an empty configuration; this is not a fault. There are two ways forward: walk the getting-started path above and build the first connection by hand, or import a configuration bundle if you have one. Our demo installation carries a flour mill configuration that loads through the same JSON import endpoint.
Integrator programme
The reason this page exists is plain: the market share of a SCADA product is set by the number of engineers who have learned it. The biggest advantage one of our competitors holds is not its price or its architecture — it is a free, open training programme. We intend to go the same way, and we will say where we are without dressing it up: at the beginning.
What we can offer concretely today is this — we do the first installation together with your engineering team, we build the screens with you, and throughout commissioning you talk to an engineer directly. There is no call-centre layer. What we ask in return is that you tell us where you got stuck: most of the diagnostic steps on this page came from exactly that.
Commercial terms differ for early reference projects; the detail is on the pricing page. If you want to see the validation status of each protocol, the protocols page lists it individually — measured status, not estimates.
See it on your own plant
We open a working demo environment with no hardware to install and no licence to wait for. Tell us which protocol is on your floor and we will prepare an example that speaks it.