Allen-Bradley Ultra5000 Owner's manual

Ultra5000
™
C Programming using the
Motion Library
Programming Manual

Important User Information
Because of the variety of uses for the products described in this
publication, those responsible for the application and use of this
control equipment must satisfy themselves that all necessary steps
have been taken to assure that each application and use meets all
performance and safety requirements, including any applicable laws,
regulations, codes and standards.
The illustrations, charts, sample programs and layout examples shown
in this guide are intended solely for purposes of example. Since there
are many variables and requirements associated with any particular
installation, Allen-Bradley does not assume responsibility or liability
(to include intellectual property liability) for actual use based upon
the examples shown in this publication.
Allen-Bradley publication SGI-1.1, Safety Guidelines for the
Application, Installation and Maintenance of Solid-State Control
(available from your local Allen-Bradley office), describes some
important differences between solid-state equipment and
electromechanical devices that should be taken into consideration
when applying products such as those described in this publication.
Reproduction of the contents of this copyrighted publication, in whole
or part, without written permission of Rockwell Automation, is
prohibited.
Throughout this manual we use notes to make you aware of safety
considerations:
Attention statements help you to:
• identify a hazard
• avoid a hazard
• recognize the consequences
Allen-Bradley is a registered trademark of Rockwell Automation, Inc.
Ultra3000, Ultra5000 and Ultraware are trademarks of Rockwell Automation, Inc.
ATTENTION
!
Identifies information about practices or
circumstances that can lead to personal injury or
death, property damage or economic loss.
IMPORTANT Identifies information that is critical for successful
application and understanding of the product.

iPublication 2098-PM001E-EN-P — July 2002
Table of Contents
Preface
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-1
Who Should Use this Manual. . . . . . . . . . . . . . . . . . . . . . . P-1
Where to Find Help . . . . . . . . . . . . . . . . . . . . . . . . . . . P-1
Contents of this Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . P-2
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . P-2
Conventions Used in this Manual. . . . . . . . . . . . . . . . . . . . P-2
Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-3
Allen-Bradley Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-3
Local Product Support . . . . . . . . . . . . . . . . . . . . . . . . . P-3
Technical Product Assistance . . . . . . . . . . . . . . . . . . . . P-3
Chapter 1
Programming Motion Control
in C
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Creating A Basic Motion Program . . . . . . . . . . . . . . . . . . . 1-1
Creating and Running a Program . . . . . . . . . . . . . . . . . 1-2
Example 1 - A Basic Motion Program . . . . . . . . . . . . . . . . . . . . 1-2
Example 1 Explained. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Variables, Loops, and Constants . . . . . . . . . . . . . . . . . . 1-5
Example 2.1 - A Motion Program Using Variables . . . . . . . . . . . 1-5
Example 2.1 Explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Example 2.2 - Varying the Program using Variables . . . . . . . . . 1-8
Example 2.2 Explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Example 2.3 - Another Variance of the Program using Variables . .
1-10
Example 2.3 Explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
User Defined Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Example 3 - Nested Functions in a Motion Program . . . 1-11
Example 3 Explained . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Program Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Example 4 - A Jog Program . . . . . . . . . . . . . . . . . . . . . 1-14
Example 5 - A Gear Program . . . . . . . . . . . . . . . . . . . . 1-15
Homing with Latch Functions . . . . . . . . . . . . . . . . . . . . . . 1-16
Example 6 - A Homing Program . . . . . . . . . . . . . . . . . . 1-16
Non-Volatile Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Example 7 - A Non-Volatile Array Program . . . . . . . . . . 1-17
Types, Operators, and Expressions . . . . . . . . . . . . . . . . . . 1-18
Variable Names and Data Types/Sizes . . . . . . . . . . . . . 1-18
Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Relational and Logical Operators . . . . . . . . . . . . . . . . . . . . 1-21
Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Operator Precedence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
Control Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23

Publication 2098-PM001E-EN-P — July 2002
ii Table of Contents
Statements and Blocks . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
Example 8 - Grouping Statements. . . . . . . . . . . . . . . . . 1-23
If-Else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24
Else-If . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24
Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26
While, For and Do-While Loops . . . . . . . . . . . . . . . . . . 1-26
Break and Continue . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-27
Chapter 2
Referencing the Motion Library Control Setting Functions. . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Axis Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
long AxisDefinePos(long position); . . . . . . . . . . . . . . . . . . . . . 2-4
float AxisGetCommandCur(void);. . . . . . . . . . . . . . . . . . . . . . . 2-4
long AxisGetCommandPos(void);. . . . . . . . . . . . . . . . . . . . . . . 2-4
float AxisGetCommandVel(void); . . . . . . . . . . . . . . . . . . . . . . . 2-4
long AxisGetFeedbackOffset(void); . . . . . . . . . . . . . . . . . . . . . 2-4
long AxisGetFeedbackPos(void); . . . . . . . . . . . . . . . . . . . . . . . 2-4
float AxisGetFeedbackVel(void); . . . . . . . . . . . . . . . . . . . . . . . 2-5
float AxisGetFGain(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
float AxisGetIGain(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
float AxisGetKff(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
float AxisGetKp(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
float AxisGetLowerCurLimit(void); . . . . . . . . . . . . . . . . . . . . . . 2-5
float AxisGetPGain(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
long AxisGetPosError(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
float AxisGetUpperCurLimit(void); . . . . . . . . . . . . . . . . . . . . . . 2-5
float AxisGetVelError(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
long AxisSetFeedbackOffset(long offset); . . . . . . . . . . . . . . . . . 2-6
long AxisSetFGain(float fgain); . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
long AxisSetIGain(float igain); . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
long AxisSetKff(float kff);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
long AxisSetKp(float kp); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
long AxisSetLowerCurLimit(float limit);. . . . . . . . . . . . . . . . . . . 2-6
long AxisSetPGain(float pgain); . . . . . . . . . . . . . . . . . . . . . . . . 2-6
long AxisSetUpperCurLimit(float limit);. . . . . . . . . . . . . . . . . . . 2-7
Axis Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
long AxisDisable(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
long AxisEnable(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
long AxisResetPosLimit(void); . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
long AxisSoftLimitDisable(void);. . . . . . . . . . . . . . . . . . . . . . . . 2-8
long AxisSoftLimitEnable(void); . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Axis Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
long AxisIsEnabled(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
long AxisIsReady(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
long AxisPosLimitGetStatus (void); . . . . . . . . . . . . . . . . . . . . . . 2-9
long AxisPosLimitIsTriggered (void); . . . . . . . . . . . . . . . . . . . . 2-9

Publication 2098-PM001E-EN-P — July 2002
Table of Contents iii
Control Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
long ControlGetFault(void); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
long EncoderGetFaultState(long channel); . . . . . . . . . . . . . . . 2-11
long EncoderGetOutput(long channel); . . . . . . . . . . . . . . . . . 2-11
long EncoderGetPos(long channel); . . . . . . . . . . . . . . . . . . . . 2-11
float RatchetGetVel(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Control Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
long ControlClearFault(void); . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
long EncoderDisableFault(long channel); . . . . . . . . . . . . . . . . 2-12
long EncoderEnableFault(long channel);. . . . . . . . . . . . . . . . . 2-12
long EncoderSetPolarity(long channel, long polarity); . . . . . . . 2-13
long RatchetSetMode(long mode); . . . . . . . . . . . . . . . . . . . . . 2-13
long SequencerAddNode(long frame, void* fptr, void* dptr); . . 2-14
long SequencerRemoveNodes(void* dptr); . . . . . . . . . . . . . . . 2-14
Program Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
long InitMotionLibrary(void); . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
long ProgramKill(char* name); . . . . . . . . . . . . . . . . . . . . . . . . 2-15
long ProgramRun(char* name); . . . . . . . . . . . . . . . . . . . . . . . 2-15
long ProgramStop(char* name); . . . . . . . . . . . . . . . . . . . . . . . 2-15
long Sleep(long ms); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Program Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
long ProgramIsRunning(char* name); . . . . . . . . . . . . . . . . . . . 2-16
long StopRequested(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Serial Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
long SerialClose(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
char SerialGetChar(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
long SerialOpen(long baudrate); . . . . . . . . . . . . . . . . . . . . . . 2-16
char SerialPutChar(char character);. . . . . . . . . . . . . . . . . . . . . 2-16
long SerialPutString(const char *string); . . . . . . . . . . . . . . . . . 2-17
Serial Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
long SerialClearToSend(void); . . . . . . . . . . . . . . . . . . . . . . . . 2-17
long SerialDataReady(void); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
long SerialReceiverFull(void);. . . . . . . . . . . . . . . . . . . . . . . . . 2-17
long SerialTransmitterEmpty(void);. . . . . . . . . . . . . . . . . . . . . 2-17
Timer Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
long TimerAccumulated(long channel); . . . . . . . . . . . . . . . . . 2-17
long TimerEnable(long channel, long preset);. . . . . . . . . . . . . 2-17
Timer Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
long TimerDone(long channel); . . . . . . . . . . . . . . . . . . . . . . . 2-18
Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
Cam Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
long CamGetCycleCount(void); . . . . . . . . . . . . . . . . . . . . . . . 2-22
long CamGetCycleLimit(void); . . . . . . . . . . . . . . . . . . . . . . . . 2-22
long CamGetFreeSegments(void);. . . . . . . . . . . . . . . . . . . . . . 2-22
long CamSetCycleLimit(long limit); . . . . . . . . . . . . . . . . . . . . . 2-23
Cam Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23

Publication 2098-PM001E-EN-P — July 2002
iv Table of Contents
long CamCloseTable(void); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
long CamConstantVelocity(long master_position, long
follower_position); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
long CamCycloidal(long master_position, long follower_position);
2-24
long CamCycloidalHarmonic(long master_position, long
follower_position); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25
long CamDisable(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26
long CamDwell(long master_position); . . . . . . . . . . . . . . . . . . 2-26
long CamEnable(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26
long CamHarmonic(long master_position,long follower_position);.
2-27
long CamHarmonicCycloidal(long master_position, long
follower_position); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
long CamLoad(char* name);. . . . . . . . . . . . . . . . . . . . . . . . . . 2-29
long CamLoadTable(long table_number,char *name); . . . . . . . 2-29
long CamModifiedSinusoidal(long master_position,long
follower_position); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30
long CamModifiedTrapezoidal(long master_position,long
follower_position); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31
long CamOpenTable(long table_number,long size,long order); 2-32
long CamPhaseAbort(void); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32
long CamPhaseAdvance(long distance,float time);. . . . . . . . . . 2-32
long CamPhaseRetard(long distance,float time); . . . . . . . . . . . 2-32
long CamQueueReset(void); . . . . . . . . . . . . . . . . . . . . . . . . . 2-33
long CamQueueTable(long table_number,long cycle_limit); . . 2-33
long CamSaveTable(long table_number,char *name); . . . . . . . 2-34
long CamSpline(long master_position,long follower_position,float
initial_ratio,float final_ratio);. . . . . . . . . . . . . . . . . . . . . . . . . . 2-34
long CamUnloadTable(long table_number); . . . . . . . . . . . . . . 2-34
Cam Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35
long CamIsEnabled(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35
long CamPhaseInProgress(void); . . . . . . . . . . . . . . . . . . . . . . 2-35
long CamQueueFull(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35
Gear Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-36
float GearGetVel(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-36
long GearSetRatio(float ratio); . . . . . . . . . . . . . . . . . . . . . . . . 2-36
long GearSlewSetAcc(float acc); . . . . . . . . . . . . . . . . . . . . . . . 2-36
long GearSlewSetDec(float dec); . . . . . . . . . . . . . . . . . . . . . . 2-36
Gear Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-36
long GearDisable(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-36
long GearEnable(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-36
long GearSlewDisable(void); . . . . . . . . . . . . . . . . . . . . . . . . . 2-37
long GearSlewEnable(void);. . . . . . . . . . . . . . . . . . . . . . . . . . 2-37
Gear Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37
long GearAtSpeed(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37

Publication 2098-PM001E-EN-P — July 2002
Table of Contents v
long GearInProgress(void); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37
long GearIsEnabled(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37
Jog Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37
long JogSetAcc(float acc); . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37
long JogSetDec(float dec); . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38
long JogSetVel(float vel); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38
Jog Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38
long JogAbort(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38
long JogForward(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38
long JogReverse(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38
long JogStop(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39
Jog Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39
long JogAtSpeed(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39
long JogGetMode(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39
long JogGetState(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39
long JogInProgress(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40
Move Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40
long MoveSetAcc(float acc); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40
long MoveSetDec(float dec); . . . . . . . . . . . . . . . . . . . . . . . . . 2-40
long MoveSetPos(long position); . . . . . . . . . . . . . . . . . . . . . . 2-40
long MoveSetVel(float vel); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40
Move Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-41
long MoveAbort(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-41
long MoveAbsolute(long position);. . . . . . . . . . . . . . . . . . . . . 2-41
long MoveCloseBuffer(void); . . . . . . . . . . . . . . . . . . . . . . . . . 2-41
long MoveCorrect(long distance);. . . . . . . . . . . . . . . . . . . . . . 2-41
long MoveCorrectAbs(long position); . . . . . . . . . . . . . . . . . . . 2-42
long MoveCorrectInc(long distance); . . . . . . . . . . . . . . . . . . . 2-42
long MoveDistance(long distance);. . . . . . . . . . . . . . . . . . . . . 2-42
long MoveDV(long distance, float vel);. . . . . . . . . . . . . . . . . . 2-43
long MoveDVS(long distance, float vel); . . . . . . . . . . . . . . . . . 2-43
long MoveDVT(long distance, float vel, float time);. . . . . . . . . 2-43
long MoveDwell(float time); . . . . . . . . . . . . . . . . . . . . . . . . . 2-44
long MoveGetFreeSegments(void); . . . . . . . . . . . . . . . . . . . . . 2-44
long MoveIncremental(long distance); . . . . . . . . . . . . . . . . . . 2-44
long MoveOpenBuffer(long size, long rotary); . . . . . . . . . . . . 2-44
long MovePosition(long position); . . . . . . . . . . . . . . . . . . . . . 2-45
long MoveStart(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45
long MoveStop(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45
Move Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-46
long MoveAtSpeed(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-46
long MoveBufferFull(void); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-46
long MoveInProgress(void); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-46
Digital and Analog I/O Functions . . . . . . . . . . . . . . . . . . . 2-47
Analog Input Attributes . . . . . . . . . . . . . . . . . . . . . . . . 2-47
float AnalogInputGetVoltage(long channel); . . . . . . . . . . . . . . 2-47

Publication 2098-PM001E-EN-P — July 2002
vi Table of Contents
Analog Output Attributes . . . . . . . . . . . . . . . . . . . . . . . 2-48
long AnalogOutputSetVoltage(long channel, float voltage); . . . 2-48
Digital Input Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48
long InputGetAll(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48
long InputGetState(long channel); . . . . . . . . . . . . . . . . . . . . . 2-49
Digital Output Attributes . . . . . . . . . . . . . . . . . . . . . . . 2-49
long OutputSetState(long channel, long state); . . . . . . . . . . . . 2-49
Digital Output Services. . . . . . . . . . . . . . . . . . . . . . . . . 2-50
long OutputSetAllOff(void); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50
long OutputSetAllOn(void); . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50
long OutputToggle(long channel); . . . . . . . . . . . . . . . . . . . . . 2-50
Digital Output Status . . . . . . . . . . . . . . . . . . . . . . . . . . 2-51
long OutputGetAll(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-51
long OutputGetState(long channel); . . . . . . . . . . . . . . . . . . . . 2-51
Latch Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52
Latch Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52
long LatchGetAutoMode(long channel); . . . . . . . . . . . . . . . . . 2-52
long LatchGetCount(long channel); . . . . . . . . . . . . . . . . . . . . 2-53
long LatchGetOutput(long channel);. . . . . . . . . . . . . . . . . . . . 2-53
Latch Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-54
long LatchOnIndex(long channel, long encoder, long rising); . 2-54
long LatchOnInput(long channel, long input, long rising);. . . . 2-55
long LatchReset(long channel); . . . . . . . . . . . . . . . . . . . . . . . 2-55
long LatchSetAutoMode(long channel, long mode); . . . . . . . . 2-56
Latch Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-56
long LatchTriggered(long channel); . . . . . . . . . . . . . . . . . . . . 2-56
Non-Volatile Array Functions. . . . . . . . . . . . . . . . . . . . . . . 2-57
Non-Volatile Array Attributes . . . . . . . . . . . . . . . . . . . . 2-57
float FloatArrayGetElement(long element); . . . . . . . . . . . . . . . 2-57
long FloatArraySetElement(long element, float data);. . . . . . . . 2-57
long LongArrayGetElement(long element); . . . . . . . . . . . . . . . 2-57
long LongArraySetElement(long element, long data); . . . . . . . 2-58
Non-Volatile Array Services . . . . . . . . . . . . . . . . . . . . . 2-58
long FloatArraySelect(char* name);. . . . . . . . . . . . . . . . . . . . . 2-58
long LongArraySelect(char* name);. . . . . . . . . . . . . . . . . . . . . 2-58
Appendix A
Updates to the Motion Library for Ultraware Release 1.5 . . . A-1
Updates to the Motion Library for Ultraware Release 1.4 . . . A-1
Updates to the Motion Library for Ultraware Release 1.3 . . . A-1
Updates to the Motion Library for Ultraware Release 1.2 . . . A-2
Index

1Publication 2098-PM001E-EN-P — July 2002
Preface
Introduction
Read this preface to familiarize yourself with this manual. This preface
covers the following topics:
• Introduction
• Who should use this manual
• Contents of this Manual
• Related documentation
• Conventions Used in this Manual
• Using Online Help
• Allen-Bradley®support
Who Should Use this
Manual
Use this manual if you are new to programming in the Ultraware
programming environment, but have a basic understanding of
programming and the C programming language.
If you do not have a basic understanding of C programming, you
should first read one of the many books available or obtain instruction
on C programming.
Where to Find Help
You can find help for Ultraware in both this manual and the User
Manual, and in the Online Help. You can also select the Tip of the
Day... command from Ultraware’s Help menu, which opens a dialog
displaying helpful hints on using Ultraware.

Publication 2098-PM001E-EN-P — July 2002
P-2 Preface
Contents of this Manual
This manual contains the following sections:
Related Documentation
The following documents contain additional information concerning
related Allen-Bradley products or general information that may be
helpful. To obtain a copy, contact your local Rockwell Automation
office or distributor, or access the documents on-line at
www.theautomationbookstore.com or
www.ab.com/manuals/gmc .
Conventions Used in this
Manual
The following conventions are used throughout this manual:
• Bulleted lists provide information, not procedural steps.
• Numbered lists provide sequential steps.
• Words you type or select, and keys that you press, appear in bold.
• Programming code appears in a Courier font.
• C Programming conventions are used as appropriate.
Chapters: Title: Contents:
Preface An overview of this manual.
Chapter 1 Programming Motion
Control in C
An overview of C Programming principles and
practices in the Ultraware environment.
Chapter 2 Referencing the
Motion Library
A description of the C functions available in the
Ultraware Motion Library
Appendix A Updates to the Motion
Library
A list of motion library enhancements at each
release level.
For Information about: Read this document: Publication Number 1
Ultra5000™ drive installation
and setup procedures
Ultra5000 Hardware
Installation Manual
2098-IN001E-EN-P
Ultraware™ setup and
operating instructions
Ultraware User Manual
Release 1.5
2098-UM001F-EN-P
Ultraware installation
instructions
Ultraware CD Installation
Instructions
2098-IN002x-EN-P
Ultra3000™ and Ultra5000
drive capabilities
Ultra Family Brochure 2098-BR001x-EN-P
1To ensure correct operation, Allen-Bradley publications referenced should be at or above the revision level
listed. (e.g., 2098-UM001F-EN-P is revision F of the Ultraware User Manual.)

Publication 2098-PM001E-EN-P — July 2002
Preface P-3
Using Online Help
The following types of online help are available:
Allen-Bradley Support
Allen-Bradley offers support services worldwide, with over 75
sales/support offices, 512 authorized distributors and 260 authorized
systems integrators located throughout the United States alone, plus
Allen-Bradley representatives in every major country in the world.
Local Product Support
Contact your local Allen-Bradley representative for:
• Sales and order support
• Product technical training
• Warranty support
• Support service agreements
Technical Product Assistance
If you need to contact Allen-Bradley for technical assistance, please
review the information in this manual or in the Online Help file first.
Then call your local Allen-Bradley representative. For the quickest
possible response, we recommend that you have the catalog numbers
of your products available when you call.
To use: Do: Description:
Ultraware Help Select Contents and Index
from the Help menu.
Navigate the help file using
the Table of Contents, the
Index and the Search tabs.
Descriptions of all on-screen
objects.
Object property
configuration settings.
How-to information.
Context Sensitive Help Either:
•Click on a Help
button in the active
window, or
•Select an on-screen
object and press F1.
For help about the selected
object.

Publication 2098-PM001E-EN-P — July 2002
P-4 Preface

1Publication 2098-PM001E-EN-P — July 2002
Chapter 1
Programming Motion Control in C
Introduction
The chapter introduces you to the C language and programming with
the Motion Library functions in Ultraware 1.3. The purpose of this
chapter is to:
• Review some of the basic C language constructs.
• Help you gain experience in developing Ultraware programs that
control the motion of a motor.
• Have you create and run motion programs using the Ultraware
Motion Library.
Before You Begin
This chapter assumes that you have read, and understand, the
contents of the Ultraware User Manual (2098-UM001F-EN-P). That
means:
• The Ultra5000 system is setup and tuning is complete.
• Controlled motion was initiated through direct mode commands,
such as Jog Forward.
Creating A Basic Motion
Program
Until now all motion occurred in what is called the direct mode; you
told the Ultra5000 what to do by selecting direct commands from the
Ultraware Commands menu. It is far more useful to have all the
moves a machine axis will do, along with I/O statements, etc., in a
program. In this chapter you will build several C programs that
automate the control of a motor and drive system.
IMPORTANT If you do not have a basic understanding of C
programming, you should consider reading one of
the many books available or obtain instruction on C
programming. This manual is not intended to
provide you with the instruction necessary to
become a proficient C programmer.

Publication 2098-PM001E-EN-P — July 2002
1-2 Programming Motion Control in C
The first short program you will write:
• Moves the axis 1000 counts in the positive direction
• Delays program execution for 1 second
• Returns the axis 1000 counts in the negative direction
While the code is compact, what is important at this point is the
process. You must create the program text in a Project file, build it
successfully, load it, and run it.
Creating and Running a Program
The Ultraware User Manual (2098-UM001F-EN-P) instructs you about
how to create and run a program. The steps involved in creating and
running a program are:
1. Create a Project.
2. Create and edit a Source (.c) file.
3. Use the Program menu’s Build command to compile and create
the executable program (.exe) file.
4. Move the executable program file to the Program branch of an
On-Line drive.
5. Use the Program menu’s Run, Stop and Kill commands to control
the program’s execution.
You may remember an additional step, creating and editing a Header
file. For now that is an unnecessary step.
Example 1 - A Basic Motion Program
The first Ultraware program example starts you programming in C
using Ultraware Motion Library functions. To begin:
1. Insert a project into your program database.
2. Insert a source file into your newly created project.

Publication 2098-PM001E-EN-P — July 2002
Programming Motion Control in C 1-3
3. Open the source file and enter the following text with the text
editor:
#include <motion.h>
int main (void)
{
InitMotionLibrary();
AxisEnable();
MoveSetAcc(1000);
MoveSetVel(1000);
MoveSetDec(1000);
MoveIncremental(1000);
while (MoveInProgress()) {/* loop */}
Sleep(1000);
MoveIncremental(-1000);
while (MoveInProgress()) {/* loop */}
AxisDisable();
return 0;
}
4. After the text is entered, right-click on the Project in which you
inserted the source file and select Build from the Project menu. If
all of the text was entered correctly, the compilation will proceed
and you will see the following statements sequentially display in
the Ultraware Output window:
Compiling yourfile.c...
Linking...
Build completed successfully!
Notice the new file created under the project. The file is named the
same as the project but has an .exe extension. This is the program’s
executable file that now may be loaded and run on the Ultra5000.
Note: If the build fails, refer to the Executable Program File section in
the Ultraware User Manual (2098-UM001F-EN-P) for instructions
on how to troubleshoot errors encountered while creating a
program.
5. Drag the .exe file from the Project to the Program branch of the
On-line Ultra5000.
6. After the on-line controller’s Program branch expands, right-click
on your program, and select Run from the menu to execute the
program.

Publication 2098-PM001E-EN-P — July 2002
1-4 Programming Motion Control in C
Example 1 Explained
Any C program, whatever its size, consists of functions and variables.
A function contains statements that specify the operations to be done,
and variables that store the values used in those operations. Braces
(opening {, and closing }) enclose the statements in a function.
Example 1 uses a function named main. Normally you are free to give
functions whatever name you like, but main is special – C programs
begin executing at main. This means that every program must have
int main(void)
as its first function.
The main function calls other functions to help perform a task, some
that you write, and others from the motion library. The first line of the
program,
#include <motion.h>
tells the compiler to include information from the motion library. This
line must appear at the beginning of any program wishing to use
motion library functions. The chapter Referencing the Motion Library
describes the functions provided in the Ultraware Motion Library.
One method of communicating data between functions is for the
calling function to provide a list of values, called arguments, to a
function it is calling. Parentheses after a function name surround an
argument list. In our example, main is defined to be a function that
expects no arguments, which is indicated by the empty or void list
[written as (void) or often as a set of empty parentheses ( )].
In the first example, the function main contains several function calls
and a return statement, which are explained later. Each function is
called by naming it, followed by its arguments in parentheses, and is
terminated with a semicolon. The line
MoveSetDec(1000);
calls the function MoveSetDec with the argument 1000. MoveSetDec is
an Ultraware Motion Library function that sets the default move
deceleration value to 1000 encoder counts/sec².

Publication 2098-PM001E-EN-P — July 2002
Programming Motion Control in C 1-5
Variables, Loops, and Constants
The next example is a motion program that makes a series of 10 index
moves of 1000 counts each. This program introduces you to:
• Comments
• Declarations
• Variables
• Arithmetic expressions
• Loops
Example 2.1 - A Motion Program Using Variables
Enter the following program into a source file using the same process
as Example 1.
#include <motion.h>
/* increment through the 10 index positions
1000, 2000,..., until target > endpoint */
int main (void)
{
long target, index, endpoint;
InitMotionLibrary();
AxisEnable();
MoveSetAcc(1000);
MoveSetVel(1000);
MoveSetDec(1000);
AxisDefinePos(0); /* define current position as
index = 1000; 0 */
target = index; /* initialize target to first
index position (1000) */
endpoint = index * 10; /* initialize endpoint to
10000 (1000 * 10) */
while (target <= endpoint) {
MoveAbsolute(target);
while (MoveInProgress()) {/* loop */}
target = target+index;
}
AxisDisable();
return 0;
}

Publication 2098-PM001E-EN-P — July 2002
1-6 Programming Motion Control in C
Example 2.1 Explained
The program still consists of a single function main. However, it
introduces several new ideas, including comments, declarations,
variables, arithmetic expressions, and loops. The two lines
/* Increment through the 10 index positions
1000, 2000, etc. until target > endpoint */
are a comment, which in this case briefly explains what the program
does. Any characters between the /* and */ are ignored by the
compiler. Comments of this type may be multi-line and should be
used freely to make a program easier to read and understand.
In C, all variables must be declared before they are used, usually at
the beginning of the function in front of any executable statements. A
declaration announces the properties of variables; it consists of a type
name and a list of variables such as
long target, index, endpoint;
The type long means that the variables listed are long integers, by
contrast the type float means floating point, i.e., numbers that may
have a fractional part. On the Ultra5000, a long integer is a 32-bit
quantity that contains a value in the range ±2,147,483,647; a floating
point is a 32-bit quantity that contains a value in the range 10-38 to
10+38.
Computation begins in the motion program with the assignment
statements
index = 1000;
target = index;
endpoint = index * 10;
which set the variables to their initial values. Semicolons terminate
individual statements.
In the example, each move is calculated and executed the same way,
and the loop repeats once per index; this is the purpose of the while
loop
while (target <= endpoint) {
...
}
The while loop tests whether a statement is true or false, and then
performs one of two possible paths. The example operates as follows:
The condition in parentheses is tested. If it is true (target is less than
or equal to endpoint), the body of the loop (the statements enclosed
by braces) is executed. Then the condition is re-tested, and if true, the
body is executed again. When the test becomes false (target exceeds

Publication 2098-PM001E-EN-P — July 2002
Programming Motion Control in C 1-7
endpoint) the loop ends, and execution continues at the statement
that follows the loop.
Statements contained inside the braces of a while loop, and in many
other cases yet to come, should always be indented so you can see at
a glance which statements are inside the loop. The indentation
emphasizes the logical structure of the program. Although the
Ultraware C compiler does not care about how a program looks,
proper indentation and spacing are critical in making a program easy
to read.

Publication 2098-PM001E-EN-P — July 2002
1-8 Programming Motion Control in C
Example 2.2 - Varying the Program using Variables
There are many different ways to write a program for a particular task.
This program performs the same tasks as Example 2.1 - A Motion
Program Using Variables, but it uses slightly different software code.
#include <motion.h>
/* increment through the 10 index positions 1000, 2000,...,
until target > endpoint */
int main (void)
{
long target;
InitMotionLibrary();
AxisEnable();
MoveSetAcc(2000);
MoveSetVel(1000);
MoveSetDec(2000);
AxisDefinePos(0);
for (target = 1000; target <= 10000; target = target + 1000) {
MoveAbsolute(target);
while (MoveInProgress()) {/* loop */}
}
AxisDisable();
return 0;
}
Example 2.2 Explained
This program produces the same motion, but looks different than
Example 2.1. One major change is the elimination of most of the
variables; only target remains. The index and endpoint values appear
only as constants in the for statement.
The for statement is a loop. Compare the for loop to the previous
usage of the while command. Within the parentheses, there are three
parts, separated by semicolons. The first part, the initialization
target = 1000
is done once, before the loop proper is entered. The second part is
the test or condition that controls the loop:
target <= 10000
This condition is evaluated, and if it is true, the body of the loop is
executed. Then the increment step
target = target + 1000