Class Home

Defined in File CoreMotionApi.h

Nested Relationships

Nested Types

Class Documentation

class Home

This class contains homing functions.

Public Functions

inline Home(CoreMotion *f)

bool IsDeviceValid()

WMX3APIFUNC StartHome(int axis)

Start homing an axis. The axis will search for the home position. If found, the home position will become the zero position for that axis.

This function searches for the home position as described by the HomeParam parameters.

Remark

The axis to home must not be a synchronous control slave axis; if it is, this function will return an error and the axis will not be homed. To home a synchronous control pair or group, call this function with the “axis” argument set to the master axis. Several parameters affect the homing procedure of synchronous control pairs.

When this function is called, the specified axis will always search for the home position. To return to the zero position without searching for the home position, use a motion API function such as StartPos with the target position set to 0.

The ZPulseDetectionUnsupported, TouchProbeDetectionUnsupported, HomeSwitchDetectionUnsupported, or LimitSwitchDetectionUnsupported if the appropriate signal required to complete homing is unavailable.

See also

Homing , Tutorial 4-1: Homing

Parameters:: axis – [in] The axis to home.

WMX3APIFUNC StartHome(AxisSelection *pAxisSelection)

Start homing multiple axes. The axes will search for the home positions. If found, the home position will become the zero position for that axis.

This function is an overloaded function of StartHome that starts the homing procedure for multiple axes.

Remark

See also

Homing , Tutorial 4-1: Homing

Parameters:: pAxisSelection – [in] A pointer to an AxisSelection class object that specifies which axes to home.

WMX3APIFUNC Continue(int axis)

Continue homing an axis that has been paused during the homing operation.

This function continues the homing operation of an axis that has been paused during homing. An axis will pause during homing only if the Pause Mode parameter is set to TRUE for that axis. See Homing for information regarding the points at which pauses are inserted for each home type.

Remark

Pause mode can be useful when experimenting with the homing routine. Pause mode is typically not used in deployed applications.

This function will return an error if the specified axis is not paused while homing.

Parameters:: axis – [in] The axis to continue homing.

WMX3APIFUNC Continue(AxisSelection *pAxisSelection)

Continue homing multiple axes that have been paused during the homing operation.

This function is an overloaded function of Continue that continues the paused homing procedure for multiple axes.

Remark

This function will return an error if any of the specified axes are not paused while homing.

Parameters:: pAxisSelection – [in] A pointer to an AxisSelection class object that specifies which axes to continue homing.

WMX3APIFUNC Cancel(int axis)

Cancel the homing operation for an axis that has been paused during homing operation.

This function cancels the homing operation of an axis that has been paused during homing. See Continue for additional information regarding pause mode in homing.

Remark

This function will return an error if the specified axis is not paused while homing.

Parameters:: axis – [in] The axis to cancel homing.

WMX3APIFUNC Cancel(AxisSelection *pAxisSelection)

Cancel the homing procedure for multiple axes that have been paused during homing operation.

This function is an overloaded function of Cancel that cancels the paused homing procedure for multiple axes.

Remark

This function will return an error if any of the specified axes are not paused while homing.

Parameters:: pAxisSelection – [in] A pointer to an AxisSelection class object that specifies which axes to cancel homing.

WMX3APIFUNC SetCommandPos(int axis, double position)

Set the current command position of the axis to the specified value.

This function will set the current command position of the specified axis to the specified value by shifting the home position. The axis will not move during this operation (the command sent to the servo will remain the same).

Remark

The specified axis must be in Idle state before calling this function. This function can be called for sync master axes or sync slave axes (in which case the axis will be in Sync instead of Idle).

If the API Wait Until Motion Start parameter is enabled, this function will not return until after the next cycle, when the home position has been updated. Motion functions can be called after this function returns, and the target positions will be calculated correctly based on the updated home position. If the API Wait Until Motion Start parameter is disabled, the user must wait until the next cycle and verify that the home position has been updated using the GetStatus function before calling motion functions. See Function Calls That Are Blocking for additional information.

See also

Tutorial 4-2: Set coordinates

Parameters:

axis – [in] The axis to set the command position of.
position – [in] The value to set the axis command position to.

WMX3APIFUNC SetFeedbackPos(int axis, double position)

Set the current feedback position of the axis to the specified value.

This function will set the current feedback position of the specified axis to the specified value by shifting the home position. This axis will not move during this operation (the command sent to the servo will remain the same).

Remark

The specified axis must be in Idle state before calling this function. This function can be called for sync master axes or sync slave axes (in which case the axis will be in Sync instead of Idle).

If the API Wait Until Motion Start parameter is enabled, this function will not return until after the next cycle, when the home position has been updated. Motion functions can be called after this function returns, and the target positions will be calculated correctly based on the updated home position. If the API Wait Until Motion Start parameter is disabled, the user must wait until the next cycle and verify that the home position has been updated using the GetStatus function before calling motion functions. See Function Calls That Are Blocking for additional information.

See also

Tutorial 4-2: Set coordinates

Parameters:

axis – [in] The axis to set the feedback position of.
position – [in] The value to set the axis feedback position to.

WMX3APIFUNC SetHomeDone(int axis, unsigned char value)

Set the “home done” state.

This function sets the Home Done state of each axis. This state can be obtained by reading the Home Done member of the CoreMotionAxisStatus structure returned by the GetStatus API function.

Remark

The Home Done state of the axis is automatically set to TRUE after a successful homing operation. Depending on the Clear Home Done On Servo Off and Clear Home Done On Comm Stop parameters, the Home Done state may be set to FALSE when communication is stopped or the axis servo is turned off.

This function can be used to manually override the Home Done state that is normally set or reset as described above. This may be useful if the user implements a custom homing routine.

The Home Done state affects several operations. The software limit (set with Soft Limit Type parameter) only triggers while the Home Done state is TRUE.

Parameters:

axis – [in] The axis to set the “home done” state.
value – [in] Specify 0 to set the “home done” state to FALSE or 1 to set the “home done” state to TRUE.

WMX3APIFUNC SetCommandPosToFeedbackPos(int axis, double posChangePerCycle = 0)

Set the current cyclic command position equal to the feedback position.

This function changes the current command position to be equal to the current feedback position. Unlike the SetCommandPos and SetFeedbackPos functions, the commanded position itself is changed and the home position is not shifted. Because of this, the axis may move as a result of this function, although it typically will not because the command position is set to the feedback position.

Remark

If the posChangePerCycle optional argument is set, the rate at which this function causes the command position to change will be limited to that many user units per cycle. Thus, it sets a “velocity” for the change in command position, in user units per cycle.

This function can be used to set the command position to be exactly at a physical boundary. A motion command can be executed to push the axis against a physical boundary (taking care that the output torque is small enough as to not damage the machine). When the axis touches the physical boundary, the feedback position will stop changing even as the command position continues increasing (or decreasing) to positions beyond the boundary. After this point, this function can be called to return the command position back to the position where the feedback position stopped changing, which is exactly at the physical boundary. The posChangePerCycle argument might be set to a nonzero value if the servo generates an alarm from changing the position command too rapidly during this operation.

Parameters:

axis – [in] The axis to set the command position to feedback position.
posChangePerCycle – [in] An optional argument that limits the rate at which this function causes the command position to change every cycle. If this value is set, the command position will cchange by at most this number of user units every cycle.

WMX3APIFUNC GetHomeData(HomeData *pHomeData)

Get the homing related data for all axes.

Parameters:: pHomeData – [out] A pointer to a HomeData object that will contain the homing related data for all axes.

Public Members

CoreMotion *cmApi

class AxisHomeData

This class contains homing related data for a single axis.

Public Functions

AxisHomeData()

Public Members

double distHStoZPulse: The distance from the home switch position to the Z-pulse (index pulse) position. This value may be negative, in which case the home switch position is greater than the Z-pulse (index pulse) position. This value is zero unless a homing operation that uses the home switch and the Z-pulse (index pulse) has been completed. For the HSReverseZPulse home type, this value is first calculated when the rising edge of the home switch is detected, and then updated if the falling edge of the home switch is detected during reverse movement. This value has units of user units.

double distLStoZPulse: The distance from the limit switch position to the Z-pulse (index pulse) position. This value may be negative, in which case the limit switch position is greater than the Z-pulse (index pulse) position. This value is zero unless a homing operation that uses the limit switch and the Z-pulse (index pulse) has been completed. This value has units of user units.

double distMechanicalEndToZPulse: The distance from the mechanical end position to the Z-pulse (index pulse) position. This value may be negative, in which case the mechanical end position is greater than the Z-pulse (index pulse) position. This value is zero unless a homing operation that uses the mechanical end and the Z-pulse (index pulse) has been completed. This value has units of user units.

double latchedZPulseEncoder: The Z-pulse (index pulse) encoder count that was latched during homing. This is the raw encoder count at the position where the Z-pulse (index pulse) was detected. It is not affected by the home offset. This value is automatically updated while homing when using a home type that searches for the Z-pulse (index pulse).

double latchedLimitSwitchEncoder: The raw encoder count at the position where the limit switch was found during homing. Because this position is latched by software, it is typically not as precise as the Z-pulse (index pulse) or touch probe. This value is automatically updated while homing when using a home type that searches for the limit switch position.

double latchedHomeSwitchEncoder: The raw encoder count at the position where the home switch was found during homing. Because this position is latched by software, it is typically not as precise as the Z-pulse (index pulse) or touch probe. This value is automatically updated while homing when using a home type that searches for the home switch position.

double latchedFirstHomeSwitchEncoder: The raw encoder count at the position where the first home switch was found during homing. This status is identical to latchedHomeSwitchEncoder, except as follows. This status does not update when the home switch is searched for the second time when homing using the HSHS home type. This status does not update when searching for the falling edge of the home switch when the home switch is on at the beginning of homing or the limit switch is triggered during homing, with one exeception as follows. If the home type is HSHS, if the home switch is on at the beginning of homing, this status will update when the falling edge of the home switch is first found.

double latchedTouchProbeEncoder: The touch probe encoder count that was latched during homing. This is the raw encoder count at the position where the touch probe was detected. It is not affected by the home offset. This value is automatically updated when homing using a home type that searches for the touch probe.

double distZPulseToMasterZPulse: The distance between the Z-pulse (index pulse) position of the axis and the Z-pulse position of the master axis. This status will contain 0 if the axis is not a sync slave axis, or if the Z-pulse position has not been detected for the master and slave axes. This value is in user units of the slave axis. This value is automatically updated while homing a pair of gantry axes when using a home type that searches for the Z-pulse.

double distLSToMasterLS: The distance between the limit switch position of the axis and the limit switch position of the master axis. This status will contain 0 if the axis is not a sync slave axis, or if the limit switch position has not been detected for the master and slave axes. This value is in user units of the slave axis. This value is automatically updated while homing a pair of gantry axes when using a home type that searches for the limit switch position.

double distHSToMasterHS: The distance between the home switch position of the axis and the home switch position of the master axis. This status will contain 0 if the axis is not a sync slave axis, or if the home switch position has not been detected for the master and slave axes. This value is in user units of the slave axis. This value is automatically updated while homing a pair of gantry axes when using a home type that searches for the home switch position.

class HomeData

This class contains homing related data for all axes.

Public Functions

HomeData()

Public Members

AxisHomeData axesHomeData[constants::maxAxes]: An array of AxisHomeData objects, each of which contains home data for a single axis. The array index corresponds to the axis number.