Class AdvSync

Nested Relationships

Nested Types

Class Documentation

class AdvSync

This class contains advanced sync functions.

Public Functions

inline AdvSync(AdvancedMotion *f)
bool IsDeviceValid()
WMX3APIFUNC StartECAM(int channel, ECAMData *pECAMData)

Start E-CAM control.

Start E-CAM control.

E-CAM control is a type of master-slave control in which the position command of a slave axis is controlled by the position of a master axis in a non-linear manner. The correlation between the position of the master axis and the position command of the slave axis is defined using an E-CAM table.

Remark

The master axis, slave axis, E-CAM table, and additional options are passed to this function using the pECAMData argument.

The E-CAM table may contain at least 2 and up to maxEcamPoints points of data.

The master axis positions must be specified in ascending order. If they are not specified in ascending order, an error will be returned.

This function both sets the E-CAM data and starts E-CAM control. If the ECAMClutchType is set to None, the slave axis may suddenly move if it is not already at the position initially commanded by E-CAM control. To avoid this, use the SimpleCatchUp clutch type or verify that this function is called while the slave axis is at the correct position.

E-CAM control is immediately started when this function is called.

The slave axis must be in Idle operation state when starting E-CAM control. The master axis may be in any state.

Each E-CAM channel supports one slave axis. Multiple E-CAM channels may have the same master axis.

Each E-CAM channel can only control one slave axis at any time. To start a different E-CAM control, the channel must first be stopped with the StopECAM function.

See also

E-CAM

Parameters:

  • channel – [in] The channel of E-CAM control. Each channel corresponds to a single slave axis. Up to maxEcamChannel channels may be operated at any time.

  • pECAMData – [in] A pointer to an ECAMData class object that specifies the E-CAM control parameters.

WMX3APIFUNC GetECAM(int channel, ECAMData *pECAMData)

Get E-CAM control parameters.

Get E-CAM control parameters.

This function obtains the currently set E-CAM control parameters for an E-CAM channel that was started with the StartECAM API function. This function will return an error if the specified E-CAM channel is not currently controlling a slave axis.

Remark

Parameters:

  • channel – [in] The channel of E-CAM control. Each channel corresponds to a single slave axis. Up to maxEcamChannel channels may be operated at any time.

  • pECAMData – [out] A pointer to an ECAMData class object that will contain the E-CAM control parameters.

WMX3APIFUNC StopECAM(int channel)

Stop E-CAM control.

Stop E-CAM control.

This function stops E-CAM control for a channel. The E-CAM channel is specified, and not the slave axis number. If the E-CAM channel is not enabled and controlling an axis, an error will be returned.

Remark

This function is used to stop E-CAM control that was started with either the StartECAM API function.

Parameters:

channel – [in] The channel of E-CAM control. Each channel corresponds to a single slave axis. Up to maxEcamChannel channels may be operated at any time.

WMX3APIFUNC StartDancerControl(int axis, DancerControlOptions *pDancerControlOptions)

Start dancer control.

Start dancer control.

Dancer control is a function to control a velocity mode axis using a PID loop with the input taken from a segment of the I/O. The velocity command of the axis is set according to the following equation:

Remark

Velocity Command = P(t) * P_Gain + I(t) * I_Gain + D(t) * D_Gain

P(t) = (input - input_zero) / (input_max - input_min)

I(t) = sum of P(T) from T = t-n to T = t

D(t) = (1/m) * sum of P(T) - P(T-1) from T = t to T = t-m

= (1/m) * (P(t) - P(t-m))

P_Gain, I_Gain, and D_Gain are specified by the dancer control option settings. These should be adjusted to tune the dancer control to achieve the desired response for the machine.

input is the current input, taken from a segment of the I/O. The address and size of the I/O segment are specified by the dancer control option settings.

input_zero is the input at which P(t) equals zero. This is the input that the dancer control should settle to.

input_min and input_max specify the expected range of inputs. If set correctly, the range of P(t) will have a span of 1. Depending on the value of input_zero, the range may be from 0 to 1, from -1 to 0, from -0.5 to 0.5, etc. If the input falls below input_min or exceeds input_max, P(t) will exceed this range.

m is the derivative sample size specified by the dancer control settings. If set to 0, the derivative sample size will be 1.

n is the number of time cycles to take the integral over, as specified by the dancer control settings. If set to 0, the integral will be taken over the entire time that the dancer control is in operation, after starting dancer control.

If the above options are configured correctly, the dancer control will settle to the state where the input is equal to input_zero, with the desired response characteristics.

Dancer control may only be executed while the axis is in Velocity mode.

Dancer control may only be executed while the axis is in Idle or DancerControl operation state.

Parameters:

  • axis – [in] The axis to execute dancer control.

  • pDancerControlOptions – [in] A pointer to a DancerControlOptions object that contains the options for dancer control.

WMX3APIFUNC StopDancerControl(int axis)

Stop dancer control.

Stop dancer control.

This function stops an axis executing dancer control. The axis will decelerate to a stop using the quick stop deceleration specified with Quick Stop Dec.

Remark

Parameters:

axis – [in] The axis to stop dancer control.

WMX3APIFUNC GetDancerControlStatus(int axis, DancerControlStatus *pDancerControlStatus)

Get the dancer control status.

Get the dancer control status.

This function obtains the dancer control status of an axis executing dancer control. See DancerControlStatus for additional information regarding each status.

Remark

Parameters:

  • axis – [in] The axis to get the dancer control status of.

  • pDancerControlStatus – [out] A pointer to a DancerControlStatus object that will contain the dancer control status for the specified axis.

Public Members

AdvancedMotion *amApi
class DancerControlOptions

This class contains options for dancer control.

Public Functions

DancerControlOptions()

Public Members

double proportionalGain

The proportional gain to multiply P(t) by.

double integralGain

The integral gain to multiply I(t) by.

double derivativeGain

The derivative gain to multiply D(t) by.

double gainFactor

A gain factor to multiply P(t), I(t), and D(t) by. This has the same effect as multiplying proportionalGain, integralGain, and derivativeGain by this factor. This parameter may be convenient when all gains should be increased or decreased by the same factor.

int derivativeSamples

The number of derivative samples to take. When calculating D(t), the derivative over the past derivativeSamples cycles is averaged. The maximum allowed value is 8. If set to 0, derivativeSamples is considered to be 1.

int integralTimeCycles

The number of cycles to calculate the integral over. When calculating I(t), the integral over the past integralTimeCycles cycles is taken. The maximum allowed value is 1024. If set to 0, integralTimeCycles is considered to be infinity, and the integral will be taken from the time that dancer control was started to the current time.

double maxIntegral

The maximum absolute value for I(t). If this is set to a positive value, if the absolute value of I(t) would exceed this value, the measured integral for that cycle is reduced so that the absolute value of I(t) would equal this value. If this is set to zero or a negative value, there is no maximum value for I(t).

unsigned int inputByteAddress

The byte address of the I/O segment to use as the input.

unsigned int inputSize

The byte size of the I/O segment to use as the input.

double inputZero

The value of the input at which P(t) should equal zero. When the gains are configured appropriately, the PID loop will settle to this input value.

double inputMax

The expected maximum value of the input. P(t) at inputMax minus P(t) at inputMin will equal 1.

double inputMin

The expected minimum value of the input. P(t) at inputMax minus P(t) at inputMin will equal 1.

unsigned char useOutput

If set to 0, the I/O segment is read from the I/O input space. If set to 1, the I/O segment is read from the I/O output space.

double zeroClampMinInput

The minimum value of the input below which the velocity command will be forcefully set to 0. Both the zeroClampMinInput and zeroClampMinVel must be satisfied for the velocity command to be clamped to zero.

double zeroClampMinVel

The minimum value of the calculated velocity command from the PID loop below which the velocity command will be forcefully set to 0. Both the zeroClampMinInput and zeroClampMinVel must be satisfied for the velocity command to be clamped to zero.

class DancerControlStatus

This class contains the status for dancer control.

Public Functions

DancerControlStatus()

Public Members

double P

The value of P(t) for the current cycle.

double I

The value of I(t) for the current cycle.

double D

The value of D(t) for the current cycle.

double inputValue

The value of the input for the current cycle.

int iSamples

The number of integral samples collected. If the time to calculate the integral from is infinite, then this value will be 0.

int dSamples

The number of derivative samples collected.

class ECAMClutchOptions

This class contains E-CAM clutch options. The E-CAM clutch determines how the slave axis synchronizes with the master axis when E-CAM is started.

Public Functions

ECAMClutchOptions()

Public Members

ECAMClutchType::T type

The type of E-CAM clutch to use.

double simpleCatchUpVelocity

The velocity to use to catch up to the E-CAM table master-slave curve. This value is only used for the SimpleCatchUp E-CAM clutch type.

double simpleCatchUpAcc

The acceleration and deceleration to use to catch up to the E-CAM table master-slave curve. This value is only used for the SimpleCatchUp E-CAM clutch type.

class ECAMClutchType

This enumerator class enumerates the E-CAM clutch types.

Public Types

enum T

Values:

enumerator None

Immediately synchronize with the master axis. This may cause the slave axis to suddenly move depending on the E-CAM table, the master axis position, and the slave axis position when E-CAM is started.

enumerator SimpleCatchUp

Catch up with the E-CAM table master-slave curve using a trapezoidal profile. The error between the slave axis command as calculated from the E-CAM table and the actual slave axis command is gradually reduced using a trapezoidal profile. This prevents the slave axis from suddenly moving depending on the E-CAM table, the master axis position, and the slave axis position when E-CAM is started.

class ECAMData

This class contains all settings for E-CAM control, including E-CAM table data.

Public Functions

ECAMData()

Public Members

int slaveAxis

The slave axis to control.

int masterAxis

The master axis to calculate the slave axis position commands from.

unsigned int numPoints

The number of points in the E-CAM table. This value must be at least 2 and at most maxEcamPoints.

ECAMOptions options

Additional options for E-CAM control.

double slavePos[constants::maxEcamPoints]

An array containing the slave positions of the E-CAM table. The first numPoints indices are read.

double masterPos[constants::maxEcamPoints]

An array containing the master positions of the E-CAM table. The first numPoints indices are read. An error will be returned if the master axis positions are not specified in ascending order.

class ECAMOptions

This class contains E-CAM options, including the E-CAM clutch options.

Public Functions

ECAMOptions()

Public Members

ECAMType::T type

The type of E-CAM to use.

ECAMSourceOptions source

The E-CAM source options to use. The source options determine the source of the master input that is used to calculate the slave command position from the E-CAM table.

ECAMClutchOptions clutch

The E-CAM clutch options to use. The clutch options determine how the slave axis initially synchronizes with the master axis when E-CAM control is started.

class ECAMSourceOptions

This class contains E-CAM source options. This determines the source of the master input that is used to calculate the slave command position from the E-CAM table.

Public Functions

ECAMSourceOptions()

Public Members

ECAMSourceType::T type

The type of E-CAM source to use.

unsigned int encoderByteAddress

The byte address of the I/O input segment to use for the master input. This parameter is only applicable for the EncoderInput source type.

unsigned int encoderSize

The size of the I/O input segment to use for the master input, in units of bytes. This parameter must be 1, 2, 3, or 4. This parameter is only applicable for the EncoderInput source type.

class ECAMSourceType

This enumerator class enumerates the sources of the E-CAM master input.

Public Types

enum T

Values:

enumerator MasterCommandPos

The master input is the command position of the master axis.

enumerator MasterFeedbackPos

The master input is the feedback position of the master axis.

enumerator EncoderInput

The master input is a segment of the I/O input. The address and size of the I/O input are set with the encoderByteAddress and encoderSize parameters. When this type is selected, the masterAxis value is ignored. When this type is selected, the E-CAM type is usually set to Repeat so that the slave axis does not move suddenly when the master axis wraps around the encoder range.

class ECAMType

This enumerator class enumerates the types of E-CAM, which determine certain characteristics of E-CAM. Also see E-CAM.

Public Types

enum T

Values:

enumerator Normal

Operate E-CAM using the standard mode.

enumerator Periodic

The master-slave position curve will be repeated when the master axis moves outside the range defined in the E-CAM table.

enumerator Repeat

The master-slave position curve will be repeated while preserving the slave axis position when the master axis moves outside or wraps around the range defined in the E-CAM table.