Fleet Deployment

Manual for deploying one project from a central system to many stations (Edge Nodes), with the values that differ per station.

Updated 19 min read
On this page (20 sections)
  1. Overview
  2. Workflow
  3. Linking a Station to the Central System
  4. Edge Nodes
  5. Edge Projects and Versions
  6. Site Parameters
  7. UDT Instances
  8. Site Values
  9. Applying Site Values Without a Central System
  10. Deploying a Version
  11. Deploy Status
  12. What Happens on the Station
  13. Package Storage and Backup
  14. Certificates for Edge Nodes
  15. System Variables on a Station
  16. Edge Nodes Viewer and Edge Node Edit Right
  17. Showing a Station on the Central System
  18. Config API and MCP
  19. Connections and Ports
  20. Notes

Fleet Deployment distributes one EnvisionSCADA project from a central system to many stations. The stations are called Edge Nodes. A typical case is a set of pump stations that run the same project and differ only in a few values, such as the IP address of the PLC, the station name in the page header and a station number.

The project is engineered and tested on one installation, the template project. Its export is uploaded to the central system as a numbered version of an Edge Project. Each Edge Node belongs to one Edge Project and has its own Site Values for the Site Parameters that the template project defines. A deploy records a version for a set of Edge Nodes; each station fetches the version at its next check-in, applies it and reports the result.

The station always opens the connection to the central system. The central system never connects to a station, so stations behind NAT, a firewall that only allows outgoing connections, or a 4G router can be deployed.

The pages are in the configuration menu under Configuration > Edge.

PageUsed onPurpose
Edge NodesCentral systemThe stations: their token, Edge Project, Site Values, Deploy Status and certificates. Deploy and the Site Values CSV export and import.
Edge ProjectsCentral systemThe projects that are deployed, with their numbered versions.
Site ParametersTemplate project and stationThe values that differ per station and the fields each value fills. On a station that is not deployed by a central system, the values are applied here.

Workflow

A roll-out consists of the following steps.

  • On the template project, define the Site Parameters and bind them to the fields they fill (Configuration > Edge > Site Parameters).
  • Export the template project with Export Project (an .envision file).
  • On the central system, create an Edge Project and upload the export as a version (Configuration > Edge > Edge Projects).
  • On the central system, add an Edge Node for each station, select its Edge Project and enter its Site Values (Configuration > Edge > Edge Nodes). The token of the Edge Node is shown once.
  • On each station, enter the Node Name, the Central URL and the token on the Parameters page, section Node.
  • On the central system, press Deploy, check the result per station and deploy. Each station applies the version within about a minute.
  • To roll back, deploy an older version.

Linking a Station to the Central System

On the central system, open Edge Nodes and press Add. Enter the Name of the station. It must equal the Node Name parameter of the station and may contain letters, digits and underscores. Press Create. The token of the new Edge Node is shown once in the Token dialog: press Copy and keep it for the station. The central system stores only a hash of the token, so it cannot be shown again. Regenerate Token in the Edge Node dialog issues a new token; the previous token stops working at once.

On the station, open the Parameters page, section Node, and enter the settings below. Node Name is saved when the field is left. The other settings are saved together with Save. Test Connection tests the settings as they are in the form, saved or not, and shows the answer of each central node.

SettingDescriptionExample
Node NameIdentifies this installation to the central system. Must equal the Name of the Edge Node on the central system. Required while a Central URL is set.Site17
Central URLAddress of the central system, http or https. The port in the URL is the port the station connects to.https://central.example.com
Secondary IPOptional. The second node of a redundant central system, on the same port as the Central URL. The station uses the node that answers as primary.10.0.0.12
TokenThe token issued by the central system under Edge Nodes. Leave the field empty to keep the stored token.
Allow Untrusted CertificatesFor https: the connection stays encrypted, but the certificate of the central system is accepted without a check. Use it for a self-signed certificate only, and leave it off on a public network.Off
With Allow Untrusted Certificates on, the station does not accept certificates from the central system. Use a certificate the station trusts, as described in the Managing Certificates article, before certificates are delivered to it.

The station checks in with the central system once a minute, and directly after the link is saved. At every check-in it reports its Node Name, its ENVISION version, the version it runs and the state of a deploy in progress, and receives the version the central system wants it to run.

The same link carries the history of the station when a Data Forwarder forwards to the central system. See the Central Historian article.

Edge Nodes

The Edge Nodes page on the central system lists every station. The status columns come from the check-ins and are kept in memory, so after a restart of the central system they fill again as the stations check in. The page refreshes every 10 seconds; Refresh reloads it at once.

13 rows
ColumnDescription
NameName of the station, equal to its Node Name.
EnableAccepts the station. Changed directly in the list.
DescriptionFree text.
Edge ProjectThe Edge Project the station runs. Empty when the central system does not deploy to it.
DesiredThe version the last deploy recorded for the station.
RunningThe version the station reported at its last check-in.
Deploy StatusThe state of the deploy, see Deploy Status. A Site Values changed mark follows when the Site Values were changed after the last deploy.
ENVISION VersionThe EnvisionSCADA build of the station, from its last check-in.
CertificatesThe certificates the central system delivers to the station and whether it holds them. Shown to Administrators only.
Last ReceivedThe last batch of history received from the station.
Rows ReceivedThe history rows stored since the central system started.
InstallationThe installation id the station sent.
Last ErrorThe last refusal or storage error, empty when the last request succeeded.

Press the settings icon on a row to open the Edge Node dialog. It has the sections General (Name, Description, Enable), Deployment (Edge Project and the Running version), Site Values and Token. When Enable is off, the central system refuses the station: it keeps its data and retries.

Press the delete icon to delete an Edge Node. Its token stops working at once. History that was already stored is kept.

Edge Projects and Versions

The Edge Projects page on the central system lists the projects that are deployed, with the columns Name, Latest Version, Edge Nodes (the number of stations that run the project) and Description. Press Add to create an Edge Project. The Name may contain letters, digits and underscores.

Press the versions icon on a row to open the versions of the project. Under Upload Version, select the Package (an .envision file made with Export Project on the template project), enter Notes and press Upload. The package is stored as the next version number (1, 2, 3 and so on), and the message names the Site Parameters it defines. A stored version does not change; a change to the template project becomes a new version.

ColumnDescription
VersionThe version number. A Missing or Damaged mark means the package file of the version is not usable, see Package Storage and Backup.
UploadedDate and time of the upload, in UTC.
UserThe user who uploaded the version.
Site ParametersThe number of Site Parameters the version defines. Hover to see their names.
Deployed ToThe number of Edge Nodes the version is deployed to.
NotesThe notes entered at the upload.

The upload is refused for a package from a newer EnvisionSCADA than the central system runs (update the central system first), and for the export of a station that the central system deployed, because its bound fields already hold the values of that station. Upload the export of the template project instead.

A version can be deleted with the cross on its row while it is deployed to no Edge Node. An Edge Project cannot be deleted while it is the Edge Project of an Edge Node: change those Edge Nodes first.

Site Parameters

Site Parameters are defined in the template project, on the Site Parameters page. Each Site Parameter has a Name (letters, digits and underscores, for example PLC_IP or StationName), a Default and a Description. The Default is the value of the station the template project is built and tested with. A station whose Site Value is empty gets the Default.

The Bindings section of the Site Parameter dialog lists the fields the parameter fills when the project is deployed to a station. Press Add Binding and select the object type, the Object and the Field. Value now shows what the field holds in this project. A bound field keeps its real value in the template project, so the template project runs and validates as it is. A field can be filled by one Site Parameter only.

A text field may contain the placeholder {Name}, for example Pump station {StationName}. At the deploy the placeholder is replaced with the value of the Site Parameter of that name.

Pages, symbols, expressions and scripts are not filled by a binding. They read the value from the read-only variable SYSTEM.Site.<Name>, which the Variable column shows. All pages stay identical on all stations.

The columns of the page are Name, Default, Value (the value in effect on this installation), Variable, Bindings and Description.

  • Can be bound: a setting of a named object, such as the IP address or port of a device, the value of a parameter, a field of a Database Connection, or a parameter of a UDT instance.
  • Cannot be bound: names of objects, references to another object by name (such as the device of a variable), pages, Python scripts, reports, users and user groups, the license, certificates, and the settings a deploy never replaces (see What Happens on the Station).
  • Rows that a UDT generates cannot be bound. Bind the parameter of the UDT instance instead.

UDT Instances

To give each station its own value in a UDT instance, select the object type UdtInstances, the instance as Object, and one of the parameters of the instance as Field. Device parameters cannot be bound, because they name another object.

After a deploy the station pushes every UDT instance that a Site Parameter fills, so the variables, alarms, events, scripts and symbols the instance generates take the values of the station. When a push fails, the version stays applied and the station reports Failed with the instances and the reason. Push those instances by hand in the UDT Manager of the station. See the UDT Manager article.

Site Values

The Site Values of a station are entered on the central system, in the Site Values section of the Edge Node dialog. The list shows the Site Parameters of the latest version of the selected Edge Project, with their Default. Leave a value empty to use the Default.

Site Values reach the station with the next deploy only. When the Site Values of a station are changed after its last deploy, the Deploy Status shows the mark Site Values changed. The station keeps running with the values of the last deploy until the version is deployed again.

To edit the values of many stations at once, press Export Site Values. The CSV file holds one row per Edge Node and one column per Site Parameter, after the column Node. When Edge Nodes are selected in the list, only those are exported. Edit the file and load it with Import Site Values. An empty cell means the Default. A Site Parameter that does not exist in the latest version of the Edge Project of a node is refused for that node, and the message lists the refusals.

Applying Site Values Without a Central System

A station that is set up by hand, without a central system, uses the same Site Parameters. On such a station the Value column of the Site Parameters page is editable. Enter the values and press Apply.

The Apply Site Values dialog first checks the values. Cannot be applied lists values that do not fit the field they fill. Changed by hand since the last apply lists bound text fields that were edited after the previous apply; Apply replaces them. Press Apply in the dialog to fill the bound fields and reload the project. The engine restarts, which means a few seconds without scanning.

A text field with a {Name} placeholder keeps its original text, so a wrong value can be corrected and applied again.

On a station that a central system deployed, the Site Parameters page is read-only and shows the Edge Project and version it runs. The Site Parameters are then changed in the template project, and the values of the station on the central system.

Deploying a Version

On the Edge Nodes page of the central system, select the stations with the checkboxes in the first column, or select none, and press Deploy. Deploy to offers Selected nodes, and All nodes of an Edge Project for each Edge Project that has Edge Nodes. Version offers Latest and every version of the Edge Project. When the selected stations belong to several Edge Projects, only Latest is offered, and each station gets the latest version of its own Edge Project.

The dialog checks every station and shows the result in the Check column. A station that fails the check cannot be selected and is skipped. Clear the checkbox of a station to leave it out, for example to deploy to a test station first. Press Deploy to N node(s) to record the version for the selected stations. Nothing is sent at this moment: each station fetches the version at its next check-in, within about a minute.

CheckMeaning
Ready (Version n)The station can receive the version.
Already on this versionThe station runs this version with these Site Values. Deploy applies it again.
IncompatibleThe station runs an older ENVISION than the version needs. The deploy is recorded and applied after ENVISION on the station is updated.
Reason in redThe station is skipped, for example because it has no Edge Project, the Edge Project has no version, a Site Value does not fit the field it fills, a bound object no longer exists in the version, or the package file is missing or damaged.
Each station restarts its engine when it applies a version, which means a few seconds without scanning. Plan a deploy to a running plant accordingly.

After Deploy the dialog stays open and follows each station until it is Up to date, Failed or Incompatible. The dialog can be closed: the deploy continues and the Deploy Status column follows it.

Deploying a version that a station already runs applies it again with the current Site Values. To roll back, deploy an older version. Every deploy is recorded in the audit trail of the central system and of the station.

Deploy Status

The Deploy Status column of the Edge Nodes page shows where each station is. In the Deploy dialog, a station that is Pending or Unknown is shown as Waiting for check-in.

Deploy StatusMeaning
(empty)Nothing was deployed to the station.
UnknownThe station has not checked in since the central system started.
PendingThe version is recorded and the station has not fetched it yet.
DownloadingThe station downloads its package.
ApplyingThe station imports the package and restarts its engine.
Pushing UDT instancesThe station pushes the UDT instances that Site Parameters fill.
Up to dateThe station runs the version of the last deploy.
Failed: reasonThe deploy failed. The reason says whether the previous project was restored, or which UDT instances could not be pushed.
Incompatible: update ENVISION on the stationThe version needs a newer ENVISION than the station runs. It is applied once the station is updated.

What Happens on the Station

When the central system wants another deploy than the station last applied, the station fetches it on its own thread and reports each step at once.

  • The station downloads its package. The central system builds it for this station from the stored version, with the Site Values of the station filled in.
  • The station compares the SHA-256 of the received package with the one the central system sent. A damaged download is refused and nothing is changed.
  • The station checks that it knows the schema of the package.
  • The station keeps a copy of its running project, imports the package in replace mode and writes back the settings that a deploy never replaces (table below). The engine restarts as after an Import Project.
  • The station pushes the UDT instances that Site Parameters fill, and reports the result.

When the import fails, the station imports the project as it ran before and reports Failed with the reason. A failed deploy is not tried again until the central system deploys again or the station restarts. A version that needs a newer ENVISION than the station runs is refused before anything is changed.

Kept on the stationDescription
Node, link and identityNode Name, Central URL, Secondary IP, Token and Allow Untrusted Certificates.
RedundancyEnable Redundancy, the participant addresses and ports, and the redundancy shared secret.
SecretsSMTP server and credentials, Git settings, the AI Chat API key, the MCP OAuth signing key and the OPC UA server credentials.
UsersThe users and their passwords.
CertificatesThe Trusted Certificates and Revoked Certificates of the station.
Forwarding positionsHow far each Data Forwarder and each MQTT Publisher has forwarded the history of the station. A forwarder or publisher with the same name continues from there.

On a redundant station only the primary checks in for deploys and applies them. The standby receives the result through the configuration replication, see the Redundancy article.

Package Storage and Backup

The central system stores each version as a file, EdgePackages/<Edge Project>/<version>.envision (1.envision for version 1), in its data folder next to the Database folder. In Docker the folder is /EnvisionVolume/EdgePackages. The versions dialog shows the folder of the project.

Every time a version is read, for the Deploy check and for the download of a station, the central system compares the file with the SHA-256 recorded at the upload. A version whose file is absent shows as Missing, and one whose file is not the uploaded package shows as Damaged. Such a version is not deployed, and the Check column names the reason and the path. A station that already runs the version is not affected. Putting the original file back in the folder is enough to deploy it again.

The EdgePackages folder is not part of the database backup or of the Export Project of the central system. Include it in the backup of the central system on its own. On a redundant central system the standby fetches the files from the primary with the redundancy file sync: an upload, a delete or a rename on the primary reaches the standby within about a minute.

Certificates for Edge Nodes

The central system can deliver certificates with their private key to a station, for example the certificates the IT department issued for it. Click the entry in the Certificates column of the Edge Node to open the dialog. Select the Certificate File (.pfx, .p12 or .pem), enter the Name and the Password, and press Add. A certificate under an existing name replaces it, for a renewal. Use for HTTPS selects the certificate the web server of a Docker station presents.

The station receives the certificates at its next check-in and keeps them in its Own Certificates. The status is Delivered when the station holds exactly this set, Pending until then, and Pending on the standby node while the standby of a redundant station does not hold them yet. Certificates are sent only over an https Central URL.

A certificate that is replaced or deleted, or whose Edge Node is deleted, is not revoked: it stays valid until it expires. To refuse it sooner, add it to the Revoked Certificates. Trusted Certificates and Revoked Certificates marked Distribute on the central system are also sent to every station at its check-in.

The Certificates column and its dialog are available to Administrators only. See the Managing Certificates article for the details.

System Variables on a Station

A station publishes the state of its link to the central system as read-only variables. Pages, alarms, expressions and scripts can use them like any other variable. They are updated after every check-in and when the project loads. Without a link they read False, empty and 0.

VariableDescription
SYSTEM.Central.LinkedTrue when a Central URL and a Node Name are set.
SYSTEM.Central.ConnectedTrue when the last check-in was answered, no longer than three minutes ago.
SYSTEM.Central.LastCheckInLocal time of the last answered check-in, yyyy-MM-dd HH:mm:ss.
SYSTEM.Central.LastErrorWhy the last check-in failed. Empty when it succeeded.
SYSTEM.Central.EdgeProjectThe Edge Project the central system deployed last. Empty when nothing was deployed.
SYSTEM.Central.RunningVersionThe version the central system deployed last. 0 when nothing was deployed.
SYSTEM.Central.DeployStatusThe step of a deploy in progress (Downloading, Applying, Pushing UDT instances), or Failed: reason. Empty otherwise. Pending and Up to date are shown on the central system only.
SYSTEM.Site.<Name>The value in effect of the Site Parameter Name, as text.

Edge Nodes Viewer and Edge Node Edit Right

The Edge Nodes viewer object shows the Edge Nodes and Edge Projects pages of the central system on a runtime page, as two tabs in one frame. Insert it in the editor from the Viewers group, Edge Nodes. See the Viewers article.

The pages need the Edge Node Edit Right, set per user group on the User Groups page. Administrators always hold it. A user with the right can open Edge Nodes and Edge Projects, upload versions, edit Site Values and deploy. The certificates of the Edge Nodes, the Site Parameters page and the MCP tools remain for Administrators. A user without the right sees a no-rights screen in the viewer.

Showing a Station on the Central System

To show the pages of a station on the central system in a Web Frame, enter the address of the central system in Allow Embedding From on the Parameters page of the station, section Engineering Settings, for example https://central.example.com. Several addresses are separated by spaces. Empty, the default, allows no other installation to show this one in a frame. Over plain HTTP, framing works only between addresses of the same host. See the Web Frame article.

The browser of the operator connects to the station directly in this case, so the station must be reachable from the operator workstation.

Config API and MCP

Everything on the Edge Nodes, Edge Projects and Site Parameters pages is also available through the Config API under /API/Config: EdgeNodes (including Site Values and Deploy), EdgeProjects with their Versions, and SiteParameters (including Apply on a station without a central system). A version is uploaded as multipart/form-data to POST /API/Config/EdgeProjects/Versions with the fields project, notes and file.

Over MCP, the tool ManageFleetDeployment lists versions, checks and runs a deploy, sets Site Values of many stations, deletes versions, lists and manages the certificates of the Edge Nodes, and applies Site Values on a station without a central system. The Edge Nodes, Edge Projects and Site Parameters themselves are edited with the generic configuration entity tools. Uploading a version and adding a certificate are not possible over MCP: a package is too large for a tool argument, and a private key and its password do not pass through an agent.

Connections and Ports

Every connection for Fleet Deployment is opened by the station. The firewall at the station only needs to allow the outgoing connections below; the central system needs no route to the station.

FromToProtocol and portPurpose
StationCentral URLHTTP or HTTPS, the port of the Central URL (443 for https and 80 for http when the URL names none)Check-in once a minute, download of the package, delivery of certificates, and forwarded history.
StationSecondary IPThe same protocol and port as the Central URLThe second node of a redundant central system, when a Secondary IP is set.
Station (optional)MQTT Broker of the central systemMQTT, TCP 1883, or 8883 with TLS (the defaults of the broker)Live values from an MQTT Publisher on the station. Not needed for deploys. See the MQTT Broker article.
Use an https Central URL. Certificates are delivered only over https, and over http the token and the package travel unencrypted.

Notes

Configuration changes on the Edge Nodes and Edge Projects pages are made on the primary node of a redundant central system and replicated to the standby. See the Redundancy article.

On Docker, the data folder of both the central system and the station is the volume /EnvisionVolume. Mount it as a volume so the EdgePackages folder and the database are kept when the container is recreated. See the Docker article.

The Parameters article describes the other settings of the Node section.

Something missing or wrong in this article? Contact us