Trend Binding Callback

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

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:

Additional Features of Flot

When using the OPC.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.

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

  • 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.

  • 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 OPC.Util.padleft(9,'0',3).

  • dt: date
    The date to be converted.
  • format: string
    A standard date formmating string which replaces specific tokens with parts of the date and time. Valid tokens:

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

  • 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:

  • 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 OPC.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:

  • 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.

Data Object

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

  • chartinstanceguid: string
    A unique identifier assigned to the Trend Binding by the OPC 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:

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:

  • 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 OPC_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:

To add Trend Bindings to this configuration, you will add the following node to your OPC_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.

  • 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 OPC 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.

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.

An array of Tag Definitions. Each tag definition represents a feed of data values corresponding to an OPC 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

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:

Of course, this example does not contain any bindings to OPC 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.

Programming Reference – Web Trend

Overview and 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

More: