| ApossC SDK V01.15

Functions
SDK_Axis_Setup.mh File Reference

Declaration of the axis setup function. More...

Go to the source code of this file.

## Functions
long | sdkSetupPositionPIDControl (long axis, long kprop, long kint, long kder)
| Set parameters for PID position control loop. More...
long | sdkSetupPositionPIDControlExt (long axis, long kprop, long kint, long kder, long kilim, long kilimtime, long bandwidth, long ffvel, long kffacc, long kffdec)
| Set extended parameters for PID position control loop. More...
long | sdkSetupAxisUserUnits (long axis, long posencrev, long posencqc, long posfact_z, long posfact_n, long feedrev, long feeddist)
| Setup to convert the resolution of the machine in user units. More...
long | sdkSetupAxisMovementParam (long axis, long velres, long maxRpm, long ramptype, long rampmin, long jerkmin, long poserr)
| Defines parameters which are required for the calculation of ramps and velocities. More...
long | sdkSetupAxisJerkLimited (long axis, long jerkmin1, long jerkmin2, long jerkmin3, long jerkmin4)
| Definition of the jerk limited extended parameter. More...
long | sdkSetupAxisDirection (long axis, long posdrct)
| Definition of the rotation direction of the axis. More...
long | skdSetupAxisSoftwareLimit (long axis, long negLimitUu, long posLimitUu)
| Setting up a software axis limitation in user units. More...
long | skdEnableAxisSoftwareLimit (long axis, long active)
| Activation of the axis software limits. More...

## Detailed Description

Declaration of the axis setup function.

Revision
  271

Definition in file SDK_Axis_Setup.mh.

## Function Documentation

## ◆ sdkSetupAxisDirection()

long sdkSetupAxisDirection | ( | long | axis,
|  | long | posdrct
| ) |  |

Definition of the rotation direction of the axis.

The application defines what is a forward and backward movement of the motor. With the help of this function this definition can be adjusted.

Parameters

  axis | Axis module number
  posdrct | Parameter to set the rotation direction (default 0) 1 Normal direction -1 Invert direction

Returns
  value: Process value
  value > 0 Process successful
  value = 0 Process is active
  value < 0 Error

Definition at line 186 of file SDK_Axis_Setup.mc.

187 {
188 // Set rotation direction
189 if (posdrct==1 || posdrct==-1 )
190 {
191 VIRTAMP_PARAM(axis,VIRTAMP_INVERT)=posdrct;
192 VIRTCOUNTIN_PARAM(axis,VIRTCNTIN_UUFACT_UNITNO)=posdrct;
193 }
194 else // Error
195 {
196 print("SDK Error: not supported rotation direction");
197 return(-1);
198 }
199
200 return(1);
201 }

## ◆ sdkSetupAxisJerkLimited()

long sdkSetupAxisJerkLimited | ( | long | axis,
|  | long | jerkmin1,
|  | long | jerkmin2,
|  | long | jerkmin3,
|  | long | jerkmin4
| ) |  |

Definition of the jerk limited extended parameter.

Function to set the extended jerk limited parameters. This topic is described in the ApossIDE Help on the page "Limited Jerk". If the parameters JERKMIN2 - 4 are set to the value 0, the jerk limit is taken from the parameter JERKMIN.

Parameters

  axis | Axis module number
  jerkmin1 | Defines the minimum time [ms] required before reaching the maximum acceleration (default 100)
  jerkmin2 | Defines the minimum time [ms] required to ramp the acceleration down from maximum acceleration to 0 (default 0)
  jerkmin3 | Defines the minimum time [ms] required to ramp the deceleration up from 0 to maximum deceleration (default 0)
  jerkmin4 | Defines the minimum time [ms] required to ramp the deceleration down from maximum deceleration to 0 (default 0)

Returns
  value: Always 1 in this function
  value > 0 Process successful
  value = 0 Process is active
  value < 0 Error

Definition at line 162 of file SDK_Axis_Setup.mc.

163 {
164 AXE_PARAM(axis, RAMPTYPE) = RAMPTYPE_JERKLIMITED; // Ramp type: Jerk limited
165 AXE_PARAM(axis, JERKMIN) = jerkmin1;
166 AXE_PARAM(axis, JERKMIN2) = jerkmin2;
167 AXE_PARAM(axis, JERKMIN3) = jerkmin3;
168 AXE_PARAM(axis, JERKMIN4) = jerkmin4;
169
170 return(1);
171 }

## ◆ sdkSetupAxisMovementParam()

long sdkSetupAxisMovementParam | ( | long | axis,
|  | long | velres,
|  | long | maxRpm,
|  | long | ramptype,
|  | long | rampmin,
|  | long | jerkmin,
|  | long | poserr
| ) |  |

Defines parameters which are required for the calculation of ramps and velocities.

The function sets all basic parameters which are needed for the calculation of the ramps and velocities.

Parameters

  axis | Axis module number
  velres | Velocity resolution, Scaling used for the velocity and acceleration/deceleration commands (default 100)
  maxRpm | Defines the rated speed of the drive. This value is listed in RPM (default 1000)
  ramptype | Defines the ramptype (default 0) 0 RAMPTYPE_TRAPEZ: Trapezoid ramp 2 RAMPTYPE_JERKLIMITED: Jerk limited ramp
  rampmin | Maximum acceleration (default 1000)
  jerkmin | Minimum time (ms) required before reaching the maximum acceleration (default 100) just usefull for ramptype "RAMPTYPE_JERKLIMITED"
  poserr | The Maximum Tolerated Position Error POSERR defines the tolerance allowed between the current actual position and the calculated command position (default 20000)

Returns
  value: Always 1 in this function
  value > 0 Process successful
  value = 0 Process is active
  value < 0 Error

Definition at line 136 of file SDK_Axis_Setup.mc.

137 {
138 AXE_PARAM(axis, VELRES) = velres; // Velocity resolution
139 AXE_PARAM(axis, VELMAX) = maxRpm; // Rated speed of drive
140 AXE_PARAM(axis, RAMPTYPE) = ramptype; // Ramp type
141 AXE_PARAM(axis, RAMPMIN) = rampmin; // Maximum acceleration
142 AXE_PARAM(axis, JERKMIN) = jerkmin; // Minimum time required before reaching the maximum acceleration
143 AXE_PARAM(axis, POSERR) = poserr; // Maximum tolerated position error
144
145 return(1);
146 }

## ◆ sdkSetupAxisUserUnits()

long sdkSetupAxisUserUnits | ( | long | axis,
|  | long | posencrev,
|  | long | posencqc,
|  | long | posfact_z,
|  | long | posfact_n,
|  | long | feedrev,
|  | long | feeddist
| ) |  |

Setup to convert the resolution of the machine in user units.

The basic resolution of the entire machine is 1 encoder quadcount. Using the above formula, this can be converted to the resolution of the machine in user units. This is the highest precision to which an application may specify positions. For example, if 1 uu equals 10 qc, then the command "AxisPosRelStart(0,1);" will move the motor foward by 10 qc; it will not be possible for the application program to move the motor by only 5 qc. Conversely, if the motor moves forward by only 1 qc, then the Apos command is likely to return the same actual position value even though the motor has moved to a new position; the application program will be unable to differentiate between these two motor positions. More information are available in the Help of ApossIDE: "How to Set Up Resolution and Gear Parameters".

Parameters

  axis | Axis module number
  posencrev | Number of revolutions of the motor
  posencqc | Number of quadcounts in POSENCREV revolutions
  posfact_z | Number of revolutions of the input shaft
  posfact_n | Number of revolutions of the output shaft in POSFACT_Z revolutions of the input shaft
  feedrev | Number of revolutions of the gear box output shaft
  feeddist | Distance travelled (in user units) in FEEDREV revolutions of the gear box output shaft

Returns
  value: Always 1 in this function
  value > 0 Process successful
  value = 0 Process is active
  value < 0 Error

Definition at line 104 of file SDK_Axis_Setup.mc.

105 {
106 AXE_PARAM(axis,POSENCREV) = posencrev; // Number of revolutions of the motor
107 AXE_PARAM(axis,POSENCQC) = posencqc; // Number of quadcounts in POSENCREV revolutions
108 AXE_PARAM(axis,POSFACT_Z) = posfact_z; // Number of revolutions of the input shaft
109 AXE_PARAM(axis,POSFACT_N) = posfact_n; // Number of revolutions of the output shaft in POSFACT_Z revolutions of the input shaft
110 AXE_PARAM(axis,FEEDREV) = feedrev; // Number of revolutions of the gear box output shaft
111 AXE_PARAM(axis,FEEDDIST) = feeddist; // Distance travelled (in user units) in FEEDREV revolutions of the gear box output shaft
112
113 return(1);
114 }

## ◆ sdkSetupPositionPIDControl()

long sdkSetupPositionPIDControl | ( | long | axis,
|  | long | kprop,
|  | long | kint,
|  | long | kder
| ) |  |

Set parameters for PID position control loop.

The function sets the basic factors of the position PID controller. With the function sdkSetupPositionPIDControlExt() the extended factors of the position controller can be set. More information are available in the Help of ApossIDE in the topic "Control Loop Design".

Parameters

  axis | Axis module number
  kprop | Proportional value for PID position control loop (default 30)
  kint | Integral value for PID position control loop (default 0)
  kder | Derivative value for PID position control loop (default 0)

Returns
  value: Always 1 in this function
  value > 0 Process successful
  value = 0 Process is active
  value < 0 Error

Definition at line 36 of file SDK_Axis_Setup.mc.

37 {
38 // Parameters for position controller
39 AXE_PARAM(axis, KPROP) = kprop; // position-controller proportional factor: 1 … 65000
40 AXE_PARAM(axis, KINT) = kint; // position-controller integral factor: 0 … 65000
41 AXE_PARAM(axis, KDER) = kder; // position-controller differencial factor: 0 … 65000
42
43 return(1);
44 }

## ◆ sdkSetupPositionPIDControlExt()

long sdkSetupPositionPIDControlExt | ( | long | axis,
|  | long | kprop,
|  | long | kint,
|  | long | kder,
|  | long | kilim,
|  | long | kilimtime,
|  | long | bandwidth,
|  | long | ffvel,
|  | long | kffacc,
|  | long | kffdec
| ) |  |

Set extended parameters for PID position control loop.

The function sets the extended factors of the position PID controller. With the function sdkSetupPositionPIDControl() the basic factors of the position controller can be set. More information are available in the Help of ApossIDE in the topic "Control Loop Design".

Parameters

  axis | Axis module number
  kprop | Proportional value for PID position control loop (default 30)
  kint | Integral value for PID position control loop (default 0)
  kder | Derivative value for PID position control loop (default 0)
  kilim | Limit value for the integral sum of the PID position control loop (default 1000)
  kilimtime | Time used to increase or decrease the integral limit (default 0)
  bandwidth | Bandwidth within which the PID filter is active. 1000 equals to 100% velocity setpoint (default 1000)
  ffvel | Velocity Feed forward (default 0)
  kffacc | Acceleration Feed forward (default 0)
  kffdec | Deceleration Feed Forward (default 0)

Returns
  value: Always 1 in this function
  value > 0 Process successful
  value = 0 Process is active
  value < 0 Error

Definition at line 65 of file SDK_Axis_Setup.mc.

66 {
67 // Parameters for position controller
68 AXE_PARAM(axis, KPROP) = kprop; // position-controller proportional factor: 1 … 65000
69 AXE_PARAM(axis, KINT) = kint; // position-controller integral factor: 0 … 65000
70 AXE_PARAM(axis, KDER) = kder; // position-controller differencial factor: 0 … 65000
71
72 AXE_PARAM(axis, KILIM) = kilim; // position-controller limits the integral sum: 0 … 65000
73 AXE_PARAM(axis, KILIMTIME) = kilimtime;// position-controller Time used to for integral limit: -10000…10000
74 AXE_PARAM(axis, BANDWIDTH) = bandwidth;// position-controller Bandwidth of the PID filter: 0 … 2000
75 AXE_PARAM(axis, FFVEL) = ffvel; // position-controller Velocity Feed forward: 0…100000
76 AXE_PARAM(axis, KFFACC) = kffacc; // position-controller Acceleration Feed Forward: 0 … 8000
77 AXE_PARAM(axis, KFFDEC) = kffdec; // position-controller Deceleration Feed Forward: 0 … 8000
78
79 return(1);
80 }

## ◆ skdEnableAxisSoftwareLimit()

long skdEnableAxisSoftwareLimit | ( | long | axis,
|  | long | active
| ) |  |

Activation of the axis software limits.

This function enables or disables the software limits set with the xy function skdSetupAxisSoftwareLimit().

Parameters

  axis | Axis module number
  active | Parameter to enable / disable the software limit 0 Disable software limit 1 Enable software limit

Returns
  value: Process value
  value > 0 Process successful
  value = 0 Process is active
  value < 0 Error

Definition at line 238 of file SDK_Axis_Setup.mc.

239 {
240 if(active == 0)
241 {
242 AXE_PARAM(axis,SWPOSLIMACT) = active;
243 AXE_PARAM(axis,SWNEGLIMACT) = active;
244 print("Disable software limit axis ", axis);
245 }
246 else
247 {
248 AXE_PARAM(axis,SWPOSLIMACT) = 1;
249 AXE_PARAM(axis,SWNEGLIMACT) = 1;
250 print("Enable software limit axis ", axis);
251 }
252
253 return(1);
254 }

## ◆ skdSetupAxisSoftwareLimit()

long skdSetupAxisSoftwareLimit | ( | long | axis,
|  | long | negLimitUu,
|  | long | posLimitUu
| ) |  |

Setting up a software axis limitation in user units.

For additional safety a software axis limit can be set. This function is for setting the limits and must be activated with the function skdEnableAxisSoftwareLimit(). The limit is set in user units.

Parameters

  axis | Axis module number
  negLimitUu | Negative axis limit [Uu]
  posLimitUu | Positive axis limit [Uu]

Returns
  value: Always 1 in this function
  value > 0 Process successful
  value = 0 Process is active
  value < 0 Error

Definition at line 215 of file SDK_Axis_Setup.mc.

216 {
217 AXE_PARAM(axis,NEGLIMIT) = negLimitUu * ((double)(AXE_PARAM(axis,FEEDREV)*AXE_PARAM(axis,POSFACT_Z)*AXE_PARAM(axis,POSENCQC))/((double)AXE_PARAM(axis,FEEDDIST)*AXE_PARAM(axis,POSFACT_N)*AXE_PARAM(axis,POSENCREV)));
218 AXE_PARAM(axis,POSLIMIT) = posLimitUu * ((double)(AXE_PARAM(axis,FEEDREV)*AXE_PARAM(axis,POSFACT_Z)*AXE_PARAM(axis,POSENCQC))/((double)AXE_PARAM(axis,FEEDDIST)*AXE_PARAM(axis,POSFACT_N)*AXE_PARAM(axis,POSENCREV)));
219 print("Set negative software limit to ", AXE_PARAM(axis,NEGLIMIT), " qc");
220 print("Set positive software limit to ", AXE_PARAM(axis,POSLIMIT), " qc");
221 return(1);
222 }
RAMPTYPE
#define RAMPTYPE
Ramp type.
Definition: SdoDictionary.mh:2610
VIRTCOUNTIN_PARAM
#define VIRTCOUNTIN_PARAM(modno, parno)
Virtual Counter Inputs parameters: Setter.
Definition: SdoDictionary.mh:4985
POSFACT_Z
#define POSFACT_Z
User factor numerator.
Definition: SdoDictionary.mh:2528
JERKMIN2
#define JERKMIN2
Minimum time required to ramp the acceleration down from maximum acceleration to 0.
Definition: SdoDictionary.mh:2947
VELMAX
#define VELMAX
Rated speed of drive.
Definition: SdoDictionary.mh:2308
KFFDEC
#define KFFDEC
Deceleration Feed Forward.
Definition: SdoDictionary.mh:3111
KILIMTIME
#define KILIMTIME
Time used to increase or decrease the integral limit.
Definition: SdoDictionary.mh:2983
KDER
#define KDER
Derivative Factor for PID position control loop.
Definition: SdoDictionary.mh:2413
POSERR
#define POSERR
Maximum tolerated position error.
Definition: SdoDictionary.mh:2444
FEEDREV
#define FEEDREV
Feed revolutions.
Definition: SdoDictionary.mh:3022
SWPOSLIMACT
#define SWPOSLIMACT
Positive software end limit active.
Definition: SdoDictionary.mh:2498
NEGLIMIT
#define NEGLIMIT
Negative software limit position.
Definition: SdoDictionary.mh:2331
POSENCREV
#define POSENCREV
Encoder resolution revolution count.
Definition: SdoDictionary.mh:3045
POSENCQC
#define POSENCQC
Encoder resolution quadcount.
Definition: SdoDictionary.mh:3035
VIRTAMP_PARAM
#define VIRTAMP_PARAM(modno, parno)
Virtual Amplifier Parameters: Setter.
Definition: SdoDictionary.mh:5280
RAMPMIN
#define RAMPMIN
Maximum acceleration.
Definition: SdoDictionary.mh:2601
FEEDDIST
#define FEEDDIST
Feed distance.
Definition: SdoDictionary.mh:3011
JERKMIN4
#define JERKMIN4
Minimum time required to ramp the deceleration down from maximum deceleration to 0.
Definition: SdoDictionary.mh:2969
KILIM
#define KILIM
Limit value for the integral sum of the PID position control loop.
Definition: SdoDictionary.mh:2507
JERKMIN
#define JERKMIN
Minimum time required before reaching the maximum acceleration.
Definition: SdoDictionary.mh:2936
VIRTAMP_INVERT
#define VIRTAMP_INVERT
Output reference reversion.
Definition: SdoDictionary.mh:5467
AXE_PARAM
#define AXE_PARAM(modno, parno)
Axis Parameters: Setter.
Definition: SdoDictionary.mh:2293
RAMPTYPE_JERKLIMITED
#define RAMPTYPE_JERKLIMITED
Definition: SdoDictionary.mh:3157
SWNEGLIMACT
#define SWNEGLIMACT
Negative software end limit active.
Definition: SdoDictionary.mh:2487
KFFACC
#define KFFACC
Acceleration Feed Forward.
Definition: SdoDictionary.mh:3102
POSFACT_N
#define POSFACT_N
User factor denominator.
Definition: SdoDictionary.mh:2561
VIRTCNTIN_UUFACT_UNITNO
#define VIRTCNTIN_UUFACT_UNITNO
Conversion Factor - number of user units.
Definition: SdoDictionary.mh:5067
JERKMIN3
#define JERKMIN3
Minimum time required to ramp the deceleration up from 0 to maximum deceleration.
Definition: SdoDictionary.mh:2958
VELRES
#define VELRES
Velocity resolution.
Definition: SdoDictionary.mh:2517
FFVEL
#define FFVEL
Velocity Feed forward.
Definition: SdoDictionary.mh:2644
KPROP
#define KPROP
Proportional value for PID position control loop.
Definition: SdoDictionary.mh:2404
POSLIMIT
#define POSLIMIT
Positive software limit position.
Definition: SdoDictionary.mh:2342
KINT
#define KINT
Integral value for PID position control loop.
Definition: SdoDictionary.mh:2422
BANDWIDTH
#define BANDWIDTH
Bandwidth within which the PID filter is active.
Definition: SdoDictionary.mh:2635

Data Sheets | Released Software | Software Manuals | Hardware Manuals | Maxon Shop

Maxon Support Center