Movement Functions

Collaboration diagram for Movement Functions:

Functions
MLPIRESULT	mlpiMotionGetStatus (const MLPIHANDLE connection, const MlpiAxisRef axis, const MLPIMOTIONHANDLE motionHandle, MlpiMotionStatus *status)
MLPIRESULT	mlpiMotionPower (const MLPIHANDLE connection, const MlpiMotionPower *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionStop (const MLPIHANDLE connection, const MlpiMotionStop *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionHome (const MLPIHANDLE connection, const MlpiAxisRef axis, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionSetAbsoluteMeasurement (const MLPIHANDLE connection, const MlpiAxisRef axis)
MLPIRESULT	mlpiMotionChangeFlexProfileSet (const MLPIHANDLE connection, const MlpiAxisRef axis, const MlpiMotionFlexProfileStep *paramSet, const ULONG numElements, const DOUBLE masterVel, const MlpiProfileSetSelection set)
MLPIRESULT	mlpiMotionMoveVelocity (const MLPIHANDLE connection, const MlpiMotionMoveVelocity *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionMoveContinuousAbsolute (const MLPIHANDLE connection, const MlpiMotionMoveContinuousAbsolute *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionMoveContinuousRelative (const MLPIHANDLE connection, const MlpiMotionMoveContinuousRelative *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionMoveAbsolute (const MLPIHANDLE connection, const MlpiMotionMoveAbsolute *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionMoveAdditive (const MLPIHANDLE connection, const MlpiMotionMoveAdditive *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionMoveRelative (const MLPIHANDLE connection, const MlpiMotionMoveRelative *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionTorqueControl (const MLPIHANDLE connection, const MlpiMotionTorqueControl *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionOpenCyclicPositionChannel (const MLPIHANDLE connection, const MlpiAxisRef axis, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionOpenCyclicVelocityChannel (const MLPIHANDLE connection, const MlpiAxisRef axis, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionOpenCyclicAnalogChannel (const MLPIHANDLE connection, const MlpiAxisRef axis, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionOpenCyclicTorqueChannel (const MLPIHANDLE connection, const MlpiAxisRef axis, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionWriteCyclicPosition (const MLPIHANDLE connection, const MlpiMotionCyclic *paramSet, const ULONG numElements=1)
MLPIRESULT	mlpiMotionWriteCyclicVelocity (const MLPIHANDLE connection, const MlpiMotionCyclic *paramSet, const ULONG numElements=1)
MLPIRESULT	mlpiMotionWriteCyclicAnalog (const MLPIHANDLE connection, const MlpiMotionCyclic *paramSet, const ULONG numElements=1)
MLPIRESULT	mlpiMotionWriteCyclicTorque (const MLPIHANDLE connection, const MlpiMotionCyclic *paramSet, const ULONG numElements=1)
MLPIRESULT	mlpiMotionControlOn (const MLPIHANDLE connection, const MlpiAxisRef axis, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionControlOff (const MLPIHANDLE connection, const MlpiAxisRef axis, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionAddAxisToGroup (const MLPIHANDLE connection, const MlpiMotionAdminAxisGroup *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionRemAxisFromGroup (const MLPIHANDLE connection, const MlpiMotionAdminAxisGroup *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionGearIn (const MLPIHANDLE connection, const MlpiMotionGearIn *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionGearInPos (const MLPIHANDLE connection, const MlpiMotionGearInPos *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionCamIn (const MLPIHANDLE connection, const MlpiMotionCamIn *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionMotionProfile (const MLPIHANDLE connection, const MlpiMotionMotionProfile *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionFlexProfile (const MLPIHANDLE connection, const MlpiMotionFlexProfile *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionSynchronOut (const MLPIHANDLE connection, const MlpiAxisRef axis, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionPhasing (const MLPIHANDLE connection, const MlpiMotionPhasing *paramSet, MLPIMOTIONHANDLE *motionHandle)
MLPIRESULT	mlpiMotionPhasingSlave (const MLPIHANDLE connection, const MlpiMotionPhasing *paramSet, MLPIMOTIONHANDLE *motionHandle)

Detailed Description

The following functions can be used to command and move an axis. The following axis shows how to do a single axis movement. For this example to work, you need to add an axis to your axis configuration and switch the control to BB. It is recommended to do this using IndraWorks.

Note

If you get a permission error, when trying to move an axis, then the user profile you are using does not have enough permissions. See Permission and user management which explains the permission handling of the MLPI. See mlpiApiConnect on how to login as a different user.

We begin the example by checking if the axis is available and what type of axis we want to move. Only virtual and real axis can be commanded.

MlpiAxisRef axis(1);    // change to select an available axis number

// let's read the axis type to check if this example is working with the given
// axis address
USHORT axisType;
MLPIRESULT result = mlpiMotionGetAxisType(connection, axis, &axisType);
if (MLPI_FAILED(result)){
  printf("\nCould not read axis type of axis %d with error 0x%08x. Is the axis address correct and the axis configured?", axis.axisNo, result);
  return -1;
}

if (MlpiAxisTypeDecoder(axisType).Type() != MLPI_AXISTYPE_REAL && MlpiAxisTypeDecoder(axisType).Type() != MLPI_AXISTYPE_VIRTUAL) {
  printf("\nThis example is only working with real or virtual axis!");
  return -1;
}

The following lines perform a check to make sure that we can move the axis and that there are no configuration errors.

// check if axis is referenced.
ULONG axisState = 0;
result = mlpiMotionGetState(connection, axis, &axisState);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

// we use the helper struct from #include <util/mlpiMotionHelper.h> to decode the axisState
MlpiAxisStateDecoder state = axisState;

if (state.Error()) {
  // axis is in error state. Clear error!
  result = mlpiMotionClearError(connection, axis);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return -1;
  }
}

if (!state.InAb()) {
  // axis needs to be in AB. Otherwise, we cannot switch to power or home.
  printf("\nAxis is not in AB. Cannot continue with example. Switch axis to AB and start example again!");
  return -1;
}

if (!state.Homed()) {
  // axis is not homed, let's set absolute measurement reference at current position
  result = mlpiMotionSetAbsoluteMeasurement(connection, axis);
  if (MLPI_FAILED(result)) {
    printf("\nCould not set absolute reference. This example needs an axis with absolute encoder! Error: 0x%08x", (unsigned)result);
    return -1;
  }
}

We are now ready to start the axis movement. Please note that all axis command functions have asynchronous behavior. This means that when the MLPI function returns, the command has not been finished yet. It might even not have been started yet. The function tells the axis to abort the current command and start with the new movement as soon as possible (e.g. next motion cycle). After setting the new command, the MLPI function returns immediately. It returns an error code if the new command has not been accepted by the axis. If the motion command has been accepted, the axis will start to execute your command. For example, moving to a given absolute position if you have commanded it using mlpiMotionMoveAbsolute. Other than the return code, the movement function also returns a so called 'Motion-Handle' (MLPIMOTIONHANDLE) as a output argument. You can use this output handle at any time with the function mlpiMotionGetStatus to check the current state of the axis movement. This way, you can check if the axis has already finished the movement (e.g. reached the target position) or an error has occurred.

In the example below, the helper function utilMotionWait is used to poll if the axis has finished the given motion command. It blocks the current thread until the command has been finished by the axis. It is also possible to give a timeout to the function. Have a look at the source code of utilMotionWait to see an example of how mlpiMotionGetStatus can be used.

// we need a motion handle for our motion commands
MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;

//
// switch power ON
//
if (MlpiAxisTypeDecoder(axisType).Type() == MLPI_AXISTYPE_REAL) {
  MlpiMotionPower cmdPower;
  cmdPower.axis = axis;
  cmdPower.power = TRUE;

  result = mlpiMotionPower(connection, &cmdPower, &motionHandle);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return -1;
  }

  // wait until command power on is finished and axis has power
  result = utilMotionWait(connection, axis, motionHandle, 1000);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return -1;
  }
}

//
// let's do some absolute positioning (MoveAbsolute)
//
const MlpiMotionMoveAbsolute cmdAbsolute[] = {
  //      Pos Vel Acc Dec Jrk
  {axis,   0, 100, 10, 10,  0},
  {axis,  90, 100, 40, 10,  0},
  {axis, 180,  50, 10, 10,  0},
  {axis, 270, 100, 40,  5,  0},
  {axis,  90, 100, 40,  5,  0},
  {axis,   0,  10, 10, 10,  0}
};

for (ULONG i=0; i<_countof(cmdAbsolute); i++) {
  printf("\nNew MoveAbsolute to position %lf", cmdAbsolute[i].position);

  // command MoveAbsolute to axis
  result = mlpiMotionMoveAbsolute(connection, &cmdAbsolute[i], &motionHandle);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return -1;
  }

  // wait until command power on is finished and has reached target position
  result = utilMotionWait(connection, axis, motionHandle, 10000);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return -1;
  }
}

//
// try some velocity movement (MoveVelocity)
//
const MlpiMotionMoveVelocity cmdVelocity[] = {
  //     Vel Acc Dec Jrk
  {axis, 100, 10, 10,  0},
  {axis, 500, 40, 10,  0},
  {axis,  50, 10, 10,  0},
  {axis, 500, 40,  5,  0},
  {axis, 100, 40,  5,  0},
  {axis, 500, 10, 10,  0}
};

for (ULONG i=0; i<_countof(cmdAbsolute); i++) {
  printf("\nNew MoveVelocity to velocity %lf", cmdVelocity[i].velocity);

  // command MoveVelocity to axis
  result = mlpiMotionMoveVelocity(connection, &cmdVelocity[i], &motionHandle);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return -1;
  }

  // wait until command power on is finished and has reached target velocity
  result = utilMotionWait(connection, axis, motionHandle, 10000);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return -1;
  }
}

//
// STOP axis
//
MlpiMotionStop cmdStop;
cmdStop.axis = axis;
cmdStop.stop = TRUE;
cmdStop.deceleration = 100;
cmdStop.jerk = 0;

// command Stop to axis
result = mlpiMotionStop(connection, &cmdStop, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

// wait until axis has stopped
result = utilMotionWait(connection, axis, motionHandle, 10000);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

// after the axis stops, we have to call the stop command again
// with "FALSE" to release axis from "STOPPED" state.
// As long as the axis is in state "STOPPED", no other motion commands
// will be allowed!
cmdStop.stop = FALSE;
result = mlpiMotionStop(connection, &cmdStop, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

//
// switch power OFF
//
if (MlpiAxisTypeDecoder(axisType).Type() == MLPI_AXISTYPE_REAL) {
  MlpiMotionPower cmdPower;
  cmdPower.axis = axis;
  cmdPower.power = FALSE;

  result = mlpiMotionPower(connection, &cmdPower, &motionHandle);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return -1;
  }

  // wait until command power on is finished and axis has power off
  result = utilMotionWait(connection, axis, motionHandle, 1000);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return -1;
  }
}

Function Documentation

MLPIRESULT mlpiMotionGetStatus	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		const MLPIMOTIONHANDLE	motionHandle,
		MlpiMotionStatus *	status
	)

This function reads the status of a motion command.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[in]	motionHandle	Handle of the motion command where the status should be requested.
[out]	status	Pointer to data where status will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionPower	(	const MLPIHANDLE	connection,
		const MlpiMotionPower *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands power to the drive. This is only necessary for a real axis. Virtual axis can be moved without giving power to the axis.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

See Movement Functions

MLPIRESULT mlpiMotionStop	(	const MLPIHANDLE	connection,
		const MlpiMotionStop *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands a stop of motion to the drive.

Note

After calling this function with TRUE you have to call it again with FALSE to get axis from state 'Stopping' to state 'Standstill' command and to make the axis accept new commands.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Reference to the axis that should be stopped.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

See Movement Functions

MLPIRESULT mlpiMotionHome	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands to home an axis. Only axes with incremental encoders can be homed. If the axis has an absolute encoder, the command "set absolute measurement" must be used.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;
MLPIRESULT result = mlpiMotionHome(connection, 1, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

// wait till homing is finished
result = utilMotionWait(connection, axis, motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionSetAbsoluteMeasurement	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis
	)

This function commands to "set absolute measurement" of an axis. Only axis with absolute encoders can be used with this function.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.

Returns

Return value indicating success (>=0) or error (<0).

Example:

See Movement Functions

MLPIRESULT mlpiMotionChangeFlexProfileSet	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		const MlpiMotionFlexProfileStep *	paramSet,
		const ULONG	numElements,
		const DOUBLE	masterVel,
		const MlpiProfileSetSelection	set
	)

This function writes all parameters necessary to configure a flex profile.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[in]	paramSet	Pointer to array of structures containing the parameters for the flex profile.
[in]	numElements	Number of structures passed.
[in]	masterVel	Master velocity for given flex profiles.
[in]	set	Set where flex profile should be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MlpiMotionFlexProfileStep profile[2];
memset(profile, 0, sizeof(profile));

// first step in profile is rest in rest poly5
profile[0].camShaftDistance          = 180.0;  // on 180 degrees of master axis travel..
profile[0].range                     = 180.0;  // ...move the slave axis by 180 degrees
profile[0].motionLaw                 = MLPI_REST_IN_REST_POLY5;
profile[0].master                    = MLPI_MASTER_AXIS0;
profile[0].startVel                  = 0.0;
profile[0].startAcc                  = 0.0;
profile[0].endVel                    = 0.0;
profile[0].endAcc                    = 0.0;
profile[0].turningPointDisplacement  = 0.5;

// second step in profile is a rest in rest sinusoidal
profile[1].camShaftDistance          = 180.0;   // on 180 degrees of master axis travel..
profile[1].range                     = -180.0;  // ...reverse the slave axis by 180 degrees
profile[1].motionLaw                 = MLPI_REST_IN_REST_MOD_SINE;
profile[1].master                    = MLPI_MASTER_AXIS0;
profile[1].startVel                  = 0.0;
profile[1].startAcc                  = 0.0;
profile[1].endVel                    = 0.0;
profile[1].endAcc                    = 0.0;
profile[1].turningPointDisplacement  = 0.5;

// write the profile to slave axis 1 onto set 0.
MLPIRESULT result = mlpiMotionChangeFlexProfileSet(connection, 1, profile, 2, 10, MLPI_PROFILE_SET_0);
if (MLPI_FAILED(result)){
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

// next step would be to start the profile on the slave axis using mlpiMotionFlexProfile()...

MLPIRESULT mlpiMotionMoveVelocity	(	const MLPIHANDLE	connection,
		const MlpiMotionMoveVelocity *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands a velocity movement. Once the commanded velocity had been reached, the axis will continue to run with this velocity until another command is issued.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

See Movement Functions

MLPIRESULT mlpiMotionMoveContinuousAbsolute	(	const MLPIHANDLE	connection,
		const MlpiMotionMoveContinuousAbsolute *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands a movement to a position where a commanded velocity is reached. Once this position is reached, the axis will continue to run with the commanded velocity until another command is issued.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;

// command continuous absolute movement with end velocity 100 at position 50
MlpiMotionMoveContinuousAbsolute cmdMoveConAbs;
cmdMoveConAbs.axis         = 1;
cmdMoveConAbs.position     = 50;
cmdMoveConAbs.endVelocity  = 100;
cmdMoveConAbs.velocity     = 100;
cmdMoveConAbs.acceleration = 10;
cmdMoveConAbs.deceleration = 10;
cmdMoveConAbs.jerk         = 0;


// do the command
MLPIRESULT result = mlpiMotionMoveContinuousAbsolute(connection, &cmdMoveConAbs, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionMoveContinuousRelative	(	const MLPIHANDLE	connection,
		const MlpiMotionMoveContinuousRelative *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands a movement of a specified relative distance ending with the specified velocity. Once this distance is reached, the axis will continue to run with the commanded velocity until another command is issued.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;

// command continuous relative movement with end velocity 100 and a distance of 200
MlpiMotionMoveContinuousRelative cmdMoveConRel;
cmdMoveConRel.axis         = 1;
cmdMoveConRel.distance     = 200;
cmdMoveConRel.endVelocity  = 100;
cmdMoveConRel.velocity     = 100;
cmdMoveConRel.acceleration = 10;
cmdMoveConRel.deceleration = 10;
cmdMoveConRel.jerk         = 0;


// do the command
MLPIRESULT result = mlpiMotionMoveContinuousRelative(connection, &cmdMoveConRel, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionMoveAbsolute	(	const MLPIHANDLE	connection,
		const MlpiMotionMoveAbsolute *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands an absolute movement. This means that the axis will move to a given target position.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

See Movement Functions

MLPIRESULT mlpiMotionMoveAdditive	(	const MLPIHANDLE	connection,
		const MlpiMotionMoveAdditive *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands an additive movement. The additive position is added to the target position and is used as new target. It can be used to add a relative position to the already commanded movement.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;

// command a move relative by 90 degrees/millimeter on axis 1
MlpiMotionMoveAdditive cmdMoveAdditive;
cmdMoveAdditive.axis         = 1;
cmdMoveAdditive.distance     = 90;
cmdMoveAdditive.velocity     = 100;
cmdMoveAdditive.acceleration = 10;
cmdMoveAdditive.deceleration = 10;
cmdMoveAdditive.jerk         = 0;


// do the command
MLPIRESULT result = mlpiMotionMoveAdditive(connection, &cmdMoveAdditive, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionMoveRelative	(	const MLPIHANDLE	connection,
		const MlpiMotionMoveRelative *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands a relative movement. The relative position is added to the current position and is used as new target. The difference between this and an additive movement is that the position offset is added to the current position, not the target position. So a movement command which is currently running will be interrupted and only the position offset is added to the current position.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;

// command a move relative by 90 degrees/millimeter on axis 1
MlpiMotionMoveRelative cmdMoveRelative;
cmdMoveRelative.axis         = 1;
cmdMoveRelative.distance     = 90;
cmdMoveRelative.velocity     = 100;
cmdMoveRelative.acceleration = 10;
cmdMoveRelative.deceleration = 10;
cmdMoveRelative.jerk         = 0;


// do the command
MLPIRESULT result = mlpiMotionMoveRelative(connection, &cmdMoveRelative, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionTorqueControl	(	const MLPIHANDLE	connection,
		const MlpiMotionTorqueControl *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands a move torque.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionOpenCyclicPositionChannel	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		MLPIMOTIONHANDLE *	motionHandle
	)

The following functions all deal with motion that is commanded by sending cyclic data. This is used to be able to generate your own profiles. This is contrary to all other motion commands where the profiles are generated by the control. In order to be able to write cyclic data, a "channel" must be opened first. Once opened, cyclic data should be written every motion cycle. No explicit error will occur if no cyclic data is written. In this case, the last known cyclic data will be send again. But keep in mind, that the movement on the drive might be jittered or even result in errors in the drive. To correctly synchronize your cyclic write access to the drive you might want to have a look at the function mlpiTaskWaitForEvent. The cyclic command mode can be canceled using any other single or synchronous motion command. Prior to opening a cyclic channel, you should initialize the first channel value by using the corresponding write command (e.g. mlpiMotionWriteCyclicPosition).

This function opens a cyclic channel for cyclic position commands.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionOpenCyclicVelocityChannel	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function opens a cyclic channel for cyclic velocity commands.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionOpenCyclicAnalogChannel	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function opens a cyclic channel for cyclic analogue commands.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionOpenCyclicTorqueChannel	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function opens a cyclic channel for cyclic torque commands.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionWriteCyclicPosition	(	const MLPIHANDLE	connection,
		const MlpiMotionCyclic *	paramSet,
		const ULONG	numElements = 1
	)

This function commands a cyclic position. It is possible to give an array to paramSet and to set the position of several axes using one call only.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[in]	numElements	Number of given positions in paramSet.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionWriteCyclicVelocity	(	const MLPIHANDLE	connection,
		const MlpiMotionCyclic *	paramSet,
		const ULONG	numElements = 1
	)

This function commands a cyclic velocity. It is possible to give an array to paramSet and to set the velocity of several axes with only one call in this way.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[in]	numElements	Number of given velocities in paramSet.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionWriteCyclicAnalog	(	const MLPIHANDLE	connection,
		const MlpiMotionCyclic *	paramSet,
		const ULONG	numElements = 1
	)

This function commands a cyclic analog value. It is possible to give an array to paramSet and to set the velocity of several axes using only one call in this way.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[in]	numElements	Number of given analog values in paramSet.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionWriteCyclicTorque	(	const MLPIHANDLE	connection,
		const MlpiMotionCyclic *	paramSet,
		const ULONG	numElements = 1
	)

This function commands a cyclic torque value. It is possible to give an array to paramSet and to set the torque of several axes with only one call in this way.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[in]	numElements	Number of given torque values in paramSet.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionControlOn	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function switches the axis to controlled motion.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionControlOff	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function switches the axis away from controlled motion.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionAddAxisToGroup	(	const MLPIHANDLE	connection,
		const MlpiMotionAdminAxisGroup *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function adds an axis to a group.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing the information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionRemAxisFromGroup	(	const MLPIHANDLE	connection,
		const MlpiMotionAdminAxisGroup *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function removes an axis from a group.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing the information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionGearIn	(	const MLPIHANDLE	connection,
		const MlpiMotionGearIn *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands velocity synchronization to the master.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// sync axis 2 to axis 1
MlpiMotionGearIn cmdGearIn;
cmdGearIn.master      = 1; // master axis
cmdGearIn.axis        = 2; // slave axis
cmdGearIn.numerator   = 1;
cmdGearIn.denominator = 1;
cmdGearIn.fineadjust  = 0;

// do the command
MLPIRESULT result = mlpiMotionGearIn(connection, &cmdGearIn, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionGearInPos	(	const MLPIHANDLE	connection,
		const MlpiMotionGearInPos *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands position synchronization to the master.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;

// sync axis 2 to axis 1
MlpiMotionGearInPos cmdGearInPos;
cmdGearInPos.master      = 1; // master axis
cmdGearInPos.axis        = 2; // slave axis
cmdGearInPos.numerator   = 1;
cmdGearInPos.denominator = 1;
cmdGearInPos.fineadjust  = 0;
cmdGearInPos.startMode   = MLPI_STARTMODE_ABSOLUTE;
cmdGearInPos.syncMode    = MLPI_SYNC_SHORTESTWAY;


// do the command
MLPIRESULT result = mlpiMotionGearInPos(connection, &cmdGearInPos, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionCamIn	(	const MLPIHANDLE	connection,
		const MlpiMotionCamIn *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands an axis to synchronize to the master by using a cam table.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionMotionProfile	(	const MLPIHANDLE	connection,
		const MlpiMotionMotionProfile *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands an axis to synchronize to the master by using a motion profile. The command can only be used on IndraDrives with interpolation in the drive.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

MLPIRESULT mlpiMotionFlexProfile	(	const MLPIHANDLE	connection,
		const MlpiMotionFlexProfile *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands an axis to synchronize to the master by using a flex profile. The command can only be used on IndraDrives with interpolation in the control or with Sercos drives.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;

// start FlexProfile 0 on slave axis 2.
// note that you need to write a profile to axis 2 prior to
// starting the FlexProfile. Do this by using the function
// mlpiMotionChangeFlexProfile().
MlpiMotionFlexProfile cmdFlex;
cmdFlex.master                   = 1; // master axis
cmdFlex.axis                     = 2; // slave axis
cmdFlex.numerator                = 1;
cmdFlex.denominator              = 1;
cmdFlex.fineadjust               = 0;
cmdFlex.profileEntry             = MLPI_SLAVE_ORIGIN_MASTER_ORIGIN;
cmdFlex.executionMode            = MLPI_EXECUTE_CYCLIC;
cmdFlex.masterOffset             = 0;
cmdFlex.slaveOffset              = 0;
cmdFlex.setSelection             = MLPI_PROFILE_SET_0;
cmdFlex.switchingPosition        = 0.0;
cmdFlex.useSwitchingPositioning  = false;
cmdFlex.syncVelocity             = 100;
cmdFlex.syncAcceleration         = 100;
cmdFlex.syncType                 = MLPI_SYNC_RAMPIN_SHORTESTWAY;

// do the command
MLPIRESULT result = mlpiMotionFlexProfile(connection, &cmdFlex, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionSynchronOut	(	const MLPIHANDLE	connection,
		const MlpiAxisRef	axis,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands an axis to become unsynchronized. The axis will continue to run with the velocity at the time the command was issued. Can be called after GearIn, GearInPos MotionProfile, FlexProfile and CamIn.

Parameters

[in]	connection	Handle for multiple connections.
[in]	axis	Reference to the axis.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;
MLPIRESULT result = mlpiMotionSynchronOut(connection, 1, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

// wait until sync out is finished
result = utilMotionWait(connection, axis, motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionPhasing	(	const MLPIHANDLE	connection,
		const MlpiMotionPhasing *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands an axis to perform a master phase offset when the drive is synchronized to the master. The command can also be executed when unsynchronized, but it will only take effect when the axis is synchronized.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;

// set the commanding values
MlpiMotionPhasing cmdPhasing;
cmdPhasing.axis         = 1;
cmdPhasing.phaseShift   = 90;
cmdPhasing.velocity     = 100;
cmdPhasing.acceleration = 10;
cmdPhasing.deceleration = 10;

// do the command
MLPIRESULT result = mlpiMotionPhasing(connection, &cmdPhasing, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}

MLPIRESULT mlpiMotionPhasingSlave	(	const MLPIHANDLE	connection,
		const MlpiMotionPhasing *	paramSet,
		MLPIMOTIONHANDLE *	motionHandle
	)

This function commands an axis to perform a slave phase offset when the drive is synchronized to the master. The command can also be executed when unsynchronized, but it will only take effect when synchronizing the axis.

Parameters

[in]	connection	Handle for multiple connections.
[in]	paramSet	Structure containing all information necessary for the command.
[out]	motionHandle	Pointer to value where motion handle will be stored.

Returns

Return value indicating success (>=0) or error (<0).

Example:

MLPIMOTIONHANDLE motionHandle = MLPI_INVALIDHANDLE;

// set the commanding values
MlpiMotionPhasing cmdPhasing;
cmdPhasing.axis         = 1;
cmdPhasing.phaseShift   = 90;
cmdPhasing.velocity     = 100;
cmdPhasing.acceleration = 10;
cmdPhasing.deceleration = 10;

// do the command
MLPIRESULT result = mlpiMotionPhasingSlave(connection, &cmdPhasing, &motionHandle);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return -1;
}