7 ObjectTypes for the Vision System in General ToC Previous Next

7.2 ConfigurationManagementType ToC Previous Next

7.2.2 ConfigurationManagementType methods ToC Previous Next

7.2.2.1 AddConfiguration ToC

7.2.2.1.1 Overview ToC

This method is used to add a configuration to the configuration management of the vision system. It concerns itself only with the metadata of the configuration, the actual content is transferred by an object of ConfigurationTransferType which is defined in Section 7.4.

The intended behavior of this method for different input arguments is described in the following subsections.

Signature

AddConfiguration ([in]	ConfigurationIdDataType	externalId[out]	ConfigurationIdDataType	internalId[out]	NodeId	configuration[out]	Boolean	transferRequired[out]	Int32	error);

Table 12 – AddConfiguration Method Arguments

Argument Description
externalId Identification of the configuration used by the environment. This argument must not be empty.
internalId System-wide unique ID for identifying a configuration. This ID is assigned by the vision system.
configuration If the server chooses to represent the configuration in the Address Space, it shall return the NodeId of the newly created entry in the Configurations variable here.
If the server uses only method-based configuration management, this shall be a null NodeId as defined in OPC 10000-3.
transferRequired In this argument, the server returns whether the vision system assumes that a transfer of the file content of the configuration is required.
Note that this is only a hint for the client. If the server returns TRUE, the client will have to assume that the vision system needs the configuration content and shall transfer it. If the server returns FALSE, the client may transfer the configuration content anyway.
error 0 – OK
Values > 0 are reserved for errors defined by this and future standards.
Values < 0 shall be used for application-specific errors.

Table 13 – AddConfiguration Method AddressSpace Definition

Attribute Value
BrowseName AddConfiguration
References NodeClass BrowseName DataType TypeDefinition ModellingRule
HasProperty Variable InputArguments Argument[] PropertyType Mandatory
HasProperty Variable OutputArguments Argument[] PropertyType Mandatory

7.2.2.1.2 New ExternalId ToC

If AddConfiguration is called with an ExternalId not yet existing in the configuration management of the vision system, it is expected that the vision system creates an appropriate management structure with an InternalId which is unique on the system. The server then returns this InternalId.

If the server chooses to represent all or selected configurations in the Address Space and if the new configuration matches the current selection criteria, the server shall create a new entry in the Configurations folder in the Address Space.

The method will return TRUE in the TransferRequired argument. Since the ExternalId does not yet exist in the configuration management of the vision system, it is expected the configuration does not yet exist either in the local configuration storage of the vision system, and therefore needs to be transferred.

7.2.2.1.3 Identically Existing ExternalId with identical configuration ToC

If AddConfiguration is called with an ExternalId already existing in the configuration management of the vision system, it is expected that the vision system checks whether an identical version of the configuration already exists, provided that the content of the ExternalId allows for such a check. (A way to perform this comparison without having to download the binary content first is offered by the optional hash value in the ExternalId. The idea is that the client computes a hash for the contents of the recipe and passes that hash in the ExternalId. The server can then check this hash against a hash transmitted earlier, or it can compute a hash by itself over the contents of the recipe currently stored on the vision system side. For this procedure, the server needs to know the hash algorithm used by the client which can be transmitted in the hashAlgorithm member of the ExternalId).

Note that the method has no way of checking this with the actual configuration content which is not yet known to the vision system.

The method will return FALSE in the TransferRequired argument if the method comes to the conclusion that the configuration already exists with identical content on the vision system. Note that the result is not binding for the client who may decide to transfer the configuration content anyway.

If the server represents configurations in the Address Space, no new entry shall be created in the configurations folder.

7.2.2.1.4 Identically Existing ExternalId with different configuration ToC

If AddConfiguration comes to the conclusion that the content of the configuration to be transferred is different from the content already existing for this ExternalId, it shall return TRUE in the TransferRequired argument.

The behavior with respect to the management of the configuration metadata and configuration content is entirely application-defined. The vision system may decide to create a new management structure and add the configuration content to the local configuration store, or it may decide to re-use the existing ExternalId and overwrite the configuration content. In any case, the vision system shall create a new, system-wide unique InternalId for this configuration.

If the server chooses to represent configurations in the Address Space, the behavior with respect to these objects should mirror the behavior of the vision system in its internal configuration management.

7.2.2.1.5 Local creation or editing of configurations ToC

This is not, strictly speaking, a use case of the method AddConfiguration, but results are comparable, and therefore the use case is described here.

If a configuration is created locally on the vision system or is loaded onto the vision system by a different interface than the OPC Machine Vision interface, i.e. the configuration is added without using method AddConfiguration, then this configuration shall have a system-wide unique InternalId, just like a configuration added through the method.

If an existing configuration which was uploaded to the vision system through the method AddConfiguration, is locally changed, the ExternalId shall be removed from the changed version and it shall receive a new system-wide unique InternalId so that the two configurations cannot be confused. The vision system may record the history from which configuration it was derived.

If the server exposes configurations in the Address Space and if the locally created or edited configurations match the current filter criteria, then they shall be represented as nodes in the Configurations folder, with their system-wide unique InternalIds, but without ExternalIds.

7.2.2.2 GetConfigurationById ToC

This method is used to get the metadata for one configuration from a number of configurations.

Signature

GetConfigurationById ([in]	ConfigurationIdDataType	internalId[in]	Int32	timeout[out]	Handle	configurationHandle[out]	ConfigurationDataType	configuration[out]	Int32	error);

Table 14 – GetConfigurationById Method Arguments

Argument Description
internalId Identification of the configuration used by the vision system. This argument must not be empty.
Timeout With this argument the client can give a hint to the server how long it will need access to the configuration data.
A value > 0 indicates an estimated maximum time for processing the data in milliseconds.
A value = 0 indicates that the client will not need anything besides the data returned by the method call.
A value < 0 indicates that the client cannot give an estimate.
The client cannot rely on the data being available during the indicated time period. The argument is merely a hint allowing the server to optimize its resource management.
configurationHandle The client can use the handle returned by the server to call the ReleaseConfigurationHandle method to indicate to the server that it has finished processing the configuration data, allowing the server to optimize its resource management.
If the server does not support the ReleaseConfigurationHandle method, this value shall be 0.
The client cannot rely on the data being available until ReleaseConfigurationHandle is called.
configuration Requested configuration.
error 0 – OK
Values > 0 are reserved for errors defined by this and future standards.
Values < 0 shall be used for application-specific errors.

Table 15 – GetConfigurationById Method AddressSpace Definition

Attribute Value
BrowseName GetConfigurationById
References NodeClass BrowseName DataType TypeDefinition ModellingRule
HasProperty Variable InputArguments Argument[] PropertyType Mandatory
HasProperty Variable OutputArguments Argument[] PropertyType Mandatory

7.2.2.3 GetConfigurationList ToC

This method is used to get a list of all configurations. It concerns itself only with the metadata of the configuration, the actual content is transferred by a ConfigurationTransferType object.

Signature

GetConfigurationList ([in]	UInt32	maxResults[in]	UInt32	startIndex[in]	Int32	timeout[out]	Boolean	isComplete[out]	UInt32	resultCount[out]	Handle	configurationHandle[out]	ConfigurationDataType[]	configurationList[out]	Int32	error);

Table 16 – GetConfigurationList Method Arguments

Argument Description
maxResults Maximum number of configurations to return in one call; by passing 0, the client indicates that it does not put a limit on the number of configurations.
startIndex Shall be 0 on the first call, multiples of maxResults on subsequent calls to retrieve portions of the entire list, if necessary.
timeout With this argument the client can give a hint to the server how long it will need access to the configuration data.
A value > 0 indicates an estimated maximum time for processing the data in milliseconds.
A value = 0 indicates that the client will not need anything besides the data returned by the method call.
A value < 0 indicates that the client cannot give an estimate.
The client cannot rely on the data being available during the indicated time period. The argument is merely a hint allowing the server to optimize its resource management.
isComplete Indicates whether there are more configurations in the entire list than retrieved according to startIndex and resultCount.
resultCount Gives the number of valid results in configurationList.
configurationHandle The server shall return to each client requesting configuration data a system-wide unique handle identifying the configuration set / client combination. The handle spans continuation calls, so on every call by the same client where startIndex is not 0, the same handle shall be returned.
This handle canbe used by the client in a call to the ReleaseConfigurationHandle method, thereby indicating to the server that it has finished processing the configuration set, allowing the server to optimize its resource management.
The client cannot rely on the data being available until the ReleaseConfigurationHandle method is called.
If the server does no support ReleaseConfigurationHandle, this value shall be 0.
configurationList List of configurations.
error 0 – OK
Values > 0 are reserved for errors defined by this and future standards.
Values < 0 shall be used for application-specific errors.

Table 17 – GetConfigurationList Method AddressSpace Definition

Attribute Value
BrowseName GetConfigurationList
References NodeClass BrowseName DataType TypeDefinition ModellingRule
HasProperty Variable InputArguments Argument[] PropertyType Mandatory
HasProperty Variable OutputArguments Argument[] PropertyType Mandatory

The following cases must be considered with the respect to the number of available configurations:

  • The number of configurations to be returned is less or equal to maxResults; the first call, with startIndex=0, returns isComplete=TRUE, so the client knows that no further calls are necessary. resultCount gives the number of valid elements in the configurationList array.
  • The number of configurations to be returned is larger than maxResults; the first N calls (N > 0 with N ≤ (number of configurations) divisor MaxResults), with startIndex=(N-1)* maxResults, return isComplete=FALSE, so the client knows that further calls are necessary. The following call returns isComplete=TRUE, so the client knows, no further calls are necessary. resultCount gives the number of valid elements in the configurationList array (on each call, so on the first N calls, this should be maxResults).

7.2.2.4 ReleaseConfigurationHandle ToC

This method is used to inform the server that the client has finished processing a given configuration set allowing the server to free resources managing this configuration set.

The server should keep the data of the configuration set available for the client until the ReleaseConfigurationHandle method is called or until a timeout given by the client has expired. However, the server is free to release the data at any time, depending on its internal resource management, so the client cannot rely on the data being available. ReleaseConfigurationHandle is merely a hint allowing the server to optimize its internal resource management. For timeout usage, see the description in Section 7.2.2.2.

Signature

ReleaseConfigurationHandle ([in]	Handle	configurationHandle[out]	Int32		error);

Table 18 – ReleaseConfigurationHandle Method Arguments

Argument Description
configurationHandle Handle returned by GetConfigurationById or GetConfigurationList, identifying the configuration set/client combination.
error 0 – OK
Values > 0 are reserved for errors defined by this and future standards.
Values < 0 shall be used for application-specific errors.

Table 19 – ReleaseConfigurationHandle Method AddressSpace Definition

Attribute Value
BrowseName ReleaseConfigurationHandle
References NodeClass BrowseName DataType TypeDefinition ModellingRule
HasProperty Variable InputArguments Argument[] PropertyType Mandatory
HasProperty Variable OutputArguments Argument[] PropertyType Mandatory

7.2.2.5 RemoveConfiguration ToC

This method is used to remove a configuration from the configuration management of the vision system.

Application Note:

It may be required from a vision system – e.g. in pharmaceutical or other safety-critical applications – to keep a record of the prior existence of a removed configuration. This may be important in such systems for the meta information of results that were generated while the removed configuration was active. It serves to keep it comprehensible which configurations were available on the vision system

Signature

RemoveConfiguration ([in]	ConfigurationIdDataType	internalId[out]	Int32	error);

Table 20 – RemoveConfiguration Method Arguments

Argument Description
internalId Identification of the configuration used by the vision system. This argument must not be empty.
error 0 – OK
Values > 0 are reserved for errors defined by this and future standards.
Values < 0 shall be used for application-specific errors.

Table 21 – RemoveConfiguration Method AddressSpace Definition

Attribute Value
BrowseName RemoveConfiguration
References NodeClass BrowseName DataType TypeDefinition ModellingRule
HasProperty Variable InputArguments Argument[] PropertyType Mandatory
HasProperty Variable OutputArguments Argument[] PropertyType Mandatory

7.2.2.6 ActivateConfiguration ToC

This method is used to activate a configuration from the configuration management of the vision system.

Since only a single configuration can be active at any time, this method shall deactivate any other configuration which may currently be active. From that point on until the next call to this method the vision system will conduct its operation according to the settings of the activated configuration.

Note that there is no way to deactivate a configuration except by activating another one to avoid having no active configuration on the system.

Signature

ActivateConfiguration ([in]	ConfigurationIdDataType	internalId[out]	Int32	error);

Table 22 – ActivateConfiguration Method Arguments

Argument Description
internalId Identification of the configuration used by the vision system. This argument must not be empty.
error 0 – OK
Values > 0 are reserved for errors defined by this and future standards.
Values < 0 shall be used for application-specific errors.

Table 23 – ActivateConfiguration Method AddressSpace Definition

Attribute Value
BrowseName ActivateConfiguration
References NodeClass BrowseName DataType TypeDefinition ModellingRule
HasProperty Variable InputArguments Argument[] PropertyType Mandatory
HasProperty Variable OutputArguments Argument[] PropertyType Mandatory

Previous Next