The ControlGroupType is used to manage the control of the functionality provided by a FunctionalEntity or part of it. ControlGroups are used when some part of a FunctionalEntity is to be “controlled” by another FunctionalEntity or application. ControlGroups can be used by an application to help understand how the Variables (inputs, outputs, configuration) and Methods are logically related to each other in the application. ControlGroups utilize the LockingServices defined in OPC 10000-100. The ControlGroupType is illustrated in Figure 26.
Figure 26 – ControlGroupType illustration
ControlGroups are part of the FunctionalEntity model and are independent of any communication model (Client Server, PubSub, etc.). A ControlGroup is used to identify the usage of parts of the FunctionalEntity. ControlGroups may result in a restriction to the grouped items. The restriction can include Objects (input and configuration Variables) and Method invocations. The restriction can block all changes to Variables or restrict changes to only the lock-owner (application or user). The lock-owner of the restrictions may be unrelated to the caller of the EstablishControl Method.
A Variable, Object, or Method may be referenced from more than one ControlGroup. Multiple ControlGroups might exist with different combinations.
ListToRestrict and ListToBlock each have their own instances of LockingServices. When a ControlGroup is assigned to a user or application, the Variables or Methods in ListToBlock or ListToRestrict are associated with that user or application (that user or application becomes the lock-owner). The LockingServices exposed in ListToBlock and ListToRestrict (InitLock, RenewLock, ExitLock) can only be called by the lock-owner. An administrative user with appropriate rights may override a Lock and release it.
The ControlGroup also exposes EstablishControl, ReassignControl, and ReleaseControl Methods. EstablishControl will acquire the Lock for both ListToRestrict and ListToBlock. ReassignControl can be used to change the lock-owner to a different user or application. ReleaseControl will release the Lock. A user or application different from the lock-owner shall not be able to successfully call EstablishControl on another ControlGroup that references the same Variables or Methods in ListToBlock or ListToRestrict.
The EstablishConnections Method supports commands to establish control (EstablishControlCmd) and reassign control (ReassignControlCmd). The CloseConnections Method will release any Locks that may have been acquired as part of connection establishment. The functionality provided by EstablishConnections (ReassignControlCmd) and CloseConnections is the same as that provided by the individual Methods in the ControlGroup, except they operate on the Locks as the lock-owner. If a ControlGroup is assigned to a ConnectionEndpoint, only those having the rights to call EstablishConnections or CloseConnections can reassign or release control (i.e., the EstablishConnections and CloseConnections Method act as the ConnectionEndpoint).
One or more Clients may call EstablishControl on separate ControlGroups that do not share any Variables or Methods (in ListToRestrict or ListToBlock). For examples of ControlGroups, see Annex D.3.
The FunctionalEntity may provide Variables in its InputData, OutputData and ConfigurationData Folders. A ControlGroup may include any combination of the input, output, and configuration Variables from the FunctionalEntity. A FunctionalEntity may provide information in InputData, OutputData and ConfigurationData that are not part of any ControlGroup.
ControlGroups are primarily used for locking, but they may also be used to merely provide a subset of FunctionalEntity configuration related to a specific described set of controls. The described grouping of functionality may be nested to allow further organization of the functionality. For example, a simple PID may be modelled as a FunctionalEntity; it can be run in cascade mode where another FunctionalEntity provides the setpoint input, or it can allow an operator to enter setpoints via an HMI. In this case, two ControlGroups could be provided by the PID FunctionalEntity, and the choice of ControlGroup would lock the functionality into a specific mode. More complex FunctionalEntities might also restrict which ControlGroups are available based on configuration settings.
The ControlGroupType is formally defined in Table 61.
Table 61 – ControlGroupType definition
|
Attribute |
Value |
||||
|
BrowseName |
3:ControlGroupType |
||||
|
IsAbstract |
False |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
Subtype of the 0:BaseObjectType defined in OPC 10000-5 |
|||||
|
0:HasComponent |
Object |
3:ListToBlock |
|
3:ControlItemFolderType |
M |
|
0:HasComponent |
Object |
3:ListToRestrict |
|
3:ControlItemFolderType |
M |
|
0:HasComponent |
Object |
3:ListOfRelated |
|
0:FolderType |
M |
|
0:HasProperty |
Variable |
3:IsControlled |
0:Boolean |
0:PropertyType |
M |
|
0:HasComponent |
Method |
3:EstablishControl |
|
Defined in 6.5.3 |
O |
|
0:HasComponent |
Method |
3:ReleaseControl |
|
Defined in 6.5.4 |
O |
|
0:HasComponent |
Method |
3:ReassignControl |
|
Defined in 6.5.5 |
O |
|
0:HasComponent |
Object |
3:<ControlGroup> |
|
3:ControlGroupType |
OP |
|
ConformanceUnits |
|||||
|
UAFX IFunctionalEntity ControlGroups |
|||||
ListToBlock is a group of items that are to be blocked from any changes to Variables or executing Methods. This could be any Variables or Methods in the hierarchical structure of instances that are in the FunctionalEntity. Once an EstablishControl Call is made, the values of Variables in this list can no longer be modified, and Methods in this list can no longer be executed.
ListToRestrict is a group of items that are to be restricted to allow only the lock owner (see OPC 10000-100) to change Variables or execute Methods. This could be any Variables or Methods in the hierarchical structure of instances that are in the FunctionalEntity.
ListOfRelated is a group of items that are part of the ControlGroup that are not blocked or restricted (i.e., it is Objects, Variables, Methods).
A Variable, Method or Object shall not be included in more than one of the lists within a ControlGroup.
IsControlled is a flag that indicates if the ControlGroup is currently controlled. When this bit is set, the controlling entity can be determined by following the Controls Reference or by the information in the Lock Object (i.e., the Lock LockingClient) in either the ListToRestrict Folder or the ListToBlock Folder.
The optional EstablishControl Method invokes the LockingServices in both the ListToBlock and ListToRestrict groups. The Lock LockingClient is set to the LockContext parameter unless this parameter is a null String, in which case it is set to the ApplicationUri of the Client connection used to call this Method.
The optional ReassignControl Method will assign all active Locks in the ControlGroup to a different LockingClient.
The Locks can be assigned to a ConnectionEndpoint. In this case, the following applies:
- All Locks automatically call the ExitLock Method if the associated ConnectionEndpoint is being removed.
- The Lock LockingUser shall be set to “UAFX”.
- The Locks are automatically renewed as long as the Status of the ConnectionEndpoint is different from Error.
- A Controls Reference (see OPC 10000-23) shall be added with a SourceNode of the ConnectionEndpoint and the TargetNode of the ControlGroup.
If the lock is assigned to the Client connection, the Controls Reference (see OPC 10000-23) shall have a SourceNode of the Object associated with the Client connection (see OPC 10000-100) and a TargetNode of the ControlGroup.
The optional ReleaseControl Method calls the ExitLock Method on all established Locks and removes the Controls Reference. It also clears the IsControlled flag.
Calling the ExitLock Method on the Locks does not affect the IsControlled flag and associated Controls Reference; it will only release the Lock on the given group of items (ListToBlock, ListToRestrict).
The LockingServices provide a system-wide MaxInactiveLockTime, which a local MaxInactiveLockTime can overwrite in each lock Folder. If the CleanupTimeout is different for each Connection, then a local MaxInactiveLockTime should be specified and related to the ConnectionEndpoint CleanupTimeout. It is important to understand that this timeout will be used to timeout locks and thus must be larger than the CleanupTimeout if a lock is not to be removed before a Connection is removed. The system-wide MaxInactiveLockTime may be used for other applications or deployments of LockingServices, so care should be exercised if a local MaxInactiveLockTime is not used.
A ControlGroup can contain additional nested ControlGroups. The specified Methods of ControlGroupType shall not be applied to any nested ControlGroups.
This Method shall acquire Locks required by the ControlGroup in the ListToRestrict and ListToBlock. If acquiring any Lock fails, all Locks shall be released, and the appropriate LockStatus shall be returned. If all required Locks can be acquired, the Method shall set the IsControlled flag and create the Controls Reference.
It is recommended that this Method be restricted to Client connections that have the well-known Role ConnectionAdmin as defined in Clause 5.9.
EstablishControl shall set Lock LockingClient to the LockContext Argument.
The signature of this Method is specified below; the arguments are defined in Table 62.
Signature
EstablishControl (
[in] 0:String LockContext,
[out] 0:Int32 LockStatus
);
Table 62 – EstablishControl Method Arguments
|
Argument |
Description |
|
LockContext |
A string used to provide context information about the lock-owner. It may be the NodeId (in string representation) of a ConnectionEndpoint or the ApplicationUri of a Client connection as provided in the CreateSession Service Call (see OPC 10000-4). If this parameter is a null string, it shall default to the ApplicationUri of the Client connection initiating this command. |
|
LockStatus |
0 – OK -1 – E_AlreadyLocked – An element is already locked; this might be an entire Lock, or it might be a single variable in one of the lists. -2 – E_Invalid – the element cannot be locked |
The possible Method result codes are formally defined in Table 63.
Table 63 – EstablishControl Method result codes
|
ResultCode |
Description |
|
Bad_UserAccessDenied |
The caller is not allowed to establish control on the ControlGroup. |
The EstablishControl Method representation in the AddressSpace is formally defined in Table 64.
Table 64 – EstablishControl Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
3:EstablishControl |
||||
|
References |
Node Class |
BrowseName |
DataType |
TypeDefinition |
Other |
|
0:HasProperty |
Variable |
0:InputArguments |
Argument[] |
0:PropertyType |
Mandatory |
|
0:HasProperty |
Variable |
0:OutputArguments |
Argument[] |
0:PropertyType |
Mandatory |
|
ConformanceUnits |
|||||
|
UAFX IFunctionalEntity ControlGroups |
|||||
This Method Call shall release the ControlGroup and issue a Call to the Lock Objects in each Folder for the ExitLock Method (see OPC 10000-100). It shall create the appropriate parameters for the ExitLock Method. It shall remove the Controls Reference from the ControlGroup.
It is recommended that this Method be restricted to Client connections that have the well-known Role ConnectionAdmin as defined in Clause 5.9.
The signature of this Method is specified below.
Signature
ReleaseControl (
);
The possible Method result codes are formally defined in Table 65.
Table 65 – ReleaseControl Method result codes
|
Result Code |
Description |
|
Bad_UserAccessDenied |
The caller is not allowed to release control on the ControlGroup. |
The ReleaseControl Method representation in the AddressSpace is formally defined in Table 66.
Table 66 – ReleaseControl Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
3:ReleaseControl |
||||
|
References |
Node Class |
BrowseName |
DataType |
TypeDefinition |
Other |
|
ConformanceUnits |
|||||
|
UAFX IFunctionalEntity ControlGroups |
|||||
This Method shall reassign Locks required by the ControlGroup in the ListToRestrict and ListToBlock. It shall reassign the SourceNode of the Controls Reference (see OPC 10000-23) to the controlling entity as defined by the LockContext.
It shall set Lock LockingClient to the LockContext Argument.
It is recommended that this Method be restricted to Client connections that have the well-known Role ConnectionAdmin as defined in Clause 5.9.
The signature of this Method is specified below; the arguments are defined in Table 67.
Signature
ReassignControl (
[in] 0:String LockContext,
[out] 0:Int32 LockStatus
);
Table 67 – ReassignControl Method Arguments
|
Argument |
Description |
|
LockContext |
A string used to provide context information about the lock-owner. It may be the NodeId (in string representation) of a ConnectionEndpoint or the ApplicationUri of a Client connection as provided in the CreateSession Service Call (see OPC 10000-4). It cannot be null. |
|
LockStatus |
0 – OK -1 – E_NotLocked – the Object is not locked -2 – E_Invalid – the element cannot be reassigned |
The possible Method result codes are formally defined in Table 68.
Table 68 – ReassignControl Method result codes
|
Result Code |
Description |
|
Bad_UserAccessDenied |
The caller is not allowed to reassign control on the ControlGroup. |
|
Bad_InvalidArgument |
LockContext was null, invalid, or non-existing. |
The ReassignControl Method representation in the AddressSpace is formally defined in Table 69.
Table 69 – ReassignControl Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
3:ReassignControl |
||||
|
References |
Node Class |
BrowseName |
DataType |
TypeDefinition |
Other |
|
0:HasProperty |
Variable |
0:InputArguments |
0:Argument[] |
0:PropertyType |
Mandatory |
|
0:HasProperty |
Variable |
0:OutputArguments |
0:Argument[] |
0:PropertyType |
Mandatory |
|
ConformanceUnits |
|||||
|
UAFX IFunctionalEntity ControlGroups |
|||||
The ControlItemFolderType is a subtype of the FunctionalGroupType.
The ControlItemFolderType is formally defined in Table 70.
Table 70 – ControlItemFolderType definition
|
Attribute |
Value |
||||
|
BrowseName |
3:ControlItemFolderType |
||||
|
IsAbstract |
False |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
Subtype of the 5:FunctionalGroupType defined in OPC 10000-100 |
|||||
|
0:HasComponent |
Object |
5:Lock |
|
5:LockingServicesType |
M |
|
0:HasProperty |
Variable |
5:MaxInactiveLockTime |
0:Duration |
0:PropertyType |
O |
|
ConformanceUnits |
|||||
|
UAFX IFunctionalEntity ControlGroups |
|||||
The Lock is of LockingServicesType defined in Device Integration (see OPC 10000-100) and provides the basic locking functionality.
As described in OPC 10000-100, Locks will timeout after a MaxInactiveLockTime period unless there is activity as defined or unless the RenewLock Method is called on a Lock. An optional local MaxInactiveLockTime shall have precedence over the global MaxInactiveLockTime defined in the ServerCapabilities Object.