Trend Binding Callback

The Trend Binding Callback function that you implement must have the following definition:

function myCallbackFunction(data) {
    ... your custom implementation here ...
}

You can name the function anything, as long as it takes a single argument. An example of how this might be used along with a set of Trend Bindings follows:

<script type="text/javascript">
    OAS_config = {
        token:'7e61b230-481d-4551-b24b-ba9046e3d8f2',
        serverURL: 'http://localhost:58725',
        trend_bindings: [
            {
                chartid: "myChart",
                samplerate: 1,
                timeframe: 100,
                tags:[
                    {
                        label:"ramp",
                        tag:"Ramp.Value",
                        color:"#090"
                    },
                    {
                        label: "random",
                        tag: "Random.Value",
                        color: "#f00"
                    }
                ],
                retain: 100,
                callback: myTrendCallback
            }
        ]
    };
 
    function myTrendCallback(data) {
        // display raw data in debug console
        console.log(data);
    }
</script>

Additional Features of Flot

When using the OAS.Flot.buildTrendData() method, all attributes on the Tag Definition are passed through to Flot, and applied to the Flot series object.

In this way, you can set up your series definition within the trend_bindings and they will seamlessly flow through to Flot when the chart is plotted. This is precisely how the label and color attributes are used.

Then, from within any Flot event handlers, those values are available for manual parsing. You can see how this was done in the Interactive Chart example, where the popup label is set to the color defined on the series.

The following links are useful references for the Flot library:

Flot Charts: http://www.flotcharts.org/

Flot API Reference: https://github.com/flot/flot/blob/master/API.md

3rd Party Flot Plugins: http://jumflot.jumware.com/examples/pluginsV2.html

Utility Functions

The following Javascript functions are provided as helper methods for formatting and extracting data from each callback or elsewhere within an application referencing the OAS Web HMI libraries.

OAS.init()  :  forces a reinitialization of the OAS_config for the entire page

Use OAS.init() after making any changes to OAS_config. For example, when altering any trend_binding features, you can then call OAS.init() to force the OAS_config to reload with the new settings.

OAS.Flot.buildTrendData(data)  :  convert trend data to Flot series data
  • data: object
    This utility converts the data returned in the trend callback into data series objects directly usable by the Flot charting library. This should only be executed within the context of a trend callback and only when using the Flot library.
OAS.Util.padleft(value, pad, len)  :  left-pad a string with another string
  • value: string
    The original string to be padded. This can also be anything that can be converted to a string, like a numeric.
  • pad: string
    The padding string, typically a single character (e.g. ‘0’ when padding numbers)
  • len: number
    The desired total length of the output string. For example, if you want to convert the number 9 to ‘009’ you would call OAS.Util.padleft(9,'0',3).
OAS.Util.formatDate(dt, format)  :  convert a Javascript Date object to a formatted string
  • dt: date
    The date to be converted.
  • format: string
    A standard date formatting string which replaces specific tokens with parts of the date and time. Valid tokens:
yyyy    : 4-digit year
yy      : 2-digit year
mm      : 2-digit month (e.g. February = '02')
dd      : 2-digit day of the month
HH      : 2-digit hours (24 hour format)
hh      : 2-digit hours (12 hour format)
MM      : 2-digit minutes
ss      : 2-digit seconds
aa      : am/pm designator
AA      : AM/PM designator

Examples: (January 6, 1970 2:23 pm as date input)

"yyyy-mm-dd HH:MM:ss"   > 1970-01-06 14:23:00
 
"mm/dd/yy hh:MM aa"     > 01/06/1970 02:23 pm
OAS.Trend.getTrendBinding(data)
  • data: object
    This utility returns an instance of a Trend Binding object given a set of data returned in the trend callback. This is useful for determining which chart and set of pens the data is for, since the trend binding calls are asynchronous.

 

Historical Data

To display historical data in a chart, you configure your Trend Binding exactly as if you were displaying trend data, then make a single JavaScript call:

OAS.Trend.getHistoryData(trend_binding, startDate, endDate);
  • trend_binding: string|trend_binding object
    This can be either a string, or a reference to a Trend Binding object. If you pass a string, it must match the chartid of an existing Trend Binding. This is the trend binding that will be placed into “History Mode”. Executing this more than once will have no effect.
  • startDate: string|date
    A Javascript Date object or string that can be converted into a Javascript Date (e.g. “01/31/2013 07:22 am”). This date and time is the start of the timespan for History data points requested from the server.
  • endDate: datetime
    A Javascript Date object or string that can be converted into a Javascript Date (e.g. “01/31/2013 07:22 am”). This date and time is the end of the timespan for History data points requested from the server.

Executing OAS.Trend.getHistoryData will place the chart in “History Mode”, displaying a static set of data for the configured Tags, between the start and end dates provided. There may be a brief delay between the execution and the display of the History Data. This is the result of the server generating the data set and sending it back to the client.

To revert back to “Real Time Mode” and to see live data, execute:

OAS.Trend.resumeTrendData(trend_binding);
  • trend_binding: string|trend_binding object
    This can be either a string, or a reference to a Trend Binding object. If you pass a string, it must match the chartid of an existing Trend Binding. This is the trend binding that will be placed back into “Real Time Mode”. Executing this more than once will have no effect.

Explicit Data Logging Group Reference

The getHistoryData call requests data for Tags within Data Logging Groups on the OAS Server. In cases where the Tag is being logged to multiple Logging Groups, you can choose which group will be used to extract data from the external database. To do this you specify the historytag field in the tag definition of your trend_binding. More information on trend_binding configurations can be found here.

Data Object

Each time the Trend Binding Callback function is called, a data object will be passed in, containing the following structure:

{
    chartinstanceguid: <string>, 
    firsttime: <datetime>, 
    lasttime: <datetime>, 
    message: <string>,
    numberofvalues: <integer>,
    penvalues: <array>,
    timesforreturnalldata: <array>,
    status: <string>
}
  • chartinstanceguid: string
    A unique identifier assigned to the Trend Binding by the OAS Server. This is used to identify the requesting client and individual binding so the server efficiently provides the client only data that is required and not previously sent. This value is used internally by the OAS Web HMI library.
  • firsttime: datetime
    A datetime representing the timestamp of the FIRST value in the series of values supplied in the data object. Combined with lasttime, you can determine the time scale for the data set.
  • lasttime: datetime
    A datetime representing the timestamp of the LAST value in the series of values supplied in the data object. Combined with firsttime, you can determine the time scale for the data set.
  • message: string
    A message sent from the server in the event of an error. For normal successful callbacks, this will be blank.
  • numberofvalues: integer
    The number of values in each array of values within the context of this data set.
  • penvalues: array
    Penvalues are an array of integer arrays, each containing a set of values corresponding directly to Tag Definitions in the Trend Binding. These arrays are provided in the same order that the Tag Definitions. Example:
[
    [0.50, 0.653, 0.480, 0.12],
    [16, 12, 38, 120]
]

The example above corresponds to a Trend Binding with 2 Tag Definitions. The full data structure may look something like the following. Note, that numberofvalues is the number of values in each set of penvalues, not the number of penvalues itself:

{
    chartinstanceguid: "d7a2b517-df07-4b5f-ab05-fd6a5e7d534b"
    firsttime: Fri Jun 28 2013 14:25:39 GMT-0400 (Eastern Daylight Time)
    lasttime: Fri Jun 28 2013 14:25:42 GMT-0400 (Eastern Daylight Time)
    message: ""
    numberofvalues: 4
    penvalues: [
        [0.50, 0.653, 0.480, 0.12],
        [16, 12, 38, 120]
    ],
    status: "OK"
}
  • timesforreturnalldata: array
    If the returnalldatawithtimes option is set to true, the timesforreturnalldata will be present in the data set. This array will contain the same number if entries in each array for each pen, and each entry will be a timestamp representing the actual date/time for the corresponding pen value.
  • status: string
    The status of the callback. For successful operations, this will be “OK” and “ERROR” for all others. So you may choose to only process results with the status is “OK” and ignore others, or display a custom message to the user.

Trend Control Description and Options

After defining the Trend Control bindings, or Trend Bindings, the OAS Web HMI library will continually poll the server for realtime data, or Historical Data, depending on the context.

After each polling cycle, a callback function will be executed, allowing you to examine the data, use it in your client side code, or simply apply it to a charting library like Flot. It is your responsibility to implement the callback function and reference it in the Trend Bindings.

The Javascript OAS_config variable contains several options for determining the behavior of the Script Library. This variable is a standard JSON construct. The full definition with defaults desplayed is:

OAS_config =
{
    debug: false,   
    debug_refresh: false,   
    interval: 1000,             
    auto_start: true,       
    token:'',                           
    serverURL:'http://localhost:58725'
};

To add Trend Bindings to this configuration, you will add the following node to your OAS_config construct. The trend_bindings node is an array of Trend Binding objects, each representing data to be displayed in a single chart or to be used together.

trend_bindings: [
    {
        chartid: <string>, 
        samplerate: <integer>,
        timeframe: <integer>,
        tags:[ <array of Tag Definitions - see below> ],
        retain: <optional:integer>,
        callback: <function>
    }
]
  • chartid: string
    This string is available within the callback
  • samplerate: integer
    The server-side sample rate for extracting trend data
  • timeframe: int
    The server-side timeframe
  • tags: array

An array of Tag Definitions. Each tag definition represents a feed of data values corresponding to an OAS Server Tag. You can either provide an array of strings containing Tag names (e.g. ‘Ramp.Value’) or you can provide an array of Tag Definition objects with the tag name and other options.

{
    tag: "Tag.Name",
    label: <string: label that can be used on a chart>,
    color: <string: html color in hex format e.g. '#FFCC00'>,
    historystatprocessing: <string: avg|min|max|lastsample>
    historytag: <string: MyDataLoggingGroup.Field>
    ... other custom nodes ...
}

Historystatprocessing and historytag are optional. Historytag is used to specify the data logging group and field to return history data from. Commonly used when the same tag is defined in multiple logging groups.

  • historystatprocessing: string
    This allows you to explicitly calculate the value of the historical data point. If omitted, “avg” is assumed which will average the value when it spans two entries in the data log.
  • historytag: string
    The history tag allow you to specify where the historical data for that tag can be found. By default, OAS will choose the data logging group based on the sample rate of the trend control. However, you can point to the specific data logging group to use if there is more than one defined on the server logging the tag values. The formats to follow are:

    • <data logging group>. <field name>
      The field name is the actual database column that stores data for the tag in question. For example if you have a data logging group called “DemoLog” and the db field is “Sine_Value” the historytag should be set to “DemoLog.Sine_Value”.
    • \\<network node>\<data logging group>.<field name>
      Additionally if your data logging is being performed by an other OAS server, you can prepend the historytag with “\\<networknode\”. For example, if the above tag data is being logged by another OAS server called “myServer” on the network, the historytag should be set to “\\myServer\DemoLog.Sine_Value”. You can use an IP address or registered domain name for network node as long as it maps to the OAS server performing the data logging.

An array of Tag Definitions. Each tag definition represents a feed of data values corresponding to an OAS Server Tag. You can either provide an array of strings containing Tag names (e.g. ‘Ramp.Value’) or you can provide an array of Tag Definition objects with the tag name and other options.

  • retain: integer
    The number of values to retain between callbacks. For example, if you are displaying real-time data, you will want to set this to the maximum number of points on the x-axis so that any chart using the data will effectively scroll. If you do not set a retain value, all values will be retained, gradually using up more memory over time, and forcing you to manually extract portions for display.
  • callback: function
    A function pointer with that receives a single argument. This function must be globally accessible and will be called on each server refresh of data. The single argument will represent the raw data from the server with metadata about the data set. More information below.
  • returnalldatawithtimes: bool
    An optional flag that determines whether the server will return timestamps for each individual data point. If this setting is not included or is set to false, only the start and end timestamps are included in along with the data points as each is assumed to be averaged between the start and end. Setting this to true will inlude an additional array of timestamps on the server response labeled timesforreturnalldata.

Installation and Configuration – Web Trend

Configuration of OAS Web HMI will not be covered in this document. Once you have a working installation of OAS Web HMI, adding Trend Control configuration is fairly simple. As with OAS Web HMI, the following are required for Trend Control operation:

  • jQuery v1.8.3 or later, found at jquery.com and is also distributed with the OAS Web HMI product
  • The OAS Web HMI Script Library
  • The OAS Web HMI Stylesheet, which is used for styling modal dialogs and can be modified to fit your web design
  • A small block of Javascript containing an authentication token and URL location of the Open Automation Software Server

Additionally, if you would like to integrate with the Flot charting library, you will need to download Flot and various plugins. Each example provided in this document will describe the specific Flot plugins required.

The following is an example of a properly configured, minimal HTML page:

<html>
    <head>
        <script type="text/javascript" src="js/jquery-1.8.3.min.js"></script>
        <script type="text/javascript" src="js/opc-lib-min.js"></script>
        <link rel="stylesheet" stype="text/css" href="css/opc-style.css"/>
        <script type="text/javascript">
            OAS_config = {
                token:'7e61b230-481d-4551-b24b-ba9046e3d8f2',
                serverURL: 'http://localhost:58725'
            };
        </script>
    </head>
    <body>
        Hello World
    </body>
</html>

Of course, this example does not contain any bindings to OAS Server Tags, but contains all elements necessary to connect to a server located at http://localhost:58725 using an authentication token of7e61b230-481d-4551-b24b-ba9046e3d8f2.

Overview – Web Trend Programming

If you are interested in visualizing your data in a desktop or mobile browser with zero programming, you may be interested in Getting Started with the Web HMI Dashboard.

Features

The OAS Web HMI provides a flexible, platform-independent way to integrate with Open Automation Software Servers. The addition of the Trend Control allows you to retrieve real time and historical data for any tags exposed as Trend Points within the OPC Server. Included in this release are:

  • A configuration interface for specifying Trend Points to monitor and be displayed
  • A client-side Javascript API for extracting data and transforming it
  • A simple interface for applying Trend Point and Historical Data to the popular open source Flot (www.flotcharts.org)charting library

Requirements

OAS Web HMI Trend Control requires the following:

  • an instance of an Open Automation Software Serveraccessible over an internal or external network
  • working knowledge of HTML
  • working knowledge of Javascript
  • working knowledge of OAS Web HMI configuration