Virtual Tag

Expression

For tag parameters not covered herein, see Tag Editor.

A simple code editor with support for basic context assistance. The input field is split into two tabs:

Readable Script

Runs code meant to generate the virtual tag’s output value. The value resulting from running the code entered in this tab will be displayed in view mode as well as in the HMI, e.g. in Tag Lookup. Therefore, the code must return a value:

var total = 2 + 2;

This code will not return a value.

var total = 2 + 2;
total

This code will.

There are several important considerations concerning readable scripts:

• The code will run as long as it is syntactically correct; the tag will not display a value if the code does not return one.
• Although the Data type selector has all possible data types in the dropdown menu, only scalar values are supported. A virtual tag will show 0, equivalent to false, if the script returns an array. Attempting to select a non-scalar data type will revert the selection to the default double (scalar).
• The Cloud does not support string values for tags, and an attempt to return one with a readable script will result in displaying an error:

  Cannot convert value 'Hello, world!' with 'class java.lang.String' class to DataValue
  

Writable Script

Runs code that is meant to generate a value to be written to another tag, see writeValue.

The two tabs function independently of each other; thus, variables declared in one will not be available in the other.

Hotkeys and Shortcuts

The code editor used in the Cloud is the open-source Monaco Editor, which in turn is the editor that VS Code is built on. Thus, the same keybindings can also be used while editing a readable or a writable script. Press F1 to bring the Command Palette that lists all available actions and their respective keyboard shortcuts, if there are any.

In addition, the following custom key combinations are available to facilitate code writing:

• alt + shift + A (Windows/Linux), ⌥ + ⇧ + A (macOS) opens alarm selector, also available by clicking on  Pick up an alarm above the code editor.
• alt + shift + T (Windows/Linux), ⌥ + ⇧ + T (macOS) opens Tag Selector, also available by clicking on  Pick up a tag above the code editor.

Update this tag using the specified period

Determines how frequently the tag will run the code written under Readable Script.

The JS implementation in the Cloud comes with the following custom methods:

inputValue

Only works in the Writable Script tab.

Enables the virtual tag to accept user input in the HMI, effectively making it writable. Unlike a regular writable tag, a virtual tag can further process user input, e.g., perform mathematical operations with it.

Syntax

inputValue(value)

Parameters

• value
  Value to be received from manual input in the HMI.

writeValue

Only works in the Writable Script tab.

Writes a value to the target tag; can be used in combination with inputValue.

Syntax

writeValue(tag, value)

Parameters

• tag (string, mandatory)
  Name of the target tag, inclusive of the full path. The target tag must support writability but does not have to be made writable.
• value (integer, float, or boolean; mandatory)
  Value to be written to the target tag; can be a function, e.g., inputValue. The script editor accepts any data type as value; however, only the specified data types can be written to tags without triggering an error in the HMI.

nordpool_areaPrices & nordpool_areaPricesValues

Requires Nord Pool API access, see Nordpool

Returns Nord Pool prices in JSON format or as an array, respectively, for the specified area in the specified currency over the specified timespan, with breakdown by hours. Prices are per megawatt-hour.

Syntax

nordpool_areaPrices(deliveryArea, currencyCode, startTime, endTime, status)
// returns JSON
nordpool_areaPricesValues(deliveryArea, currencyCode, startTime, endTime, status)
// returns array

Parameters

• deliveryArea (string, mandatory)
  Specifies the area to return price values for. For list of delivery areas, consult Nord Pool API documentation here or here. For a map with available delivery area codes, see Day-ahead overview.
• currencyCode (string, mandatory)
  Specifies the currency to return price values in. Currently, only four currencies are supported: EUR, SEK, NOK, DKK.
• startTime (string or number, mandatory)
  Specifies the starting point of the timespan to return price values for.
• endTime (string or number, mandatory)
  Specifies the ending point of the timespan to return price values for.

  For both startTime and endTime, use UTC datetime represented either in the ISO 8601: RFC 3339 format (string) or as a Unix epoch timestamp (integer) in milliseconds.

• status (string, optional)
  Specifies whether to return preliminary (P) or confirmed (O) price values; defaults to the latter unless specified. The difference between these two status codes is explained here.

Output

nordpool_areaPrices(...)

returns a JSON series of several sets of key-value pairs, one set for each hour within the specified timespan. The keys in each set are startTime, endTime, and value, where the values for startTime and endTime are strings representing the start and end of an hour-long subperiod in the RFC 3339 format; the value for value is a float representing the price in that subperiod.

nordpool_areaPricesValues(...)

returns an array of floats representing price values, one for each hour within the specified timespan.

Examples

Both expressions below request day-ahead prices in euros for the area designated as SE3 for a period spanning 48 hours from the time of the virtual tag’s update (now); however, they will produce different outputs.

var now = getCurrentTime();
var json = nordpool_areaPrices('SE3', 'EUR', now, now+3600000*48);
json[0].value;

This expression will return the first hourly price value within the specified timespan (indexed as [0]):

[25.86]

Virtual tags can only display or return scalars and/or arrays. Dictionary-like objects, such as JSON outputs, can be used within a virtual tag’s expression and performed various operations on, e.g., to retrieve a value by index as shown in the example above. However, a virtual tag will not produce any output if programmed only to return such an object. Therefore, nordpool_areaPrices should always be used in conjunction with an operation that returns a single value or array.

Note as well that virtual tags do not support string output.

var now = getCurrentTime();
nordpool_areaPricesValues('SE3', 'EUR', now, now+3600000*48);

This expression will return an array like this:

[25.86, 25.23, 24.63, 25.02, 27.71, 37.66, 60.93, 64.89, 68.25, 66.78, 64.88, 63.84, 61.27, 60.31, 60.84, 60.25, 58.74, 60.03, 60.26, 53.25, 30.6, 24.62, 22.37, 20.61, 130.32, 78.14, 66.68, 63.04, 31.94, 24.02]

The returned array may contain fewer values than the requested coverage would suggest, e.g., when requesting data over a timespan that extends further into the future than Nord Pool’s most recent update would cover, as illustrated in the example above.

Either function returns price values only for full hours within the timespan specified in the request. For instance, if the requested timespan begins at 21:44, the first value will be valid for 22:00:01 — 22:59:59.

Nord Pool updates preliminary prices for a given calendar day at 10:45 UTC the day before and normally publishes confirmed values to the APIs by 11:00 UTC, thus providing a theoretical maximum coverage of ~37 hours in advance.

Note as well that data retrieval is not supported for periods exceeding 8 calendar days.

While there are no technical restrictions regarding this, EnergyMachines™ kindly asks users utilizing Nord Pool integration to set the respective virtual tags to a 24-hour update interval, in order to avoid excessive API surcharge. This does not apply if the user has their own Nord Pool subscription.

metryReadings

Requires Metry API access, see Metry.

Returns an array of values from a Metry data point.

Syntax

metryReadings(metryId, period, metric)

Parameters

All parameters are mandatory strin

• metryId (string, mandatory)
  Target meter ID; available IDs can be retrieved using Display Meters.
• period (string, mandatory)
  Specifies the period of data retrieval; two options are available:
  • Hyphen-separated substrings for start and end; OR
  • Single string for a calendar period.

  YYYYMMDDHH-YYYYMMDDHH
  // calendar period; OR
  YYYYMMDDHH
  // start and end
  

  The period string, or each substring, contains up to 10 characters specifying the year (4 characters), followed by month, day, and hour (two characters each). Only numeric characters and the hyphen are accepted.

  Data timestamps are not converted into the project’s timezone; refer to the timezone set for the meter in order to set the period.

• metric (string, mandatory)
  Target metric, which must be one of the metrics associated with the target meter; other metrics are filtered out.

Examples

The expressions below use different period specification methods:

metryReadings("{metryId}", "2024", "energy");

Returns an array of values where:

• value source is the meter with the specified metryId,
• value timestamps fall within 2024,
• the associated metric is energy.

metryReadings("{metryId}", "2022031514-202405", "flow");

Returns an array of values where:

• value source is the meter with the specified metryId,
• value timestamps fall within the period from 14:00 (2 PM) on March 15, 2022 through May 2024,
• the associated metric is ‘flow’.

This function returns an array where values might have decimal points. Set the Data type and the External data type to float or double arrays, or program array-processing logic to ensure correct display of the tag’s output.