| |
|
|
|
2 USER'S GUIDE
This section describes the API functions and ACI commands provided by the mot and motci SW modules.
2.1 Overview
The Motor Control Module is designed for a standard LCU environment, consisting of a VMEbus system with a CPU board, running the VxWorks operating system. The MCM makes extensive use of the LCU Common Software facilities, such as Event, Error and Signal Handling, Time functions and, in particular Local Database access.
The Motor Control Module forms a service layer between application level and device driver level to provide a standardized, hardware independent interface between applications and motors. An application attaches the required motor(s) and performs operations with that/these motor(s) by means of the API routines or ACI commands without knowing details about drivers or boards.
In particular, the ACI, used in combination with the motei, provides a mean to the engineer to tune the motor configuration parameters and test the motions without having to write any code.
The following environment must be provided and set-up at boot-time to enable operation of the Motor Control Module.
All versions correspond to VLT Common Software Release OCT98, unless specified.
Note: The version of the Motor Control Module described in this manual works only with the above described versions of board firmware and device drivers. It is not possible to run the current version of the Motor Control Module together with older versions of the drivers.
Figure 1 shows the hardware and software environment of the MCM :
· The interface to the applications is covered by the modules mot (API ), and motci (ACI), which are described later in this document. The API provides a library of routines callable by LCU applications, while the ACI provides a LCU process implementing a set of commands which can be sent by LCU and WS applications (see also Figure 2).
· The interface to the device drivers, through which all hardware accesses are made, is covered by the so-called SDL modules. This interface is described in [4].
· The local database is accessed by dedicated routines, which are provided by the LCU Common Software [1] and by the Common Access Interface module [5].
· The facilities of the LCU Common Software are used whenever applicable for the needs of the Motor Control Module.
· The interface to the VxWorks operating system, i.e. to VxWorks specific system services is kept as small as possible.
2.2 Supported Configurations
This section describes the hardware components and configurations from the final-version point of view. The restrictions of the implementation of this version and the explicit identification of boards are described in the next section.
The motor hardware (i.e. the logical level below the driver level) can be divided into various groups. There are:
All the supported configurations are listed in Appendix A.
The only mandatory board for motion control is the amplifier, which may not be controlled by MCM (Stand-Alone mode).
Important Note: In all the supported configurations but #21 to #23, the amplifier can be replaced by any kind of Maccon MAC4-compatible purely passive amplifier.
· Limit and reference switches: There may exist two sets of upper/lower limit switches and one reference switch. When only an amplifier controls the hardware then only one set of limit switches is allowed, otherwise each combination of one or two sets of limit switches and/or one reference switch are possible.
· Types of position encoders: serial and parallel encoders for linear and circular axis with absolute (type SSI) or incremental (type INC) coding, with and without zero pulse are supported. The use of an encoder requires a motion controller board or an external encoder interface to get the encoder value.
· Additional I/O-Signals like interlock, emergency stop, motion stop etc. can be configured. Such signals are connected to a LCU through I/O-Boards. The mot module uses the Common Software signal handling facilities to process such signals.
Note: Internally, the mot module has no practical limitation on the number of motors it can support. However, each motor occupies system resources (CPU, dynamic memory, database space, etc.) on a LCU, which limits the maximum number of motors to about 30. The MCM object modules need about 200 kBytes memory space.
In addition, each motor requires the following resources:
In the above list the number of interrupt hooks is the strongest constraint because the hardware supports a maximum of 256 interrupts, which cannot be extended. All other resources can be extended by supplying more memory and configuring VxWorks appropriately.
2.2.1 Version Related Configurations
The MCM software supports all the configurations listed in Appendix A, but #21 and #23.
These configurations consist in:
· an amplifier (mandatory). If declared, the respective SDL is used. Otherwise, the MCM does not attempt to access any amplifier board. (see 4)
· a serial incremental INC/absolute SSI encoder, connected to the controller or to an external interface board.
The MCM package supports DC and Stepper motors.
2.3 Motor Registration
2.3.1 Configuration
Depending on the way the database branch of the motor has been generated (see 5.3.1), one may need to load the configuration file (<motor>.dbcfg file) into the DB branch. The configuration files are part of the application software and generated via the Engineering tool motei. They shall be installed in the $INS_ROOT/SYSTEM/COMMON/CONFIGFILES path and the $INS_ROOT file system shall be NFS mounted as /INSROOT on the LCU. The function motInitDb(1) performs this initialization, as shown in the example below for the motor aliased M1:
From the VxWorks shell, the installation of a motor is performed as shown below:
After this step has been successfully performed, the database branch of the motor has been initialized to the values contained in the file.
If no file name is provided, the file $INS_ROOT/SYSTEM/COMMON/CONFIGFILES/<alias>.dbcfg will be loaded (assumed it exists). It is also possible to give any valid absolute path, assumed it can be accessed via NFS from the LCU.
2.3.2 Installation
Before any operation on motors can be performed, all the motors connected to the LCU and intended to be accessed by the MCM, must be installed. The installation must be done only once for each motor and can be invoked either from the VxWorks Shell as a tool function, or within the application. The function motInstall() requires as parameter the alias (or the absolute path to the database branch) of the motor. It does various operations:
a. Resolution of the external functions (see HW-Initialization and Unit conversions): At installation time, the only requirement is that all external functions are resolved (their entry points have been found in the symbol table).
c. Conversion of the database attributes in board units: Database entries specified in user units are here converted to board units for performance.
From the VxWorks shell, the installation of a motor is performed as shown below:
The tool function motPrintMotors displays all the installed motors (see 3.3.4), see also motMotors(3).
2.3.3 Deinstallation
Deregistration: a motor can be de-registered from the MCM, after it has been detached, by the function motDeinstall(), which offers the same interface as motInstall().
2.4 Application Programmatic Interface
The mot SW module consists in two parts: the API functions and the Server routines. The API functions are the one that are invoked by the application, the Server routines manage the interface to the SDL layer; they operate on a single motor (see Figure 2).
Two groups of functions have to be distinguished among the API routines:
The motor branches of the local database contain all information needed by the API routines for motion control. The direct access to the database by applications is foreseen only for maintenance purposes (i.e. motor parameters configuration) and for the special applications (e.g. UIF) to monitor the motor status. Parameter passing from the application to the MCM is made via the arguments of the API routines. No parameter passing through the Local Database is foreseen.
Hence, during normal operation, only the API routines are invoked by applications.
The access to motors is realized by so-called motor handles. A motor handle is a number, which is delivered by the mot SW module to an application attaching a motor and enables the access to this motor. The access to a set of motors is released by detaching them.
One application can access several motors and the same motor can be accessed simultaneously (with restrictions, described below) by several applications. Moreover, an application can pass a motor handle to another application to enable its access to the corresponding motor.
On attachment request, a motor is identified by its name, which corresponds to the alias of the main point of the motor branch in the local database (see section 4 ).
With exception of the install, clear, attach and unit conversion functions, a list of handles terminated by the value 0 has to be passed as first parameter to each mot API routine.
Furthermore, the last argument of each API routine to be passed is the address of a ccsERROR structure. In the case of an error the error reason and number are passed back to the calling routine by this structure. In general, the processing loop of the passed handle list is broken when the first error occurs.
Finally, each API routine returns a ccsCOMPL_STAT completion status. Further arguments of API routines are function dependent. Hence, the generic synopsis of an API routine is:
ccsCOMPL_STAT mot<Function>(motHANDLE *handle,...,ccsERROR *error)
where the ellipsis ... stands for the function dependent parameters.
The API functions available in the current version are:
See section 3.1 for detailed information concerning each function.
Note 2 In the following sections, various examples will be listed. The variables used will be declared with the appropriate type where they are needed. The variables, which have been previously declared, will not be declared again.
Database attributes will be referenced by <path>:SUB_POINT.attribute, where <path> is the path to the motor point (e.g. :INS1:DC_MOTOR1).
2.4.1 Access Control
To get access to a motor, an application must attach the requested motor. The function motAttach is the first function to call. It returns the motor handle, with which further operation is possible. The application can attach the motor in several modes:
· motread_only motions are not allowed, only the request of status and configuration parameters, the status sampling, unit conversions and waiting for motion to complete are authorized
Only one application at a time can attach a motor in exclusive mode. Further attempts are rejected with an error. However, an arbitrary number of applications can attach in read-only mode. The emergency mode is always allowed without restrictions but shall really be used in case of emergency only.
The associated literals to the type motACCESS_MODE are defined in motDefines.h.
Table 1 shows the allowed combinations, where RO, EX and EM stand resp. for Read-Only, Exclusive and Emergency; [n] means many times, [1] once only.
A connection to a motor is released, i.e. the corresponding motor handle is freed by calling the function motDetach, which results in the application losing access to the motor.
Important Note: After a motor has been attached in Exclusive mode, it must be SW and HW initialized. Detaching an initialized motor from Exclusive mode leads to loose the initialization.
2.4.2 Operational Modes
Each motor can be used in several modes of operation:
The SIMULATION mode is used for operation without hardware. No driver calls are made in this mode. The simulation mode is handled on the Single Device Library level (see [4]). The processing down to the level of driver calls is identical to the NORMAL mode. In simulation mode all hardware actions are simulated to be done instantaneously and successfully.
In HANDSET mode the motor is controlled manually through LCU boards. No motion can be started, but read access is granted for the current status.
The mode NOT AVAILABLE signals that a motor cannot be used. This state is entered by command after a malfunction is detected from the outside. No motion is allowed. Read access is granted for the current status.
The mode FIXED POSITION is internally treated in the same way as the NOT AVAILABLE mode. It is just for information of an application that the motor is available but cannot be moved.No motion is allowed. Read access is granted for the current status .
The operational mode can be set by an application through the motSetOpMode routine. It can be used regardless of the active operational mode. The associated literals to the type motOPMODE are defined in motDefines.h.It is not allowed to change the operational mode while a motor is moving.
The current operational mode can be requested through a motGetOpMode call.
Furthermore, the current operational mode is stored in the local database attribute <path>:STATUS.opMode.
On the first attachment, an initial operational mode is read from the database and activated:
attribute <path>:SERVER:CONF.motor(0,opMode).
Note : When a motor is not anymore attached by any application, its operational mode is set to the internal mode motDETACHED. This mode can not be selected by the application.
Note : When the operation mode of a motor is changed by an application, its initialization state is reset to motNOT_INIT.
2.4.3 Initialization Procedure
After the first attach in exclusive mode, a motor must be initialized before any motion can be performed.
The initialization is divided into two phases: software and hardware initialization.
The software initialization must be performed first. The motor configuration as stored in the database is loaded to the boards and the internal data structures are initialized.
If the logical variable mandatory is TRUE, the SW initialization will be performed in any case; if it is FALSE, the SW initialization will be performed only if the motor has not been initialized before.
On success, the attribute <path>:STATUS.initStatus is set to motSW_INIT. The associated literals to the type motINIT_STATUS are defined in motDefines.h. On failure, it is set back to motNOT_INIT.
The SW initialization completes when all parameters used by the user-defined functions are valid (see 2.4.12).
In the case the encoder is not connected to the Motion Controller board and the position information is available from the CPU (valid VME address), a special procedure must be implemented that updates the position information as requested by the Motion Controller (assumed the board can handle this feature; available on Maccon MAC4 from this release on). Detailed information is given in section 2.4.13.
This procedure must be invoked before any motion is initiated.
The hardware initialization performs a sequence of actions (motions and settings), necessary to bring the motor and its parameters to a known initial state. The wanted sequence must be defined in the LCU Local Database, attribute <path>:SERVER:INIT.actions. The number of actions is not limited. The associated literals to the type motACTION_TYPE are defined in motDefines.h:
An action is defined by the following parameters:
A typical sequence of actions to initialize a motor could be
If the logical variable mandatory is TRUE, the HW initialization will be performed in any case; if it is FALSE, the HW initialization will be performed only if the motor has not been initialized before (i.e. the attribute <path>:STATUS.initStatus is motSW_INIT). While the HW initialization is running, the attribute initStatus is set to motHW_INIT_RUN. On success, the attribute initStatus is set to motINIT_DONE; on failure, it is set back to motSW_INIT.
The HW initialization completes when positions which have been defined relative to HW positions are fully resolved.
The HW initialization procedure may last some time, and the application may want to use this time for other operations. It would also like to know exactly when the HW initialization procedure is completed, without consuming CPU time. The function motWaitInit fulfills these expectations:
The function returns when all the motors of the handle list have completed their HW initialization procedure or a timeout has occurred, or immediately if an error occurred. The function returns SUCCESS when the HW initialization has been successfully completed within the given time; it returns FAILURE if a timeout has occurred (error number set to motERR_TIMEOUT), or if the procedure failed (the error number is then set appropriately).
The status of each specified motor is updated on function completion, regardless of the returned completion status.
On failure, the HW initialization procedure of the remaining motors is not interrupted.
Only one process can wait for the HW initialization procedure of a given motor to complete.
The timeout can also be set to WAIT_FOREVER (-1), this should be handled with care.
2.4.4 Motion Modes
In order to be able to move a motor, a motion mode must be set through the motSetMotionMode routine. Possible choices:
In motPOSITION_MODE mode, a motor can be moved to a position defined by a relative or absolute value.
In motDIRECT_MODE mode, a motor will be moved directly via the amplifier, whereby only the speed can be specified. The speed can be changed at any time by a further call to motMove.
In motTRACKING_MODE mode, a motor can be moved to a given absolute or a relative position, or at a given speed, whereby the next position/speed can be redefined at any time during the motion by a further call to motMove.
In motSPEED_MODE mode, a motion is defined by a speed and controlled by a motion controller. After starting a motion by motMove, the motor will move with the specified speed until a limit is reached or the motor is stopped by motStop. The speed can be changed at any time during the movement by a further call to motMove.
The associated literals to the type motMOTIONMODE are defined in motDefines.h.
2.4.5 Motion Specification
A motion is specified via a motMOTION structure. A sequence of motions is specified by an array of such structures. The motMOTION structure type is defined in the motor control module include file mot.h. A motion structure consists of the following parameters:
· a flag indicating, when TRUE, that this structure is the last element of the motion sequence array.
The position type specifies how to interpret the specified position. The associated literals to the type motPOS_TYPE are defined in motDefines.h. Possible types are:
Up to 10 steps may be defined in a sequence, but the position types motINDEX_PULSE, motTWO_STEP_ABS, motTWO_STEP_REL, motHALF_TURN_ABS and motHALF_TURN_REL extend to 2 entries, increasing the length of the sequence. If the sequence is longer than 10 entries, an error message will be logged (motERR_EXTRA_IGNORED), and the first ten entries of the sequence will be processed.
One additional position type is available for the HW Initialization only: motOFF_REFERENCE_SWITCH which operates in Position mode. The position of the motor is checked against the Reference Switch; if the Reference switch is not active, no motion is initiated, otherwise the motor is moved of the specified relative displacement off the Reference Switch.
For relative positioning, only positions specified by value are allowed (see below).
According to the definition of the motion modes, table 2 shows the possible combinations of motion mode and position type:
The motion to the index pulse is performed in two steps: the first step is a coarse search made at the given speed, the second is made in reverse direction at the speed predefined in the database attribute <path>:SERVER:CONF.indexPulseSpeed. Depending on the motion controller board, this feature may not be supported; however, the mot SW module invoke twice the same call to the motion controller MoveToInd (see [4]), with successively the two speeds. The way the motion controller handles these calls is not in the scope of this manual.
The motion to the Home position is defined as being the overlap of the Reference Switch and of the Index Pulse of the encoder (this position can be reached only if the hardware has been configured so that these two positions overlap and assuming that the encoder delivers the Index Pulse signal (Incremental encoder only).
Two step motions are handled as normal steps in POSITION mode, but the motion is executed in two steps, whereby the second step is predefined in the database attribute <path>:SERVER:CONF.twoStepOffset. This offset is added to the target position for the first step, then the way is covered back at the predefined speed. This feature allows the positioning to be executed always from the same side of the target position (eliminating possible backlash effects).
Half Turn motions are handled as normal steps in POSITION mode for CIRCULAR axis only, but the motion is executed in two steps, whereby the second step is predefined in the database attribute <path>:SERVER:CONF.twoStepOffset. This absolute offset is subtracted to the target position for the first step, then the way is covered in the same direction at the predefined speed. This feature allows the positioning to be executed in a deterministic way.
However, for not optimized circular axis, the motor will not (per definition) cross the zero.
If the requested position (HW limit, Reference Switch, Index Pulse or Home position) is not available on the hardware or the action is not supported by the firmware/driver or SDL, the motion fails (see section 2.4.6).
The position and the speed can be specified in three, resp. four ways:
· by value, whereby all information defining the position or the speed has to be provided by the user.
· by name, whereby only a position/speed name has to be provided by the user and any further information is retrieved from the database attributes:
· by index, whereby only an index to the namedPositions/Speeds attribute of the motor in the local database has to be provided by the user and any further information is retrieved from the local database
The associated literals to the type motSPEC_TYPE are defined in motDefines.h,.
The following parameters have to be defined by the user specifying the target position or speed:
· by value: The position or speed is specified by a value and a unit (see data structure type motMETRIC in mot.h). For the speed, three additional parameters are required (see section 2.4.7 for explanation):
· pollInt Monitoring polling interval in ms of the far phase; the motor is moving to the target position
· by name: for the position, an additional parameter is required specifying the offset to the named position: the so-called section (the offsets are defined for each namedPosition entry in the database). The associated literals to the type motSECTION are defined in motDefines.h:
· by index: The index number specifies the record number of the entry of the attribute named Positions/Speeds to be used.
For the position indexing, it is possible to specify the section (as for by name). The following macros are available:
For the position specification by name or by index, the value stored in the field number is taken as an offset if the string defining the unit is not empty.
2.4.6 Motion Control
Before trying to move a motor the following actions have to be performed:
· Perform the SW and HW initialization of the motor, calling motInitSw and motInitHw (see section 2.4.3)
· Configure the motion mode according the intended movement, calling motSetMotionMode (see section 2.4.4).
After successful execution of these operations a single motion or sequence of motions of the motor can be started using the motMove function.
Motions are rejected, when the access mode is not EXCLUSIVE or EMERGENCY, the motor is not available because of hardware malfunctions, the brake is clamped, the interlock line is active or the initialization procedure failed.
An application can ask once or periodically for the status of a motor or a set of motors, by calling the routine motGetStatus (see also 2.4.8), or wait for the motion completion, by calling the routine motWaitMove, which works like motWaitInit. This function returns either on motion successful completion, time-out or abnormal event.
Two types of timeout may occur:
Motion step timeout The motion step could not be completed within the time within which any motion step shall complete. This time is defined in the database attribute <path>:SERVER:CONF.motor(0,timeout) in milliseconds.
Motion sequence timeout The motion sequence could not be completed within the time given to the motWaitMove function.
This routine returns a structure, containing the status of the motors. The associated literals to the type motMOTION_STATUS are defined in motDefines.h:
An application can stop a motor by using the motStop routine. After the motor has stopped, another process waiting with motWaitMove is resumed and returns FAILURE. The motion status is set to STANDING; if in POSITION motion mode, the status flag inPosition is not set because the target position was not reached.
2.4.7 Motion Monitoring
From the point of view of the MCM a movement consists of two phases:
· the near phase, where the target is almost reached, the motor is in the target window and the motor slowly moves to its end position
A movement is automatically supervised by a monitoring task, which periodically requests and evaluates the actual status. Three parameters have to be made available to the monitoring task:
These parameters have to be specified either by the user via the motMOTION data structure passed to motMove (see section 2.4.5) or, if a named speed is used, in the corresponding namedSpeeds record of the local database.
For each motor a time-out value is configured in the local database, to specify when motions of this motor shall be treated as lasting too long and be timed-out. However, the motion monitor task does not undertake any actions on abnormal events or time-out but informs the application by setting the motor status in the local database accordingly.
If the motion completion is to be reported by an interrupt (see 2.4.10), it returns the motion status STANDING as soon the motion end event has been registered by the motion monitor (assumed the in Position time is larger than the target settle time, see motion controller mac4 parameter TT).
2.4.8 Status Sampling
The Motor Status Sampling facility performs monitoring and status sampling of any set of motors, no matter whether they are moving or initialized. The sampling is started by the routine motInitSampling. A sample period can be specified at which the general status data in the local database is updated. The motStopSampling routine is used to stop the sampling. For detailed information about the general status data section of a motor in the local database, see section 4.
The status sampling task is automatically spawned after the motor has been successfully SW initialized. The sampling task updates the status with the period specified in the database attribute <path>:SERVER:CONF.motor(0,timemon) in milli-seconds. The sampling task runs until the motor is detached or explicitly stopped by motStopSampling. The sampling task remains alive (regardless of any call to motStopSampling) as long a motor is at least SW Initialized. For Read-Only processes, calls to motStopSampling will have little effect.
Note: During all the time a motor is SW initialized, the status part of the database is automatically updated on change of any value, but the quantities defined in user units (speed, current, position, next position, position names and following error).
These fields are updated each time motGetStatus in invoked, thus when the status sampling is running.
The section in which the named position will be retrieved from is set by the section passed in the motion definition. If no section is specified, the actual section remains valid (target defined by value). The function motSetSection allows the setting of a new section, it remains valid until a motion referencing another section is initiated. It is however possible to invoke motGetStatus specifying a different section: the DB values will continue to be updated according to the actual section, but the returned status structure will be updated according to the section set in status.posSection (the section used for the nextPos fields is the same).
2.4.9 Unit Conversion Facility
The Motor Control Module allows the user to specify positions, speeds and electric currents in common user units (e.g. meters, meters/second or ampere). Internally, such values must be known in board specific units (e.g. encoder ticks, digital binary or velocity reference). Vice versa, the boards return run-time data in specific units which must be converted into user units.
Therefore, the mot SW module provides a set of unit conversion functions, which are used internally but also accessible from application level. The unit conversion facility is designed to transform user units for position, speed and electric current into board specific values and vice versa.
The mot API provides the following routines for unit conversion:
An application can specify a position, speed or current argument to a mot function in any appropriate user units. A user unit is of the type motUNIT and can be seven characters long at maximum. The speed unit must contain a slash '/'. Possible units are for example:
The function motSetDefaultUnits allows the user to set the three user units to be used for every conversion from board to user unit. For each user unit, a conversion method must be defined in the local database motor section, to be able to convert a speed/position or motor current value to a board specific value and vice versa (see section 4). The board specific values and their units are:
· for a speed value: encoder ticks per ms ("Enc/ms") for a motion controller board and velocity reference value ("Ref") for an amplifier board
The board units are defined in motDefines.h: motBOARD_UNIT_POS, motBOARD_UNIT_SPD, motBOARD_UNIT_REF and motBOARD_UNIT_CUR, resp. for position, speed (Motion Controller and Servo Amplifier related) and current.
For each motor all necessary user unit conversion methods have to be defined in the local database motor section, point <path>:SERVER:UNIT. This point contains the unit conversion table named "unitConversion", whereby each record defines a unit conversion method. The table must contain at least 4 methods, corresponding to the four default units. The name of the unit conversion is specified in the first field and is built up in the following way
So, for example, the first field of the record specifying the unit conversion "deg" to "encoder ticks" (Enc) contains "degToEnc".
Thus for each user unit to be used for motions, the following unit conversions must be specified in the unit conversion table.
Three methods for conversion are available:
two parameters (slope and offset) define the conversion formula
a vector of 50 pairs of coordinates (x,y) defines the domain of conversion.
the point coordinate x (or y) greater than or equal to the origin value x (or y) is searched, the interpolation is performed linearily between this point and its predecessor.
Any position, speed or motor current is specified by a motMETRIC data structure containing
Beside the unit conversion, the functions motNameToEnc, motEncToIndex and motEncToName allow to convert a named position to an encoder value and vice versa. Each named position to be used has to be defined in the "named positions table" in the configuration section of the local database, attribute <path>:SERVER:CONF.namedPositions.
The function motNameToVel provides the facility to convert a named speed into its value in Enc/ms. Each named speed to be used has to be defined in the "named speeds table" in the configuration section of the local database, attribute <path>:SERVER:CONF.namedSpeeds.
For relative positions, it is mandatory to give the position unit either as Enc or as the default position unit.
2.4.10 Emergency Handling and Abnormal Events
Abnormal events are caused and detected by hardware components. Up to 32 events may be configured. They can be processed by software, interrupt, signal or not processed. (Literals are defined type in motDefines.h). The database attribute <path>:SERVER:CONF.events contains the description of the event handling mechanism for all the supported events.
Interrupts are generated by the hardware. As configured in the local database, the internal interrupt service routine (motsrvIsr) can be connected to the given board in order to catch the interrupts, and inform the motion monitor about the event. If the event is to be connected to an interrupt, then the board generating this interrupt (Literals for the type motBOARD_TYPE in motDefines.h) and the name of the interrupt must be supplied.
The boards return status data which may contain information about abnormal events. This includes on-limit flags, board failure status, over-temperature and over-current. These data are stored in the local database STATUS section of each motor and updated on every motGetStatus call. The motion monitor calls this routine in every polling cycle and processes abnormal event information directly.
When an abnormal event is detected, the motion monitor writes error information into the local database STATUS, releases a motWaitMove or motWaitInit immediately and terminates. The application gets informed by motWaitMove/Init returning and the appropriate motion/init status in the motor status.
In case of emergency, a supervising task can get access to a motor by attaching it in EMERGENCY mode. This mode overrides even the EXCLUSIVE mode and enables all actions for the attaching task.
2.4.11 I/O Signals
Three digital I/O signals may be handled for a motor:
· Interlock Line The status of this line may be retrieved by the function motCheckInterlock, it is also updated in the status by the function motGetStatus. If this line is active, the motor is not accessible by other applications, even if it is detached or attached in read-only mode.
· Brake Status The status of this line is updated in the status by the function motGetStatus. If this line is active, the motor cannot be moved.
· Brake Line The brake may be clamped or unclamped by the functions motClampBrake and motUnclampBrake. The brake status of the database is updated accordingly.
These signals are handled by the digital I/O board ACROMAG. They are mapped by one I/O line per signal (fully configurable: digital I/O device, line number and logical level) as described in the attribute <path>:SERVER:CONF.signals.
2.4.12 User Function Hooks
Two types of user-defined function hooks are available:
A user-defined function may be invoked automatically from the API while performing the HW initialization procedure or for unit conversion, if the following requirements are satisfied.
2.4.12.1 HW Initialization Procedure
An action of type motACTION_USER_DEFINED must be created in definition of the HW initialization procedure in the database (see section 2.4.3) and the following two parameters have to be set:
· userParList is the address of a data structure to be passed to the function. Depending on the function, this parameter may be optional and the structure and content of the parameter list is under responsibility of the user.
The interface of the user-defined initialization functions must comply the following rule:
2.4.12.2 Unit Conversion
A conversion method of type motEXTERN must be created in the database (see section 2.4.9) and the following two parameters have to be set:
· userParList is the address of a data structure to be passed to the function. Depending on the function, this parameter may be optional and the structure and content of the parameter list is under responsibility of the user.
The interface of the user-defined conversion function must comply the following rule:
2.4.12.3 Arguments Passing Mechanism
It is possible to pass the address of a user-defined data structure to the function. The addresses of the structures must be stored into the database before the function is invoked.
The enumeration type motUSER_FCT provides the necessary literals specifying the attribute to be accessed:
For this purpose, two functions are available motSetParListAddress, that stores the address of the user-defined data structure into the database, and motGetParListAddress, that retrieves the address from the database.
Example for the HW Initialization Procedure:
Assumed one entry of the HW Initialization procedure is set as follows in the INIT part of the database:
The function expects the address of a structure containing the two parameters handle and param, as declared in the structure defined below:
The main code invoking the HW initialization will then be as follows:
Important note: The user parameter list must be set to a valid address or to NULL before invoking the user function. For the user initialization function before invoking motInitHw, for the user defined unit conversion function before invoking the function. It also strongly recommended to preset these addresses after installing a motor, at the latest before initializing the motor. The address is checked for validity when set (see motSetParListAddress), NULL is always accepted.
2.4.13 External encoder support
For the case, where the encoder is not connected directly to the standard motion controller and where the CPU shall provide the encoder value, a couple of dedicated actions must be initiated so that the CPU and the Motion Controller board get synchronized.
The attributes SERVER:CONF.encoder(0,board) must be set to motCPU_BOARD
and SDL:MAC4:CFG.configValues(IEV) = 192 (0xC0).
During the SW initialization, the motion controller is configured to deliver an interrupt every 2.5ms. On the CPU, the Interrupt Service Routine motsrvIEV is connected to this interrupt. It catches the interrupts and gives a semaphore. A dedicated task is to be spawned that waits on this semaphore, reads the encoder information (not in the scope of MCM) and writes the new encoder value to the Motion Controller.
The task must be spawned before the Software Initialization has been successfully performed.
Two functions are provided that:
The motor must be attached in motExclusive mode.
When the motor is detached or set in another operational mode than motNORMAL, the interrupt is disabled. The semaphore is deleted, when the motor is de-installed. The task should terminate before the motor is detached (device is closed, handle is not valid any more).
2.5 Application Command Interface
The Application Command Interface (ACI) is implemented in the module motci and is available as a LCU process (motServer). It is based on the LCC Command Interpreter, implementing in form of commands most of the functions of the Application Programmatic Interface (API). The ACI is built on top of the API and adds two major advantages:
· It allows applications running on WS or LCU to deal directly with motors independently on the platform.
· It provides, in combination with the CCS Engineering Interfaces ccsei, or with the MCM Engineering Interface motei engineers with tools to configure motor parameters and test motors without having to write code.
The main concepts described in section 2.4 and sub-sections apply to the ACI module as well and will not be repeated here.
2.5.1 Commands
The commands supported in the current version are listed below, they are grouped by topic.They will not be described in detail; see section 2.12 and following of the LCC Common Software User Manual [1] for further explanations.
Most of the command refer to the notion of set. A set is a group of motors that are intended to be controlled simultaneously, but which may perform independent actions. The commands that apply to a set also apply to a single motor, but the commands handling the sets (1 to 5).
Speed definition and Sequence management
For detailed information on commands see section 3.2 and on-line help using ccsei/motei.
2.5.2 Input Syntax
All enumerated input parameters can be given either as numerical value (e.g. 4) or as the corresponding string (e.g. Simulation). The command interpreter is case sensitive.
The command STATUS, MOTPAR, NAM2ENC and ENC2NAM accept the enumerated parameter section, specifying the position section to search in for the position and next position names (if any). If no name is found the string "None -1" is returned. This parameter can be defaulted, the value "No Section" is then passed, the actual section is then used.
Example: The sign > prefixes a command, the actual position is assumed as 'blue' in the Maintenance section.
>STATUS DC1,UserDefined,PositionName
>STATUS DC1,Maintenance,PositionName
The STATUS command accepts a parameter list as third parameter. If this list is empty, the complete status is returned. Otherwise, for each requested parameter (up to 10), the status value will be returned:
Example: The sign > prefixes a command
>STATUS DC1 returns the full status,
>STATUS DC1,Observation returns the full status but the names are searched in the Observation section,
>STATUS DC1,,MotionMode returns only the motion mode.
The WAITINI and WAITMOV commands are the only commands which do not return immediately the last reply. The first reply is the command acknowledge, the following replies are returned on function completion (in the meanwhile the command interpreter is available for other commands). One reply is returned for each specified motor. If an error occurred, an additional reply is returned containing the error message. The time-outs have to be given in seconds.
Example: The sign 12> prefixes the command #12
10>CREASET X,DC1,DC2 create a set containing the motors DC1 and DC2
11>INITHW X perform HW initialization procedure,
12>WAITINI X,300 wait max. 300s for completion
12 REPLY WAITINI command accepted
13>STATUS DC1,,MotionMode returns only the motion mode.
13 REPLY STATUS DC1 : Speed motor DC1 is in Speed mode
14>WAITINI DC1,5 wait 5 seconds for completion for DC1 only
14 REPLY WAITINI DC1 : ...,InitStatus H/W Initialization Running,...
14 ERROR WAITINI 0x0CF30003.1 mot (motWaitInit.c)
"motERR_MULTIPLE_WAIT : motor 'DC1', handle is 5023804 - Another application is already waiting for action completion" (Serious 40)
12 REPLY WAITINI DC1 : ...,InitStatus Initialization Done,...
12 REPLY WAITINI DC2 : ...,InitStatus Initialization Done,...
2.5.3 Output Syntax
The output syntax is built as follows:
For all the commands, but STATUS, MOTPAR, GENSTAT and HWSTAT, one reply is returned; otherwise one reply per motor is returned.
For commands that query a single parameter (e.g. GETOPMO), the field parName is omitted. For position names, the field parValue takes the position name, the field parUnit takes the section; if no name can be found the fields parValue and parUnit take the value "None" and "-1", resp.
Example: The sign > prefixes a command
GETOPMO DC1 : Simulation,DC2 : Normal
>STATUS X,,OperationalMode MotionMode
STATUS DC1 : OperationalMode Simulation,MotionMode Direct
STATUS DC2 : OperationalMode Normal,MotionMode Direct
2.5.4 Output Format
The commands that query information from the motors accept an additional parameter (which may be ignored). This integer parameter takes the values 0 or 1 and is defaulted with 0. It influences the output format for enumerated parameters only:
All literals for status parameter values are defined in motDefines.h.
The names of the status parameters are defined in motciDefines.h.
Example: The sign > prefixes a command
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|
