Axis Straight Line Move

Usage

status = nimcAxisStraightLineMove(TnimcDeviceHandle deviceHandle, TnimcAxisHandle axisHandle, TnimcAxisStraightLineMoveData* data, TnimcMoveConstraints* moveConstraints);

Purpose

Performs a straight line move on an axis.

Parameters

Parameter Discussion

axisHandle is the axis to read with this function. Valid values are 1 through 15. On motion controllers that support fewer than fifteen axes, reading non-existent axes returns error –70006 (NIMC_badResourceIDOrAxisError).

data is the data record containing straight line move information in the following structure:

struct{
   u32 size;
   TnimcAxisStraightLineMoveStartMode startMode;
   TnimcAxisStraightLineMovePositionMode positionMode;
   f64 targetPosition;
} TnimcAxisStraightLineMoveData;

TnimcAxisStraightLineMoveStartMode is an enum with the following attributes:

TnimcAxisStraightLineMovePositionMode is an enum with the following attributes. Refer to Using This Function for more information about the available position modes.

targetPosition is the target position for the straight line move in counts (servo axes) or steps (stepper axes).

moveConstraints contains move constraint information in the following structure:

struct{
   u32 size;
   f64 velocity; //velocity in counts/s or steps/s
   f64 acceleration; //acceleration in counts/s^2 or steps/s^2
   f64 deceleration; //deceleration in counts/s^2 or steps/s^2
   f64 accelerationJerk; //jerk in counts/s^3 or steps/s^3
   f64 decelerationJerk; //jerk in counts/s^3 or steps/s^3
} TnimcMoveConstraints;

Note  accelerationJerk and decelerationJerk are not supported at this time. Use Load S-Curve Time or Load Move Constraints to configure S-curve values.

Using This Function

Use this function to perform a straight line move on an axis. The position modes are described in the following sections:

Absolute Position Mode

In absolute position mode, target positions are interpreted with respect to an origin, reference, or zero position. The origin is typically set at a home switch, end of travel limit switch, or encoder index position. An absolute position move uses the specified values of acceleration, deceleration, and velocity to complete a trajectory profile with an ending position equal to the specified absolute target position.

Caution  Any single move is limited to between –231 and 231–1 counts or steps. An error is generated if you exceed this limit by specifying a target position too far from the current position.

The length of an absolute move depends upon the specified position and the current position when the move is started. If the target position is the same as the current position, no move occurs.

Relative Position Mode

In relative position mode, if a relative position move is started while motion is not in progress, specified target positions are interpreted with respect to the current position at the time the value is specified. A relative position move uses the specified values of acceleration, deceleration, and velocity to complete a trajectory profile with an ending position equal to the sum of the specified relative target position and the starting position.

If a relative move is started while motion is in progress, the new target position is calculated with respect to the target position of the move already in progress (considered to be the new starting position), as if that move had already completed successfully. Motion continues to the new relative position, independent of the actual position location when the new move is started.

Velocity Mode

In velocity mode, the axis moves at the specified velocity until you execute a Stop Motion function, a limit is encountered, or a new velocity is specified and you execute a Start Motion function. Specified target positions have no effect in velocity mode. The direction of motion is determined by the sign of the specified velocity.

You can update velocity at any time to accomplish velocity profiling. Changes in velocity while motion is in progress use the specified acceleration and deceleration values to control the change in velocity. You can reverse direction by changing the sign of the specified velocity.

Example

To call this function to start an absolute move with a target position of 1000 counts or steps, a velocity of 100 counts/s or steps/s, and an acceleration and deceleration of 50 counts/s or steps/s on axis 2, use the following syntax:

TnimcAxisStraightLineMoveData data;
data.size = sizeof(TnimcAxisStraightLineMoveData);
data.targetPosition = 1000.0;
data.startMode = TnimcAxisStraightLineMoveStartModeStart;
data.positionMode = TnimcAxisStraightLineMovePositionModeAbsolute;

TnimcMoveConstraints moveConstraints;
moveConstraints.size = sizeof(TnimcMoveConstraints);
moveConstraints.velocity = 100.0;
moveConstraints.acceleration = 50.0;
moveConstraints.deceleration = 50.0;

nimcAxisStraightLineMove(boardID, 2, &data, &moveConstraints);

Note  You must specify the value for the size elements of data and moveConstraints before calling this function. If you do not properly set the size elements, the function will return error –70023 (NIMC_parameterValueError).

Note  Refer to Function Execution Times for benchmark timing information about your controller.