Servolib - Software Driver
for
SER04 PC Based Servo Controller Card Set

Programmer’s Reference

Contents

1. ServoLib - Driver for SC-02
1.1 Installation and Usage

1.2 Description of Functions
1.2.1 int SetBase(int xDacAddr, int xEncAddr[2] )
1.2.2 int PosSampleTime(int  nPCount)
1.2.3 int RampSampleTime(int  nRCount)
1.2.4 int RampUpRate(int nAxis, unsigned nNewramp)
1.2.5 int RampDownRate(int nAxis, unsigned nNewramp)
1.2.6 int SetDACFACT( int nAxis,  float rDfact )
1.2.7 int SetPosLimit(int nAxis,long lLimit)
1.2.8 int SetDeadBand(int nAxis,int nBand)
1.2.9 int SetMotorGain( int nAxis, int nGain)
1.2.10 int ServoInit(void)
1.2.11 int ServoClose(void)
1.2.12 int LoadAxis(int nAxis, MOVT_DATA *pMovt)
1.2.13 int ReadPosition(int nAxis, long *lPosition)
1.2.14 int ReadSpeed( int nAxis,float *rSpeed )
1.2.15 int ReadRampStat(int nAxis)
1.2.16 int StopAxis(int nAxis,char fHow)
1.2.17 int ClearMovement (int nAxis)
1.2.18 int ReadEncoder(int nAxis,long *lpPos)
1.2.19 int WriteDac(int nAxis,int nVoltage)
1.2.20 int InitDac(void)
1.2.21 int InitEncoder(void)

1.3 Global Variables


1. ServoLib - Driver for SC-02

The  SER04  card set neex powerful programs to realise its  versatility  in  control.  From  the user manual for SER04, programming a servo application  looks  formidable  and  it is so. This can be avoided by  using  the  SERVOLIB  driver package.

The library also affords a simple upgrade path for application based on the STEPLIB stepper control library.
 

1.1 Installation and Usage
The package consists of 4 files :

  1. SERVOLIB.OBJ - Containing the routines
  2. SERVORMP.OBJ - Containing routines coded in assembly language
  3. SERVOLIB.H - Containing data structure definitions and global variables
  4. EXMPL2.C - Turbo C example program
  5. EXMPL2.PRJ - Make file for example program
Installation is done by copying these onto the target computer.

The  library  module  is linkable to Turbo C programs.  Part  of  this  library  has  been coded in C and the rest in ASSEMBLER.  The  library,  when invoked, takes over the system timer for the purposes of ramping.  However,  the  ramping  routines  alter the  frequency  of  the  timer  interrupt  on the PC and hence the system clock would not be  accurate  for  the period for which the program linked to SERVOLIB is active.  If  accurate time is required then the real time clock (RTC) can be  used.  It is essential that the library be initialised and closed by the user  program after entering and before quitting. The user program should be  a LARGE or HUGE memory model program.

This package consists of routines for the following operations :

1. Setting up of parameters

  1. Base address
  2. Ramp loop time
  3. Position loop time
  4. Ramp up rate
  5. Ramp Down rate
  6. Forward loop gain
  7. Position control band
  8. Dead band for position control
2. Initialising and closing the software library and card

3. Control Port Operations

  1. Drive enable/disable
  2. Start/stop
  3. Digital I/O port operations
  4. Loading motion parameters
4. Readback operations
  1. Read position
  2. Set position to zero
  3. Speed of motor
  4. Ramping status


All  programs  using the functions in the library  are  prototyped  in  SERVOLIB.H  and  this file should be included in the  source  file.  The  important  data  structure defined in this include file is  the  MOVT_DATA  type  structure  which  is  used for passing  data  to  the  load_axis  routine.


1.2 Description of Functions
This  section  describes the functions included in the  library.   The  names  of  the routines are mentioned in the same format as  they  are  prototyped  in the library. All the names are case sensitive  and  are  available publicly with preceding underbars.

Each function description consists of the function name. The  variable  name  given with the function name is a dummy name and given  for  the  purposes of illustration. A short summary of the operations  performed  by  the routine is provided followed by a clear indication  of  inputs  and  outputs to the routines. Special considerations  are  illustrated  with examples.
 

1.2.1 int SetBase(int xDacAddr, int xEncAddr[2] )
This  function informs other routines in SERVOLIB  of the base  address  that has been selected on the card

Call with :
                            xDacAddr  :      Base address of the DAC02 card
                            xEncAddr  :      Base addresses of the EN03 cards
 

Return Value :
                           0    Always

Default value of the DAC card is factory set 340 (Hex)  and for the EN03 cards are set at 330 (hex) and 320 (hex).  Note that if only one EN03 card is being used, the NAXIS value in SERVOLIB.H should be set to 2.  The library should be recompiled and hence this information should be part of ordering information.

This function should be called only before ServoInit(...) is called.  If ServoInit has already been called, call ServoClose(...) before calling this function.
 

1.2.2 int PosSampleTime(int  nPCount)
1.2.3 int RampSampleTime(int  nRCount)
These routines set the sampling frequency of the ramping and position control routines.  Ramp sample time is the time interval in which the speed of the motor  is updated while ramping up and down.  Position sample time is the time interval for servo position control. The values are in number of milliseconds.

While the lowest interval is the best, the computational speed of the PC on which the card set is plugged determines the optimum values.  The following constraint applies:

                       nRCount = 5 * nPCount.
 

Call with
                      nPCount  or nRCount : Interval in milliseconds

Return Value :
                     0      if successful
                     1      if out of range inputs
 

These functions should be called only before ServoInit(...) is called.  If ServoInit has already been called, call ServoClose(...) before calling this function.
 

1.2.4 int RampUpRate(int nAxis, unsigned nNewramp)
1.2.5 int RampDownRate(int nAxis, unsigned nNewramp)
These functions set the ramping up and ramping down rates to be followed while positioning.  The values are in terms of DACCOUNTS.  Refer to the function SetDacFact(...) for conversion from counts to actual speed of the motor.

Note, contrary to previous functions, the ramp rates are settable for each individual axis.

Call with

                     nAxis         :  Axis on which ramp is to be set (0 - 4)
                  nNewRamp    :     New ramping value (up or down)

 Return Value

                0      if successful
                1      if not

Call these routines only after setting rDacFact with SetDacFact(...) function.
 

1.2.6 int SetDACFACT( int nAxis,  float rDfact ) ;
This function sets the computation between the change actual speed of the motor (in encoder counts/second) and two consecutive values of the DAC card.  This factor is used by the library to compute the dac value to be output to the DAC02 card corresponding to the required speed in calls to LoaxAxis (...).  Assuming,

 N = RPM of the motor/output shaft at maximum output voltage of DAC card
 E = Encoder counts per revolution of output shaft (after multiplying, if any)

The factor F would be:

  F =    E*N/(2048*60)

Note that N corresponds to the output shaft speed and hence depends upon the mechanism and the drive unit used.

However, rDacFact may be set to any arbitrary value provided subsequent calls to moving the motor use the same units to set the speed.

Each axis may have individual factors.

Call with
               axis           :  Axis number ( 0,1 or 2 )
               rDacFact    :     Factor described abvoe.
 

Return value
                0      if successful
                1      if not

This function should always be called before setting ramping parameters.

1.2.7 int SetPosLimit(int nAxis,long lLimit) ;
This function sets the band of servo position control.  Any given movement is profiled in the following phases:

  1. Ramping up to the required speed.
  2. Coasting at the rquired speed
  3. Ramping down to near the final position, say x from the final position.  This band is called the positioning band.
  4. Servo controlled positioning and servo locking
This function sets the x value.  If this value is too little, over shooting will occur and the system will be under damped.  If this value is too high, then the required motion profile may not be achieved.

Each axis may have individual positioning bands.

Call with
            axis      :     Axis number ( 0,1 or 2 )
            lLimit    :     Positioning band in encoder counts
 

Return value
                0      if successful
                1      if not

1.2.8 int SetDeadBand(int nAxis,int nBand) ;
It is not always possible to achieve 0 count error. It is possible that under high gain and heavy inertial load conditions, the controller hunts i.e., oscillates about the set position.  To avoid this problem, SERVOLIB provides a dead band function.  The controller takes no action if the position error (difference between the set and actual positions) is within this deadband.  This funciton sets this dead band value.

Each axis may have individual dead band values.

Call with
           axis       :     Axis number ( 0,1 or 2 )
           nBand    :     Dead band value in encoder counts
 

Return value
                0      if successful
                1      if not

1.2.9 int SetMotorGain( int nAxis, int nGain)
The servo controller library implements a gain scheduled simple proportional control algorithm.  The gain is set by this function.  The other parts of scheduled gains are automaticaly calculated by the control software.  Whereas, the value of nGain is an integer, the gain internally scaled by 100.  Hence to set a gain of 1.05, call this function with 105 as the nGain value.

Each axis may have individual control loop gains.

Call with
           axis       :  Axis number ( 0,1 or 2 )
           nGain    :     Gain value
 

Return value
                0      if successful
                1      if not

Example:

1.2.10 int ServoInit(void) ;
1.2.11 int ServoClose(void) ;
These functions are called for initialising the library and then for freeing the resources used by the library.  When ServoInit(...) is called the following actions are taken:

  1. Output voltage is set to 0.
  2. Encoder position is cleared.
  3. All internal variables are initialised
  4. The PC timer is replaced with an internal timer.
  5. Ramping loop and position control loop are started to be spawned.
When ServoClose(...) is called, the timer is released and the original PC timer is reinstalled.  Output voltage is set to 0.

The program should never be ended without calling ServoClose().
ServoClose(...) should never be called without a previous call to ServoInit(...).

Call with:

  None.

Return:

  Always successful.

1.2.12 int LoadAxis(int nAxis, MOVT_DATA *pMovt);
This  function programs the axis with the speed and  movement  values  specified. The structure MOVT_DATA is defined in servolib.h. This structure  is defined as follows :
 
 



typedef struct


 










                                                                  {
 
 



    float rSpeed ;
 char  fRamp ;
 char fHowStop ;
    long lDeltaPos ;
 signed char fDirection ;
}  MOVT_DATA  ;


 






where
         rSpeed is in encoder counts per second (refer to discussion for the function SetDacFact(...) ),
         fRamp specifies whether ramping is to be followed or not. This may be RAMPON or RAMPOFF, which are defined in servolib.h
         fHowStop specifes whether servo lock is to be implemented after after stopping or not,
         lDeltaPos is the amout of movement required (in encoder counts)
         fDirection is whether the movement is to be CLOCK or ACLOCK.

Call with
       nAxis     : Axis number
       pMovt     :     Pointer to the MOTOR structure

Return value
                0      if successful
                1      if not

The values structure passed to the routine is not affected by  the function.

1.2.13 int ReadPosition(int nAxis, long *lPosition)
The routine is used to readback current position of the output shaft.  The function reads the EN03 card indirectly - the EN03 card is read at PosSampleTime intervals at all times.  This routine returns the latest reading.

Hence, if this routine is called before ServoInit(), it will always return 0.

Call with
  nAxis          :   Axis number
  lPosition      :   pointer to a long integer.

Return Value
                0      if successful
                1      if not

1.2.14 int ReadSpeed( int nAxis,float *rSpeed )
The routine is used to read the  current speed of the motor.  The returned speed in terms of counts per second - see discussion on SetDacFact(...) for the units.

Call with
  nAxis         :   Axis number
  rSpeed       :   Speed in counts per second

Return Value
                0      if successful
                1      if not
 

1.2.15 int ReadRampStat(int nAxis)
The status of the motion may be read through this function.  The background position and ramp control loops set the status of the motion and this function reads this value.

Call with
  nAxis :   Axis number

Return Value
                 0 :    Motor is in dead band zone
                        (defined as NMVING)
                 1 :    Motor is ramping up (defined as URAMP)
                 2 :    Motor is Running at constant speed
                        (defined as FRAMP)
                 3 :    Motor is ramping down (defined as DRAMP)
                 4 :    Position control zone is reached
                         (defined as POSCTRL)

1.2.16 int StopAxis(int nAxis,char fHow)
This function stops the motion of the axis nAxis.  Two options are provided: immediate stop or ramp down to stop.  The parameter fHow is used to indicate which method is to be used for stopping.

Call with:

          nAxis  : Axis Number
          fHow   : IMMDSTP or SLWSTP

Return Value:

  Always successful

Note:

  1. Specifying sudden stop under heavy load condition may lead to overload condition of the drive unit.
  2. When stopping with SLWSTP, following code should monitor the motion with ReadRampStat(...) till the motor stops before issuing any movement commands (for the concerned axis)


1.2.17 int ClearMovement (int nAxis)
This function resets the position and ramping loops and effectively stops the movement of the motor.  This routine provides a way out of a situation where the motioin paraemters and controller constants are not matched and the system hunts.  Under these conditions, a call to ClearMovement(...) will stop the hunting and makes it possible to retune the system.

Call with:

  nAxis  : Axis Number

Return Value:

  Always successful

1.2.18 int ReadEncoder(int nAxis,long *lpPos)
This function provides a way of reading the encoder directly.  Please note that using this function after ServoInit(...) or before ServoClose(..) will lead to unpredictable results.  ReadEncoder is provided for use when the system has to be operated without other routines of servolib temporarily, for example, while referencing or homing.

Call with:

  nAxis  : Axis number
  lpPos  : Pointer to a long integer

Return Value

  Always SUCCESS

1.2.19 int WriteDac(int nAxis,int nVoltage)
This function provides a way of writing a new voltage directly to the DAC card.  Please note that using this function after ServoInit(...) or before ServoClose(..) will lead to unpredictable results.  WriteDacis provided for use when the system has to be operated without other routines of servolib temporarily, for example, while referencing or homing.

Call with:

  nAxis        : Axis number
  nVoltage   : Output voltage -2048 to +2048

Return Value

  Always SUCCESS

1.2.20 int InitDac(void)
1.2.21 int InitEncoder(void)
These routines initialise the DAC and EN02 cards.  The results are:

  1. The output voltage is set to 0
  2. The counters are cleared.
Care should be exercised while using these routines while the servo loop is active.  They should be used only when ReadRampStat return NMVING.

Call with:

  None.

Return Value:

  Always SUCCESS


1.3 Global Variables

Apart from servolib functions, certain global variables are defined which control the way the function operate.  They are listed below:

long fEncDirection

This variable controls the sign of the encoder feedback.  By default it is set to 1.  When set to -1, the reported count is of negative sign, effectively reversing the direction of rotation.

int fDACDirection

This variable controls the sign of the output voltage.  The default value is 1.  When it is set to -1, the polarity of voltage is reversed.

This control is particularly important in the following cases: