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.
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.
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.
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.
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.
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.
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');
Each group created under a specific client object must have 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.
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:
The title of the Summary
includes the name of
the dagroup
object. In the example, this is the server-assigned
name Group0
.
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.
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.
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.
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.
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');
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.
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.
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:
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.
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.
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.
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.
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.
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 might want to build up a toolbox object hierarchy without connecting to the server. For example, you might be off site and want 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 performs some basic validation on the objects you create, and revalidates those objects with the server when you connect.
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
'group
N
'
, 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 is generated if a group with the same name
already exists.
When adding an item to a group using the additem
function, an error is 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 might 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 might not be valid for that
server, or a group name might 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.
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 describes how to create object vectors.
Display a Summary of Object Vectors describes how object vectors are displayed at the command line.
Use Object Vectors describes how you can use object vectors with OPC Toolbox software.
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.
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.
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);
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 describes how you can create new public groups.
Connect to an Existing Public Group describes how you can utilise a public group that is already defined on the server.
Remove Public Groups from the Server describes how you can remove public groups from an OPC server.
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
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.
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.