This method is used to prepare a recipe so that it can be used for starting a job on the vision system.

Signature

PrepareRecipe ([in]RecipeIdExternalDataTypeexternalId[in]RecipeIdInternalDataTypeinternalIdIn[out]RecipeIdInternalDataTypeinternalIdOut[out]BooleanisCompleted[out]Int32error);

Table 33 – PrepareRecipe Method Arguments

Argument

Description

externalId

Identification of the recipe used by the environment which is to be prepared.

internalIdIn

Internal identification of the recipe which is to be prepared.

The client can use either the externalId or the internalIdIn, leaving the other empty. If both are given, the InternalIdIn takes precedence.

internalIdOut

Internal identification of the recipe selected based on the given externalId or internalId.

isCompleted

Flag to indicate that the recipe has been completely prepared before the method returned.

If False, the client needs either to check the properties of the recipe to determine when preparation has completed or wait for the RecipePrepared event.

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 34 – PrepareRecipe Method AddressSpace Definition

Attribute

Value

BrowseName

PrepareRecipe

References

Node Class

BrowseName

DataType

TypeDefinition

ModellingRule

HasProperty

Variable

InputArguments

Argument[]

PropertyType

Mandatory

HasProperty

Variable

OutputArguments

Argument[]

PropertyType

Mandatory

If the vision system is in state Initialized, it is expected to change into state Ready after successful preparation of the recipe and be able to execute jobs called by a Start method with the given ExternalId.

If the vision system is already in state Ready when PrepareRecipe is called, it is expected to be in state Ready again after successful preparation of the recipe and be able to execute jobs called by a Start method with the given ExternalId. Depending on the capabilities of the vision system, it may temporarily leave state Ready for state Initialized, then return to Ready, or, if the system is capable of preparing recipes in the background, it may stay in state Ready and react instantaneously to Start jobs for other, already prepared, recipes. Also depending on the capabilities of the vision system, preparing an additional recipe may unprepare others if the number of recipes being prepared at the same time is limited.

The preparation of a recipe may be a time-consuming operation. The client cannot necessarily assume that the recipe is completely prepared when the method returns. The client should therefore check the preparedness of the recipe after a reasonable amount of time or wait for a RecipePrepared event with the correct ExternalId to be fired. During the time required for preparing a recipe, the system may or may not be capable of reacting to a start method. However, the server is free to handle PrepareRecipe as a synchronous method, returning only after the recipe is completely prepared unless an error has occurred.

Not that the local editing of an already prepared recipe, as described in Sections 7.5.2.1.5 and B.1.2.3 is considered to be the same as the preparation of a new recipe, because after local editing, the already prepared recipe is different from before, so effectively a new recipe has been prepared by the local editing. Therefore, a new RecipePrepared event shall be generated (see also Section 8.3.8.1).

Some recipes may exclude each other from being in prepared state at the same time, for example, when there are mechanical movements involved. Having two such recipes prepared at the same time would mean that an instantaneous reaction to calling the Start method for a prepared recipe would not be possible. However, this is at the discretion of the vision system. The client may merely notice an unusually long reaction time between calling the Start method and the actual state change, or the vision system may prevent the simultaneous preparation by returning an error.

If there is more than one recipe with the identical ExternalId – e.g. due to local copying and modifying of recipes on the vision system – it is implementation-defined how this ambiguity will be handled. The vision system will prepare only a single one of these recipes, which may be the latest one or the latest externally defined one.