Class Sync

Defined in File CoreMotionApi.h

Nested Relationships

Nested Types

Class Documentation

class Sync

This class contains sync functions.

Public Functions

inline Sync(CoreMotion *f)

bool IsDeviceValid()

WMX3APIFUNC SetSyncMasterSlave(int masterAxis, int slaveAxis, SyncOptions *pSyncOptions = NULL)

Establish synchronous control between a master axis and a slave axis.

This function starts sync control between a master axis and a slave axis. The command position of the slave axis at the time that this function is executed becomes synchronized to the command position of the master axis at the time that this function is executed. Any subsequent changes to the master axis command position will also be added to the slave axis command position.

Remark

A slave axis will follow the movements of the master axis.

When this function returns, sync control is already established. The master axis can be moved immediately.

The master and slave axes must not be in motion (must be in Idle operation state) when this function is called. To start synchronization with a master axis that is in motion, use the SetSyncGearRatio function (with a gear ratio of 1) instead.

The slave axis servo must be in Servo On state when this function is executed. The master axis servo may be on or off.

The slave axis must not be a sync master of any other axis.

The Master Desync Type and Slave Desync Type parameters can be set to automatically stop or turn off the axis servo when synchronization is broken.

The Single Turn Mode parameter must be set to the same value for the master and slave axes (this parameter must be enabled or disabled for both axes). If the Single Turn Mode parameter is set to enabled, then the master and slave axes must have the same Single Turn Encoder Count.

When the slave servo turns off (Servo On becomes FALSE), synchronous control is resolved for that slave axis. This function must be called again to reestablish synchronous control for that axis.

See also

Synchronization

Parameters:

masterAxis – [in] The master axis.
slaveAxis – [in] The slave axis.
pSyncOptions – [in] An optional argument that is used to specify additional options for the sync control.

WMX3APIFUNC SetSyncCombine(int masterAxis1, int masterAxis2, int slaveAxis, SyncCombineOptions *pSyncCombineOptions = NULL)

Combine the position commands of two master axes and set it as the position command of a slave axis.

Combine sync is a special type of sync control in which two master axes control a slave axis. The cyclic position command of the slave axis will be set equal to the sum of the cyclic position commands of the two master axes.

Remark

Upon initiating combine sync control, a single offset to the slave axis will be calculated so that the current position command of the slave axis equals the sum of the position commands of the two master axes.

When this function returns, sync control is already established. The master axes can be moved immediately.

Both master axes and the slave axis must not be in motion (must be in Idle operation state) when this function is called.

The slave axis servo must be in Servo On state when this function is executed. The master axis servos may be on or off.

The slave axis must not be a sync master of any other axis.

The Master Desync Type and Slave Desync Type parameters can be set to automatically stop or turn off the axis servo when synchronization is broken.

Single turn mode is not supported in combine sync control. An error will be returned when attempting to start combine sync control for axes in single turn mode.

The VelocityOffset and SymmetricVelocityOffset sync offset compensation modes are not supported when operating combine sync control.

Homing is not supported in combine sync control. Attempting to start homing for combine sync axes will cause the homing function to return an error.

The ResolveSync function can be used resolve combine sync control and regular sync control.

Slave axes which are controlled with combine sync will have an operation state of Sync in the Op State status returned by the GetStatus function. The axis numbers of the two master axes can be found in the Master Axis and Second Master Axis statuses returned by the GetStatus function.

When the slave servo turns off (Servo On becomes FALSE), synchronous control is resolved for that slave axis. This function must be called again to reestablish synchronous control for that axis.

See also

Combine Sync

Parameters:

masterAxis1 – [in] The first master axis.
masterAxis2 – [in] The second master axis.
slaveAxis – [in] The slave axis.
pSyncCombineOptions – [in] An optional argument that is used to specify additional options for the sync control.

WMX3APIFUNC SetAbsoluteSyncPhase(int slaveAxis, double phase, Profile *pProfile)

Set the absolute sync phase of a slave axis.

This function sets the absolute sync phase of a slave axis. The sync phase is an additional offset that is applied to the sync slave axis but not the master axis.

Remark

The sync phase is 0 when sync control is started.

The slave will shift from the master axis by the sync phase amount using the specified profile. The time taken for the slave to completely shift by the sync phase amount will depend on the specified profile type, velocity, acceleration, etc.

The sync phase may be changed while the master and slave axes are in motion.

The sync phase may not be changed while the axis has still only partially applied a previous sync phase shift or a sync gear shift. Whether a sync axis is currently in the middle of applying a sync phase shift or sync gear shift can be checked with the Detail Op State status. An axis executing phase shift will be in the Sync_PhaseShift state and an axis executing gear shift will be in the Sync_GearShift state.

The currently applied sync phase can be obtained by checking the Sync Phase Offset status. An absolute phase that is greater than the currently applied sync phase will cause the slave to shift in the positive direction. An absolute phase that is less than the currently applied sync phase will cause the slave to shift in the negative direction.

See also

Sync Phase Offset

Parameters:

slaveAxis – [in] The slave axis to apply the sync phase.
phase – [in] The absolute sync phase to apply.
pProfile – [in] A pointer to a Profile class object that contains the profile to use when applying the phase.

WMX3APIFUNC AddRelativeSyncPhase(int slaveAxis, double phase, Profile *pProfile)

Add a relative sync phase to a slave axis.

This function adds a relative sync phase to a slave axis. The sync phase is an additional offset that is applied to the sync slave axis but not the master axis.

Remark

The sync phase is 0 when sync control is started.

The slave will shift from the master axis by the sync phase amount using the specified profile. The time taken for the slave to completely shift by the sync phase amount will depend on the specified profile type, velocity, acceleration, etc.

The sync phase may be changed while the master and slave axes are in motion.

The sync phase may not be changed while the axis has still only partially applied a previous sync phase shift or a sync gear shift. Whether a sync axis is currently in the middle of applying a sync phase shift or sync gear shift can be checked with the Detail Op State status. An axis executing phase shift will be in the Sync_PhaseShift state and an axis executing gear shift will be in the Sync_GearShift state.

The currently applied sync phase can be obtained by checking the Sync Phase Offset status. A positive relative sync phase will cause the slave to shift in the positive direction. A negative relative sync phase will cause the slave to shift in the negative direction.

See also

Sync Phase Offset

Parameters:

slaveAxis – [in] The slave axis to apply the sync phase.
phase – [in] The relative sync phase to apply.
pProfile – [in] A pointer to a Profile class object that contains the profile to use when applying the phase.

WMX3APIFUNC SetSyncGearRatio(int slaveAxis, double gearRatio, Profile *pProfile)

Set the sync gear ratio between a sync slave axis and the master axis.

The sync gear ratio is the ratio between the slave axis position command and the master axis position command. The amount that the master axis moves during one cycle is multiplied by the sync gear ratio to calculate the amount that the slave axis moves during that cycle.

Remark

The sync gear ratio can be any value between 0.000001 and 2147483647, or any value between -0.000001 and -2147483647. A negative sync gear ratio will cause the slave axis to move in the opposite direction as the master axis.

A sync gear ratio with magnitude greater than 1 causes the slave axis to move at a greater velocity (in terms of user units of the slave axis) than the master axis. A sync gear ratio with magnitude less than 1 causes the slave axis to move at a smaller velocity (in terms of user units of the slave axis) than the master axis.

The sync gear ratio may be changed while the master and slave axes are in motion.

If the sync gear ratio is changed while the master and slave axes are in motion, the new sync gear ratio is not applied immediately to prevent the slave axis velocity from suddenly changing. The slave axis will shift from the current velocity to the velocity that would be commanded by the new gear ratio using the specified profile parameters (profile type, velocity, acceleration, etc.). The slave axis will follow any changes to the master axis velocity during the catch up motion, but the total time taken for the catch up motion to complete will not be affected by changes in the master axis velocity.

The sync gear ratio may not be changed while the axis has still only partially applied a previous sync phase shift or a sync gear shift. Whether a sync axis is currently in the middle of applying a sync phase shift or sync gear shift can be checked with the Detail Op State status. An axis executing phase shift will be in the Sync_PhaseShift state and an axis executing gear shift will be in the Sync_GearShift state.

This function causes the sync offset between the slave and master positions to change based on the gear ratio and the position and velocity of the master axis at the time that this function is called. A phase shift operation such as SetAbsoluteSyncPhase may be necessary after this operation completes.

Example:

The master and slave axes are moving at a rate of 10000 pulses per second when this function is called with a sync gear ratio of 2. The new slave axis velocity is 20000 pulses per second, but the slave axis does not instantly change to this velocity. Instead, the slave axis gradually ramps to to this velocity using the profile parameters passed to this function. If the master axis velocity changes to 30000 pulses per second while the slave axis is shifting to the new gear ratio, the slave axis will ramp up to 60000 pulses per second, but the total time taken to shift the gear ratio remains the same.

If the master and slave axes are not in motion when this function is executed, the slave will instantly shift to the new gear ratio.

The currently applied sync gear ratio can be obtained by checking the Sync Gear Ratio status.

The sync gear ratio operates independently from the Gear Ratio Numerator and Gear Ratio Denominator parameters.

See also

Sync Gear Ratio

Parameters:

slaveAxis – [in] The slave axis to apply the sync gear ratio.
gearRatio – [in] The sync gear ratio to apply.
pProfile – [in] A pointer to a Profile class object that contains the profile to use when applying the sync gear ratio.

WMX3APIFUNC SetSyncGearRatio(int masterAxis, int slaveAxis, double gearRatio, Profile *pProfile)

Establish sync control between two axes, and set the sync gear ratio between a sync slave axis and the master axis.

This function is similar to SetSyncGearRatio, but this function will also establish sync control between the specified master and slave axes if they are not synchornized already.

Remark

When this function establishes sync control, the command position of the slave axis at the time that this function is called becomes synchronized to the command position of the master axis at the time that this function is called.

When this function establishes sync control, the master axis can be moved immediately after this function returns.

Unlike many other sync functions, this function is also able to establish sync control while the master and slave axes are not in Idle state. The slave axis will catch up to the master axis velocity using the profile parameters passed to this function. Sync control is established at the position that the slave axis velocity catches up the master axis velocity.

If the specified slave axis has already established sync control with the specified master axis, this function behaves the same as SetSyncGearRatio. If the specified slave axis is synchronized to a different master axis, an error will be returned.

See also

Sync Gear Ratio

Parameters:

masterAxis – [in] The master axis.
slaveAxis – [in] The slave axis to apply the sync gear ratio.
gearRatio – [in] The sync gear ratio to apply.
pProfile – [in] A pointer to a Profile class object that contains the profile to use when applying the sync gear ratio.

WMX3APIFUNC SyncToJog(int slaveAxis, Profile *pProfile)

Resolve sync control for a slave axis, and immediately start a jog command for the slave axis.

This function resolves sync control for a slave axis, and immediately starts a jog command for the slave axis. If the slave axis was in motion when this function is called, the initial velocity of the jog command will be the velocity of the slave axis when this function is called (unless a non-zero startingVelocity is specified in the profile argument of this function, in which case that starting velocity will take precedence).

Remark

Parameters:

slaveAxis – [in] The slave axis to resolve sync.
pProfile – [in] A pointer to a Profile class object that contains the profile parameters for the jog command.

WMX3APIFUNC SyncToJog(int slaveAxis)

Resolve sync control for a slave axis, and immediately start a jog command for the slave axis with the velocity equal to the velocity that the slave axis was moving at.

This function resolves sync control for a slave axis, and immediately starts a jog command for the slave axis. The velocity of the jog command will equal the velocity of the slave axis when this function is called.

Remark

Because the deceleration is not specified for the jog command, attempting to stop the jog command using the Stop function will cause the default deceleration (10000 user units per second) to be used. For most applications, the default deceleration is not suitable, so the Stop function with a deceleration argument should be used instead.

Parameters:: slaveAxis – [in] The slave axis to resolve sync.

WMX3APIFUNC ResolveSync(int slaveAxis)

Release the specified slave axis from synchronous control.

Parameters:: slaveAxis – [in] The slave axis to release synchronous control.

WMX3APIFUNC SetSyncGroup(int groupId, SyncGroup syncGroup)

Set the axes and parameters of a synchronization group.

This function sets the settings of a sync group. The maximum number of sync groups that can be defined at once is equal to maxSyncGroup.

Remark

A sync group consists of one sync master axis and any number of slave axes. The sync group tracks the home done status of the sync group and any errors encountered during the sync operation. These statuses can be checked using the GetSyncGroupStatus function.

A sync group must first be enabled using the EnableSyncGroup function before it has any effect. Once enabled, a sync group will automatically start sync control for the defined slave axes while they are in servo on (Servo On is TRUE) state.

If this function is called to redefine a sync group that is currently enabled, the sync group will return to disabled state and must be enabled again using the EnableSyncGroup function.

There are several sync group functions that cannot be replicated with normal sync control. For example, sync groups can be configured to turn all sync axis servos on or off together with the servoOnOffSynchronization option. Using the CatchUp startup type, sync groups are able to execute catch up motion to restore the previous sync offset after sync is broken.

See also

Sync Group

Parameters:

groupId – [in] The sync group ID. This value must be between 0 and maxSyncGroup - 1.
syncGroup – [in] A pointer to a SyncGroup class object that specifies the sync group parameters.

WMX3APIFUNC GetSyncGroup(int groupId, SyncGroup *pSyncGroup)

Get the axes and parameters of a sync group.

This function gets the settings of a particular sync group. To get for the statuses of the sync group, including whether the sync group is enabled, use the GetSyncGroupStatus function.

Remark

Parameters:

groupId – [in] The sync group ID. This value must be between 0 and maxSyncGroup - 1.
pSyncGroup – [out] A pointer to a SyncGroup class object that specifies the sync group parameters.

WMX3APIFUNC AddAxisToSyncGroup(int groupId, int axis, unsigned char isMaster)

Add another axis to an existing sync group.

This function adds an axis to a sync group. A slave axis or a master axis can be added, depending on the value of the isMaster argument.

Remark

Adding a master axis will remove any existing master axis from the sync group. A sync group may only have one master axis at any time.

If a master axis is added, but the axis is already one of the slave axes in the sync group, the axis will become the master axis and no longer be a slave axis.

If a slave axis is added, but the axis is already the master axis of the sync group, the axis will become a slave axis and the sync group will have no master axis (until a new master axis is added).

Calling this function on a sync group that is currently enabled will disable it. The sync group must be enabled again using the EnableSyncGroup function.

Parameters:

groupId – [in] The sync group ID. This value must be between 0 and maxSyncGroup - 1.
axis – [in] The axis to add to the sync group.
isMaster – [in] 0: The axis is a slave axis; 1: The axis is a master axis.

WMX3APIFUNC RemoveAxisFromSyncGroup(int groupId, int axis)

Remove an axis from an existing sync group.

This function removes an axis from the sync group.

Remark

Calling this function on a sync group that is currently enabled will disable it. The sync group must be enabled again using the EnableSyncGroup function.

Parameters:

groupId – [in] The sync group ID. This value must be between 0 and maxSyncGroup - 1.
axis – [in] The axis to remove from the sync group.

WMX3APIFUNC EnableSyncGroup(int groupId, unsigned char enable)

Enable or disable a sync group.

This functions enables or disables a sync group. A sync group must be enabled before it has any effect.

Remark

Parameters:

groupId – [in] The sync group ID. This value must be between 0 and maxSyncGroup - 1.
enable – [in] 0: Disable the sync group; 1: Enable the sync group.

WMX3APIFUNC GetSyncGroupStatus(int groupId, SyncGroupStatus *pStatus)

Read the current status of the specified sync group.

This function gets the current status of a sync group.

Remark

Parameters:

groupId – [in] The sync group ID. This value must be between 0 and maxSyncGroup - 1.
pStatus – [out] A pointer to an object of the class SyncGroupStatus that contains the sync group status.

WMX3APIFUNC ClearSyncGroupError(int groupId)

Clear all sync group errors of the specified sync group.

This function clears the catchUpError, syncError, axisError, and interruptError errors of the specified sync group to 0.

Remark

Parameters:: groupId – [in] The sync group ID. This value must be between 0 and maxSyncGroup - 1.

Public Members

CoreMotion *cmApi

class SyncCombineOptions

This class contains options for combine sync control.

Public Functions

SyncCombineOptions()

Public Members

bool useMaster1Feedback: If TRUE, the command position of the slave axis is calculated from the feedback position of the first master axis. If FALSE, the command position of the slave axis is calculated from the command position of the first master axis. Normally, this value is set to FALSE.

bool useMaster2Feedback: If TRUE, the command position of the slave axis is calculated from the feedback position of the second master axis. If FALSE, the command position of the slave axis is calculated from the command position of the second master axis. Normally, this value is set to FALSE.

class SyncGroup

This class contains settings for a sync group.

Public Functions

SyncGroup()

Public Members

int masterAxis: The master axis.

int slaveAxisCount: The number of slave axes in this sync group.

int slaveAxis[constants::maxAxes - 1]: The slave axis.

unsigned char servoOnOffSynchronization: When this parameter is set to 1, if any of the sync axes (master or slave) enters servo off state for any reason (such as user input or amp alarm), the remaining axes in the sync group are sent a servo off signal. Similarly, if any of the sync axes receives a servo on signal, the remaining axes in the sync group are sent a servo on signal. When this parameter is set to 0, the servo on/off signals of the sync axes are handled individually by each axis.

SyncGroupStartupType::T startupType: The startup type of the sync group.

unsigned int gantryLoopCycleRatio: The ratio of cycles to update the velocity offset (used for sync compensation calculations) and the total cycles. If set to 0 or 1, the velocity offset is updated every communication cycle. If set to a value larger than 1, the velocity offset if only updated once that many communication cycles.

double maxCatchUpDistance: The maximum distance at which a catch up motion is executed when reestablishing sync control. If the difference between the master and slave axis command positions exceeds this distance, a sync error will be generated (the sync error can be checked in syncError returned by GetSyncGroupStatus). This parameter only applies if startupType is set to CatchUp.

double catchUpVelocity: The velocity to use during the sync catch up motion when reestablishing sync control. This parameter is only applicable when the startupType is CatchUp.

double catchUpAcc: The acceleration to use during the sync catch up motion when reestablishing sync control. This parameter is only applicable when the startupType is CatchUp.

double syncErrorTolerance: The maximum difference between the master and slave axis feedback positions that can be tolerated. If the difference between the master axis feedback position and the slave axis feedback position (for 0 sync offset case) exceeds this value, a sync error will be generated. This parameter is disabled and no sync error is generated when set to 0. This error will be detected only if the sync group has completed homing (the sync group homeDone status is 1) and the master axis is in servo on state.

unsigned char useMasterFeedback: If set to 1, the command position of the slave axis is calculated from the feedback position of the master axis. If set to 0, the command position of the slave axis is calculated from the command position of the master axis. Normally, this value is set to 0.

class SyncGroupStartupType

This enumerator class enumerates startup types for a sync group.

Public Types

enum T

Values:

enumerator Normal: When the sync group is enabled, sync control will be started immediately. The master and slave axes will be synchronized based on their current command positions. For proper synchronization, gantry homing must be executed again.

enumerator CatchUp: The slave axis will catch up to the master axis position when reestablishing sync control. The catch up motion only occurs after homing has been completed for the sync group while sync control is established. When the sync control is broken (for example, because one of the axis servos turned off) and subsequently restored, a catch up motion will occur to preserve the offset between the master and slave axes. For other sync startup types, reestablishing sync control will reset the offset between the master and slave axes. This startup type will always generate a catchUpError error if the master or slave axis is a single turn axis, as the maxCatchUpDistance cannot be calculated.

class SyncGroupStatus

This class contains the current status of a sync group channel.

Public Functions

SyncGroupStatus()

Public Members

unsigned char enabled: 0: Sync group control is disabled, 1: Sync group control is enabled.

unsigned char homeDone: 0: Sync group has not finished homing, 1: Sync group has finished homing.

unsigned char catchUpError: 0: Sync group has not encountered a catch up error, 1: Sync group has encountered a catch up error. A catch up error occurs during catch up motion when the difference between the command positions of the master and slave axes exceeds maxCatchUpDistance while the startupType is CatchUp and homing is complete.

unsigned char syncError: 0: Sync group has not encountered a sync error, 1: Sync group has encountered a sync error. A sync error occurs when the difference between the feedback positions of the master and slave axes exceeds syncErrorTolerance after homing is complete.

unsigned char axisError: 0: No sync group axis error is detected. 1: Sync group was enabled while one or more axes in the sync group is also in another enabled sync group.

unsigned char interruptError: 0: No sync group interrupt error is detected. 1: Sync group was enabled while containing axes from different interrupts (cyclic handlers).

class SyncOptions

This class contains options for sync control.

Public Functions

SyncOptions()

Public Members

bool useMasterFeedback: If TRUE, the command position of the slave axis is calculated from the feedback position of the master axis. If FALSE, the command position of the slave axis is calculated from the command position of the master axis. Normally, this value is set to FALSE.