CreateTargetOnEntity (Method)

Overview

Type:	Method
Available as of:	V1.1.0.0

Task

Creating a target on an entity.

Description

The method CreateTargetOnEntity creates a target on the specified entity.

Ensure that the following prerequisites are fulfilled:

The inputs i_udiTargetId and i_udiEntityId are valid.
If i_udiEntityId refers to a conveyor, then also provide a valid reference position i_lrReferencePosition.

Define the entity ID within the ranges defined for the category of the mechatronic object with ET_EntityOffset. For a conveyor, for example, select an entity ID within the range of 300...399.
The cartesian pose (position and orientation) corresponds to the orientation convention ZYX. If the orientation convention is different, the event is not set.
The entity ID is set to 1 if a target is to be attached to a global pose. For this, you can use the enumeration element Global in the enumeration ET_SystemEntity in the SchneiderElectricRobotics Toolbox library.

The event is written to the internal events buffer and to the OPC UA structure by the method Update.

Interface

Input	Data type	Description
i_udiTargetId	UDINT	ID of the target to be created on the entity. The ID must be unique.
i_udiEntityId	UDINT	ID of the entity on which the target is to be created.
i_lrReferencePosition	LREAL	The reference position on the entity where the target is to be created. NOTE: This input is only needed when i_udiParentId is a conveyor.
i_stCartesianPose	GEM.ST_CartesianPose	The cartesian pose of the target.
i_etColorId	ET_EmulationColors	The color configured for the target. The default value is GPL.Gc_etDefaultTargetColor.

Output	Data type	Description
q_xError	BOOL	Indicates TRUE if an error has been detected. For details, refer to q_etResult and q_sResultMsg.
q_etResult	ET_Result	Provides diagnostic and status information as a numeric value. If q_xError = FALSE, q_etResult provides status information. If q_xError = TRUE, q_etResult provides diagnostic/error information.
q_sResultMsg	STRING [80]	Provides additional diagnostic and status information as a text message.

Diagnostic Messages

q_xError	q_etResult	Description
FALSE	Ok	The event was set.
TRUE	TargetIdInvalid	The event was not set. Cause: The input value of i_udiTargetId is invalid. Solution: Provide a valid target ID. The value must be greater than 0. Configure the target ID with the variable udiUnivocalId.
TRUE	TargetTypeInvalid	The event was not set. Cause: The input value of i_udiTargetType is invalid. Solution: Provide a valid target type. Configure the target type in the OPC UA structure with the variable GVL_OpcUaTargetTypes.G_stTargetTypes.
TRUE	EntityIdInvalid	The event was not set. Cause: The input value of i_udiEntityId is invalid. Solution: Provide a valid entity ID. The value must be greater than 0. Configure the entity ID with the variable udiUnivocalId.
TRUE	OrientationConventionInvalid	The event was not set. Cause: The input value of i_stCartesianPose.etOrientationConvention is invalid. Solution: Provide a valid value. Ensure that the orientation convention is ZYX, which corresponds to a right-hand coordinate system. For more information, refer to GEM.ET_OrientationConventionGEM.ET_OrientationConvention.
TRUE	ColorIdInvalid	The event was not set. Cause: The input value of i_etColorId is invalid. Solution: Provide a valid value. Select a value defined in ET_EmulationColors.
FALSE	BufferFull	The event was set. Cause: The internal events buffer is full and starts to overwrite prior events. Solution: Enlarge the internal events buffer by using the global parameter Gc_udiInternalEventsBufferSize and/or enlarge the event OPC UA structure by using the global parameter Gc_udiMaxNumberOfEventData.
FALSE	ReferencePositionIgnored	The event was set. Cause: The reference position lrReferencePosition was ignored because the entity is not a conveyor. Solution: Set the value of lrReferencePosition to 0.
FALSE	EntityInvalid	The event was set. Cause: The input value of i_udiEntityId does not match the predefined entity ranges. Solution: Provide an entity ID corresponding to the predefined ranges for the category of the mechatronic object. The value must be greater than 0. Configure the entity ID with the variable udiUnivocalId of ST_ConfigDataGeneric according to the entity ID ranges defined with ET_EntityOffset.