Debug Universal Driver Interface

You can test and Debug a Universal Driver Interface with the Universal Driver Interface Test application that is installed with Open Automation Software.
Follow these simple steps to Debug a UDI Project..

Step 1

You will need to be running Open Automation Software Version 11 or greater to support Universal Drivers.  You can download the latest version at https://openautomationsoftware.com/download/

Step 2

Copy the Universal Driver Interface Test App Project from C:\Program Files (x86)\Open Automation Software\OPC Systems.NET\Universal Drivers\Example Driver Code\.

Step 3

Set your Driver Project Active Solution Configuration to Debug and compile it.

Step 4

From the Test App Project Solution add your Driver Project to the Solution.

Step 5

Set the LoadFrom path in DriverWindow.xaml.vb of the Test App to the path of your Driver Project Debug directory.

Step 6

Start the Test App in Debug mode and select Create Driver to load the driver assembly.

The Driver Interface properties defined in the GetDefaultDriverConfig function should appear in the window.

Step 7

Set the desired driver interface property values and select Update Driver.

Select the Connect button to call the Connect method.

Step 8

Select New Tag to show the Tag properties.

The Tag properties defined in the GetDefaultTagConfig function should appear.

Step 9

Set the Tag Name, Polling Rate, and other properties to your desired values and then select Add Tag to call the AddTags method.

If your driver code raises the event AsyncReadCallback you will see a value update in the Tag Value field.

Step 10

Change the Tag Name and select Add Tag to add additional tags.
Select Remove Tag to remove the Tag you have specified in the Tag Name field.
Use the Write button to call the WriteValues method.
Use the Sync Read button to call the SyncRead function.

To see how to create your own driver view Create a Universal Driver Interface.
View Deploy and Use a Universal Driver Interface for instructions on how to use the driver in the OAS.

Deploy and Use Universal Driver Interface

To deploy a Universal Driver Interface for Open Automation Software is extremely simple.
Follow these simple steps to deploy and use the driver with each OAS installation.

Step 1

You will need to be running Open Automation Software Version 11 or greater to support Universal Drivers.  You can download the latest version at https://openautomationsoftware.com/download/

Step 2

Copy each compiled assembly from Create Universal Driver Interface to the Universal Driver directory specified under Configure-Options-Drivers of the Configure OAS application. The default is \Universal Drivers\ which would be the sub directory under the OAS installation directory.

Step 3

Anytime a Universal Driver Interface assembly is updated and copied to the directory the OAS Services will need to be restarted to load the new updates into the Framework. Use the OAS Services manager to stop and start the OAS Services.

Step 4

Create and update Drivers and Tags manually using the Configure UDI application or programmatically using the TagCSVImport and DriverInterfaceCSVImport methods.
Note: The legacy Configure application does not support the new UDI.

Configure-Drivers

The driver name will appear at the bottom of the list of available drivers with UDI preceding the name.

Configure-Tags

The driver name will appear at the bottom of the list of available Data Sources.
Select the desired Driver Interface that is defined for the matching driver type.

Step 5

Save your Tag configuration to a file which will also include the Drivers using the Save button on the toolbar in Configure-Drivers or Configure-Tags. You can also programmatically save Tag configurations using the SaveTagConfiguration method of the OPCSystems component.

Step 6

Under Configure – Options set the Default Tag Configuration File so when the computer restarts the tag file will automatically be loaded.

To see how to create your own driver view Create a Universal Driver Interface.
To Debug a Universal Driver Interface with the UDI Test Application view Debug Universal Driver Interface.

Create Universal Driver Interface

With the Universal Driver Interface you can create your own data source for Open Automation Software. Simply follow these steps to define your own tag and interface properties that will be included in the OAS framework.

Step 1

You will need to be running Open Automation Software Version 11 or greater to support Universal Drivers.  You can download the latest version at https://openautomationsoftware.com/download/

Step 2

Copy the C# or VB Example Driver Code from C:\Program Files (x86)\Open Automation Software\OPC Systems.NET\Universal Drivers\Example Driver Code\

Step 3

Open the project with Visual Studio.
Note: If you do not have Visual Studio installed on your system you can obtain a free version from https://visualstudio.microsoft.com/vs/community/

Step 4

Under the Project Properties set the Assembly name and Root namespace name to something unique for each driver you create.

Step 5

Open the file DriverInterface.vb for the VB project or DriverInterface.cs for the C# project.
Set the m_DriverName variable to a unique name for each driver you create.

VB

C#

Step 6

Define the Driver Interface properties you would like make adjustable in the function GetDefaultDriverConfig with a list of ClassProperty objects.
VB

C#

ClassProperty
The ClassProperty object is used to define both Driver Interface and Tag properties that you would like to appear in the OAS Framework for system setup.
Following is a list of the variables of a ClassProperty object.

PropName:
A unique name that identifies the property. This will the be name used for CSV Import and Export and also for programmatic setup with the TagCSVImport and DriverInterfaceCSVImport methods.

PropDescription:
The text that will appear next to the property in the Configure OAS application.

PropHelp:
The text that will appear in the help window for this property in the Configure OAS application. If left blank the help icon will not appear next to the property.

PropType:
The data type of the property value. You can define enumerations or common data types.

PropValue:
This will be the default value of the property when a Driver Interface or Tag is created.

InputType:
This is the configuration input type to use for the property. Manual is the most commonly used input type, but there are also FileBrowse and other configuration input types that can be used to define a value in the Configure OAS application.

Binding:
This is an optional property that can be used to control the visibility of property in the Configure OAS application based on the values of other configuration properties. If left blank the property will always appear.

Units:
This is an optional property that defines the text that will appear after the property value. If left blank the text will not appear.

Example of what will appear in Configure-Drivers with this example code:

Step 7

Add code to the Connect method to be executed when the driver instance enters runtime mode.
VB

C#

Note: You can optionally use the GetPropValue function to obtain the configuration value in any of the routines.

Step 8

Add code to the Disconnect method to be executed when the driver instance exits runtime mode.
VB

C#

Step 9

Define the Tag properties you would like make adjustable in the function GetDefaultTagConfig with a list of ClassProperty objects.
VB

C#

Example of what will appear in Configure-Tags with this example code:

Step 10

Add code to the AddTags method that passes the tags to be monitored with continuous polling.
The TagName, PollingRate, and all driver tag property values will be passed to this function. Use the GetPropValue to obtain any values for the properties.

C#

Step 12

Add code to the RemoveTags method that passes the tags to be removed from continuous polling.

C#

Step 13

Add code to the SyncRead method that passes a tags list, each containing properties. This is for one time read of values based on a trigger in OAS for a Device Read.

C#

Step 14

Add code to the WriteValues method that passes a list tagnames, values to be written, and a list of property values for each tag.

C#

Step 15

Add code for continuous polling that will obtain values for the tags and fire the event AsyncReadCallback which will pass an array of tag values.

C#

Step 16

To post a System Error to OAS raise the event UpdateSystemError.
Set the first parameter to true to post the System Error as active and false to clear the System Error that has been previously posted.
Specify a Category to group the error along with a unique MessageID.

VB

C#

View Deploy and Use a Universal Driver Interface for instructions on how to use the driver in the OAS.
To Debug a Universal Driver Interface with the UDI Test Application view Debug Universal Driver Interface.

Getting started: OAS REST API and native iOS

Step 1

To read and write data between a native iOS app and OAS, you can use the OAS REST API. As a first step, register the HTTP listener with the OAS Service Control Manager under the section labeled “HTML HMI Registration”.

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be the registered domain name, IP address, or network node name that all clients will connect to from their browsers. If you are unsure of which node name to use, localhost will work in most cases.

NOTE: Before clicking “Register”, be sure to stop all services. If services are running, the Service Control app will prompt you to stop them.

Step 2

Start up all services, and be sure to include the Framework 4.5 Service as this houses the listener specific to the REST API.

Step 3

Test your API Service from your iOS device.

You will now ensure that your iPhone or iPad can communicate with OAS via the REST API. In this example, the OAS host is located at 192.168.0.101 on the local network, but you will have to replace this with the OAS host node on your network. The base URL you will use to connect to the REST API is http://{{node}}:{{port}}/OASREST/v2. Each operation performed against the REST API will use the specific operation name prepended with the base {{url}}. The first operation to complete is authentication. All sessions with the REST API must be authenticated. You can adjust the {{url}} in the following snippet and test authentication. In Xcode, create a new single-view iOS application, and choose Swift as the language. Add the following code to MainViewController.swift:

Authenticate Session (Swift):

If this code is executed without error, the response will include a clientid and token. These will be included in the header for all other operations.

Here are some Python examples of basic HTTP requests you might wish to make via the REST API after having completed authentication. For additional information, see our REST API documentation.

Create a Tag (Python 3):

Successful tag creation results in the following response from the OAS server:

Read a Tag (Python 3):

Reading a tag is accomplished with a GET request, using a simple query including the path to the Tag.

A possible response from the OAS server:

Update a Tag (Python 3):

Updating a tag is accomplished with a PUT request, using a payload including the path to the Tag, and the parameter(s) to be updated.

Update confirmation from the OAS server:

Step 4

Write tag data from Raspberry Pi to OAS.
Now that you’ve established connectivity with the REST API, you can complete a Python script to write data from your device. Here is an example script which detects when a button is pushed, and forwards that data into OAS as a discrete tag value. An LED on the breadboard (see figure) indicates the current value, and the OAS server is polled at a frequency of 1 Hz to reflect the current state.

For further help with the REST API, navigate to http://restapi.openautomationsoftware.com to open the REST API online documentation.

Writing data from Raspberry Pi using OAS REST API

Step 1

To write data into OAS from a Raspberry Pi, you will use the OAS REST API. As a first step, register the HTTP listener with the OAS Service Control Manager under the section labeled “HTML HMI Registration”.

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be the registered domain name, IP address, or network node name that all clients will connect to from their browsers. If you are unsure of which node name to use, localhost will work in most cases.

NOTE: Before clicking “Register”, be sure to stop all services. If services are running, the Service Control app will prompt you to stop them.

Step 2

Start up all services, and be sure to include the Framework 4.5 Service as this houses the listener specific to the REST API.

Step 3

Test your API Service from your Raspberry Pi.

You will now ensure that the Raspberry Pi can communicate with OAS via the REST API. In this example, the OAS host is located at 192.168.0.101 on the local network, but you will have to replace this with the OAS host node on your network. The base URL you will use to connect to the REST API is http://{{node}}:{{port}}/OASREST/v2. Each operation performed against the REST API will use the specific operation name prepended with the base {{url}}. The first operation to complete is authentication. All sessions with the REST API must be authenticated. You can adjust the {{url}} in the following snippet and test authentication.

Authenticate Session (Python 3):

If this code is executed without error, the response will include a clientid and token. These will be included in the header for all other operations.

Here are some Python examples of basic HTTP requests you might wish to make via the REST API after having completed authentication. For additional information, see our REST API documentation.

Create a Tag (Python 3):

Successful tag creation results in the following response from the OAS server:

Read a Tag (Python 3):

Reading a tag is accomplished with a GET request, using a simple query including the path to the Tag.

A possible response from the OAS server:

Update a Tag (Python 3):

Updating a tag is accomplished with a PUT request, using a payload including the path to the Tag, and the parameter(s) to be updated.

Update confirmation from the OAS server:

Step 4

Write tag data from Raspberry Pi to OAS.
Now that you’ve established connectivity with the REST API, you can complete a Python script to write data from your device. Here is an example script which detects when a button is pushed, and forwards that data into OAS as a discrete tag value. An LED on the breadboard indicates the current value, and the OAS server is polled at a frequency of 1 Hz to reflect the current state.

For further help with the REST API, navigate to http://restapi.openautomationsoftware.com to open the REST API online documentation.

Read Database Data

Use the OPCSystems.dll assembly to call GetDatabaseData to return a DataTable of values from a database table or view.

  • The GetDatabaseData function returns a DataTable of values from the local or remote service by obtaining database values where the service is running.
  • Returns blank DataTable if service is not reachable.
  • DBProvider is the database provider type to use.
  • DBServer is the database server to connect to. Not applicable for MS Access and Oracle.
  • TableOrView is the table name or view name to query the data from.
  • MSSQLWindowsAuthentication – when connecting with SQL Server use Windows Authentication. When false specify the DBUser and DBPassword for SQL user login.
  • DBUser is the user name for security authentication. Not applicable if using SQL Server and MSSQLWindowsAuthentication is set to true.
  • DBPassword is the password for security authentication. Not applicable if using SQL Server and MSSQLWindowsAuthentication is set to true.
  • FieldNames is a string array containing the field names to query from the table for view.
  • DataTypes is an array of field data types for the fields.
  • UseDates will enable using the StartDate and EndDate.
  • StartDate as the start date and time of history to retrieve.
  • EndDate as the end date and time of history to retrieve.
  • QueryString is the WHERE condition to append to the query. When blank it is not used.
  • NetworkNode is the name of the network node of the OPC Systems Service to connect to. Leave blank for localhost connection.
  • ErrorString will be set to Success when function is successful and an error message when in error.
  • RemoteSCADAHostingName is the name of the Live Data Cloud OPC Systems Service to connect to.
CONTENTS

VB

C#

Software Maintenance

ANNUAL SOFTWARE MAINTENANCE

BENEFITS TO PURCHASING MAINTENANCE WITH LICENSE:

1. Free version upgrades for maintenance contract duration plus 90 days
2. Product upgrades, such as tag or feature increases, for the difference in price vs. the full feature price.
3. If you have the full OAS suite, then new features will be added to your contract at no additional cost.
4. For your maintenance renewal(before expiration date), you pay percentage(20%) of your original price.
5. You can move a license from one system to another.

WITHOUT A MAINTENANCE CONTRACT:
1. No version upgrades after 90 days of purchase.
2. If you want a change in tag or features, you must pay full price for new license.
3. If you have the full OAS suite, to obtain new features purchase of product feature is required.
4. If you decide to get on maintenance after it has expired it will cost double(40% of the current price of the license vs. 20% of the original price) what it would have if you had purchased it with your license.
5. You cannot move a license.

Web HMI Dashboard Modules

Modules are each self-contained, and files relative to each can be found in the installation directory under the modules folder.
At a minimum, under each module folder you fill find a module.js file and a style.css file. The module.js file is the core module executable, and the style.css contains specific stylesheet rules used by the module.  Some modules may contain other assets, such as the Demo Module.

Removing Modules
To remove a module from the application, you simply need to remove the reference to the module script and stylesheet within the index.html file. These references are found in the <head> element of the index.html file.  Once you remove these references, the module will no longer appear in the list of  of modules for users to select.

See lines 31 – 51 in the code below to locate the module references.

If you are interested in modifications to the Web HMI Dashboard, or would like to speak with us about creating a module specific to your application, Contact Us today!


Demo Module

The Demo Module is an example of an interactive, visual representation of a physical system, with pumps, valves, and fluid level sensors. You can click or tap on each of the valves and pumps to simulate fluid flowing into or out of the two tanks. The corresponding tags in the OAS server can be found under the WPF/New Tanks Demo structure that is present in the demo tags included with each installation.


Numeric Tag Module

This module allows you to display a real time numeric value rendered as a gauge. As values change, the needle will animate, indicating the current value.can be configured

Configuration settings

Tag Name: the tag to be visualized – click the icon to browse or manually enter the tag
Label: the text label displayed below the current value
Min/Max: the range that determines the needle position (default: 0/100)
Gain/Offset: optional multiplier and value offset applied to the raw value
Decimals/Units: number of decimal places to display, and unit suffix added to the value
Read/Write: when checked, displays an input field, allowing users to set the tag’s value


Boolean Tag Module

This module displays the current live value of a Boolean Tag. When configured to allow for read/write access, the display icon becomes a switch. If the switch is clicked or tapped, the server value will be toggled between True and False.  The display can also be customized so that True and False text can be replaced with text of your choosing.


Configuration settings

Tag Name: the tag to be visualized – click the icon to browse or manually enter the tag
Label: 
the text label displayed with the current value
False/True: optional text to display when the value is false or true, respectively
Gain/Offset: optional multiplier and value offset applied to the raw value
Text Scale: optional scaling % applied to text
Read/Write: when checked, changes the indicator to a switch icon and allows the user o toggle the value


Tag Data Module

This modules allows for the display of multiple server Tags along with their data type and real time values. This is very useful for checking the raw data coming from the server within a single tabular format. This module also allows the end user to modify Tag values when the Read/Write option is enabled.

Configuration settings

Label: the text label displayed above the grid
Tags: the list of tags to display – click the icon to choose one or more tags
Read/Write: when checked, adds an edit button next to each tag, allowing the user to set the tag’s current value


Alarm Module

This module encapsulates the Web Alarm viewer and allows the end-user to configure it to display the columns desired. It also allows users to configure the viewer to filter alarms by type, group, status, and priority. Because it is based on the Web Alarm product, it retains all functionality. See the following for more information on Web Alarm.

Configuration settings

Label: the text label displayed above the alarms
Show Search/History: when checked, display the inline search and historical input fields
Alarm Types: list of Alarm Types to include in the display
Alarm Groups: a comma-delimited list of Alarm Groups to include in the display, defaulting to all if left blank
Network Nodes: a comma-delimited list of Network Nodes to include in the display, defaulting to localhost if left blank
Columns: list of Alarm fields to display in the grid
Include Alarms: list of Alarm statuses to include in the display
Priorities: the min and max priorities to include in the display


Trend Module

This module encapsulates the Web Trend viewer and allows the end-user to configure it to display a chart plotting both real time and historical trends. Because it is based on the Web Trend product, it retains all functionality, but requires no programming to configure. See the following for more information on Web Trend.

Configuration settings

Label: the text label displayed above the chart
Sample Rate: the frequency (in seconds) for each data point to be acquired
Timeframe: the number of seconds in the initial data set
Retain: The number of data points to retain in client memory – as more data is received, the chart will animate as it flushes non-retained values
History Data: when checked, allows users to select start and end dates for displaying historical data
Pens: click Add Tag to add a pen linked to a server tag. Each tag will include settings for Name, Label, Line style, and Y-axis range and position


Custom Module

This module allows you to specify any web URL so you may embed your custom code into the Web HMI Dashboard. You can either host the contents of a Custom module on any web server, or you may also add it to the modules folder in the application itself.

The module has a single parameter of a URL. When you use an absolute URL (containing the full URL such as “http://someurl.com/page”), the module will load from the source.  If you use a relative URL (e.g. “somepage.html”) it will be loaded from the Web HMI Dashboard www folder. For example, if you create an HTML page titled index.html and you put it in a folder titled “newModule” under the modules folder, set the URL parameter to “modules/newModule/index.html”.


If you are interested in modifications to the Web HMI Dashboard, or would like to speak with us about creating a module specific to your application, Contact Us today!