The first step in creating a custom communication driver for OAS is to create the Driver Assembly. This .NET Assembly will be referenced by a .NET Hosting Application, and depending on the target deployment platforms, can be developed to be cross-platform compatible for use on Windows, Mac, Linux, Android, and iOS operating systems.
Choosing a Framework
If you would like the flexibility of being able to run your driver on multiple operating systems, your driver should target the .NET Standard 2.0+ framework. Yet, we understand that in some cases you must rely on other 3rd party libraries that are not compatible, or you cannot upgrade your infrastructure to the NET Framework 4.6.1+. In these cases, your driver must target the .NET 4.0 Framework, and will be limited to being run on a Windows platform.
In the OAS Platform distribution, we have provided Examples for any of these scenarios. In the installation directory, locate the Universal Drivers folder, to find all Example code for drivers and Hosting Apps, in both C# and VB.NET.
For cross-platform support, choose the examples under the Standard directory, and for .NET 4.0 or 4.5 only support, select examples under the Framework4 directory.
The Driver Architecture
Building a functional UDI Driver includes the development of your own Driver assembly following our example code, then running this within a Hosting Application. In this tutorial, we will be building a .NET Framework 4.0 Driver hosted within a Windows Service to be deployed on a Windows Server or PC.
Prerequisites
You will need to be running Open Automation Software Version 11.00.0017 or greater to support Universal Drivers. You can download the latest version at /download/
You will also need Microsoft Visual Studio to work with any of these examples and to compile your custom driver. If you do not currently have Visual Studio installed, you can try out Visual Studio Community which is a fully functional, free version of the IDE.
Step 1
Copy the C# or VB Driver Code from the OAS installation path, typically C:\Program Files\Open Automation Software\OAS\Universal Drivers\Framework4\Driver\ to a location of your choosing, then open the project in Visual Studio.
NOTE: Under the project references, if you are getting a warning or if the OASDriverInterface (or OASDriverInterfaceFramework4 for a .NET Framwework 4.0 Driver project) assembly is missing, remove the reference and add it back in, locating it in the base OAS installation directory.
Step 2
Under the Project Properties set the Assembly name and Root namespace name to something unique for each driver you create. The default is ExampleDriver, so we’ll leave this as is but you should change this to uniquely identify your driver for each data source.
The Assembly Name will be the resulting DLL that is compiled. In this case, the assembly will compile to a file named ExampleDriver.dll.
The Default Namespace will only affect new classes and files added to your driver. You may also search and replace all references of ExampleDriver with your own custom driver name so that it displays properly in all other project references.
Step 3
Open the file DriverInterface.vb for the VB project or DriverInterface.cs for the C# project and set the m_DriverName variable to a unique name for each driver you create.
This string is the display name that will appear within the OAS Configuration application. The driver name will display in the following formats.
In the list of Drivers associated with the OAS Server, you will see UDI drivers in the left pane as:
<Driver Name>-<MachineName>
The <Machine Name> will be defined in the host application configuration file (detailed in the Hosting App tutorial), so this can be changed upon deployment and will help with identifying instances of the same drivers hosted on different or remote machines.
In the dropdown lists of drivers, including the dropdowns used to select the data source of a Tag, the UDI Driver will be displayed as:
UDI <Driver Name>
The Driver Name is set within the source code by setting the m_DriverName string.
VB
Private m_DriverName As String = "Example Driver"
C#
private string m_DriverName = "Example Driver";
The example below shows how the driver would be listed in the OAS Configuration app if the m_DriverName string was set to “Example Driver”.
The driver name also becomes an available selection for Data Source in the Tag parameters for Value and Alarm Limits.
Step 4
Define the Driver Interface properties you would like make adjustable in the function GetDefaultDriverConfig with a list of ClassProperty objects.
The collection of DriverProps returned in the GetDefaultDriverConfig defines the list of configurable properties for the driver which will be exposed in the OAS Configuration application.
Below is an example that adds several properties, including one called “Driver Type” that selectively triggers other property fields’ visibility depending on the value selected.
Each Driver property is an instance of a ClassProperty that can be one of many different types, including selectable options, input text fields and more.
VB
Public Overrides Function GetDefaultDriverConfig() As List(Of ClassProperty)
Try
Dim DriverProps As New List(Of ClassProperty)
DriverProps.Clear()
' Define the properties for the Interface. Typically IP Address, Port Number, database connection settings, etc.
' Example of an enumerated value
DriverProps.Add(New ClassProperty("DriverType", "Driver Type", "Select Driver Type
DriverType0: Example driver type 0
DriverType1: Example driver type 1
DriverType2: Example driver type 2", GetType(SelectDriverType), SelectDriverType.DriverType0, ClassProperty.ePropInputType.Manual))
' Example of Integer values.
' Optionally to each property you can add a Visible property binding to the value of another control. In this example the DriverType selected will show the appropriate integer value.
' The Visible binding can use | for an OR condition or & for AND condition to combine criteria for the property to be visible.
DriverProps.Add(New ClassProperty("DriverType0Integer", "Driver Type 0 Integer", "Example value for DriverType0", GetType(Int32), 0, ClassProperty.ePropInputType.Manual, "Visible,DriverType.DriverType0"))
DriverProps.Add(New ClassProperty("DriverType1Integer", "Driver Type 1 Integer", "Example value for DriverType1", GetType(Int32), 1, ClassProperty.ePropInputType.Manual, "Visible,DriverType.DriverType1"))
DriverProps.Add(New ClassProperty("DriverType1And2Integer", "Driver Type 1 and 2 Integer", "Example value for DriverType1 and DriverType2", GetType(Int32), 2, ClassProperty.ePropInputType.Manual, "Visible,DriverType.DriverType1|DriverType.DriverType2"))
DriverProps.Add(New ClassProperty("ExampleDouble", "Example Double", "Example value for all types", GetType(Double), 1, ClassProperty.ePropInputType.Manual))
Return DriverProps
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Configuration", 1, "GetDefaultDriverConfig Exception: " + ex.Message)
End Try
End Function
C#
public override List GetDefaultDriverConfig()
{
try
{
List DriverProps = new List();
DriverProps.Clear();
// Define the properties for the Interface. Typically IP Address, Port Number, database connection settings, etc.
// Example of an enumerated value
DriverProps.Add(new ClassProperty("DriverType", "Driver Type", @"Select Driver Type
DriverType0: Example driver type 0
DriverType1: Example driver type 1
DriverType2: Example driver type 2", typeof(SelectDriverType), SelectDriverType.DriverType0, ClassProperty.ePropInputType.Manual));
// Example of Integer values.
// Optionally to each property you can add a Visible property binding to the value of another control. In this example the DriverType selected will show the appropriate integer value.
// The Visible binding can use | for an OR condition or & for AND condition to combine criteria for the property to be visible.
DriverProps.Add(new ClassProperty("DriverType0Integer", "Driver Type 0 Integer", "Example value for DriverType0", typeof(Int32), 0, ClassProperty.ePropInputType.Manual, "Visible,DriverType.DriverType0"));
DriverProps.Add(new ClassProperty("DriverType1Integer", "Driver Type 1 Integer", "Example value for DriverType1", typeof(Int32), 1, ClassProperty.ePropInputType.Manual, "Visible,DriverType.DriverType1"));
DriverProps.Add(new ClassProperty("DriverType1And2Integer", "Driver Type 1 and 2 Integer", "Example value for DriverType1 and DriverType2", typeof(Int32), 2, ClassProperty.ePropInputType.Manual, "Visible,DriverType.DriverType1|DriverType.DriverType2"));
DriverProps.Add(new ClassProperty("ExampleDouble", "Example Double", "Example value for all types", typeof(double), 1, ClassProperty.ePropInputType.Manual));
return DriverProps;
}
catch (Exception ex)
{
m_OASDriverInterface.UpdateSystemError(true, "Configuration", 1, "GetDefaultDriverConfig Exception: " + ex.Message);
}
return null;
}
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 passed into the constructor for a ClassProperty object.
Public Sub New(ByVal newPropName As String,
ByVal newPropDescription As String,
ByVal newPropHelp As String,
ByVal newPropType As Type,
ByVal newPropValue As Object,
ByVal newPropInputType As ePropInputType,
Optional ByVal newBinding As String = "",
Optional ByVal newUnits As String = "")
End Sub
- 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 5
Add code to the Connect method to be executed when the driver instance enters runtime mode.
This method is where you would do one or more of the following:
- Execute initialization code for connecting to your data source
- Read driver configuration properties for initialization using the GetPropValue function
- Set up timers to trigger polling activities
In this example, we read some of the persisted properties for the driver as it was configured. Then we check a flag (m_Connected) to determine if the driver has already executed Connect, and if not, start a local Timer to begin triggering.
VB
Public Overrides Sub Connect()
Try
'Add Connection Logic. m_DriverProps is a list of ClassDriverProperty in the same order of Get Driver Config
Dim DriverType As SelectDriverType = GetPropValue(m_DriverProps, "DriverType")
Dim DriverType0Integer As Int32 = GetPropValue(m_DriverProps, "DriverType0Integer")
Dim DriverType1Integer As Int32 = GetPropValue(m_DriverProps, "DriverType1Integer")
Dim DriverType2Integer As Int32 = GetPropValue(m_DriverProps, "DriverType1And2Integer")
Dim ExampleDouble As Double = GetPropValue(m_DriverProps, "ExampleDouble")
If Not (m_Connected) Then
localTimer.Change(100, 100)
End If
m_Connected = True
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Connect", 1, "GetDefaultDriverConfig Exception: " + ex.Message)
End Try
End Sub
C#
public override void Connect() {
try {
//Add Connection Logic. m_DriverProps is a list of ClassDriverProperty in the same order of Get Driver Config
SelectDriverType DriverType = (MyExampleOASDriver.DriverInterface.SelectDriverType)GetPropValue(m_DriverProps, "DriverType");
int DriverType0Integer = Convert.ToInt32(GetPropValue(m_DriverProps, "DriverType0Integer"));
int DriverType1Integer = Convert.ToInt32(GetPropValue(m_DriverProps, "DriverType1Integer"));
int DriverType2Integer = Convert.ToInt32(GetPropValue(m_DriverProps, "DriverType1And2Integer"));
double ExampleDouble = Convert.ToDouble(GetPropValue(m_DriverProps, "ExampleDouble"));
if (!(m_Connected))
{
localTimer.Change(100, 100);
}
m_Connected = true;
}
catch (Exception ex) {
m_OASDriverInterface.UpdateSystemError(true, "Connect", 1, "GetDefaultDriverConfig Exception: " + ex.Message);
}
}
Step 6
Add code to the Disconnect method to be executed when the driver instance exits runtime mode. This should be used to shut down any connections and undo any initialization that was performed during the Connect method.
In this example, we set the m_Connected flag to false, stop the local Timer, and clear out any tag data using the m_Tags.Clear method.
VB
Public Overrides Function Disconnect() As Boolean
Try
If Not (m_Connected) Then
Return m_Connected
End If
'Add Disconnection Logic
localTimer.Change(Timeout.Infinite, Timeout.Infinite)
SyncLock m_Tags.SyncRoot
m_Tags.Clear()
End SyncLock
m_Connected = False
Return m_Connected
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Disconnect", 1, "GetDefaultDriverConfig Exception: " + ex.Message)
End Try
End Function
C#
public override bool Disconnect() {
try {
if (!(m_Connected)) {
return m_Connected;
}
//Add Disconnection Logic
localTimer.Change(Timeout.Infinite, Timeout.Infinite);
lock (m_Tags.SyncRoot) {
m_Tags.Clear();
}
m_Connected = false;
return m_Connected;
}
catch (Exception ex)
{
m_OASDriverInterface.UpdateSystemError(true, "Disconnect", 1, "GetDefaultDriverConfig Exception: " + ex.Message);
}
return false;
}
Step 7
Define the Tag properties you would like make adjustable in the function GetDefaultTagConfig with a list of ClassProperty objects.
These are properties that will be displayed and associated with a Tag configuration when the tag source uses your Driver. These properties will be added to the Value tab in the OAS Configuration app.
These properties are also defined using the ClassProperty object and added to the m_TagProps collection.
In this example, we are adding two Tag properties for Simulation Type and Dynamic Simulation Type.
VB
Public Overrides Function GetDefaultTagConfig() As List(Of ClassProperty)
Try
Dim m_TagProps As New List(Of ClassProperty)
m_TagProps.Add(New ClassProperty("SimType",
"Simulation Type",
"The simulation type of a Parameter can be set to one of the following types.
Dynamic: Read only value that changes dynamically from one of the Dynamic Simuation Types
Static: Value is fixed and can be written to.",
GetType(SimTypes),
SimTypes.Dynamic,
ClassProperty.ePropInputType.Manual))
m_TagProps.Add(New ClassProperty("DynamicSimType",
"Dynamic Simulation Type",
"The dynamic simulation type of a Parameter can be set to one of the following types.
Ramp: Value changes from 0 to 100.
Random: Value changes randomly from 0 to 100
Sine: Value changes from -1 to 1",
GetType(DynamicSimTypes),
DynamicSimTypes.Ramp,
ClassProperty.ePropInputType.Manual,
"Visible,SimType.Dynamic"))
Return m_TagProps
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Configuration", 1, "GetDefaultTagConfig Exception: " + ex.Message)
End Try
End Function
C#
public override List GetDefaultTagConfig() {
try {
List m_TagProps = new List();
m_TagProps.Add(new ClassProperty("SimType",
"Simulation Type",
@"The simulation type of a Parameter can be set to one of the following types.
Dynamic: Read only value that changes dynamically from one of the Dynamic Simuation Types
Static: Value is fixed and can be written to.",
typeof(SimTypes),
SimTypes.Dynamic,
ClassProperty.ePropInputType.Manual));
m_TagProps.Add(new ClassProperty("DynamicSimType",
"Dynamic Simulation Type",
@"The dynamic simulation type of a Parameter can be set to one of the following types.
Ramp: Value changes from 0 to 100.
Random: Value changes randomly from 0 to 100
Sine: Value changes from -1 to 1",
typeof(DynamicSimTypes),
DynamicSimTypes.Ramp,
ClassProperty.ePropInputType.Manual,
"Visible,SimType.Dynamic"));
return m_TagProps;
}
catch (Exception ex) {
m_OASDriverInterface.UpdateSystemError(true, "Configuration", 1, "GetDefaultTagConfig Exception: " + ex.Message);
}
return null;
}
}
Example of what will appear in Configure-Tags with this example code:
Step 8
Add code to the AddTags method that passes the tags to be monitored with continuous polling.
All Tag Properties defined in the driver will be available at this point and additionally TagName and PollingRate and can be inspected using the GetPropValue method.
This example demonstrates pulling the TagName, and PollingRate. To add a Tag to the continuous polling routines, the tag is then added to the m_Tags collection. We further reset the timestamp stored in the m_LastUpdateTime for the Tag which is used to track the last time the Tag value has been updated.
Public Overrides Sub AddTags(ByVal Tags() As List(Of ClassProperty))
Try
'Add Logic. Props is a list of ClassProperty in the same order of Get Tag Config
Dim Props As List(Of ClassProperty)
SyncLock m_Tags.SyncRoot
For Each Props In Tags
' Use the TagName as a unique identifier for the Tag Name and Parameter being interfaced with.
Dim TagID As String = GetPropValue(Props, "TagName")
' Use the polling rate to set the communication rate to your device or software application.
' If you interface uses async callbacks with a subscription rate you could create multple collections of tags based on PollingRate.
Dim PollingRate As Double = GetPropValue(Props, "PollingRate")
If m_Tags.Contains(TagID) Then
m_Tags(TagID) = Props
Else
m_Tags.Add(TagID, Props)
End If
If m_LastUpdateTime.Contains(TagID) Then
m_LastUpdateTime.Remove(TagID)
End If
Next
End SyncLock
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Communications", 1, "AddTags Exception: " + ex.Message)
End Try
End Sub
C#
public override void AddTags(List[] Tags) {
try
{
//Add Logic. Props is a list of ClassProperty in the same order of Get Tag Config
lock (m_Tags.SyncRoot)
{
foreach (List Props in Tags)
{
// Use the TagName as a unique identifier for the Tag Name and Parameter being interfaced with.
string TagID = Convert.ToString(GetPropValue(Props, "TagName"));
// Use the polling rate to set the communication rate to your device or software application.
// If you interface uses async callbacks with a subscription rate you could create multiple collections of tags based on PollingRate.
double PollingRate = Convert.ToDouble(GetPropValue(Props, "PollingRate"));
if (m_Tags.Contains(TagID))
{
m_Tags[TagID] = Props;
}
else
{
m_Tags.Add(TagID, Props);
}
if (m_LastUpdateTime.Contains(TagID))
{
m_LastUpdateTime.Remove(TagID);
}
}
}
}
catch (Exception ex)
{
m_OASDriverInterface.UpdateSystemError(true, "Communications", 1, "AddTags Exception: " + ex.Message);
}
}
Step 9
Add code to the RemoveTags method that passes the tags to be removed from continuous polling. This should reverse the code added to the AddTags method by removing tags from continuous polling.
This example demonstrates the removal of all Tags from the m_Tags collection and clears out the associated timestamps from the m_LastUpdateTime collection.
Public Overrides Sub RemoveTags(ByVal Tags() As String)
Try
Dim TagID As String
SyncLock m_Tags.SyncRoot
For Each TagID In Tags
If m_Tags.Contains(TagID) Then
m_Tags.Remove(TagID)
End If
If m_LastUpdateTime.Contains(TagID) Then
m_LastUpdateTime.Remove(TagID)
End If
Next
End SyncLock
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Communications", 2, "RemoveTags Exception: " + ex.Message)
End Try
End Sub
C#
public override void RemoveTags(string[] Tags) {
try {
lock (m_Tags.SyncRoot) {
foreach (string TagID in Tags) {
if (m_Tags.Contains(TagID)) {
m_Tags.Remove(TagID);
}
if (m_LastUpdateTime.Contains(TagID)) {
m_LastUpdateTime.Remove(TagID);
}
}
}
}
catch (Exception ex) {
m_OASDriverInterface.UpdateSystemError(true, "Communications", 2, "RemoveTags Exception: " + ex.Message);
}
}
Step 10
Optionally, you can have your custom Driver create and configure Tags on the server in which it is installed by implementing the GetTagsToAdd method. This example demonstrates adding tags to the configuration so that data will begin flowing as soon as the Driver is activated.
As you can see, we are also using the ClassProperty to define all of the Tags’ configuration properties and even ensure that they connect using the custom Driver as a source. However, you can configure any other Tags that you choose, truly making the deployment of a Driver a hands-off operation.
VB
Public Function GetTagsToAdd() As List(Of List(Of ClassProperty))
Try
Dim m_Tags As List(Of List(Of ClassProperty)) = New List(Of List(Of ClassProperty))()
Dim DynamicSimTypesToAdd As String() = {"Ramp", "Random", "Sine"}
Dim DynamicSimTypeToAdd As DynamicSimTypes = 0
For Each DynamicSimTypeString As String In DynamicSimTypesToAdd
Dim m_TagProps As List(Of ClassProperty) = New List(Of ClassProperty)()
m_TagProps.Add(New ClassProperty("Tag", "", "", GetType(String), m_DriverName & "." + m_MachineName & "." & DynamicSimTypeString, ClassProperty.ePropInputType.Manual))
m_TagProps.Add(New ClassProperty("Value - Data Type", "", "", GetType(String), "Double", ClassProperty.ePropInputType.Manual))
m_TagProps.Add(New ClassProperty("Value - Source", "", "", GetType(String), "UDI " & m_DriverName, ClassProperty.ePropInputType.Manual))
m_TagProps.Add(New ClassProperty("Value - Driver Interface", "", "", GetType(String), m_DriverName & "-" + m_MachineName, ClassProperty.ePropInputType.Manual))
m_TagProps.Add(New ClassProperty("Value - UDI " & m_DriverName & " SimType", "", "", GetType(SimTypes), SimTypes.Dynamic, ClassProperty.ePropInputType.Manual))
Select Case DynamicSimTypeString
Case "Ramp"
DynamicSimTypeToAdd = DynamicSimTypes.Ramp
Case "Random"
DynamicSimTypeToAdd = DynamicSimTypes.Random
Case "Sine"
DynamicSimTypeToAdd = DynamicSimTypes.Sine
End Select
m_TagProps.Add(New ClassProperty("Value - UDI " & m_DriverName & " DynamicSimType", "", "", GetType(DynamicSimTypes), DynamicSimTypeToAdd, ClassProperty.ePropInputType.Manual))
m_Tags.Add(m_TagProps)
Next
Return m_Tags
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Configuration", 4, "GetTagsToAdd Exception: " & ex.Message)
Return Nothing
End Try
End Function
C#
public List<List> GetTagsToAdd() {
try {
List<List> m_Tags = new List<List>();
string[] DynamicSimTypesToAdd = {"Ramp", "Random", "Sine"};
DynamicSimTypes DynamicSimTypeToAdd = 0;
foreach (string DynamicSimTypeString in DynamicSimTypesToAdd) {
List m_TagProps = new List();
// The name of the tag to add. Use periods to create tags within groups, each group seperated by a period.
m_TagProps.Add(new ClassProperty("Tag", "", "", typeof(string), m_DriverName + "." + m_MachineName + "." + DynamicSimTypeString, ClassProperty.ePropInputType.Manual));
// Include any property values of the Tag to set. If the Tag already exists these values will be update the existing Tag.
// Use the same property names as that are set in a Tag CSV Export
// The Data Type of Tag value
m_TagProps.Add(new ClassProperty("Value - Data Type", "", "", typeof(string), "Double", ClassProperty.ePropInputType.Manual));
// The Data Source of Tag value
m_TagProps.Add(new ClassProperty("Value - Source", "", "", typeof(string), "UDI " + m_DriverName, ClassProperty.ePropInputType.Manual));
// The Driver Interface of Tag value
m_TagProps.Add(new ClassProperty("Value - Driver Interface", "", "", typeof(string), m_DriverName + "-" + m_MachineName, ClassProperty.ePropInputType.Manual));
m_TagProps.Add(new ClassProperty("Value - UDI " + m_DriverName + " SimType", "", "", typeof(SimTypes), SimTypes.Dynamic, ClassProperty.ePropInputType.Manual));
switch (DynamicSimTypeString) {
case "Ramp":
DynamicSimTypeToAdd = DynamicSimTypes.Ramp;
break;
case "Random":
DynamicSimTypeToAdd = DynamicSimTypes.Random;
break;
case "Sine":
DynamicSimTypeToAdd = DynamicSimTypes.Sine;
break;
}
m_TagProps.Add(new ClassProperty("Value - UDI " + m_DriverName + " DynamicSimType", "", "", typeof(DynamicSimTypes), DynamicSimTypeToAdd, ClassProperty.ePropInputType.Manual));
m_Tags.Add(m_TagProps);
}
return m_Tags;
}
catch (Exception ex) {
m_OASDriverInterface.UpdateSystemError(true, "Configuration", 4, "GetTagsToAdd Exception: " + ex.Message);
return null;
}
}
Step 11
Optionally 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. If you do not need support for the Device Read feature this method can be left blank. For continuous monitoring refer to Step 13 with the AsyncReadCallback method.
If you are connecting to a data source or application, this is where you may pull values from an API or memory cache just once on each call made to the method for the Tags requested.
' This call is performed when a Device Read is executed in OAS.
Public Overrides Function SyncRead(ByVal Tags() As List(Of ClassProperty)) As ClassTagValue()
Try
Dim currentTime As Date = Now
Dim localSeconds As Double = currentTime.Second + (currentTime.Millisecond / 1000)
Dim TagItems As List(Of ClassProperty)
Dim localArrayList As New ArrayList
SyncLock m_StaticTagValues.SyncRoot
For Each TagItems In Tags
Dim TagID As String = GetPropValue(TagItems, "TagName")
Dim SimType As SimTypes = GetPropValue(TagItems, "SimType")
Dim Value As Object
Select Case SimType
Case SimTypes.Dynamic
Dim DynamicType As DynamicSimTypes = GetPropValue(TagItems, "DynamicSimType")
Select Case DynamicType
Case DynamicSimTypes.Ramp
Value = localSeconds * 100 / 60
Case DynamicSimTypes.Random
Value = Rnd() * 100
Case DynamicSimTypes.Sine
Value = Math.Sin(Math.PI * (localSeconds * 360 / 60) / 180.0)
End Select
Case SimTypes.Static
If m_StaticTagValues.Contains(TagID) Then
Value = m_StaticTagValues(TagID)
Else
Value = 0
End If
End Select
Dim Quality As Boolean = False
If Not (Value Is Nothing) Then
Quality = True
End If
localArrayList.Add(New ClassTagValue(TagID, Value, currentTime, Quality))
Next
End SyncLock
Return CType(localArrayList.ToArray(GetType(ClassTagValue)), ClassTagValue())
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Communications", 3, "SyncRead Exception: " + ex.Message)
End Try
End Function
C#
// This call is performed when a Device Read is executed in OAS.
public override ClassTagValue[] SyncRead(List[] Tags) {
try {
DateTime currentTime = DateTime.Now;
double localSeconds = currentTime.Second + (currentTime.Millisecond / 1000.0);
ArrayList localArrayList = new ArrayList();
lock (m_StaticTagValues.SyncRoot) {
foreach (List TagItems in Tags) {
string TagID = Convert.ToString(GetPropValue(TagItems, "TagName"));
SimTypes SimType = (MyExampleOASDriver.DriverInterface.SimTypes)GetPropValue(TagItems, "SimType");
object Value = null;
switch (SimType) {
case SimTypes.Dynamic:
DynamicSimTypes DynamicType = (MyExampleOASDriver.DriverInterface.DynamicSimTypes)GetPropValue(TagItems, "DynamicSimType");
switch (DynamicType) {
case DynamicSimTypes.Ramp:
Value = localSeconds * 100 / 60;
break;
case DynamicSimTypes.Random:
Value = Microsoft.VisualBasic.VBMath.Rnd() * 100;
break;
case DynamicSimTypes.Sine:
Value = Math.Sin(Math.PI * (localSeconds * 360 / 60) / 180.0);
break;
}
break;
case SimTypes.Static:
if (m_StaticTagValues.Contains(TagID)) {
Value = m_StaticTagValues[TagID];
}
else {
Value = 0;
}
break;
}
bool Quality = false;
if (Value != null) {
Quality = true;
}
localArrayList.Add(new ClassTagValue(TagID, Value, currentTime, Quality));
}
}
return (ClassTagValue[])localArrayList.ToArray(typeof(ClassTagValue));
}
catch (Exception ex) {
m_OASDriverInterface.UpdateSystemError(true, "Communications", 3, "SyncRead Exception: " + ex.Message);
}
return null;
}
Step 12
Add code to the WriteValues method that passes a list Tag name, values to be written, and a list of property values for each Tag. This section of code is where you would receive tag names, values, and properties defined in the OAS Platform for each tag for tags that are to be written.
In this example simulation the values are added to the m_StaticTagValues collection for persistence in this simulation, most likely they would be sent back to the data source of you are implementing a writeable interface to your source.
Public Overrides Sub WriteValues(ByVal TagIDs() As String, ByVal Values() As Object, TagProperties() As List(Of ClassProperty))
Try
'Add write Logic to actual driver
Dim Index As Int32
For Index = 0 To TagIDs.GetLength(0) - 1
Dim SimType As SimTypes = GetPropValue(TagProperties(Index), "SimType")
If SimType = SimTypes.Static Then
SyncLock m_StaticTagValues.SyncRoot
If m_StaticTagValues.Contains(TagIDs(Index)) Then
m_StaticTagValues(TagIDs(Index)) = Values(Index)
Else
m_StaticTagValues.Add(TagIDs(Index), Values(Index))
End If
End SyncLock
End If
Next
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Communications", 4, "WriteValues Exception: " + ex.Message)
End Try
End Sub
C#
public override void WriteValues(string[] TagIDs, object[] Values, List[] TagProperties) {
try {
//Add write Logic to actual driver
int Index = 0;
for (Index = 0; Index < TagIDs.GetLength(0); Index++) {
SimTypes SimType = (MyExampleOASDriver.DriverInterface.SimTypes)GetPropValue(TagProperties[Index], "SimType");
if (SimType == SimTypes.Static) {
lock (m_StaticTagValues.SyncRoot) {
if (m_StaticTagValues.Contains(TagIDs[Index])) {
m_StaticTagValues[TagIDs[Index]] = Values[Index];
}
else {
m_StaticTagValues.Add(TagIDs[Index], Values[Index]);
}
}
}
}
}
catch (Exception ex) {
m_OASDriverInterface.UpdateSystemError(true, "Communications", 4, "WriteValues Exception: " + ex.Message);
}
}
Step 13
Add code for continuous polling that will obtain values for the tags and call the method AsyncReadCallback on the OAS Driver Interface object which will pass an array of tag values.
This code is triggered by the Timer that is started and stopped in the Connect and Disconnect methods. In this routine, you would perform periodic updates on your Tags and mark them as updated by recording an associated timestamp in the m_LastUpdateTime collection.
You can also see in this example that our Tags marked as “Dynamic” are provided calculated values, and “Static” tags pull values from the m_StaticTagValues collection which is set in the WriteValues routine.
' This is a simple example of getting the properties of a tag and using that to generate a update to the tag value
Private Sub TimerRoutine(ByVal State As Object)
Try
If m_InTimerRoutine Then
Exit Sub
End If
m_InTimerRoutine = True
Dim currentTime As Date = Now
Dim localSeconds As Double = currentTime.Second + (currentTime.Millisecond / 1000)
Dim localArrayList As New ArrayList
SyncLock m_Tags.SyncRoot
SyncLock m_StaticTagValues.SyncRoot
Dim TagItems As List(Of ClassProperty)
For Each de As DictionaryEntry In m_Tags
Dim TagID As String = de.Key
TagItems = de.Value
' Just simulating using the PollingRate property
Dim OKToPoll As Boolean = True
If m_LastUpdateTime.Contains(TagID) Then
Dim PollingRate As Double = GetPropValue(TagItems, "PollingRate")
Dim lastUpdateTime As Date = m_LastUpdateTime(TagID)
If lastUpdateTime.AddSeconds(PollingRate) > currentTime Then
OKToPoll = False
End If
End If
If OKToPoll Then
If m_LastUpdateTime.Contains(TagID) Then
m_LastUpdateTime(TagID) = currentTime
Else
m_LastUpdateTime.Add(TagID, currentTime)
End If
Dim SimType As SimTypes = GetPropValue(TagItems, "SimType")
Dim Value As Object
Select Case SimType
Case SimTypes.Dynamic
Dim DynamicType As DynamicSimTypes = GetPropValue(TagItems, "DynamicSimType")
Select Case DynamicType
Case DynamicSimTypes.Ramp
Value = localSeconds * 100 / 60
Case DynamicSimTypes.Random
Value = Rnd() * 100
Case DynamicSimTypes.Sine
Value = Math.Sin(Math.PI * (localSeconds * 360 / 60) / 180.0)
End Select
Case SimTypes.Static
If m_StaticTagValues.Contains(TagID) Then
Value = m_StaticTagValues(TagID)
Else
Value = 0
End If
End Select
Dim Quality As Boolean = False
If Not (Value Is Nothing) Then
Quality = True
End If
' You can include multiple values to the same tag with different timestamps in the same callback if you like.
' In this example it just updates when the timer fires and the check for the PollingRate succeeds.
localArrayList.Add(New ClassTagValue(TagID, Value, currentTime, Quality))
End If
Next
End SyncLock
End SyncLock
If localArrayList.Count > 0 Then
' Send values to OAS Service
m_OASDriverInterface.AsyncReadCallback(CType(localArrayList.ToArray(GetType(ClassTagValue)), ClassTagValue()))
End If
' The following can be used in any routine to post an error during Runtime operation of OAS.
'm_OASDriverInterface.UpdateSystemError(True, "Communications", 1, "An example of posting a system error")
Catch ex As Exception
m_OASDriverInterface.UpdateSystemError(True, "Communications", 5, "TimerRoutine Exception: " + ex.Message)
End Try
m_InTimerRoutine = False
End Sub
C#
// This is a simple example of getting the properties of a tag and using that to generate a update to the tag value
private void TimerRoutine(object State) {
try {
if (m_InTimerRoutine) {
return;
}
m_InTimerRoutine = true;
DateTime currentTime = DateTime.Now;
double localSeconds = currentTime.Second + (currentTime.Millisecond / 1000.0);
ArrayList localArrayList = new ArrayList();
lock (m_Tags.SyncRoot) {
lock (m_StaticTagValues.SyncRoot) {
List TagItems = null;
foreach (DictionaryEntry de in m_Tags) {
string TagID = Convert.ToString(de.Key);
TagItems = (List)de.Value;
// Just simulating using the PollingRate property
bool OKToPoll = true;
if (m_LastUpdateTime.Contains(TagID)) {
double PollingRate = Convert.ToDouble(GetPropValue(TagItems, "PollingRate"));
DateTime lastUpdateTime = Convert.ToDateTime(m_LastUpdateTime[TagID]);
if (lastUpdateTime.AddSeconds(PollingRate) > currentTime) {
OKToPoll = false;
}
}
if (OKToPoll) {
if (m_LastUpdateTime.Contains(TagID)) {
m_LastUpdateTime[TagID] = currentTime;
}
else {
m_LastUpdateTime.Add(TagID, currentTime);
}
SimTypes SimType = (MyExampleOASDriver.DriverInterface.SimTypes)GetPropValue(TagItems, "SimType");
object Value = null;
switch (SimType) {
case SimTypes.Dynamic:
DynamicSimTypes DynamicType = (MyExampleOASDriver.DriverInterface.DynamicSimTypes)GetPropValue(TagItems, "DynamicSimType");
switch (DynamicType) {
case DynamicSimTypes.Ramp:
Value = localSeconds * 100 / 60;
break;
case DynamicSimTypes.Random:
Value = Microsoft.VisualBasic.VBMath.Rnd() * 100;
break;
case DynamicSimTypes.Sine:
Value = Math.Sin(Math.PI * (localSeconds * 360 / 60) / 180.0);
break;
}
break;
case SimTypes.Static:
if (m_StaticTagValues.Contains(TagID)) {
Value = m_StaticTagValues[TagID];
}
else {
Value = 0;
}
break;
}
bool Quality = false;
if (Value != null) {
Quality = true;
}
// You can include mutiple values to the same tag with different timestamps in the same callback if you like.
// In this example it just updates when the timer fires and the check for the PollingRate succeeds.
localArrayList.Add(new ClassTagValue(TagID, Value, currentTime, Quality));
}
}
}
}
if (localArrayList.Count > 0)
{
// Send values to OAS Service
m_OASDriverInterface.AsyncReadCallback((ClassTagValue[])localArrayList.ToArray(typeof(ClassTagValue)));
}
// The following can be used in any routine to post an error during Runtime operation of OAS.
//m_OASDriverInterface.UpdateSystemError(True, "Communications", 1, "An example of posting a system error")
}
catch (Exception ex) {
m_OASDriverInterface.UpdateSystemError(true, "Communications", 5, "TimerRoutine Exception: " + ex.Message);
}
m_InTimerRoutine = false;
}
Step 14
To post a System Error to OAS call the method UpdateSystemError on the OAS Driver Interface object.
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
m_OASDriverInterface.UpdateSystemError(True, "myCategory", 1, "Error message to display")
C#
if (UpdateSystemError != null)
m_OASDriverInterface.UpdateSystemError(true, "myCategory", 1, "Message to display when error is cleared");
NEXT STEPS
Creating a Hosting App
Once you have compiled the custom Driver assembly, your next step will be to Create a Hosting Application that will load the assembly and run it. This application can be any .NET app, but for most deployments, you will be creating a .NET Windows Service or a Console Application. Services are perfect for deployment on a Windows platform, and Console Applications, when written using .NET Core, can be hosted on non-Windows operating systems like Linux and Mac. Additionally, you can create an Android or iOS app using the Xamarin development tools within Visual Studio.
Copy the C# or VB Hosting App Code from the OAS installation path, typically C:\Program Files\Open Automation Software\OAS\Universal Drivers\Framework4\Hosting App\. Locate the Windows Service directory and copy to a location of your choosing, then open the project in Visual Studio. We suggest copying to a directory near the Driver source code you created in the previous tutorial as you will be referencing it.
Open up your choice of VB or C# example code, preferably matching the language chosen for your driver. It is not necessary for them to be written in the same language, but is easier to debug when they are consistent.
the Service runtime settings.
Start the service by selecting it from the Service Control Panel and select Start. If the service functions properly and starts with no issues, you should see “Running” under the Status column.
Open OAS Configuration to Configure Drivers and Tags. Within the OAS installation directory, you can find the OAS Configuration.exe application. Execute this application and when the window opens select Configure > Drivers. Then click Select next to the field containing “Localhost“. You should see your new ExampleDriver listed to the left. Select it and you should see the following screen:
Windows
Mac OS
Linux
Unofficially Supported
