The Local Variables configuration page defines internal project variables that are not connected to an external communication driver. They are used for intermediate calculations, operator-controlled states, internal flags, accumulator values, and page logic.
Local variables can be read and written by alarms, events, schedules, Python scripts, and runtime page actions. They are referenced at runtime by their Name exactly as configured. A Python script with Network & File Access, a program that uses the Runtime API WriteVariable, and the gateways (the built-in OPC UA server, the built-in Modbus server, MQTT publishers and Kafka devices) can only write Local variables with External Source enabled, see External Source below.
Name variables according to their function in the process rather than a generic index. This makes alarm and historian configurations easier to maintain.
Variable Naming Rules
These rules apply to every variable in the project, on a device as well as in the Local list. A variable name is stored and used exactly as it is written, and the resolved name must be unique across the whole project.
A name is built from letters, digits and underscores. A dot separates namespaces, so a name may be grouped as Plant.Line1.Flow, and a name without any dot such as Counter is equally valid. An array element is addressed with an index in square brackets. A device variable may start with the optional {Device}. replacer, which resolves to the name of the owning device so the variable follows a device rename.
| Rule | Description | Example |
|---|---|---|
| Allowed characters | Letters, digits and underscores, with dots as namespace separators and an optional index in square brackets. Characters outside this set, such as a hyphen or a hash sign, are reported when the variable is saved. | Pump1_Speed, Plant.Line1.Flow, Tank[3] |
| Optional device replacer | A device variable may be prefixed with {Device}. so the name follows the device when it is renamed. A literal name is kept exactly as written across a rename. | {Device}.Power |
| Reserved namespaces | The SYSTEM and client namespaces are reserved for the values the system publishes. | SYSTEM.Time |
| Reserved words | A name without a dot may not be a word that the expression editor uses, so that expressions stay unambiguous. | Use FlowRate rather than a bare expression keyword |
| Unique across the project | The resolved name may occur once. Two devices can carry the same short name when each embeds {Device}, because the resolved names then differ. | Pump1.Speed and Pump2.Speed |
No rows match the filter.
Variable Settings
Each Local Variables row represents one variable.
Create a new variable with the Add button in the toolbar. The Add variable dialog organizes all variable settings in the tabs General, Scaling, Historian, and Gateway, with default values already filled in. Enter at least the Name on the General tab and press Create.
The variable row shows Enable, Name, Asset, Type, Value, Description, and External Source directly and these values can be edited in place. Press the Settings icon on a variable row to open the Edit variable dialog, which contains the same tabs and all settings of the variable. Press Save to apply the changes. The Gateway tab settings Modbus Address, OPC UA, Writeable, MQTT Publisher, Kafka Device, Kafka Remap Device, and Kafka Remap Variable are also available as table columns, which are shown with Columns as described in the Configuration Tables article.
| Setting | Description | Example | Units / Format |
|---|---|---|---|
| Enable | Enables or disables this local variable. | true | Boolean |
| Name | Full variable name, free to choose (for example Local.Pump1_RunCount or Plant.Counter). The name must be unique across the whole project and is referenced at runtime exactly as written. | Local.Pump1_RunCount | Text |
| Asset | Asset path for logical grouping. Used for filtering in alarm, event, and historian viewers. | PumpStation | Text |
| Type | Data type of the variable. | REAL | Enum |
| Value | Initial value applied when the system starts. When Persistent is enabled, the last runtime value is restored instead. | 0 | Text |
| Description | Free text description for documentation purposes. | Counts pump 1 run cycles | Text |
| User Groups | Comma-separated user groups allowed to write this variable from the runtime. | Operators,Engineers | Text |
| Signature Required | Requires an electronic signature for each write to this variable from a page object, the Live Manager, the Runtime API or MCP while Part 11 compliance mode is enabled and Write variables marked Signature Required is selected under Signature Required Actions on the Parameters page. The write rights of the user and the value range are checked first, so a refused write does not open the Electronic Signature dialog. A variable created while Part 11 compliance mode is enabled starts with Signature Required selected. Writes by alarm, event and schedule actions, Python scripts and the gateways run without a signature. See the Electronic Signatures article. | true | Boolean |
| Recipe Targets | Recipe type name (target) this variable belongs to. Supports the {Device} placeholder, which resolves to the owning device name so one naming rule can spread a set of variables across several devices. | Line1 | Text |
| Recipe Parameter Name | Explicit name of the parameter this variable represents inside a recipe. Variables that fill the same role across different targets share the same Recipe Parameter Name, which is how values are matched on Apply and Snapshot. A variable takes part in recipes only when both Recipe Targets and Recipe Parameter Name are set. | Setpoint | Text |
| Trend Groups | Comma-separated list of trend group names this variable belongs to. A variable can be in several groups. The groups are the filter the Trend Analyst offers when picking variables. The names accept the {Device}, {DeviceName} and {VariableName} placeholders, so one UDT definition gives every instance its own group. | Pumps,{Device} | Text |
| Units | Engineering units displayed alongside the value. | RPM | Text |
| Format | Display format of the value on screens and in the Trend Analyst: the value of a Label or Input (unless the object uses its own Floating Point and Decimals), the value text of a Knob and a Slider, the Trend tooltip, a Data Grid Variable column, the right-click menu, Quick Trend, the current value in the Recipe Manager, variable tokens in alarm and event messages, and the Trend Analyst tooltip, summary and pen Format. An Input shows the plain value while it is being edited. 0 shows no decimals, 0.00 always shows two decimals, 0.0## shows one to three decimals and #,##0.00 adds a thousands separator, with up to 15 decimals. Values are rounded half away from zero for display only; alarms and expressions keep the full value, and so does the historian unless Round to Format is on. ReadVariable in the runtime API and MCP returns the Format beside the full value. Leave empty to show the value as received. | 0.00 | Text |
| Min Raw | Minimum raw value for linear scaling. | 0 | Number |
| Max Raw | Maximum raw value for linear scaling. | 27648 | Number |
| Min Scaled | Minimum scaled (engineering) value. | 0 | Number |
| Max Scaled | Maximum scaled (engineering) value. | 100 | Number |
| Converter | Converter name applied to the variable value. | Celsius_Fahrenheit | Text |
| Persistent | When enabled, the last runtime value is saved and restored on system restart instead of using the configured Value. | false | Boolean |
| External Source | Supplied from outside EnvisionSCADA: by a script with Network & File Access, the Runtime API or a gateway (Writeable). Counts as a license point. Enable it on every Local variable that receives data from outside EnvisionSCADA. Ticking Writeable enables it as well. Each enabled Local variable with External Source enabled counts as one license point, an array as one point per element. See External Source below. | false | Boolean |
| Historian | Enables historian logging for this variable. | true | Boolean |
| Round to Format | Stores the historian samples of this variable rounded to the decimals of its Format, as a plain number: with Format 0.00 the value 34.30487 is stored as 34.3. The deadband compares the rounded values, so with Deadband 0 a sample is written only when the rounded value changes. On a variable without scaling the Raw value is stored empty, since it equals the value. The live value, alarms, expressions and all interfaces keep the full value. Applies to new samples only; samples already stored keep their values. Requires a Format. | false | Boolean |
| Deadband | Minimum value change required before the historian records a new sample. | 0.5 | Number |
| MinimumTime (seconds) | Minimum time in seconds between historian samples regardless of value change. | 60 | Seconds |
| SampleGroup | Sample group name for historian grouping. | Fast | Text |
| History Source | Where the trends read the history of this variable: Project default (the History Source with Project default enabled on the History Sources page, or the EnvisionSCADA Historian when no source has it), EnvisionSCADA Historian (the samples recorded while Historian is on) or a History Source of the History Sources page (a query on a Database Connection or the fetch() function of a Python Module script). In the table, an empty History Source is Project default and Historian is the EnvisionSCADA Historian. Live values always come from the variable itself. Test reads the last 24 hours with the settings in the dialog. See the History Sources article. | Project default | Enum |
| History Reference | What the History Source reads for this variable: the reference passed to fetch(), or @Variable of the History Query. When empty, the History Reference of the source is used, by default the full name of the variable; the field shows it in italics. {Name} is replaced by the full name of the variable. Browse lists the references that a Script source offers. | CDT158 | Text |
| History Parameters | Shown for a Script source: optional key=value pairs separated by ;, added to the History Parameters of the source. A key set here replaces the same key of the source. The field shows the History Parameters of the source in italics. | scale=0.1 | Text |
| Modbus Address | Optional address on the built-in Modbus TCP and Modbus RTU servers where this local variable is exposed. The servers are enabled in the Gateways section of the Parameters page. | %MW0 | See Modbus TCP Addressing |
| OPC UA | Exposes this variable on the built-in OPC UA server. When Historize is also ticked, the Historian data of the variable is readable through OPC UA Historical Access. | true | Boolean |
| Writeable | Allows external systems to write this variable through the gateways: the OPC UA Server, the Modbus TCP and Modbus RTU servers, the MQTT publisher when Subscribe is enabled on the publisher, and Kafka when Consumer is enabled on the Kafka device. Writes from pages, actions, scripts and the API are independent of this setting. An enabled Local variable with Writeable ticked counts as a license point. See External Source below. | true | Boolean |
| MQTT Publisher | Name of the MQTT publisher that publishes this variable, typed or chosen with the ... button. A variable is published by one publisher, and the name must match a publisher on the MQTT Publishers page. Leave empty to keep the variable unpublished. Writes from the broker need Subscribe on the publisher and Writeable on the variable. See the MQTT Publishers article. | CloudIoT | Text |
| Kafka Device | Name of the Kafka device this variable is linked to, typed or chosen with the ... button. Every value change of a linked variable is produced to the Producer Topic of the Kafka device while the device is enabled. Writes from the Consumer Topic need Consumer on the Kafka device and Writeable on the variable. Leave empty to keep the variable unlinked. See the Kafka Devices article. | KafkaBroker1 | Text |
| Kafka Remap Device | Device name used for this variable in Kafka messages instead of Local, the device name of local variables. Inbound messages from the Consumer Topic are matched on this name as well. Leave empty to use Local. | RemotePLC1 | Text |
| Kafka Remap Variable | Variable name used for this variable in Kafka messages instead of its own name. Inbound messages from the Consumer Topic are matched on this name as well. Leave empty to use the variable name, for example Counter. A name that starts with Local. is used without that part, so Local.Pump1_RunCount is sent as Pump1_RunCount. | RunCount | Text |
No rows match the filter.
Supported Data Types
The Type field determines how the variable value is stored and interpreted.
| Type | Description | Size |
|---|---|---|
| BOOL | Single bit value (true/false). | 1 bit |
| BYTE | Unsigned 8-bit integer. | 1 byte |
| INT | Signed 16-bit integer. | 2 bytes |
| UINT | Unsigned 16-bit integer. | 2 bytes |
| WORD | Unsigned 16-bit word. | 2 bytes |
| DINT | Signed 32-bit integer. | 4 bytes |
| UDINT | Unsigned 32-bit integer. | 4 bytes |
| DWORD | Unsigned 32-bit word. | 4 bytes |
| REAL | 32-bit IEEE 754 floating point. | 4 bytes |
| LINT | Signed 64-bit integer. | 8 bytes |
| ULINT | Unsigned 64-bit integer. | 8 bytes |
| LREAL | 64-bit IEEE 754 floating point. | 8 bytes |
| STRING | Text string. | Variable |
No rows match the filter.
Variable Arrays
A variable can expand into an array by setting the Array size field to a value between 2 and 512. The variable itself is the first element and its Name must end in the first index, for example Temps[0]. The remaining elements are created automatically as Temps[1], Temps[2] and so on. A Local variable carries no address, so only the name advances. Each element holds its own value and can be given its own initial value after the array is created.
The element rows are managed by the first element: they follow its settings, appear locked in the variable list, and are edited by editing the first element. Changing the Array size adds or removes elements at the end. Renaming the first element or changing its address renames and re-addresses all elements. Setting Array size back to 0 while elements exist removes the elements.
To turn the elements into ordinary independent variables, use the Ungroup array action on the first element's row in the variable list, or the Configuration API (POST /API/Config/VariableArrays/Ungroup). All rows are kept and only the grouping is removed. This is one-way. The element count badge next to the first element's name folds and unfolds the element rows in the list.
External Source
Local variables do not count against the license, so they hold calculations, operator settings and internal states. A Local variable counts as a license point like a device variable when it is enabled and receives data from outside EnvisionSCADA through one of three settings:
External Source: a Python script with Network & File Access writes data it obtains from a device, a web service or a file, or a program writes through the Runtime API.
Writeable: a client writes through a gateway.
History Source: the trend history is read from another system. Historian, and an empty History Source while no History Source is the project default, is the EnvisionSCADA Historian and does not count.
The three settings are independent: ticking Writeable or selecting a History Source does not enable External Source. The variable list and the variable dialog mark a variable that counts with License point, and its tooltip names the settings that make it count. The count follows the configuration: it changes when one of these settings or Enable changes, not while scripts run.
The line Local variables that count as license points above the variable list shows the points these variables use. In this version they are counted and shown on the License page, but are not yet part of the license check: a future version adds them to the Current Point Count, see the License article.
These writers only write device variables and Local variables that count as license points:
| Writer | A write to a Local variable that does not count as a license point |
|---|---|
| Python script with Network & File Access | Refused, while the other writes of the run take effect. The run reports Not written, not an External Source variable: Name. Tick External Source on these Local variables. |
| Runtime API WriteVariable | Refused with Runtime API: WriteVariable can only write device variables and External Source variables. followed by the reason. A write to a disabled variable is reported the same way. |
| Built-in OPC UA server, built-in Modbus server, MQTT publishers, Kafka devices | Written when Writeable is ticked, which makes the variable count. A write to a disabled variable is refused: an OPC UA client receives BadNotWritable, and the System Log reports Write to Name refused. with the reason, once per variable. |
| MCP WriteVariable, pages, actions, Python scripts without Network & File Access | Written. These writers act for an operator or within EnvisionSCADA. |
No rows match the filter.
The Mark as External Source dialog of the Python Editor enables External Source on the variables that a script with Network & File Access could not write, see the Python Scripts article.
The License point mark in the variable row updates as soon as one of these settings changes. The line above the variable list shows the new count after the page is reloaded.
A project made with an earlier version can contain Local variables with Writeable ticked. After the update these variables count as license points and the gateways write them.
A STRING Local variable that counts as a license point can only be read by scripts with Network & File Access and by reports. A script without Network & File Access that reads it stops with a message that names the variable.
On a Local variable created by a UDT instance, External Source, Writeable and History Source are set on the Local variable member of the UDT definition and applied to the instances by the push. The Asset Manager marks a variable member whose variables count with License point. On an array, these settings are set on the first element and apply to every element.
Notes
Local variables are not connected to any external device or protocol. Their values exist only within EnvisionSCADA.
The Value field defines the initial value loaded at system start. When Persistent is enabled, the system saves the last known runtime value and restores it on restart instead of using the configured Value.
The Modbus Address field optionally registers the local variable on the built-in Modbus server, making it accessible to external Modbus masters. Use the same addressing notation as Modbus TCP variables.
Variables are referenced at runtime by their full Name exactly as written, for example Local.Pump1_RunCount. The name is free to choose and must be unique across the whole project.