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.
Table of Contents Preface Introduction . . . . . . . . . . . . . . . . Who Should Use this Manual. . . . Where to Find Help . . . . . . . . Contents of this Manual. . . . . . . . Related Documentation . . . . . . . . Conventions Used in this Manual. Using Online Help . . . . . . . . . . . Allen-Bradley Support . . . . . . . . . Local Product Support . . . . . . Technical Product Assistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ii Table of Contents Statements and Blocks . . . . . . . . . Example 8 - Grouping Statements. If-Else . . . . . . . . . . . . . . . . . . . . . Else-If . . . . . . . . . . . . . . . . . . . . . Switch . . . . . . . . . . . . . . . . . . . . . While, For and Do-While Loops . . Break and Continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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); . . . . . . . . . . . . . . . . . . . . . . . . . . .
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); . . . . . . . . . . . . . . .
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); . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . .
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.
P-2 Preface Contents of this Manual This manual contains the following sections: Chapters: Related Documentation 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.
Preface Using Online Help Allen-Bradley Support P-3 The following types of online help are available: 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.
P-4 Preface Publication 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.
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.
Programming Motion Control in C 1-3 3. Open the source file and enter the following text with the text editor: #include 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.
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.
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 /* increment through the 10 index positions 1000, 2000,...
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.
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.
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 /* increment through the 10 index positions 1000, 2000,...
Programming Motion Control in C 1-9 is executed, and the condition is re-evaluated. The loop terminates when the condition becomes false. As with the while, the body of the loop is enclosed by braces. The initialization, condition, and increment can be any expressions. The choice between while and for is arbitrary, based on which seems clearer. The for is usually appropriate for loops in which the initialization and increment are single statements and logically related.
1-10 Programming Motion Control in C Example 2.3 - Another Variance of the Program using Variables A third way to achieve the same result is to write the program as follows: #include #define #define #define #define #define ACCEL DECEL TARGETVEL INDEX ENDPOINT 2000 2000 1000 1000 10000 /* /* /* /* /* counts/second**2 */ counts/second**2 */ counts/second */ counts */ counts */ /* increment through the 10 index positions 1000, 2000,...
Programming Motion Control in C User Defined Functions 1-11 A function provides a convenient way to encapsulate a sequence of motion commands and computations. Example 3 - Nested Functions in a Motion Program This program shows the function insert and the main program to exercise it. In this example you see the whole structure at once. #include
1-12 Programming Motion Control in C { MoveSetAcc(accdec); /* Initialize index move */ MoveSetVel(velocity); MoveSetDec(accdec); OutputSetState(INMOTION, ON); MoveIncremental(distance); while (MoveInProgress()); OutputSetState(INMOTION, OFF); return ++partcount; /* Set Output 1 */ /* Start Move */ /* Wait for move to complete */ /* Clear Output 1 */ /* Increment partcount by 1.
Programming Motion Control in C 1-13 The declaration long insert(long distance, long velocity, long accdec); just before main says that insert is a function that expects three long arguments and returns a long value. This declaration, which is called a function prototype, has to agree with the definition and uses of insert. It is an error if the definition of the function or any uses of it do not agree with its prototype. Parameter names need not agree.
1-14 Programming Motion Control in C Example 4 - A Jog Program #include #define #define #define #define JOGREVERSE JOGFORWARD ACCDEC JOGVEL 7 8 10000 20000 /* /* /* /* Input 7 */ Input 8 */ counts/second**2 */ counts/second */ #define #define #define STOPPED FORWARD REVERSE 0 1 2 /* Jog modes */ /* This program uses inputs 7 and 8 to Jog the axis in the reverse and forward direction, respectively. It will continue to run until a Stop or Kill command is issued from Ultraware.
Programming Motion Control in C 1-15 Example 5 - A Gear Program #include #define ADCCHANNEL 1 /* Analog input chnl 1 */ /* This program uses analog input channel 1 to determine the gearing ratio. The purpose of comparing the old ratio to new is to avoid resetting the gear ratio when it has not changed.
1-16 Programming Motion Control in C Homing with Latch Functions Latch functions are used to capture axis position when certain events occur. The following example shows their use in a simple homing routine. Example 6 - A Homing Program This program simulates a simple homing routine while demonstrating the use of Latch functions. #include #define #define #define #define HOME_OFFSET 250 HOME_VEL 5000.0 HOME_ACC 160000.0 HOME_DEC 160000.
Programming Motion Control in C 1-17 controller’s non-volatile memory but only one of each type may be accessed at a time. One way to access non-volatile arrays is shown. Example 7 - A Non-Volatile Array Program #include /* This program assumes that two 10-element arrays have been created through Ultraware. One floating-point array named "FArray" and one long integer array named "IArray". This program continuously cycles through the array elements incrementing the value to be written.
1-18 Programming Motion Control in C Types, Operators, and Expressions The C language allows you a great deal of flexibility in deciding what type of data the Ultra5000 will use. Some of the data is preset or static, such as (#define ACCEL 1000), while other data changes or is assigned different values as your program runs (long partcount; is an example). The preset and unchanging data is called a constant, while the changing data is called a variable.
Programming Motion Control in C 1-19 Two limitations that apply to variable names are: • Underscores (“_”) count as a letter, and should be used to enhance readability. • Upper and lower case letters are unique, so code and Code are two distinct names. It is very important to remember the last stipulation as you write programs using variables. It is one of the most common sources of program compilation problems.
1-20 Programming Motion Control in C lists the precedence and describes the functions and any limitations placed on the arithmetic operations in C. Operator: Precedence: Function: * 1 Multiplies the value on its right by the value on its left. / Divides the value at its left by the value on its right. Answer is truncated if both operands are integer or long. % Yields the remainder when the value at its left is divided by the value to it right.
Programming Motion Control in C Relational and Logical Operators 1-21 The relational operators (<, <=, >=, >) make comparisons that test expressions. They have lower precedence than arithmetic operators, but higher precedence than the equality operators (==, !=). The logical operators (&& and ||) have a lower precedence than either the relational operators and equality operators. Each of these operators (except the unary !) compares the value to the left of the operator to the value at its right.
1-22 Programming Motion Control in C For example, the following code yields the absolute value of a number. if (y < 0) x = -y; else x = y; This statement can be written as x = (y < 0) ? –y : y; The meaning of either statement above is: If y is less than zero, then x = -y; else, x = y. Operator Precedence The following table shows the precedence of the operators introduced in this chapter and the associativity (i.e., the direction in which each operation flows). Operator: Associativity: ( ) [ ] -> .
Programming Motion Control in C Control Flow 1-23 In this section you will learn about the functions that control the flow of a C program. The functions include: • Statements and Blocks • If-Else • Else-If • Switch • While, For and Do-While Loops • Break and Continue Statements and Blocks A statement is a command to the computer. In C, any expression followed by a semicolon forms a statement. A statement may or may not do something.
1-24 Programming Motion Control in C In grouping example A, the assignment statement is included in the while loop, because a while loop runs from the while to the next semicolon. In grouping example B, the braces group both the assignment and MoveAbsolute statements into a single block. The entire compound statement is executed as a single loop. Thus the MoveAbsolute function is called each pass through the while loop. If-Else The if-else statement is a branching statement.
Programming Motion Control in C 1-25 The last statement (else) performs the default or “none of the above” case, and may be omitted in obvious situations. The structure is shown below.
1-26 Programming Motion Control in C Switch The switch statement performs a multiple path decision. It tests whether an expression matches one of several constant integer values, and branches accordingly. If no expression value matches, control passes through each case until the default statement is encountered, or no action takes place when the default option is absent.
Programming Motion Control in C 1-27 the update (expression3) is evaluated. The loop is repeated until test (expression2) is false or zero. for (expression1;expression2;expression3) statement; /* if expression2 is non-zero, loop until zero */ The initialize and update components (expression1 and expression3) may be omitted, but the semicolons must remain.
1-28 Programming Motion Control in C Publication 2098-PM001E-EN-P — July 2002
Chapter 2 Referencing the Motion Library This chapter provides information on the functions available in the Ultraware Motion Library. The functions are grouped into the following areas: • Control Setting Functions • Motion Functions • Digital and Analog I/O Functions • Latch Functions • Non-Volatile Array Functions Each group of functions is summarized in a table and then individually explained. IMPORTANT The first line of your motion program must declare #include
2-2 Referencing the Motion Library Control Setting Functions Control Setting functions directly control aspects of the controller. Use these functions: To: Axis Attributes • AxisDefinePos Get and set axis attributes.
Referencing the Motion Library Control Attributes • ControlGetFault 2-3 Get control attributes. • EncoderGetFaultState • EncoderGetOutput • EncoderGetPos • RatchetGetVel Control Services • ControlClearFault Manage control services. • EncoderDisableFault • EncoderEnableFault • EncoderSetPolarity • RatchetSetMode • SequencerAddNode • SequencerRemoveNodes Program Services • InitMotionLibrary Manage program execution.
2-4 Referencing the Motion Library Axis Attributes long AxisDefinePos(long position); Sets the axis command position to the specified position. Position is programmed in counts. Returns 0 if successful, or -1 on an error. float AxisGetCommandCur(void); Returns command current (filtered and clipped output of the velocity regulator) measurement in Amps. long AxisGetCommandPos(void); Returns the command position of the axis in counts.
Referencing the Motion Library 2-5 float AxisGetFeedbackVel(void); Returns the feedback velocity of the axis in counts/second. Note: Velocity error is calculated by subtracting this value from the command velocity. float AxisGetFGain(void); Returns the acceleration feedforward gain of the velocity loop. float AxisGetIGain(void); Returns the integral gain of the velocity loop in units of 1/second. float AxisGetKff(void); Returns the velocity feedforward gain of the position loop.
2-6 Referencing the Motion Library float AxisGetVelError(void); Returns the velocity error in counts/second. Note: Velocity error is calculated by subtracting the value of feedback velocity from the command velocity. long AxisSetFeedbackOffset(long offset); Sets the feedback offset of the axis. Offset is programmed in counts. Returns 0 if successful, or -1 on an error. long AxisSetFGain(float fgain); Sets the acceleration feedforward gain. Returns 0 if successful, or -1 on an error.
Referencing the Motion Library 2-7 long AxisSetUpperCurLimit(float limit); Sets the upper current limit in Amps. Returns 0 if successful, or -1 on an error.
2-8 Referencing the Motion Library Axis Services long AxisDisable(void); Disables the axis (amplifier). Returns 0 if successful, or -1 on an error. IMPORTANT This function will cause the axis to coast to a stop without controlled deceleration if the axis is disabled while motion is occurring. long AxisEnable(void); Enables the axis. When the axis is enabled, power is applied to the motor. The command position is set equal to the feedback position and it holds the present position.
Referencing the Motion Library 2-9 Axis Status long AxisIsEnabled(void); Determines if Axis is enabled. Note: Prior to initiating motion ensure that the axis is ready using the AxisIsReady function. Returns non-zero if the axis is enabled. long AxisIsReady(void); Determines if axis is ready. Note: After the axis is enabled, the motor may not be ready immediately, particularly if it is set for self-sensing startup. Returns non-zero if axis is ready.
2-10 Referencing the Motion Library Control Attributes long ControlGetFault(void); Returns controller fault.
Referencing the Motion Library 2-11 long EncoderGetFaultState(long channel); Returns state of fault checking for an encoder. The channel selects the encoder channel. Valid channels are as follows: • 1 = Motor Encoder • 2 = Aux Encoder The returned state can be one of the following: • 0 = Disabled • 1 = Enabled long EncoderGetOutput(long channel); Returns the output of the encoder in counts. This function is identical to the EncoderGetPos function.
2-12 Referencing the Motion Library Control Services long ControlClearFault(void); Clears a controller fault. Returns 0 if successful, or -1 on an error. long EncoderDisableFault(long channel); Disables fault checking for an encoder. The channel selects the encoder channel. Valid channels are as follows: • 1 = Motor Encoder • 2 = Aux Encoder Returns 0 if successful, or -1 on an error. long EncoderEnableFault(long channel); Enables fault checking for an encoder. The channel selects the encoder channel.
Referencing the Motion Library 2-13 long EncoderSetPolarity(long channel, long polarity); Sets the polarity of the specified encoder channel. Valid channel arguments are: • 1 = Motor Encoder • 2 = Auxiliary Encoder Valid polarity arguments are: • 0 = Positive • 1 = Negative Returns 0 if successful, or -1 on an error. ATTENTION Frame time is limited - adding excessive code to the sequencer will force an Excess CPU Load error and fault the drive. ! long RatchetSetMode(long mode); Set the ratchet mode.
2-14 Referencing the Motion Library long SequencerAddNode(long frame, void* fptr, void* dptr); Inserts a user function into a sequencer frame. The frame argument indicates which frame of the sequencer the function is to be inserted. Valid frames arguments are 1 - 4. The ftpr argument is a pointer to the user function to be inserted. The dptr argument is a pointer to the user data. Returns 0 if successful, or -1 on an error.
Referencing the Motion Library 2-15 Program Services long InitMotionLibrary(void); Initializes the motion library functions so the program may access them. If this function is not called, all motion library function calls will fail. Returns 0 if successful, or -1 on an error. IMPORTANT If Motion Library functions are used in a program, this function should be called as the first line of the program’s main function, and must be made before calling other Motion Library functions.
2-16 Referencing the Motion Library Program Status long ProgramIsRunning(char* name); Determines if the specified program is running. Returns non-zero if the program is running. long StopRequested(void); Determines if a program stop has been requested. Returns non-zero if the program is requested to stop. ATTENTION ! This function must be called in your main program execution loop if the program is to react to a Stop command.
Referencing the Motion Library 2-17 long SerialPutString(const char *string); Puts a character string into the ASCII transmit buffer. Returns 0 if successful, or -1 on an error. Serial Status long SerialClearToSend(void); Returns non-zero if space is available in ASCII transmit buffer. long SerialDataReady(void); Returns non-zero if data is available in ASCII receive buffer. long SerialReceiverFull(void); Returns non-zero if ASCII receive buffer is full.
2-18 Referencing the Motion Library Timer Status long TimerDone(long channel); Returns non-zero if specified timer has completed. Valid channel arguments are 1 - 8.
Referencing the Motion Library Motion Functions 2-19 Motion functions include all functions that cause or directly affect motion of the axis. The motion library provides functions for moving, jogging, electronic gearing, and electronic cams. The following table presents the functions names for each function in this category along with a brief description. More detailed descriptions of the functions are contained on the pages following this table.
2-20 Referencing the Motion Library Gear Attributes • GearGetVel Get and set gear attributes. • GearSetRatio • GearSlewSetAcc • GearSlewSetDec Gear Services • GearDisable Turns electronic gearing on of off. • GearEnable • GearSlewDisable • GearSlewEnable Gear Status • GearAtSpeed Query gear status. • GearInProgress • GearIsEnabled Jog Attributes • JogSetAcc Get and set jog attributes.
Referencing the Motion Library Move Attributes • MoveSetAcc 2-21 Get and set move attributes. • MoveSetDec • MoveSetPos • MoveSetVel Move Services • MoveAbort • MoveAbsolute • MoveCloseBuffer Move the axis to a specified absolute position, or by a specified incremental distance.
2-22 Referencing the Motion Library Cam Attributes long CamGetCycleCount(void); Returns the cam cycle count. The cycle count is the number of complete cycles that the cam has gone through since it was enabled. Cam cycle count is in cycles. long CamGetCycleLimit(void); Returns the cam cycle limit. The cycle limit is the number of cycles that the cam will go through before automatically disabling. If the cycle limit is zero, the cam will run continuously.
Referencing the Motion Library 2-23 long CamSetCycleLimit(long limit); Sets the cam cycle limit. The cycle limit is the number of cycles that the cam will go through before automatically disabling. If the cycle limit is zero, the cam will run continuously. • Positive values for limit will disable the cam after the given number of cycles in the positive direction. No checks are made in the negative direction.
2-24 Referencing the Motion Library long CamCycloidal(long master_position, long follower_position); Adds a cycloidal curve to the table. The profile of a normalized cycloidal curve is shown in Figure 2.1. • The master_position argument defines the master position at the end of the curve. • The follower_position argument defines the follower position at the end of the curve. Returns 0 if successful, or -1 if there was an error. This function requires three free segments. Figure 2.1 Cycloidal Curve 1.0 0.
Referencing the Motion Library 2-25 long CamCycloidalHarmonic(long master_position, long follower_position); Adds a cycloidal harmonic curve to the table. The profile of a normalized cycloidal harmonic curve is shown in Figure 2.2. • The master_position argument defines the master position at the end of the curve. • The follower_position argument defines the follower position at the end of the curve. Returns 0 if successful, or -1 if there was an error. This function requires three free segments.
2-26 Referencing the Motion Library long CamDisable(void); Disables electronic cam. Returns 0 if successful, or -1 on an error. long CamDwell(long master_position); Adds a dwell segment to the table. • The master_position argument defines the master position at the end of the segment. Returns 0 if successful, or -1 if there was an error. This function requires one free segment. long CamEnable(void); Enables the electronic cam using the previously loaded cam table.
Referencing the Motion Library 2-27 long CamHarmonic(long master_position,long follower_position); Adds a harmonic curve to the table. The profile of a normalized harmonic curve is shown in Figure 2.3. • The master_position argument defines the master position at the end of the curve. • The follower_position argument defines the follower position at the end of the curve. Returns 0 if successful, or -1 if there was an error. This function requires one free segment. Figure 2.3 Harmonic Curve 1.0 0.
2-28 Referencing the Motion Library long CamHarmonicCycloidal(long master_position, long follower_position); Adds a harmonic cycloidal curve to the table. The profile of a normalized harmonic cycloidal curve is shown in Figure 2.4. • The master_position argument defines the master position at the end of the curve. • The follower_position argument defines the follower position at the end of the curve. Returns 0 if successful, or -1 if there was an error. This function requires three free segments.
Referencing the Motion Library 2-29 long CamLoad(char* name); Loads cam table number one. • The name argument specifies the name of the file. This is the base filename of the cam file, with the file path and extension added automatically. A cam table cannot be loaded if it is active or queued. Returns 0 if successful, or -1 if there was an error. long CamLoadTable(long table_number,char *name); Loads a cam table. • The table_number argument specifies the table number.
2-30 Referencing the Motion Library long CamModifiedSinusoidal(long master_position,long follower_position); Adds a modified sinusoidal curve to the table. The profile of a normalized modified sinusoidal curve is shown in Figure 2.5. • The master_position argument defines the master position at the end of the curve. • The follower_position argument defines the follower position at the end of the curve. Returns 0 if successful, or -1 if there was an error. This function requires three free segments.
Referencing the Motion Library 2-31 long CamModifiedTrapezoidal(long master_position,long follower_position); Adds a modified trapezoidal curve to the table. The profile of a normalized modified trapezoidal curve is shown in Figure 2.6. • The master_position argument defines the master position at the end of the curve. • The follower_position position argument defines the follower position at the end of the curve. Returns 0 if successful, or -1 if there was an error.
2-32 Referencing the Motion Library long CamOpenTable(long table_number,long size,long order); Opens the cam table. • The table_number argument specifies the table number. Valid tables are one, two, and three. • The size argument specifies the number of segments to be allocated. • The order argument specifies the precision of the segments. Valid values are one through nine, inclusive. Returns 0 if successful, or -1 if there was an error. A cam table cannot be opened if it is active or queued.
Referencing the Motion Library 2-33 long CamQueueReset(void); Resets the queue. Returns 0 if successful, or -1 if there was an error. long CamQueueTable(long table_number,long cycle_limit); Queues a cam table. • The table_number argument specifies the table number. Valid tables are one, two, and three. • The cycle_limit argument specifies the cycle limit to take effect when the queued table becomes active. Returns 0 if successful, or -1 if there was an error.
2-34 Referencing the Motion Library long CamSaveTable(long table_number,char *name); Saves a cam table. • The table_number argument specifies the table number. Valid tables are one, two, and three. • The name argument specifies the name of the file. This is the base filename of the cam file, with the file path and extension added automatically. Returns 0 if successful, or -1 if there was an error.
Referencing the Motion Library 2-35 Cam Status long CamIsEnabled(void); Determines if electronic cam is enabled. Returns non-zero if cam is enabled. long CamPhaseInProgress(void); Checks if phase adjustment is in progress. Returns non-zero if phase adjustment is in progress. long CamQueueFull(void); Checks if the queue is full. Returns non-zero if the queue is full.
2-36 Referencing the Motion Library Gear Attributes float GearGetVel(void); Returns the gear velocity in counts/second. long GearSetRatio(float ratio); Sets the default count-to-count electronic gear ratio. If gearing is enabled, the ratio is changed to the specified ratio subject to any Gear Slew settings. If the gearing is not enabled, the value is set and will take effect when gearing is enabled. Returns 0 if successful, or -1 on an error.
Referencing the Motion Library 2-37 long GearSlewDisable(void); Disables gearing slew. Returns 0 if successful, or -1 on an error. long GearSlewEnable(void); Enables gearing slew. Returns 0 if successful, or -1 on an error. Gear Status long GearAtSpeed(void); Determines if electronic gearing is at speed. Returns non-zero if gear enabled and slew is not active. long GearInProgress(void); Determines if electronic gearing is in progress. Returns non-zero if gear enabled or slew is active.
2-38 Referencing the Motion Library long JogSetDec(float dec); Sets the default deceleration for the jog. Deceleration is programmed in counts/second². Returns 0 if successful, or -1 on an error. long JogSetVel(float vel); Sets the default velocity for the jog. Velocity is programmed in counts/ second. Returns 0 if successful, or -1 on an error. Jog Services long JogAbort(void); Halts jog immediately, without deceleration. Returns 0 if successful, or -1 on an error.
Referencing the Motion Library 2-39 long JogStop(void); Stops the jog motion using the programmed deceleration value. Returns 0 if successful, or -1 on an error. Jog Status long JogAtSpeed(void); Determines if a jog is at the programmed speed. Returns non-zero if jog is at speed.
2-40 Referencing the Motion Library long JogInProgress(void); Determines if a jog is in progress. Returns non-zero if jog is in progress. Move Attributes long MoveSetAcc(float acc); Sets the programmed acceleration for a move. Acceleration is programmed in counts/second². Returns 0 if successful, or -1 on an error. long MoveSetDec(float dec); Sets the programmed deceleration for a move. Deceleration is programmed in counts/second². Returns 0 if successful, or -1 on an error.
Referencing the Motion Library 2-41 Move Services long MoveAbort(void); Halts motion immediately, ignoring deceleration and position values. Returns 0 if successful, or -1 on an error. ATTENTION ! This function stops motion immediately; without decelerating the motor in a controlled manner. If a controlled deceleration is desired, your program should use the MoveStop function to slow the motor using the programmed deceleration value.
2-42 Referencing the Motion Library long MoveCorrectAbs(long position); Corrects a move to stop at a new target position specified in the argument. Uses the programmed move acceleration, deceleration, and velocity values. Position is programmed in counts. The reference position for the MoveCorrectAbs function is set using the MoveSetPos function. Move status may be checked with a MoveInProgress function. Returns 0 if successful, or -1 on an error.
Referencing the Motion Library 2-43 long MoveDV(long distance, float vel); The distance argument is the delta distance of the move. The vel argument specifies the move profile final velocity. This function fits a move profile to the specified DV parameters using linear acceleration and deceleration. Note: Negative motion requires both the distance and the vel arguments to be negative. Returns 0 if successful, or -1 on an error.
2-44 Referencing the Motion Library long MoveDwell(float time); The time argument specifies the time duration for which the axis will remain stationary. This function inserts into the move buffer a move profile dwell. Returns 0 if successful, or -1 on an error. long MoveGetFreeSegments(void); Returns number of free segments in the move buffer.
Referencing the Motion Library 2-45 long MovePosition(long position); Starts an absolute move to the specified position using the programmed move acceleration, deceleration, and velocity values. Position is programmed in counts. The reference position for the MovePosition function is set using the MoveSetPos function. Move status may be checked with a MoveInProgress function. Returns 0 if successful, or -1 on an error. Note: Returns an error if a move is already in progress.
2-46 Referencing the Motion Library Move Status long MoveAtSpeed(void); Determines if a move is currently at the programmed speed. Returns non-zero if move is at speed. long MoveBufferFull(void); Determines if the move buffer, opened with the MoveOpenBuffer function, is full. Returns non-zero if move is at speed. long MoveInProgress(void); Determines if a move is currently in progress. Returns non-zero if a move is in progress.
Referencing the Motion Library Digital and Analog I/O Functions 2-47 Digital and Analog I/O functions control discrete I/O. The following table presents the function names for each function in this category along with a brief description. More detailed descriptions of the functions are contained on the pages following the table. Use these functions: To: Analog Input Attributes • AnalogInputGetVoltage Read voltage from a specified analog input channel.
2-48 Referencing the Motion Library Analog Output Attributes long AnalogOutputSetVoltage(long channel, float voltage); Sets the voltage output value for the auxiliary analog channel specified by the channel argument. Valid channel arguments are: • 1 = Auxiliary analog output channel 1 • 2 = Auxiliary analog output channel 2 Returns 0 if successful, or -1 on an error. Digital Input Status long InputGetAll(void); Returns the state of all digital inputs.
Referencing the Motion Library 2-49 long InputGetState(long channel); Returns the state of the digital input specified by the channel argument. Valid channel arguments are 1 through 28 as follows.
2-50 Referencing the Motion Library Digital Output Services long OutputSetAllOff(void); Turns all digital outputs OFF. Returns 0 if successful, or -1 on an error. long OutputSetAllOn(void); Turns all digital outputs ON. Returns 0 if successful, or -1 on an error. long OutputToggle(long channel); Toggles a digital output. The channel selects the digital output.
Referencing the Motion Library 2-51 Digital Output Status long OutputGetAll(void); Returns the state of all digital outputs. The return value is bitmapped as follows: Bit Input Description 0–7 OUT1 – OUT8 Digital outputs 1-8 8 – 31 — Reserved long OutputGetState(long channel); Returns the state of the digital output referenced by the channel argument.
2-52 Referencing the Motion Library Latch Functions Latch functions control registration events. The table presents the function names for each function in this category along with a brief functional description. Detailed descriptions of the functions follow the table. Use these functions: To: Latch Attributes • LatchGetAutoMode Get latch attributes.
Referencing the Motion Library 2-53 long LatchGetCount(long channel); Returns the value of the latch counter. The channel argument selects the channel latch counter to read. Latch count is the number of latches that have occurred. Valid channel arguments are: • 1 = Primary motor latch • 2 = Secondary motor latch • 3 = Primary auxiliary latch • 4 = Secondary auxiliary latch long LatchGetOutput(long channel); Returns the output of the selected latch.
2-54 Referencing the Motion Library Latch Services long LatchOnIndex(long channel, long encoder, long rising); Arms a latch to trigger on an encoder index. The channel argument selects the latch channel. The encoder argument selects which encoder index triggers the latch.
Referencing the Motion Library 2-55 long LatchOnInput(long channel, long input, long rising); Arms a latch to trigger on an digital input signal. Valid channel arguments are: • 1 = Primary motor latch • 2 = Secondary motor latch • 3 = Primary auxiliary latch • 4 = Secondary auxiliary latch Valid input arguments are 1 through 16. Valid rising arguments are: • 0 = Falling edge of digital input signal (This is the default argument.
2-56 Referencing the Motion Library long LatchSetAutoMode(long channel, long mode); Sets the auto mode of a latch. Enabling auto mode allows the latch to automatically rearm after detecting a latch. The latch count is read with the LatchGetCount function. Valid channel arguments are: • 1 = Primary motor latch • 2 = Secondary motor latch • 3 = Primary auxiliary latch • 4 = Secondary auxiliary latch Valid mode arguments are: • 0 = Disabled • 1 = Enabled Returns 0 if successful, or -1 on an error.
Referencing the Motion Library Non-Volatile Array Functions 2-57 Non-volatile array functions store numeric values for retrieval from non-volatile memory in the Ultra5000. The array index is zero-based with a range of 0 through the size of the array minus one. IMPORTANT Non-volatile arrays must be set up in Ultraware before they may be accessed by a program. Use these functions: To: Non-Volatile Array Attributes • FloatArrayGetElement Store and retrieve non-volatile array values.
2-58 Referencing the Motion Library long LongArraySetElement(long element, long data); Stores data into a previously selected zero-based, long integer array. The element argument indicates which cell of the array to access. The data argument is the new value to be stored in the specified element. Returns 0 if successful, or -1 on an error. Non-Volatile Array Services long FloatArraySelect(char* name); Selects the active floating point array for access by the program.
Appendix A This appendix summarizes the library functions added in various releases of the Ultraware software. Updates to the Motion Library for Ultraware Release 1.5 New Library Functions Updates to the Motion Library for Ultraware Release 1.4 New Library Functions Updates to the Motion Library for Ultraware Release 1.
A-2 Updates to the Motion LIbrary Updates to the Motion Library for Ultraware Release 1.
Updates to the Motion LIbrary A-3 Modified library Functions LatchGetOutput(channel); In previous Ultraware versions, this library function returned the motor encoder output position captured when the latch occurred. The axis feedback offset was not applied to the latched positions. In Ultraware 1.20 Motion Library, this function returns the Axis feedback position, with the feedback offset added, captured when the latch occurred.
A-4 Updates to the Motion LIbrary Publication 2098-PM001E-EN-P — July 2002
Index A Allen-Bradley support general information P-3 IMC e-mail addresses, see back cover IMC fax numbers, see back cover IMC telephone numbers, see back cover AnalogInputGetVoltage 2-47 AnalogOutputSetVoltage 2-48 arithmetic operators 1-19 arrays 1-16 AxisDefinePos 2-4 AxisDisable 2-8 AxisEnable 2-8 AxisGetCommandCur 2-4 AxisGetCommandPos 2-4 AxisGetCommandVel 2-4 AxisGetFeedbackOffset 2-4 AxisGetFeedbackPos 2-4 AxisGetFeedbackVel 2-5 AxisGetFGain 2-5 AxisGetIGain 2-5 AxisGetKff 2-5 AxisGetKp 2-5 AxisGet
I-2 Index declarations 1-19 definition 1-21, 1-21 - (arithmetic operator) 1-20 -- (arithmetic operator) 1-20 - (binary arithmetic operator) 1-20 ! (logical operator) 1-21 != (logical operator) 1-21 % (arithmetic operator) 1-20 && (logical operator) 1-21 * (arithmetic operator) 1-20 + (binary arithmetic operator) 1-20 + (unary arithmetic operator) 1-20 ++ (arithmetic operator) 1-20 == (logical operator) 1-21 > (logical operator) 1-21 >= (logical operator) 1-21 ? (logical operator) 1-21 || (logical operator
Index CamGetCycleCount 2-22 CamGetCycleLimit 2-22 CamGetFreeSegments 2-22 CamHarmonic 2-27 CamHarmonicCycloidal 2-28 CamIsEnabled 2-35 CamLoad 2-29 CamLoadTable 2-29 CamModifiedSinusoidal 2-30 CamModifiedTrapezoidal 2-31 CamOpenTable 2-32 CamPhaseAbort 2-32 CamPhaseAdvance 2-32 CamPhaseInProgress 2-35 CamPhaseRetard 2-32 CamQueueFull 2-35 CamQueueReset 2-33 CamQueueTable 2-33 CamSaveTable 2-34 CamSetCycleLimit 2-23 CamSpline 2-34 CamUnloadTable 2-34 CCamDwell 2-26 ControlClearFault 2-12 ControlGetFault 2-1
I-4 Index ProgramIsRunning 2-16 ProgramKill 2-15 ProgramRun 2-15 ProgramStop 2-15 RatchetGetVel 2-11 RatchetSetMode 2-13 SequencerAddNode 2-14 SequencerRemoveNodes 2-14 SerialClearToSend 2-17 SerialClose 2-16 SerialDataReady 2-17 SerialGetChar 2-16 SerialOpen 2-16 SerialPutChar 2-16 SerialPutString 2-17 SerialReceiverFull 2-17 SerialTransmitterEmpty 2-17 Sleep 2-15 StopRequested 2-16 TimerAccumulated 2-17 TimerDone 2-18 TimerEnable 2-17 G GearAtSpeed 2-37 GearDisable 2-36 GearEnable 2-36 GearGetVel 2-36
Index AxisGetPGain 2-5 AxisGetPosError 2-5 AxisGetUpperCurLimit 2-5 AxisGetVelError 2-6 AxisIsEnabled 2-9 AxisIsReady 2-9 AxisPosLimitGetStatus 2-9 AxisPosLimitIsTriggered 2-9 AxisResetPosLimit 2-8 AxisSetFeedbackOffset 2-6 AxisSetFGain 2-6 AxisSetIGain 2-6 AxisSetKff 2-6 AxisSetKp 2-6 AxisSetLowerCurLimit 2-6 AxisSetPGain 2-6 AxisSetUpperCurLimit 2-7 AxisSoftLimitDisable 2-8 AxisSoftLimitEnable 2-8 CamCloseTable 2-23 CamConstantVelocity 2-23 CamCycloidal 2-24 CamCycloidalHarmonic 2-25 CamDisable 2-26 CamD
I-6 Index MoveAtSpeed 2-46 MoveCloseBuffer 2-41 MoveCorrect 2-41 MoveCorrectAbs 2-42 MoveCorrectInc 2-42 MoveDistance 2-42 MoveDV 2-43 MoveDVS 2-43 MoveDwell 2-44 MoveGetFreeSegments 2-44 MoveIncremental 2-44 MoveInProgress 2-46 MoveOpenBuffer 2-44 MovePosition 2-45 MoveSetAcc 2-40 MoveSetDec 2-40 MoveSetPos 2-40 MoveSetVel 2-40 MoveStop 2-45 OutputGetAll 2-51 OutputGetState 2-51 OutputSetAllOff 2-50 OutputSetAllOn 2-50 OutputSetState 2-49 OutputToggle 2-50 ProgramIsRunning 2-16 ProgramKill 2-15 ProgramRu
Index break 1-27 build (command) 1-2 conditional expressions 1-21 constants 1-5 continue 1-27 control flow 1-23 data sizes 1-18 data types 1-18 declarations 1-19 do-while 1-26 else-if 1-24 example 2.1 - variables 1-5 example 2.2 - variables option 1-8 example 2.
I-8 Index SerialPutChar 2-16 SerialPutString 2-17 SerialReceiverFull 2-17 SerialTransmitterEmpty 2-17 Sleep 2-15 source file creation 1-2 statements 1-23 stop (command) example 1-2 StopRequested 2-16 switch 1-26 TimerEnable 2-17 tip of the day P-1 troubleshooting build (command) 1-3 types 1-18 V variable names 1-18 variables 1-5 W T TimerAccumulated 2-17 TimerDone 2-18 Publication 2098-PM001E-EN-P — July 2002 where to find help P-1 while 1-26 who should use this manual P-1
Notes 1
2
3
Publication 2098-PM001E-EN-P — July 2002 Supercedes Publication 2098-PM001D-EN-P – January 2002 0013-1085-005-01 © 2002 Rockwell Automation, Inc. All rights reserved. Printed in the U.S.A.
