Create OPC Toolbox Data Access Objects

Overview to Objects

The first step in interacting with an OPC server from MATLAB® software is to establish a connection between the server and OPC Toolbox™ software. You create opcda client objects to control the connection between an OPC server and the toolbox. Then you create dagroup objects to manage sets of daitem objects, and then you create the daitem objects themselves, which represent server items. A server item corresponds to a physical device or to a storage location in a SCADA system or DCS.

You must create the toolbox objects in the order described above. Connect to OPC Data Access Servers describes how to create an opcda client object. This section discusses how to create and configure dagroup and daitem objects.

Toolbox Object Hierarchy for the Data Access Standard

OPC Toolbox DA software is implemented using three basic objects, designed to help you manage connections to servers and collections of server items. The three objects are arranged in a specific hierarchy, shown in the following figure.

  1. OPC Data Access Client objects (opcda client objects) represent a specific OPC client instance that can communicate with only one server. You define the server using the Host and ServerID properties. The Host property defines the computer on which the server is installed. The ServerID property defines the Program ID (ProgID) of the server, created when the server was installed on that host. The opcda client object acts as a container for multiple group objects, and manages the connection to the server, communication with the server, and server name space browsing.

  2. Data Access Group objects (dagroup objects) represent containers for one or more server items (data points on the server.) A dagroup object manages how often the items in the group must be read, whether historical item information must be stored, and also manages creation and deletion of items. Groups cannot exist without an opcda client object. You create dagroup objects using the addgroup function of an opcda client object.

  3. Data Access Item objects (daitem objects) represent server items. Items are defined by an item ID, which uniquely defines that server item in the server's name space. A daitem object has a Value, a Quality, and a TimeStamp, representing the information collected by the server from an instrument or data point in a SCADA system. The Value, Quality, and TimeStamp properties represent the information known to the server when the server was last asked to access information from that instrument.

A dagroup object can only exist “within” an opcda client object. Similarly, a daitem object can only exist within a dagroup object. You create dagroup objects using the addgroup method of an opcda client object. You create daitem objects using the additem method of the dagroup object.

How Toolbox Objects Relate to OPC DA Servers

OPC Toolbox software uses objects to define the server that the client must connect to, and the arrangement of items in groups. The following figure shows the relationship between the OPC Toolbox Data Access objects and an OPC server.

The opcda client object establishes the connection between OPC Toolbox software and the OPC server, using OPC Data Access Specification standards. The standards are based on Microsoft® COM/DCOM interoperability standards.

The daitem objects represent specific server items. Note that a client typically requires only a subset of the entire name space of a server in order to operate effectively. In the figure above, only the PV and SP items of FIC01, and the LIT01 item, are required for that particular group. Another group may only contain a single daitem object, representing a single server item.

Note

The dagroup object has no equivalent on the OPC server. However, the server keeps a record of each group that a client has created, and uses that group name to communicate to the client information about the items in that group.

Create Data Access Group Objects

Once you have created an opcda client object, you can add groups to the client. A dagroup object manages multiple daitem objects. Using a dagroup object, you can read data from all items in that group in one action, write data to the items in the group, define actions to take when any of the items in that group change value, or log data for all the items in that group for analysis and processing.

To create a dagroup object, you use the addgroup function, specifying the opcda client object that you want to add the group to, and an optional group name. See Specify a Group Name for rules on defining your own group name.

The example below creates an opcda client object, connects that object to the server, and adds two groups to the client. The first group is automatically named by the server, and the second group is given a specified name.

da = opcda('localhost','Matrikon.OPC.Simulation.1');
connect(da);
grp1 = addgroup(da);
grp2 = addgroup(da,'MyGroup');

Specify a Group Name

It is required that each group created under a specific client object has a unique name. This allows the OPC server to uniquely identify the group when a client makes a server request using that group. The name can be any nonempty character vector.

You do not need to specify a group name for each group that you add to a client. If you do not specify a name, the OPC server will automatically assign a group name for you. Each OPC server defines different rules for automatic naming of groups.

If you attempt to create a group with the same name as a group already created for that client, an error will be generated.

See Delete Objects for information about how groups are automatically named when you create groups with a disconnected client.

View a Summary of a Group Object

To view a summary of the characteristics of the dagroup object you created, enter the variable name you assigned to the object at the command prompt. For example, this is the summary for the object grp1.

grp1

The items in this list correspond to the numbered elements in the object summary:

  1. The title of the Summary includes the name of the dagroup object. In the example, this is the server-assigned name Group0.

  2. The Object Parameters section lists the values of key dagroup object properties. These properties describe the type of group, the daitem objects associated with the group, the name of the group's parent opcda client object, and properties that control how the server updates item information for this group. In the example, any items created in this group will be updated at half-second intervals, with a deadband of 0%. For information on how the server updates item information, see Data Change Events and Subscription.

  3. The Object Status section lists the current state of the object. A dagroup object can be in one of several states:

    • The Active state defines whether any operation on the group applies to the item.

    • The Subscription state defines whether changes in the item's value or quality will produce a data change event. See Data Change Events and Subscription for more information about the Subscription property.

    • The Logging state describes whether the group is logging or not. See Log OPC Server Data for information on how to log data.

  4. The Logging Parameters section describes the values of the logging properties for that group. Logging properties control how the dagroup object logs data, including the duration of the logging task and the destination of logged data. See Log OPC Server Data for information on logging data using dagroup objects.

Use a Group Object

A dagroup object with no items does not perform any useful functions. Once you have added items to a group, you can use the group to

  • Read data from, and write data to, the OPC server. See Read and Write Data for more information.

  • Control how an OPC server notifies MATLAB about changes in any item associated with a dagroup object. See Data Change Events and Subscription for more information.

  • Log data from all items in that group, for later processing and analysis. Log OPC Server Data describes how to control logging.

Create Data Access Item Objects

A dagroup object provides a container for collecting one or more daitem objects. A daitem object provides a link to a specific server item. The daitem object defines how you want to retrieve and store the client-side value of the server item, and also stores the last data retrieved from the server for that server item. You can use a daitem object to read data from the server for that server item, or to write values to that server item on the server.

You create a daitem object using the additem function, specifying the dagroup object to which the item must be added and the fully qualified item ID of the server item. You can obtain a list of the fully qualified item IDs for all server items using the serveritems function.

The example below builds on the example in Create Data Access Group Objects by adding a daitem object to the first group created in that example. The server item associated with this item is called 'Random.Real8'.

itm1 = additem(grp1,'Random.Real8');

Specify a Local Data Type for the Item

When you create a daitem object, you create an object that stores the value of the server item locally on the client. You can specify that the local storage data type be different from the server storage data type. For example, you can specify that a value stored on the server as an integer be stored in MATLAB as a double-precision floating-point value, because you know that you will be performing double-precision calculations with that item's value.

Although it is possible to modify the data type of the item after it is created, you can also create an item with a specific data type by specifying the data type as the third parameter to the additem function. The data type specification must be a character vector describing that data type. Valid OPC data types are any MATLAB numeric data type, plus 'char', and 'logical'. See Work with Different Data Types for more information on supported data types.

The example below adds another item to the group grp1 created by the example in Create Data Access Group Objects. The item ID is 'Random.UInt2', which is stored on the server as an unsigned 16-bit integer. By specifying the data type as 'double', the value will be returned to MATLAB and stored locally as a double-precision floating-point number.

itm2 = additem(grp1,'Random.UInt2','double');

Note

The conversion process from the server's data type to the item's data type is performed by the server, using Microsoft COM Variant conversion rules. If you attempt to convert a value to a data type that does not have that value's range, the OPC server will return an error when attempting to update the value of that item. You should then change the data type to one that has the same or larger range than the server item's data type. See Work with Different Data Types for more information.

Specify the Active Status of an Item Object

You can optionally specify the Active status of an daitem object by passing a character vector as the fourth parameter to the additem function. The Active status can be 'on' or 'off'. An item with an Active status of 'off' behaves as if the item was never created: No server updates of the item's value will take place, and a read or write with that item will fail. You use the Active status to temporarily disable an item without deleting that item from MATLAB. For more information on the Active status, see the reference page for the Active property.

View a Summary of the Item Object

To view a summary of the characteristics of the daitem object you created, enter the variable name you assigned to the object at the command prompt. For example, this is the summary for the object itm1.

itm1

The items in this list correspond to the numbered elements in the object summary:

  1. The title of the Summary includes the fully qualified item ID of the item. In the example, the item is associated with the 'Random.Real8' server item.

  2. The Object Parameters section lists the values of key daitem object properties. These properties describe the name of the item's Parent group, and the Access Rights advertised by the server.

  3. The Object Status section lists the Active state of the object. The Active state defines whether any operation on the parent group applies to the item, and whether you want to be notified of any changes in the item's value.

  4. The Data Parameters section lists the Data Type used by the daitem object to store the value, and the Value, Quality, and TimeStamp of the last value obtained from the server for this item. For more information on the Value, Quality, and TimeStamp of an item, see OPC Data: Value, Quality, and TimeStamp.

Use an Item Object

You create a daitem object to query the value of the associated server item, or to write values to that server item. You can write values to a single item, and read values from a single item, using the daitem object. For more information on reading and writing values, see Read and Write Data.

You can also use the parent dagroup object to read and write values for all of the daitem objects contained in that group, or to log changes in the item's value for a period of time. See Log OPC Server Data for information on logging data.

Build an Object Hierarchy with a Disconnected Client

When you create objects with a connected client, OPC Toolbox software validates those objects with the OPC server before creating them on the client. For example, when adding a group to the client using the addgroup function, the validation process ensures that no other group with the same name exists on the server, and that the server will accept the group. When adding an item, the item ID is verified to be a valid server item.

Occasionally you may wish to build up a toolbox object hierarchy without connecting to the server. For example, you may be off site and wish to configure a logging task for use on the following day, rather than wait to configure the objects for that task when you are on site.

OPC Toolbox software allows you to configure an entire toolbox object hierarchy without connecting to the server. However, without a connection to the server, the toolbox cannot validate the created objects with that server. Instead, OPC Toolbox software will perform some basic validation on the objects you create, and revalidate those objects with the server when you connect to the server.

When you create toolbox objects with a disconnected client, the following validation is performed:

  • When adding a group using the addgroup function, if you do not specify a name, OPC Toolbox software automatically assigns a unique name 'groupN', where N is the lowest integer that ensures that the group name is unique. For example, the first group created will be 'group1', then 'group2', and so on.

  • When you specify a group name when using the addgroup function, an error will be generated if a group with the same name already exists.

  • When adding an item to a group using the additem function, an error will be generated only if an item with the same name already exists in that group. No other checking is performed on the item.

  • When adding an item to a group, if you do not specify a data type for that item, the data type is set to 'unknown'. When you connect to the server, the data type will be changed to the server item's CanonicalDataType.

Despite all of the checks described above, the server may not accept all objects created on a disconnected client when that client is connected to the server using the connect function. For example, an item's item ID may not be valid for that server, or a group name may not be valid for that server. When you connect a client to the server using connect, any objects that the server rejects will be deleted from the object hierarchy, and a warning will be generated. In this way, all objects on a connected client are guaranteed to have been accepted by the server.

Create OPC Toolbox Data Access Object Vectors

OPC Toolbox software supports the use of object vectors. An object vector is a single variable in the MATLAB workspace containing a reference to more than one object. For example, all the groups added to an opcda client object are stored in the client's Group property. The Group property contains a dagroup object vector that represents all groups in that client. Similarly, a dagroup object has an Item property that contains a reference to every daitem object created in the group.

You can construct vectors using any of the standard concatenation techniques available in MATLAB. However, OPC Toolbox software imposes some limitations on the construction of object vectors:

  • Objects must be the same class. For example, you can concatenate two dagroup objects, but you cannot concatenate a dagroup object with a daitem object.

  • Group and item objects must have the same parent.

  • One of the dimensions of the resulting array must be scalar. You can create a column vector (m-by-1 objects) or a row vector (1-by-n objects), but not an m-by-n matrix.

  • OPC Toolbox software does not fill in missing elements in a vector. Instead, an error is generated. For example, you cannot assign a scalar object at the 4th index to a scalar object.

The following sections discuss how to create and use toolbox object vectors:

Construct Object Vectors

You can construct an object vector using any of the following techniques:

  • Using concatenation of lists of individual object variables

  • Using indexed assignment

  • Using object properties to retrieve object vectors

Create Object Vectors Using Concatenation.  To construct an OPC Toolbox Data Access object vector using concatenation, you use the normal MATLAB syntax for concatenation. Create a list of all objects you want to create, and surround that list with square brackets ([]). Separate each element of the object vector by either a comma (,) to create a row vector, or a semicolon (;) to create a column vector.

The following example creates three fictitious opcda client objects, and concatenates them into a row vector.

da1 = opcda('Host1','Dummy.Server.1');
da2 = opcda('Host2','Dummy.Server.2');
da3 = opcda('Host3','Dummy.Server.3');
dav = [da1, da2, da3];

Create Object Vectors Using Indexed Assignment.  Indexed assignment refers to creating vectors by assigning elements to specific indices in the vector. The following example constructs the same three-element opcda client object vector as in the previous example, using indexed assignment.

dav(1) = opcda('Host1','Dummy.Server.1');
dav(2) = opcda('Host2','Dummy.Server.2');
dav(3) = opcda('Host3','Dummy.Server.3');

Create an Object Vector Using Object Properties.  You may obtain an object vector if you assign the Group property of a opcda client object, or the Item property of a dagroup object, to a variable. If the client has more than one group, or the group has more than one item, the resulting property is an object vector.

For information on obtaining object properties, see View the Value of a Particular Property.

Display a Summary of Object Vectors

To view a summary of an object vector, type the name of the object vector at the command prompt. For example, this is the summary of the client vector dav.

dav
   OPC Data Access Object Array:

   Index:  Status:         Name:
   1       disconnected    Host1/Dummy.Server.1
   2       disconnected    Host2/Dummy.Server.2
   3       disconnected    Host3/Dummy.Server.3

The summary information for each OPC Toolbox Data Access object class is different. However, the basic display is similar.

Use Object Vectors

You use object vectors just as you would a normal object variable. The function you call with the object vector simply gets applied to all objects in the vector. For example, passing the client vector dav to the connect function connects each object in the vector to its OPC server.

Note

Some OPC Toolbox functions do not accept object vectors as arguments. If you attempt to use an object vector with a function that does not accept object vectors, an error will be generated. Consult the relevant function reference page for information on whether a function supports object vectors.

If you need to extract elements of an object vector, use standard MATLAB indexing notation. For example, the following example extracts the second element from the client vector dav.

dax = dav(2);

Work with Public Groups

The OPC Data Access Specification provides a mechanism for sharing group configuration amongst many clients. Normally, a client has private access to a group; no other client connected to the same server can see that group, and the items configured in that group. However, a client can define a group as public, allowing other clients connected to the same server to gain access to that group.

Note

The OPC Data Access Specification defines the support for public groups as optional. Consequently, some OPC servers will not support public groups.

A public group differs from a private group in the following ways:

  • Once a group is defined as public, you cannot add items to that group, nor remove items from the group. This restriction ensures that every client using that public group has access to the same items, and does not need to worry about items being added or removed from that group. You should ensure that a group's items are correct before making that group public.

  • Each client that accesses the public group is able to set its own group properties, such as the UpdateRate, DeadbandPercent, Active, and Subscription properties. For example, one client can define an UpdateRate of 10 seconds for a public group, while another client specifies the UpdateRate as 2 seconds.

  • Each public group defined on a server must have a unique name. If you attempt to create a public group with a name that is the same as a public group on the server, an error is generated.

  • A single client cannot have a public group and a private group with the same name. For example, you cannot connect to a public group named 'LogGroup' and then create a private group called 'LogGroup'.

Using OPC Toolbox software, you can define and publish your own public groups or connect to existing public groups. You an also request that public groups be removed from an OPC server. The following sections illustrate how you can work with public groups using OPC Toolbox software:

Define a New Public Group

You define a new public group by creating a private group in the normal way (described in Create Data Access Group Objects) and then converting that private group into a public group.

You use the makepublic function to convert a private group into a public group. The only argument to the makepublic function is the group object that you want to convert to a public group.

The following example creates a private group, with specific items in that group. The group is then converted into a public group.

da = opcda('localhost','My.Server.1');
grp = addgroup(da,'PublicGrpExample');
itms = additem(grp,{'Item.ID.1','Item.ID.2'});
makepublic(grp);

You can check the group type using the GroupType property.

grp.GroupType
public

Connect to an Existing Public Group

In addition to creating new public groups, you can also create a connection to an existing public group on the server. To obtain a list of available public groups on a server, you use the opcserverinfo function, passing the client object that is connected to the server as the argument. The returned structure includes a field called 'PublicGroups', containing a cell array of public groups defined on that server. If the 'PublicGroups' field is empty, then you should check the 'SupportedInterfaces' field to ensure that the server supports public groups. A server that supports public groups will implement the IOPCServerPublicGroups interface.

Once you have a list of available public groups, you can create a connection to that group using the addgroup function, passing it the client that is connected to the server containing the public group, the name of the public group, and the 'public' group type specifier.

Note

You cannot create a connection to an existing public group if your client object is disconnected from the server.

The following example connects to a public group named 'PublicTrends' on the server with program ID 'My.Server.1'.

da = opcda('localhost','My.Server.1');
connect(da);
pubGrp = addgroup(da,'PublicTrends','public');

When you connect to a public group, the items in that group are automatically created for you.

itm = pubGrp.Items
itm =

   OPC Item Object Array:

   Index:  DataType:  Active:  ItemID:
   1       double     on       item.id.1
   2       uint16     on       item.id.2
   3       double     on       item.id.3

You cannot add items to or remove items from a public group. However, you can still modify the update rate of the group, the dead band percent, and the active and subscription status of the group, and you can use the group to read, write, or log data as you would for a private group.

When you have finished using a public group, you can use the delete function to remove that group from your client object. Deleting the group from the client does not remove the public group from the server; other clients might require that group after you have finished with it. Instead, deleting the group from the client indicates to the server that you are no longer interested in the group.

Remove Public Groups from the Server

You can request that a public group be removed from a server using the removepublicgroup function, passing the client object that is connected to the server and the name of the public group to remove.

Caution

The OPC Data Access Specification does not provide any security mechanism for removing public groups; any client can request that a public group be removed. You should use this function with extreme caution!

If any clients are currently connected to that group, the server will issue a warning stating that the group will be removed when all clients have finished using the group.

OPC Toolbox Documentation
Support

Try MATLAB, Simulink, and Other Products

Get trial now