Class Compensation

Defined in File CompensationApi.h

Class Documentation

class Compensation

This class contains compensation functions.

Public Functions

Compensation(WMX3Api *f): Constructor to initialize an object of this class. The device created by the WMX3Api object passed to this constructor is used to execute API functions. Also see Devices.

Compensation(const Compensation &src): Copy constructor to initialize an object of this class based on an existing object of this class. Also see Copy Operators.

Compensation &operator=(const Compensation &src): Copy assignment operator to initialize an object of this class based on an existing object of this class. Also see Copy Operators.

Compensation(): Constructor to initialize an object of this class with a self device. Also see Self Devices.

~Compensation(): Destructor for this class.

bool IsDeviceValid()

Return TRUE if this class object has access to a device, and FALSE otherwise. A device is required to execute most functions in this class. If this function returns FALSE, a device can be created by calling the CreateDevice function from the WMX3Api object that was passed to the constructor of this class.

WMX3APIFUNC GetVersion(int *pMajorVersion, int *pMinorVersion, int *pRevisionVersion, int *pFixVersion)

Get the version of the module rtdll.

Parameters:

pMajorVersion – [out] The major version number.
pMinorVersion – [out] The minor version number.
pRevisionVersion – [out] The revision version number.
pFixVersion – [out] The fix version number.

WMX3APIFUNC SetPitchErrorCompensation(int axis, PitchErrorCompensationData *pitchErrCompData)

Set pitch error compensation parameters.

In pitch error compensation, offsets are defined at regularly spaced points along the axis. When the axis command position is at one of these points, the corresponding offset is added to the command position.

Remark

If this function is called with the enable parameter set to 1, pitch error compensation is immediately enabled. Otherwise, if this parameter is set to 0, pitch error compensation can be started by calling the EnablePitchErrorCompensation function.

If pitch error compensation is currently enabled, it must be disabled with the DisablePitchErrorCompensation function before the pitch error compensation parameters can be changed with this function.

The current offset applied by pitch error compensation is stored in compensation in the CoreMotionStatus structure obtained by the GetStatus function.

Pitch error compensation is automatically disabled after starting any homing operation, as the pitch error is invalid if the home position is not known.

See also

Pitch Error Compensation

Parameters:

axis – [in] The axis to set the pitch error compensation parameters.
pitchErrCompData – [in] A pointer to a PitchErrorCompensationData object that contains the pitch error compensation parameters.

WMX3APIFUNC SetPitchErrorCompensation(int axis, PitchErrorCompensationFreePositionData *pitchErrCompData)

Set free position mode pitch error compensation parameters.

This function is an overloaded version of the SetPitchErrorCompensation(int axis, PitchErrorCompensationData *pitchErrCompData) function that allows pitch error compensation to be started in free position mode.

Remark

In free position mode, the position of each pitch point is specified instead of the pitch interval. This allows the spacing between pitch points to be variable.

The difference between the largest pitch position and the smallest pitch position must be less than or equal to maxPitchErrorCompFreePositionRangeMultiplier times the distance between the two closest pitch positions. For example, 1000, 1039, 1040, and 41000 is a valid sequence of pitch positions because the difference between the largest pitch position and the smallest pitch position (41000 - 1000 = 40000) is less than or equal to the maxPitchErrorCompFreePositionRangeMultiplier (40000) times the distance between the two closest pitch positions (1040 - 1039 = 1). If the difference between the largest pitch position and the smallest pitch position is too large, the PitchPositionRangeTooLarge error will be returned.

Other than the way in which the pitch point positions are specified, the specifications are the same as normal (pitch interval mode) pitch error compensation.

If this function is called with the enable parameter set to 1, pitch error compensation is immediately enabled. Otherwise, if this parameter is set to 0, pitch error compensation can be started by calling the EnablePitchErrorCompensation function.

If pitch error compensation is currently enabled, it must be disabled with the DisablePitchErrorCompensation function before the pitch error compensation parameters can be changed with this function.

The current offset applied by pitch error compensation is stored in compensation in the CoreMotionStatus structure obtained by the GetStatus function.

Pitch error compensation is automatically disabled after starting any homing operation, as the pitch error is invalid if the home position is not known.

Parameters:

axis – [in] The axis to set the pitch error compensation parameters.
pitchErrCompData – [in] A pointer to a PitchErrorCompensationFreePositionData object that contains the pitch error compensation parameters.

WMX3APIFUNC GetPitchErrorCompensation(int axis, PitchErrorCompensationData *pitchErrCompData)

Get pitch error compensation parameters.

This function obtains the pitch error compensation parameters and whether or not pitch error compensation is enabled for an axis.

Remark

If the pitch error compensation parameters were specified in free position mode (with the SetPitchErrorCompensation(int axis, PitchErrorCompensationFreePositionData *pitchErrCompData) function), this function cannot be used to read the pitch error compensation parameters. The overloaded GetPitchErrorCompensation(int axis, PitchErrorCompensationFreePositionData *pitchErrCompData) function must be used instead.

Parameters:

axis – [in] The axis to get the pitch error compensation parameters.
pitchErrCompData – [out] A pointer to a PitchErrorCompensationData object that will contain the pitch error compensation parameters.

WMX3APIFUNC GetPitchErrorCompensation(int axis, PitchErrorCompensationFreePositionData *pitchErrCompData)

Get free position mode pitch error compensation parameters.

This function obtains the free position mode pitch error compensation parameters and whether or not pitch error compensation is enabled for an axis.

Remark

If the pitch error compensation parameters were specified in pitch interval mode (with the SetPitchErrorCompensation(int axis, PitchErrorCompensationData *pitchErrCompData) function), this function cannot be used to read the pitch error compensation parameters. The overloaded GetPitchErrorCompensation(int axis, PitchErrorCompensationData *pitchErrCompData) function must be used instead.

Parameters:

axis – [in] The axis to get the pitch error compensation parameters.
pitchErrCompData – [out] A pointer to a PitchErrorCompensationFreePositionData object that will contain the pitch error compensation parameters.

WMX3APIFUNC EnablePitchErrorCompensation(int axis)

Enable pitch error compensation.

This function enables pitch error compensation for an axis. Pitch error compensation parameters must be set beforehand using the SetPitchErrorCompensation function.

Remark

Parameters:: axis – [in] The axis to enable pitch error compensation.

WMX3APIFUNC DisablePitchErrorCompensation(int axis)

Disable pitch error compensation.

This function disables pitch error compensation for an axis. Pitch error compensation can be enabled again using the EnablePitchErrorCompensation function.

Remark

Parameters:: axis – [in] The axis to disable pitch error compensation.

WMX3APIFUNC GetPitchErrorCompensationAtPosition(int axis, double pos, double *pCompensation)

Obtain the pitch error compensation amount at the specified position.

This function returns the pitch error compensation amount that would be applied if the axis is at the specified position.

Remark

Even if pitch error compensation is disabled, this function returns the pitch error compensation amount based on the last set pitch error compensation data.

Parameters:

axis – [in] The axis to get the pitch error compensation amount.
pos – [in] The position to get the pitch error compensation amount at.
pCompensation – [out] A pointer to a double type variable that returns the pitch error compensation amount at the specified position.

WMX3APIFUNC Set2DPitchErrorCompensation(unsigned int channel, TwoDPitchErrorCompensationData *pitchErrCompData2D)

Set two-dimensional (2D) pitch error compensation parameters.

Two-Dimensional (2D) pitch error compensation is a more flexible and powerful version of pitch error compensation in which the offset amount is determined from the positions of two reference axes instead of just one axis. The offset is added to the position command of either of the two reference axes or to a third axis.

Remark

If this function is called with the enable parameter set to 1, two-dimensional pitch error compensation is immediately enabled. Otherwise, if this parameter is set to 0, two-dimensional pitch error compensation can be started by calling the Enable2DPitchErrorCompensation function.

If two-dimensional pitch error compensation is currently enabled, it must be disabled with the Disable2DPitchErrorCompensation function before the two-dimensional pitch error compensation parameters can be changed with this function.

The current offset applied by two-dimensional pitch error compensation to an axis is stored in compensation in the CoreMotionStatus structure obtained by the GetStatus function.

When two-dimensional pitch error compensation is disabled for an axis, all other two-dimensional pitch error compensation channels for which that axis is one of the reference axes are also disabled to prevent any axes from moving.

Two-dimensional pitch error compensation is automatically disabled after starting any homing operation, as the pitch error is invalid if the home position is not known.

Parameters:

channel – [in] The channel to set the two-dimensional pitch error compensation parameters. Up to max2dPitchErrorCompChannel channels may be defined.
pitchErrCompData2D – [in] A pointer to a TwoDPitchErrorCompensationData object that contains the two-dimensional pitch error compensation parameters.

WMX3APIFUNC Set2DPitchErrorCompensation(unsigned int channel, TwoDPitchErrorCompensationFreePositionData *pitchErrCompData2D)

Set free position two-dimensional (2D) pitch error compensation parameters.

This function is an overloaded version of the Set2DPitchErrorCompensation(unsigned int channel, TwoDPitchErrorCompensationData *pitchErrCompData2D) function that allows two-dimensional pitch error compensation to be started in free position mode.

Remark

In free position mode, the reference axis positions of each pitch point are specified instead of the pitch intervals. This allows the spacing between pitch points to be variable.

The difference between the largest pitch position and the smallest pitch position of each reference axis must be less than or equal to max2dPitchErrorCompFreePositionRangeMultiplier times the distance between the two closest pitch positions of that reference axis. For example, 1000, 1039, 1040, and 41000 is a valid sequence of pitch positions because the difference between the largest pitch position and the smallest pitch position (41000 - 1000 = 40000) is less than or equal to the max2dPitchErrorCompFreePositionRangeMultiplier (40000) times the distance between the two closest pitch positions (1040 - 1039 = 1). If the difference between the largest pitch position and the smallest pitch position is too large for either reference axis, the PitchPositionRangeTooLarge error will be returned.

Other than the way in which the pitch point positions are specified, the specifications are the same as normal (pitch interval mode) two-dimensional pitch error compensation.

If this function is called with the enable parameter set to 1, two-dimensional pitch error compensation is immediately enabled. Otherwise, if this parameter is set to 0, two-dimensional pitch error compensation can be started by calling the Enable2DPitchErrorCompensation function.

If two-dimensional pitch error compensation is currently enabled, it must be disabled with the Disable2DPitchErrorCompensation function before the two-dimensional pitch error compensation parameters can be changed with this function.

The current offset applied by two-dimensional pitch error compensation to an axis is stored in compensation in the CoreMotionStatus structure obtained by the GetStatus function.

When two-dimensional pitch error compensation is disabled for an axis, all other two-dimensional pitch error compensation channels for which that axis is one of the reference axes are also disabled to prevent any axes from moving.

Two-dimensional pitch error compensation is automatically disabled after starting any homing operation, as the pitch error is invalid if the home position is not known.

Parameters:

channel – [in] The channel to set the two-dimensional pitch error compensation parameters. Up to max2dPitchErrorCompChannel channels may be defined.
pitchErrCompData2D – [in] A pointer to a TwoDPitchErrorCompensationFreePositionData object that contains the two-dimensional pitch error compensation parameters.

WMX3APIFUNC Get2DPitchErrorCompensation(unsigned int channel, TwoDPitchErrorCompensationData *pitchErrCompData2D)

Get two-dimensional (2D) pitch error compensation parameters.

This function obtains the two-dimensional pitch error compensation parameters and whether or not two-dimensional pitch error compensation is currently enabled for a two-dimensional pitch error compensation channel.

Remark

If the two-dimensional pitch error compensation parameters were specified in free position mode (with the Set2DPitchErrorCompensation(unsigned int channel, TwoDPitchErrorCompensationFreePositionData *pitchErrCompData2D) function), this function cannot be used to read the two-dimensional pitch error compensation parameters. The overloaded Get2DPitchErrorCompensation(unsigned int channel, TwoDPitchErrorCompensationFreePositionData *pitchErrCompData2D) function must be used instead.

In the returned TwoDPitchErrorCompensationData object, the pitchCompensationValue at indices greater than or equal to the pitchCount of each respective axis will be set to 0.

Parameters:

channel – [in] The channel to get the two-dimensional pitch error compensation parameters. Up to max2dPitchErrorCompChannel channels may be defined.
pitchErrCompData2D – [out] A pointer to a TwoDPitchErrorCompensationData object that will contain the two-dimensional pitch error compensation parameters.

WMX3APIFUNC Get2DPitchErrorCompensation(unsigned int channel, TwoDPitchErrorCompensationFreePositionData *pitchErrCompData2D)

Get free position two-dimensional (2D) pitch error compensation parameters.

This function obtains the two-dimensional pitch error compensation parameters and whether or not two-dimensional pitch error compensation is currently enabled for a two-dimensional pitch error compensation channel.

Remark

If the two-dimensional pitch error compensation parameters were specified in pitch interval mode (with the Set2DPitchErrorCompensation(unsigned int channel, TwoDPitchErrorCompensationData *pitchErrCompData2D) function), this function cannot be used to read the two-dimensional pitch error compensation parameters. The overloaded Get2DPitchErrorCompensation(unsigned int channel, TwoDPitchErrorCompensationData *pitchErrCompData2D) function must be used instead.

In the returned TwoDPitchErrorCompensationData object, the pitchCompensationValue at indices greater than or equal to the pitchCount of each respective axis will be set to 0.

Parameters:

channel – [in] The channel to get the two-dimensional pitch error compensation parameters. Up to max2dPitchErrorCompChannel channels may be defined.
pitchErrCompData2D – [out] A pointer to a TwoDPitchErrorCompensationFreePositionData object that will contain the two-dimensional pitch error compensation parameters.

WMX3APIFUNC Enable2DPitchErrorCompensation(unsigned int channel)

Enable two-dimensional (2D) pitch error compensation.

This function enables the specified two-dimensional pitch error compensation channel. Two-dimensional pitch error compensation parameters must be set beforehand using the SetPitchErrorCompensation function.

Remark

Parameters:: channel – [in] The channel to enable two-dimensional pitch error compensation. Up to max2dPitchErrorCompChannel channels may be defined.

WMX3APIFUNC Disable2DPitchErrorCompensation(unsigned int channel)

Disable two-dimensional (2D) pitch error compensation.

This function disables the specified two-dimensional pitch error compensation channel. Two-dimensional pitch error compensation can be enabled again using the Enable2DPitchErrorCompensation function.

Remark

Parameters:: channel – [in] The channel to disable two-dimensional pitch error compensation. Up to max2dPitchErrorCompChannel channels may be defined.

WMX3APIFUNC Get2DPitchErrorCompensationAtPosition(unsigned int channel, double refPos1, double refPos2, double *pCompensation)

Obtain the two-dimensional (2D) pitch error compensation amount at the specified position.

This function returns the two-dimensional pitch error compensation amount that would be applied if the reference axes are at the specified positions.

Remark

Even if two-dimensional pitch error compensation is disabled, this function returns the two-dimensional pitch error compensation amount based on the last set two-dimensional pitch error compensation data.

Parameters:

channel – [in] The channel to get the two-dimensional pitch error compensation amount. Up to max2dPitchErrorCompChannel channels may be defined.
refPos1 – [in] The position of the first reference axis to get the two-dimensional pitch error compensation amount at.
refPos2 – [in] The position of the second reference axis to get the two-dimensional pitch error compensation amount at.
pCompensation – [out] A pointer to a double type variable that returns the two-dimensional pitch error compensation amount at the specified reference axis positions.

WMX3APIFUNC SetBacklashCompensation(int axis, BacklashCompensationData *pBacklashCompData)

Set backlash compensation parameters.

Backlash compensation will apply an offset based on the direction of motion. Parameters determine whether this offset is applied immediately upon changing direction, or if it is applied more gradually over a short distance after changing direction.

Remark

If backlash compensation is currently enabled, it must be disabled with the DisableBacklashCompensation function before the backlash compensation parameters can be changed with this function.

The current backlash compensation parameters and whether backlash compensation is enabled for an axis can be obtained using the GetBacklashCompensation function. The current offset applied by backlash compenation is stored in compensation in the CoreMotionStatus structure obtained by the GetStatus function.

See also

Backlash Compensation

Parameters:

axis – [in] The axis to set the backlash compensation parameters.
pBacklashCompData – [in] A pointer to a BacklashCompensationData object that contains the backlash compensation parameters.

WMX3APIFUNC GetBacklashCompensation(int axis, BacklashCompensationData *pBacklashCompData)

Get backlash compensation parameters.

This function obtains the backlash compensation parameters and whether or not backlash compensation is enabled for an axis.

Remark

Parameters:

axis – [in] The axis to get the backlash compensation parameters.
pBacklashCompData – [out] A pointer to a BacklashCompensationData object that will contain the backlash compensation parameters.

WMX3APIFUNC EnableBacklashCompensation(int axis)

Enable backlash compensation.

This function enables backlash compensation for an axis. Backlash compensation parameters must be set beforehand using the SetBacklashCompensation function.

Remark

Parameters:: axis – [in] The axis to enable backlash compensation.

WMX3APIFUNC DisableBacklashCompensation(int axis)

Disable backlash compensation.

This function disables backlash compensation for an axis. Backlash compensation can be enabled again using the EnableBacklashCompensation function.

Remark

Parameters:: axis – [in] The axis to disable backlash compensation.

Public Static Functions

static WMX3APIFUNC ErrorToString(int errCode, char *pString, unsigned int size)

Get a string representation of the specified error code.

This function returns a string representation of the specified error code. The error code must be defined in the CompensationErrorCode enum or the ErrorCode enum in the WMX3Api.h header. All errors returned by functions in class Compensation will be defined in one of these enums. Errors returned by functions in other classes may not be defined in one of these enums, and when such errors are passed to this function, an ErrorCodeNotDefined error will be returned and pString will contain the string representation of this error.

Remark

If pString is too small to contain the entire string representation of the error code, pString will be set to an empty string. An array size of 256 characters will be enough to hold all string representations.

This function is static, and may be called without declaring an instance of the Compensation class or creating a device.

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A char array that will contain the string representation of the error.
size – [in] The size of the char array in number of characters.

static WMX3APIFUNC ErrorToString(int errCode, wchar_t *pString, unsigned int size)

Get a string representation of the specified error code.

This function is a variation of ErrorToString that accepts a wchar_t array. Use this function when using Unicode character sets.

Remark

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A wchar_t array that will contain the string representation of the error.
size – [in] The size of the wchar_t array in number of characters.

static WMX3APIFUNC ApiLogToString(unsigned char *pLogData, unsigned int logDataSize, char *pString, unsigned int size)

Get a string representation of the raw data of an API log.

This function converts the raw data for one API function call that was extracted from the API log with the GetApiLogData function.

Remark

See also

Extracting the API Log Information

Parameters:

pLogData – [in] A char array containing the raw data.
logDataSize – [in] The size of the pLogData char array. This size must be equal to or greater than the size of the raw data.
pString – [out] A char array that will contain the string representation of the raw data of the API log.
size – [in] The size of the pString char array in number of characters.

static WMX3APIFUNC ApiLogToString(unsigned char *pLogData, unsigned int logDataSize, wchar_t *pString, unsigned int size)

Get a string representation of the raw data of an API log.

This function is a variation of ApiLogToString that accepts a wchar_t array. Use this function when using Unicode character sets.

Remark

Parameters:

pLogData – [in] A char array containing the raw data.
logDataSize – [in] The size of the char array. This size must be equal to or greater than the size of the raw data.
pString – [out] A wchar_t array that will contain the string representation of the raw data of the API log.
size – [out] The size of the pString wchar_t array in number of characters.

static WMX3APIFUNC GetLibVersion(int *pMajorVersion, int *pMinorVersion, int *pRevisionVersion, int *pFixVersion)

Get the version of the module library.

This function is static, and may be called without declaring an instance of this class or creating a device.

Remark

Parameters:

pMajorVersion – [out] The major version number.
pMinorVersion – [out] The minor version number.
pRevisionVersion – [out] The revision version number.
pFixVersion – [out] The fix version number.