Control Parameters and Virtual Parameters a Series on Scripting in OnPing

by: Scott Murphy

1 What are we doing?

Using control parameters and virtual parameters, we will extend the gathered information
in a system. I will build a set of min, max, accumulated and average parameters.

Going through this will introduce a lot of the techniques available to manipulate data
in onping.

This will be the first in a series of onping blog posts on building up more advanced parameters.
This will be building the parameters in the first place, the next will be designing a template system
to deploy them.

2 Why scriptable systems?

One of the main themes of onping is reducing code. So if that is true, why add a script language?
The answer to this question is, some tasks are just best accomplished in code!

3 Getting Started

First, lets look at the data we have

3.1 The Best Bread Bakery

The Best Bread Bakery uses a hosted SCADA system, OnPing to allow quick adjustment and customizaton.
They calculate the performance of each machine and display in this overview hmi.

We have been asked to add a few new parameters to the system.

  • Uptime
  • Monthly Max uptime
  • Monthly Min Uptime

3.2 Control Parameters and Virtual Parameters

There are two kinds of paramters for adding calculated values into onping.

  • Control Parameters
  • Virutal Parameters

3.2.1 Control Parameters

Control parameters run on the lumberjack application system. They are executed
on a schedule, on event, or at a set frequency. They have access to the history
and parameters that are local to the lumberjack in question. They are defined
entirely by the parameter they write to. It can be a new data point if they
are tied to a manual-entry device in OnPing. Control parameters can also be used
to script a value directly into an existing device supported by OnPing.

3.2.2 Virtual Parameters

Virtual parameters run on OnPing’s cloud servers. They can access parameters from anywhere
you have permissions for in OnPing. They are calculatd at the point of request.
They are not able to write values nor do they store values. Because they calculate values
on demand they can suffer from some performance problems when running complex commands.
However for a large variety of tasks they are completely usable and they are the most affordable
tags in OnPing by far.

3.2.3 Which will we use?

We will define each of our key values with a Control Parameter but then
use virtual parameters to make the values graph a little nicer in analysis systems.

3.2.4 Structured-Script

OnPing uses a scripting language called Structured Script. It is very similar to Structured Text
but does have some differences. The best overview for the language is here.

One major difference between structured-script and many other languages is the concept of Unit.
Our parameters (virtual or control) process data as a stream, because of that there are a lot of
times the data is not available. We have a lot of support to help you remember this is possible.

The main structure for ensuring a stream has data looks like this:

example := latestInput(1);

if (isUnit(example)) then 

output := ();

else

output := example/2;

end_if;

We can’t do math like example/2 until we show the math will not hit a unit value.

4 Building the Control Parameters

4.0.1 Create a Target Location

Control parameters are defined by their output so first we will make a new Manual Entry
location to target for control parameters.
DoughMixerExampleParameters.png

4.0.2 Add Output Parameters

Once the location is defined the outputs are added.
AddDestinationParameters.png

4.0.3 Add the Scripts

To add a Control Parameter you look up the device by lumberjack ID.
It generates a list of the output parameters.

ShowOutputsInControlParameters.png

  1. Uptime

    After clicking New the screen for putting together control params comes up.
    ControlParameterEditScreen.png
    Here you can see several sections.

    1. Properties

      The properties section has the

      • Resolution, which controls the granularity

      of the parameter history.

      • Lumberjack, simply the ID of the lumberjack
    2. Update Configuration

      The update configuration sets when a control parameter is calculated and its output
      is updated. We will run our scripts on a scheduled time 12:00AM.

    3. Input Parameters Output Parameters

      The output parameter can’t be changed. The input parameters are any parameter saved on the lumberjack.
      We will select Run Status of the mixer for ours.

    4. Example Scripts

      The example scripts give you a quick reference for several methods.

    5. Edit Screen

      This is where we write the script. It is also where the output is shown during testing.
      Test and write will save a value to the output parameter.

    6. Enough of all this lets write a script!
      acc := 0.0;
      
      WITH t FROM now - days(1) TO now EVERY minutes(1) DO
        x := input(1,t);
        IF not(isUnit(x)) THEN
        
        IF (x == 1.0) THEN
        
          acc := acc + 1.0;
        
        END_IF;
        
        
        END_IF;
      END_LOOP ;
      
      /* Output Hours Runtime */
      output := acc / 60.0;
      
      

      We gather 1 point every minute and check that a value is there, if it is
      we add it to a running total. At the end we convert the total into hours
      and save the result to output.

      That is it!

  2. The rest
    1. Monthly Max/Min uptime
      • Ran Monthly
      • Use Uptime we just made as the input

      ConfigurationParameter.png

      max := latestBefore(now-months(1), 1);
      
      if not(isUnit(max)) then 
      
      WITH t FROM now - months(1) TO now EVERY days(1) DO
        x := latestBefore(t,1);
        if not(isUnit(x)) then 
          if (x > max) then 
            max := x;
          end_if;
        end_if;
      END_LOOP;
      output := max;
      
      
      else 
      
      output := ();
      
      end_if;
      
      

      Lots of neat things going on here, we use the defined date and time functions.
      months is defined to be 1 month back from whatever the current month is.

      We use latestBefore instead of input to gather the values this time.
      This allows us to just go lightly through the historical values and let
      OnPing do the work of finding where the uptime actually is and giving it to us.

      Min is defined the same way but with the opposite sign.

      min := latestBefore(now-months(1), 1);
      
      if not(isUnit(min)) then 
      
      WITH t FROM now - months(1) TO now EVERY days(1) DO
        x := latestBefore(t,1);
        if not(isUnit(x)) then 
          if (x > min) then 
            min := x;
          end_if;
        end_if;
      END_LOOP;
      output := min;
      
      
      else 
      
      output := ();
      
      end_if;
      
      

5 Building the Virtual Parameters

We could just stop here, the control parameters define the data we need.
But it would be nice to map the value being calculated to anywhere in a trend line.

There is an existing script we have that is perfect for this sparseDataMapper and it is a perfect
item for a virtual parameter.

5.1 Components of the Virtual Parameter screen.

PropertiesAndInputParameters.png

5.1.1 Properties

  • VP Name – The name displayed everywhere
  • VP Description – The description of what we are building
  • Script Name – The name of the script for future use
  • Script Group – Permissions for the script
  • Resolution – The amount of approximation used (I will write a whole blog post at some sort)

5.1.2 Input Parameters

Just like control parameters, these are the parameters used to do calculations.
But unlike control parameters, you can pick any parameter you have access to.
We will pick each of the control parameters we made, one by one.

5.1.3 Editor Screen

Again very similar to the CP Editor, but without the test and write function. Since there is no “write”.

5.2 Using existing script

For this parameter we are using an existing script.
ContinueEditing.png
we need to select continue editing and name it.

The script is just…

output := latestInput(1);

Now we can see a clean line for the uptime (even though it is only calculated at one point).
analysis-mapped.png

6 Now what?

We can use these parameters in any context we want. However, it is a lot and we wouldn’t want to do all this over and over.
In the next post we will show how to templatize making these for multiple machines or sites.