KINGSTAR 4 Motion porting information
If you have used KINGSTAR 3.x before, you'll notice that KINGSTAR updates the motion library that breaks the compatibility between version 3.x and 4.x. To clear up the confusion you might have, we list the primary changes KINGSTAR makes in 4.x motion library.
The PLCopen and motion board style APIs have been merged into a single API set which provides the simplicity of the motion board style and the flexibility of the PLCopen style.
- Naming convention.
- Command states and outputs are optional. They are stored in a KsCommandStatus return structure. You no longer need to pass pointers for each output variable. This KsCommandStatus structure includes a handle that identifies the command.
- The state of commands can be queried with GetCommandStatus using the KsCommandStatus instead of queue indexes.
- Calling MoveAxisAbsolute allways creates a new command. To modify an existing command use UpdateCommand and pass the KsCommandStatus.
- Cancelling commands like StopAxis is now done using the AbortCommand method.
- You can block a thread until a command is completed or aborted using the WaitForCommand method.
Names use VerbAxisType. For example, MC_MoveAbsolute and MoveServoAbsolute become MoveAxisAbsolute.
Examples
- Sending an absolute move command. This sample shows the use of the command states and outputs.
- Query the state of a command.
- Update the parameters of command.
- Cancelling a command.
3.x PLCopen style:
MC_MoveAbsolute(Index, &QueueIndex, FALSE, Target, MAXIMUM_VELOCITY,
MAXIMUM_ACCELERATION, MAXIMUM_DECELERATION, MAXIMUM_JERK,
mcPositiveDirection, mcAborting, &Done, &Busy, &Active,
&CommandAborted, &Error, &ErrorId);
3.x Motion board style:
int nRet = MoveServoAbsolute(Index, Target);
4.x:
KsCommandStatus status = MoveAxisAbsolute(Index, Target, MAXIMUM_VELOCITY,
MAXIMUM_ACCELERATION, MAXIMUM_DECELERATION, MAXIMUM_JERK,
mcPositiveDirection, mcAborting);
3.x PLCopen style. When you query, you need to send the same command again.
QueueIndex = -1;
MC_MoveRelative(Index, &QueueIndex, TRUE, Target, MAXIMUM_VELOCITY,
MAXIMUM_ACCELERATION, MAXIMUM_DECELERATION, MAXIMUM_JERK,
mcAborting, &Done, &Busy, &Active, &CommandAborted,
&Error, &ErrorID);
Sleep(3000);
//Read the states of the motion command.
MC_MoveRelative(Index, &QueueIndex, TRUE, Target, MAXIMUM_VELOCITY,
MAXIMUM_ACCELERATION, MAXIMUM_DECELERATION, MAXIMUM_JERK,
mcAborting, &Done, &Busy, &Active, &CommandAborted,
&Error, &ErrorID);
RtPrintf("MC_MoveRelative Done: %d, Error: %d, ErrorID: %d\n", Done, Error, ErrorID);
3.x Motion board style:
It is not possible to query the state of a command in this API style.
4.x:
KsCommandStatus status = MoveAxisRelative(Index, Distance, MAXIMUM_VELOCITY,
MAXIMUM_ACCELERATION, MAXIMUM_DECELERATION, MAXIMUM_JERK, mcAborting);
Sleep(3000);
RtPrintf("MoveAxisRelative Done: %d, Error: %d, ErrorID: %d\n",
status.Done, status.Error, status.ErrorId);
3.x PLCopen style. Notice that ContinuousUpdate is TRUE to receive the new values.
MC_MoveContinuousAbsolute(Index, &QueueIndex, TRUE, Target, 1500,
1000, 10000, 10000, 1000000, mcPositiveDirection, mcAborting,
&InEndVelocity, &Busy, &Active, &CommandAborted, &Error, &ErrorID);
Sleep(1000);
MC_MoveContinuousAbsolute(Index, &QueueIndex, TRUE, Target, 1800,
2000, 20000, 20000, 2000000, mcPositiveDirection, mcAborting,
&InEndVelocity, &Busy, &Active, &CommandAborted, &Error, &ErrorID);
Sleep(1000);
3.x Motion board style:
It is not possible to update the parameters of a command in this API style.
4.x:
KsCommandStatus abs = MoveAxisContinuousAbsolute(Index, 3000, 2000, 1500,
20000, 20000, 2000000, mcPositiveDirection, mcAborting);
Sleep(1000);
UpdateCommand(6000, 3000, 2000, 30000, 30000, 3000000, abs);
Sleep(1000);
3.x PLCopen style. Notice the TRUE and FALSE in MC_Stop. TRUE is to stop an axis and FALSE is to release the axis from the Stopping state.
MC_Jog(Index, &QueueIndex, TRUE, FALSE, MAXIMUM_VELOCITY, MAXIMUM_ACCELERATION,
MAXIMUM_DECELERATION, MAXIMUM_JERK, &InVelocity, &Done, &Busy,
&CommandAborted, &Error, &ErrorID);
Sleep(2000);
MC_Stop(Index, &QueueIndex, TRUE, MAXIMUM_DECELERATION, MAXIMUM_JERK,
&Done, &Busy, &CommandAborted, &Error, &ErrorID);
Sleep(100);
MC_Stop(Index, &QueueIndex, FALSE, MAXIMUM_DECELERATION, MAXIMUM_JERK,
&Done, &Busy, &CommandAborted, &Error, &ErrorID);
3.x Motion board style:
Cancelling commands in not available in this API style. There was no axis lock method like MC_Stop as StopServo corresponds to HaltAxis and QuickStopServo corresponds to a power off.
4.x:
KsCommandStatus status = JogAxis(Index, MAXIMUM_VELOCITY, MAXIMUM_ACCELERATION,
MAXIMUM_DECELERATION, MAXIMUM_JERK, mcNegativeDirection);
Sleep(2000);
KsCommandStatus status = StopAxis(Index, MAXIMUM_DECELERATION, MAXIMUM_JERK));
Sleep(100);
AbortCommand(status);
- Wait a command to be completed.
3.x PLCopen style:
MC_MoveRelative(Index, &QueueIndex1, FALSE, 5000, MAXIMUM_VELOCITY,
MAXIMUM_ACCELERATION, MAXIMUM_DECELERATION, MAXIMUM_JERK,
mcBuffered, &Done, &Busy, &Active, &CommandAborted,
&Error, &ErrorID);
while (Timeout < 1000 && !Error && !Done && !CommandAborted)
{
Sleep(50);
MC_MoveRelative(Index, &QueueIndex1, FALSE, 5000, MAXIMUM_VELOCITY,
MAXIMUM_ACCELERATION, MAXIMUM_DECELERATION, MAXIMUM_JERK, mcBuffered,
&Done, &Busy, &Active, &CommandAborted, &Error, &ErrorID);
Timeout++;
}
if (Timeout >= 1000)
RtPrintf("MC_MoveRelative Timeout\n.");
3.x Motion board style:
INT nRet = MoveServoAbsolute(Index, Target);
INT Timeout = 0;
MotionStatus motionStatus = motionAcc;
nRet = GetServoMotionStatus(Index, &motionStatus);
while (motionStatus > motionStopped && Timeout < 100)
{
Sleep(50);
nRet = GetServoMotionStatus(Index, &motionStatus);
Timeout++;
}
4.x:
KsCommandStatus move = WaitForCommand(30, TRUE, MoveAxisAbsolute(Index, Target,
MAXIMUM_VELOCITY, MAXIMUM_ACCELERATION, MAXIMUM_DECELERATION, MAXIMUM_JERK,
mcNegativeDirection, mcAborting));
//or
KsCommandStatus move = MoveAxisAbsolute(Index, Target, MAXIMUM_VELOCITY,
MAXIMUM_ACCELERATION, MAXIMUM_DECELERATION, MAXIMUM_JERK,
mcNegativeDirection, mcAborting);
move = WaitForCommand(30, TRUE, move);