Lua runner examples

Configuration Example With Default and Saved Values (Modbus TCP, IEC104)

Excel configuration

An Excel configuration for WCC Lite is needed to control signals with a Lua script. In this case, three devices are required: one for Modbus TCP Master, one for IEC104-slave and one for Lua runner. Configuration example:

image-1691501602369.png

To connect slave and master devices, the master's IP address and the slave's host addresses have to be specified. Modbus IP address will be the address of Wi-Fi to which the computer is connected (this can be checked on the terminal window with the command ipconfig), and the host address for IEC104 slave protocol will be the IP address to which WCC Lite is connected. To reach the device via these addresses, WCC Lite has to be connected to the internet.

When creating an Excel configuration with Lua, there is an option default value for the signal. This value will be set to the signal right after uploading the configuration, or if the script does not return any saved values.

Signals sheet:

image-1692706261790.png

As it is seen from example values, such as min_value and max_value, can be added to determine the limits of a signal. This way command signal will only return results which are within this range. Otherwise command value will have negative cot with invalid, non topical or overflow attributes and new value will not be sent to result signals. As configured, until command value is sent default value will be represented for Lua command signal. For saved values to be represented a Lua script is needed. 

Lua script 

Lua script example for this configuration is shown below:

local saved = get(signals.result) --getting result signal which is equated to new variable 'saved'
local command = get(signals.command) --getting command signal which is equated to new variable 'command'

--get() function returns nill if there is no valid value

if not command then --if command is not nill
    if saved then --if signal is not nill
        publish(signals.result, saved.value) --this value is published to result signals and saved value
    end
    return 0
end 


local time_diff = time_ms() - tonumber(command.time) --compares command time and real time
local is_command = time_diff < 30000 and time_diff > -30000 --if command time differs from
--real time more than 30s it will not be executed 


if string.find(command.attributes, "nt") or string.find(command.attributes, 
    "iv") or string.find(command.attributes, "ov") then
  --searching if signal has negative attributes 
    if is_command then --if command execution time is not exceeding the limits then
        command.attributes = "cot=7,cotn" --equates negative cot values to response signal attributes
        publish(signals.command, command) -- and publishes value to command signals and value
        if saved then --if there is saved value then
            publish(signals.result, saved.value) --restores saved value to result signals
        end
        return 0
    end
else
    if is_command then
        command.attributes = "cot=7" 
        publish(signals.command, command)   --in this cycle command value is being returned as well as
    --cot7 and cot10 values in case given signal is command and has no negative attributes
        command.attributes = "cot=10"
        publish(signals.command, command) --publishes response to the command
        save(signals.result, command.value) --command value is being saved to result signal
    end
    publish(signals.result, command.value) --in this row command value is being published to result signals
end

Uploading configuration and Lua script to WCC Lite

First Excel configuration needs to be uploaded to WCC Lite:

image-1671526558865.png

After uploading configuration default value will be shown:

image-1692712552551.png

After uploading configuration no errors should appear and all signal should be represented on the web. To upload Lua script go to Script-Runner, select upload script and then start:


image-1671526957681.png

Connecting master and slave via Vinci software

Connecting IEC104 slave 

In order to connect to WCC Lite via IEC104 protocol, select Master(Client) mode on Vinci:

image-1671528870849.png

Check Settings tab to match excel configuration:

image-1671528969827.png

Specify IP address which should match the one in Excel configuration.

Connecting ModbusTCP master:

To connect ModbusTCP Master, select Slave (Server) mode on Vinci:

image-1671530055509.png

Check address to match id in Excel configuration:

image-1691399259812.png

Match the IP address given in Excel configuration as well.

Executing commands

Start both master and slave simulations on Vinci. Check if both protocols are connected to WCC Lite on the web tab Protocol Connections:

image-1692703562023.png

To execute commands, open Vinci program with IEC104 master running. Here, go to System tab and fill in required fields such as IOA and select data type indicated in Excel configuration. First, try sending value that is outside the set range:

image-1692952309993.png

After selecting execute this value will not be showed on the web and positive cot6 and negative cot7 values will be seen on Vinci IEC104 simulation window. Positive cot6 indicates command activation and negative cot7 means that command activation confirmation was denied. The command signal value will not be represented as result signals, because it is determined in the script, that signals with negative attributes will not be published. 

image-1692957902714.png

Now specify value which will be sent as a result and is within the given range.  

image-1691399941593.png

Positive cot7 and cot10 values will be seen on the Vinci IEC104 simulation window:

image-1691400062905.png

This value will also be represented on Modbus TCP master Vinci simulation window:

image-1691400136020.png

To show what happens if the value is not within determined range after the correct value has been sent before, try executing command with smaller or larger value specified:

image-1691400179325.png

Again, positive cot6 and negative cot7 values is seen on Vinci window.

image-1691400197027.png

As seen on WCC Lite web window, command signals have negative attributes and result signals have the same value as before, because it was saved by Lua script. This example shows that Lua runner can be used to save certain values to signal. For example after the restart saved value could be seen on command signal to determine minimum or maximum value, last value or typical value. This solution could be useful for protecting important data even after reboot or connection faults. 

Configuration --> Download

Lua script --> Download


Signal Delay with Lua

For delaying the response of command execution, the Lua runner could be used as one of the solutions. In this example, IEC104 and Modbus TCP are used. IEC104 protocol sends the command to Modbus and Lua signals, and the results are represented as two separate signals. To create an Excel configuration for WCC Lite, in this case device sheet should look like this:

image-1691574338163.png

In the fields marked red, for Modbus TCP, enter the IP address of the Wi-Fi connected to a computer, and for IEC104, enter the IP address of WCC Lite. Map the signals as shown below:

image-1692965126845.png

IEC104 SCADA will send a command, which will then go to the Lua signal. Lua signal will send the response back to the IEC104 SCADA and Modbus TCP result signal. 

For delaying signal response, a Lua script could be written in many ways, however, the simplest and effective one is to determine a wait time before publishing signal values to result signals. So in this case Lua script will look like this:

local saved = get(signals.result)--getting result signal which is equated to new variable 'saved'
local command = get(signals.command) --getting command signal which is equated to new variable 'command'

if not command then
    if saved then
        publish(signals.result, saved.value)--this value is published to result signals and saved value
    end
    return 0
end

if string.find(command.attributes, "nt") or string.find(command.attributes, "iv") or string.find(command.attributes, "ov") then
   --searching if signal has negative attributes 
  if command then
      	command.attributes = "cot=7,cotn"--equates negative cot values to response signal attributes
        publish(signals.command, command)-- and publishes value to command signals and value
        if saved then
            publish(signals.result, saved.value)--restores saved value to result signals
        end
        return 0
    end   
else
  if command then
        command.attributes = "cot=7"
        publish(signals.command, command)--in this cycle command value is being returned as well as
  --cot7 and cot10 values in case given signal is command type and has no negative attributes
        command.attributes = "cot=10"
        publish(signals.command, command) --publishes response to the command
        save(signals.result, command.value)--command value is being saved to result signal
    end
    local sleepTime = 30 
    sleep(sleepTime) --before publishing values to result signals script waits 30s
    publish(signals.result, command.value)--in this row values are being published to result signals
end

After entering values to empty Excel configuration fields, upload the configuration to WCC Lite (it should upload without any errors):

image-1691483399099.png

Upload the Lua script to the script runner and press start. After this, Status should show Running, and the script process number will appear.image-1691650520213.png

Open Vinci as an IEC104 master, enter the IP address of WCC Lite and start communication. Then open another Vinci window and connect Modbus TCP master – select Modbus TCP slave in Vinci and enter the same IP address as set in the Excel configuration for the Modbus device. With both communications running, check Protocol connections on the WCC Lite web interface, it should show connected. From the IEC104 Vinci window, go to the System tab. Select command determined in the Excel configuration (50), IOA (1) and value (eg, 2). 

image-1691656106450.png

Execute the command and check Imported signals:

image-1691656557970.png

After 30s the result signals will now have the same value:

image-1691657076669.png

Signal delay could be used as a tool to synchronise signals so all the values are received at the same time. It can also be used to schedule commands or tasks when a delay is required. Since Lua is one of the fastest programming languages, it is the most effective instrument to be used in such matters.

Configuration --> Download

Lua script --> Download

Mathematical Operations With Lua (FW version 1.7)

Mathematical operations can be applied to Lua signals as in any other protocol. This can be done by configuring WCC Lite according to the solution needed. To create an example which tests multiple mathematical operations, an Excel configuration and a Lua script are required. The device sheet should look similar to this:

image-1691759419298.png

Each Lua device is created to send result values to Modbus TCP signals with different mathematical functions applied. This way, the same Lua script can be reused and is more optimal since the signal alias for each device can stay the same. There are many other solutions, but this one allows us to observe results more clearly.

In the field  "ip" for Modbus TCP master, enter the IP address of the Wi-Fi connection for the computer in use. In the field "host" for IEC104 slave protocol, enter the IP address of the WCC Lite device. 

Signals for these devices should be mapped, for example, to this:

image-1691761247612.png

Each Lua device has command and result signals. Command received from the IEC104 protocol is sent to the Lua command signal, and then this signal sends back a response for the IEC104 protocol. If the response does not have negative cot attributes, the value is then sent to the Lua result signal, which sends the value to the Modbus TCP result signal. Mathematical operations are applied to IEC104 protocol signals since it is the one sending the commands.

As mentioned before Lua script for each Lua device is going to be unchanged and should look like this:

local saved = get(signals.result) --getting result signal which is equated to new variable 'saved'
local command = get(signals.command) --getting command signal which is equated to new variable 'command'

--get() function returns nill if there is no valid value

if not command then --if command is not nill
    if saved then --if signal is not nill
        publish(signals.result, saved.value) --this value is published to result signals and saved value
    end
    return 0
end 


local time_diff = time_ms() - tonumber(command.time) --compares command time and real time
local is_command = time_diff < 30000 and time_diff > -30000 --if command time differs from
--real time more than 30s it will not be executed 


if string.find(command.attributes, "nt") or string.find(command.attributes, 
    "iv") or string.find(command.attributes, "ov") then
  --searching if signal has negative attributes 
    if is_command then --if command execution time is not exceeding the limits then
        command.attributes = "cot=7,cotn" --equates negative cot values to response signal attributes
        publish(signals.command, command) -- and publishes value to command signals and value
        if saved then --if there is saved value then
            publish(signals.result, saved.value) --restores saved value to result signals
        end
        return 0
    end
else
    if is_command then
        command.attributes = "cot=7" 
        publish(signals.command, command)   --in this cycle command value is being returned as well as
    --cot7 and cot10 values in case given signal is command and has no negative attributes
        command.attributes = "cot=10"
        publish(signals.command, command) --publishes response to the command
        save(signals.result, command.value) --command value is being saved to result signal
    end
    publish(signals.result, command.value) --in this row command value is being published to result signals
end

Upload Excel configuration to WCC Lite:

image-1671526558865.png

After uploading the configuration, no errors should appear, and all signals should be represented on the web. To upload a Lua script, go to Script-Runner, select upload script and then start (for each Lua device):

image-1691650520213.png


Open Vinci as an IEC104 master, enter the IP address of WCC Lite and start communication. Then open another Vinci window and connect Modbus TCP master – select Modbus TCP slave in Vinci and enter the same IP address as set in the Excel configuration for the Modbus device. With both communications running, check Protocol connections on the WCC Lite web interface, it should show Connected. From the IEC104 Vinci window, go to the System tab. Select command determined in the Excel configuration (50), IOA (different for each signal) and value. After executing the command, each signal (IEC104 command, Lua command, Lua result and Modbus result) will have the same value, which will now be with math applied. For example, a command with IOA=1 and value 1 is being executed. In Excel configuration for this signal, add a column has a value of 5, which means that this value is going to be added to the value sent and the result will be 6.

There can be multiple mathematical operations for one signal. For example, add, multiply, bit select, etc. If that is the case, math will be applied in typical order (eg, first bit select, then multiply, then add).  A more detailed explanation about mathematical operations in Excel configuration can be found here: Optional parameters for signals.

A user can also apply a mathematical condition for the signal value. For example, minimum or maximum value, threshold, suppression time for specific value, etc. Minimum and maximum values can be applied to set the range of the signal; if the value is smaller or larger signal state will show invalid or overflow. Thresholds can be used in many ways. It can be a specific value or a percentage. If the signal value passes the set threshold, it will be represented in the imported signals window. Threshold works by comparing the old value with the new value and then applying the condition of either representing the value or suppressing it, depending on the value change. Suppression value and suppression time are best used together because suppression time determines how long the specific value should be suppressed. There could be multiple values set for suppression. In Excel configuration, those values should be separated by a comma. 

Mathematical operations combined with a Lua script are useful for many cases. They can be used for filtering data, converting units, applying specific mathematical logic or other solutions. 

Configuration --> Download

Lua script --> Download


Cronjob example

Lua device can be configured using a cron time expression. This way, script execution can be scheduled or executed at certain times. To create such a solution, the device sheet of the Excel configuration should look like this:image-1692192128948.png

As seen in this configuration, the execution type for the Lua device is date, and the execution parameter is in a cron time expression. In this case script will be executed every 30 seconds starting from a mm:30 or a mm:00 mark. There are a lot of online cron expression parsers or generators to convert this expression to a more understandable form: https://crontab.cronhub.io/.

A Cron expression must have six variables; for instance, the code "0 * * * *" will not suffice because it contains only five variables. To rectify this, add a "0" to the beginning of the code: "0 0 * * * *". Similarly, the code "0 20-23,0-4,11 * * *" which is displayed as correct on the website, to achieve the effect of every hour from 08:00 PM to 11:59 PM, 12:00 AM to 04:59 AM, and 11:00 AM, it must be adjusted as follows: "0 0 20-23,0-4,11 * * *".

To complete the Excel configuration, fill out the red fields with the correct parameters. For the "ip" field, enter the IP address of the Wi-Fi connection that is connected to the computer. This can be checked by entering the command "ipconfig" in a terminal window. For the "host" field, enter the IP address of the WCC Lite device.

The signals sheet should look similar to this:

image-1692193770966.png

IEC104 SCADA will send a command, which will then go to the  Lua signal. Lua signal will send the response back to the IEC104 SCADA and Modbus TCP result signal. 

The Lua script in this case will be very simple. To show how Lua with cronjob can be used in real life, a calculation for kilowatts per hour has been added:

local kW = tonumber(get_value(signals.command))--function "get_value" will get value from iec104 command
--without any attributes this value is still in string form so funtion "tonumber" will convert it to number
--a new variable is creted which is now equal to command value
value = value or 0 --new variable is created. It has to be equal to itself or to 0 if the script is running
--for the forst time
value = (kW * 30/3600) + value --formula for calculating kilowatts. command value from iec104 is multiplied by time. 
--Since the script is being executed every 30s, this time needs to be converted to hours. an old value is being
--added to new value, this way result value that is being published will grow every 30s
publish(signals.result, value)--publishes result to result signals for lua and modbus TCP. 
--Since the script is being executed every 30s, those values will be refreshed every 30s as well

To test the functionality of this script, upload the Excel configuration to WCC Lite (it should upload without any errors):

image-1691483399099.png

Upload the Lua script to the script runner and press start. After this, Status should show Running, and the script process number will appear:

image-1692256160683.png

Open Vinci as an IEC104 master, enter the IP address of WCC Lite and start communication. Then open another Vinci window and connect Modbus TCP master – select Modbus TCP slave in Vinci and enter the same IP address as set in the Excel configuration for the Modbus device. With both communications running, check Protocol connections on the WCC Lite web interface, it should show connected. From the IEC104 Vinci window, go to the System tab. Select command determined in the Excel configuration (50), IOA (1) and value (for example 3600).

image-1692256267495.png

Execute the command and check Imported signals:

image-1692256755579.png

On a 30s mark, result signals will have a calculated value:

image-1692256964491.png

After another 30 seconds, a new value will be added to the old value, and the result signals will be updated accordingly:

image-1692257097082.png

Cronjob with Lua can be used mainly to schedule tasks. It can also be used as a way to filter, monitor or control the data. As seen in this example, a Lua script can help calculate certain parameters, which then can be sorted using a cron time expression. 

Configuration --> Download

Lua script --> Download

Execution_signal example

The execution_signal parameter returns information about the specific signal that triggered execution. If there are multiple possible source signals, it identifies the one that initiated the execution. In this example, the Modbus RTU protocol is used. Configuration of devices:

image-1740645086014.png

Execution_signal should always be "signal" when execution_signal is used. PORT2 is used to connect IOMod 8DI8DO to WCC Lite via RS-485. IOMod signals configuration in this case:

image-1740645367520.png

In this case, IOMod's input signals are used, but other signals can be used depending on needs. Map the signals as shown below:

image-1740646177825.png

The first Lua signal is executing the first input signal, while the second Lua signal is executing the second input signal. The results signal is used to store information about the executed signal.


A Lua script can be written in various ways using the execution_signal parameter. However, in this example, a simple Lua script is used to retrieve the signal_alias of the executing signal by accessing execution_signal.tag.signal_alias:

local DI = execution_signal.tag.signal_alias

if DI == "DI1_lua" then
    publish(signals.results, 1)
elseif DI == "DI2_lua" then
    publish(signals.results, 2)
end

This is just one example of execution_signal usage. It can retrieve different information about executing a signal using:

Upload the configuration to WCC Lite (it should upload without any errors):

image-1740649584122.png

Upload the Lua script to the script runner and press start. After this, Status should show Running, and the script process number will appear.

image-1740649663116.png

After activating the first input, in the WCC Lite web's imported signals tab, results should display 1:

image-1740650410927.png

After activating the second input, in the WCC Lite web's imported signals tab, results should display 2:

image-1740650545463.png

Configuration --> Download

Lua script --> Download