| |
|
|
|
3 REFERENCE
3.1 Introduction
This chapter provides a detailed description of the Maccon driver module interface to the user, namely functions, commands, include files and tools.
These functions are described in UNIX man-page format and are organized in a functional order. Below is an index of the routines in the same order.
Each of these calls returns a status code which signals the success of the call. A zero value always means "successful completion", while a negative one indicates an error. The value -1 stands for "general error" and originating in VxWorks while other values signal a specific error reason and are returned by the driver itself. Literals of all error codes can be found in the header-files lcudrvErrors.h and mconErrors.h.
3.2 Functions
As mentioned above, the Maccon driver uses the standard VxWorks I/O system calls open, close, ioctl to interface to the user. These functions are described in the following sections with respect to their special meaning in the Maccon driver context. For more general informations see the "VxWorks Programmers Guide".
3.2.1 Installation Functions
These functions are used to install the driver and devices at system start-up. They must not be invoked more than once.
This function installs the MACCON device driver.
It is called only once at startup. It hooks up the various
I/O service calls to the diver's functions, assigns the driver number,
and adds the driver to the driver table.
devices - number of supported devices by the driver
channels - number of channels that can be simultanously opened
timeout - access timeout value (in ticks) or NO_WAIT or WAIT_FOREVER
lcudrvOK - driver successfully installed
lcudrvERROR_DRIVER_EXISTS - the driver is already installed
lcudrvERROR_NO_MEMORY - there is not enough memory for dynamic
data structures
lcudrvERROR_INVALID_ARGUMENT - the value of one of the parameters is
out of range
'timeout' should always be > 0 and effectively around 0.1 - 1 second.
This value is applied for semaphore-waits, the total command execution
time is additionally checked after completion with '4 * timeout'.
NO_WAIT and WAIT_FOREVER should only be used for test purposes.
mconDevCreate(3), mconOpen(3), mconClose(3), mconIoctl(3),
lcudrvInitDCT(3),
iosLib(1), iosDrvInstall(2), open(2), close(2), ioctl(2)
#include "mcon.h"
STATUS mconDevCreate (const char *devName,
const void *baseAddrA24,
int devNumber,
int backplaneAddr,
u_char vectorOutputNbr,
u_char vectorNbrDriveFault,
u_char vectorNbrMotionEnd,
u_char vectorNbrEmergencyStop,
int intrLevel
int mac4Version)
This function is called at startup once for each device (i.e. each
axis controlled by a MACCON controller) to be installed.
It adds a device to the driver, making it available for subsequent open
operations.
devName - device name (must be "/mconX" X>=0, e.g. "/mcon0")
baseAddrA24 - VMEbus base address of the board in the A24 standard
address space [0x00000000..0x00ffffff]
(upper 8 address-bits are ignored, but should be zero)
0xffffffff: map board space into main memory for simulation
devNumber - number of board channel used for the device [1..4]
backplaneAddr - backplane address (jumpered board number code)
vectorOutputNbr - interrupt vector number of output
vectorNbrDriveFault - interrupt vector number of drive fault
vectorNbrMotionEnd - interrupt vector number of motion end
vectorNbrEmergencyStop - interrupt vector number of emergency stop
intrLevel - interrupt-level used for the device [1..7]
mac4Version - firmware and hardware version of the MAC4 controller,
'0' means don't care
Note: See CAUTION for interrupt vectors, '0' means 'no interrupt'.
lcudrvOK - successful completion
lcudrvERROR - there is a general VxWorks I/O error
lcudrvERROR_NO_DRIVER - MACCON driver not installed
lcudrvERROR_INVALID_DEVICE - invalid device name or device number
lcudrvERROR_DEVICE_EXISTS - device already installed
lcudrvERROR_NO_SEMAPHORE - failed to create semaphore
lcudrvERROR_NO_MEMORY - failed to create object in memory
lcudrvERROR_TIMEOUT - failed to take semaphore before timeout
lcudrvERROR_INVALID_ARGUMENT - Maccon controller baseaddress,
version or backplane-address not valid
mconERROR_START_TIMER - failed to start VxWorks watchdog timer
mconERROR_STOP_TIMER - failed to stop VxWorks watchdog timer
mconERROR_QUEUE_FULL - failed to send command to the controller
mconERROR_SYNC_TIMEOUT - failed to take synchr.-semaphore, i.e.
no "answer ready"-intr. before timeout
mconERROR_NO_REPLY - failed to read reply from queue although
intr. indicates that reply is available
mconERROR_WRONG_REPLY - reply contains not the same axis number
as the command (maybe interrupt vectors
are not properly assigned)
mconERROR_STATUS_INVALID_AXIS - controller detected invalid axis number
mconERROR_STATUS_SYNTAX - controller detected invalid command no.
mconERROR_STATUS_PARAM_RANGE - controller detected invalid parameter,
e.g. value/position out of limits
mconERROR_STATUS_UNEXP_COMMAND -controller detected unexpected command,
e.g. wrong sequence in initialisation
mconERROR_STATUS_FOLLOWING_ERROR - max. following error exceeded
mconERROR_STATUS_ENCODER_FAULT - read encoder value out of limits
mconERROR_STATUS_DRIVE_FAULT - drive-fault signal is active,
e.g. amplifier not in normal-mode
mconERROR_STATUS_COMM - communication error, i.e.
controller watchdog timeout
Access protection semaphores for critical data are created on a
per-board basis, i.e. only one device per board can be accessed at a
given time. If a command is specified as 'protected' in the cmd-table,
then the access is locked until the reply for this command is issued,
otherwise multiple commands can be entered in the input-queue.
Accesses to the queue itself are always protected.
Synchronisation semaphores are created seperately for each channel and
are connected to the "answer ready" interrupt of the channel.
The interrupt-vector of EmergencyStop is common to all devices on one
controller-board. Therefore either the vectors of all devices must be
set equal or only the vector of the first device must be set to a
non-zero value and the rest to zero (then the other devices effectively
use the same vector as the first device)
mconDrv(3), mconOpen(3), mconClose(3), mconIoctl(3),
iosLib(1), iosDevAdd(2), open(2), close(2), ioctl(2)
3.2.4 VxWorks System Calls
The following functions are used after driver and device installation to open and close a channel to a specific device and send commands to it. They are part of the VxWorks I/O-system and route the call to the respective mcon routine described in section 3.2.8.1
This operation opens the device corresponding to deviceName, in read-only mode or in one of the three read-write modes described below. The read accesses are always granted for any open modes.
Shareable read and write mode. Write access is granted to a defined number of processes to use this open mode. Exceeding this number or requesting this mode for a device already opened in Exclusive write mode returns an error.
Exclusive read and write mode. Write access is granted to the process using this open mode. Requesting this mode for a device already opened in Exclusive or Shareable write mode returns an error.
Test read and write mode. Write access is granted to the process using this open mode regardless of the status of the device. Requesting this mode for a device already opened in Test mode returns an error.
· A value of -1 signals a general error. The specific error reason is provided in the argument status which can be:
The requested open mode is conflicting with the open modes of already existing channels. This error is caused by one of the following reasons:
int fd;
...
fd = open ("/mcon0", lcudrvOPEN_READONLY);
if (fd < = 0)
{
/* error process */
}
else
{
/* normal process */
}
· Device names shall not be longer than 15 characters. They shall be defined by use of the function mconDevCreate at start-up.
· This function is not queued by the driver, it always returns with the file descriptor or an error type.
· Applications can have the same device opened several times, using different file descriptors. Furthermore, open modes can be mixed according to the rules previously described.
· As only one process can open a device for Exclusive write mode at any one time, and the number of channels is limited, applications should issue a close call if no action on the device has to be performed.
· The VxWorks include file "configAll.h" contains two literals used by iosInit function: NUM_DRIVERS which defines the maximum number of drivers allowed, and NUM_FILES, the maximum number of opened files. They are respectively defined as 20 and 50.
· The VxWorks command "iosDrvShow" shows all drivers of the system, and their basic i/o entry_points. The commands "iosFdShow" shows all currently used file descriptors, and "iosDevShow" (or "devs") all devices.
This operation closes a channel to an opened device, and frees the file descriptor. fileDescriptor must correspond to one of those obtained previously by an open call.
int fd;
int closeError;
...
fd = open ("/mcon0", lcudrvOPEN_TEST);
...
closeError = close (fd);
if (closeError != lcudrvOK)
{
/* error process */
}
else
{
/* normal process */
}
This function commands the driver to perform the specified operation on the device. The commands are divided into read and write commands. Read commands are allowed in each open mode, while write commands will be rejected if the channel was not previously opened in Shared, Exclusive or Test mode.
· command is an integer identifying a Maccon command to be sent to the driver. The values identifying a command are defined in the include file mconCommands.h.
· argument is the address of the command argument, or NULL if no argument is used. For 'Write' commands, argument contains the values to be written, for 'Read' commands, argument contains the value read.
Arguments, when used, can only be an integer. Exceptions are for the commands to connect an interrupt service routine to emergency stop, drive fault or motion end event, where argument shall be a pointer of the structure mconCONFIG_INT.
· lcudrvERROR_ACCESS_CONFLICT if the write command can not be executed by use of a file descriptor previously obtained with a read-only open mode.
· Other driver specific values returned by the driver are described for each ioctl command in section 3.3 and a full description of errors can be found in chapter 5.
· This function is protected by semaphores, and commands are queued by application priorities rather than by First-in First-out. The timeout value is applied for tasks which are blocked on a semaphore. This delay, expressed in ticks, is initialized at start-up, and can be set/got at run-time by two additional commands: set/get timeout.
· A VxWorks-timer is implemented to check the permissible maximum execution delay of a command. This delay is derived from the above timeout-value. An error is returned when the execution-time of a command was longer than the delay (see section 3.2.1).
3.2.8 Interface Functions
These function represent the interface between the VxWorks I/O system calls open(), close() and ioctl() to the controller-hardware. Therefore they are not directly used by application programs.
This function is installed in the I/O-system of VxWorks and is
called via open() when a channel to a MACCON device shall be opened.
It represents an interface routine between the MACCON driver
routines and the general lcudrv driver routines.
device - pointer to the descriptor of the required device
remainder - remainder of the device name; should be blank
mode - open mode, specifiying the access to the device
status - pointer to the returned status value (NULL: not returned)
channel number (> 0) - successful completion
lcudrvERROR - error (detailed in '*status')
In '*status':
lcudrvERROR_INVALID_DEVICE - remainder not blank/invalid name
lcudrvERROR_ACCESS_CONFLICT - open mode not consistent
lcudrvERROR_NO_CHANNEL - no more channel available
lcudrvERROR_INVALID_OPEN_MODE - unknown open mode
This routine is called when a channel of a MACCON device shall be
closed. It represents a interface routine between the special
MACCON driver routines and the general lcudrv driver routines.
channel - channel to be closed
lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT - invalid channel number
lcudrvERROR_NO_CHANNEL - channel was not open
This routine is called when a control command is send to a MACCON
device via ioctl(). It validates the command request, performs a
semphore protection if required and calls the command procedure to
be executed.
channel - channel number as returned by the mconOpen() function
command - number identifying the operation to be performed by the
driver (as defined in 'mconCommands.h')
argument - address of the command argument or NULL if no argument is
used. For commands needing multiple arguments it is the
address of a specific data structure.
lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT - invalid channel number
lcudrvERROR_CHANNEL_NOT_OPEN - channel was not open
lcudrvERROR_INVALID_COMMAND - command code invalid
lcudrvERROR_ACCESS_CONFLICT - insufficient access rights
lcudrvERROR_TIMEOUT - failed to take semaphore before timeout
mconERROR_START_TIMER - failed to start VxWorks watchdog timer
mconERROR_STOP_TIMER - failed to stop VxWorks watchdog timer
mconERROR_QUEUE_FULL - failed to send command to the controller
mconERROR_SYNC_TIMEOUT - failed to take synchr.-semaphore, i.e.
no "answer ready"-intr. before timeout
mconERROR_NO_REPLY - failed to read reply from queue although
intr. indicates that reply is available
mconERROR_WRONG_REPLY - reply contains not the same axis number
as the command (maybe interrupt vectors
are not properly assigned)
mconERROR_STATUS_INVALID_AXIS - controller detected invalid axis number
mconERROR_STATUS_SYNTAX - controller detected invalid command nr.
mconERROR_STATUS_PARAM_RANGE - controller detected invalid parameter,
e.g. value/position out of limits
mconERROR_STATUS_UNEXP_COMMAND -controller detected unexpected command,
e.g. wrong sequence in initialisation
mconERROR_STATUS_FOLLOWING_ERROR - max. following error exceeded
mconERROR_STATUS_ENCODER_FAULT - read encoder value out of limits
mconERROR_STATUS_DRIVE_FAULT - drive-fault signal is active,
e.g. amplifier not in normal-mode
mconERROR_STATUS_COMM - communication error, i.e.
controller watchdog timeout
Automatic EXECUTE:
For some commands there is an EXECUTE-command appended, to activate
the settings automatically (see Maccon User Manual).
Automatic CLEAR:
If one of the 'mconERROR_STATUS_...' codes is returned, then there was
an automatically issued CLEAR-command before, to acknowledge the
error in the controller. The status flags are therefore cleared.
Any error during the CLEAR-command itself is discarded.
Some command numbers may be processed inside the ioctl() function of
VxWorks. For these numbers the driver will be bypassed!
In VxWorks version 5.1.1, at least the command 'FIOGETNAME' (number 18)
is handled in this way. There might be differences for other versions.
All conflicting command numbers must be translated.
3.3 Ioctl Control Commands
This section describes all the control commands which can be invoked by use of the VxWorks ioctl() function (see section 3.2.7). The parameter command specifies which operation has to be performed by the driver while the parameter argument passes the address of an argument to the command handler. In cases where multiple arguments are needed the address of a structure which contains those is passed.
All command literals and argument data structures are defined in the include file mconCommands.h. Read commands are allowed in each open mode, while Write commands are only allowed in Shared, Exclusive or Test mode.
This section lists all control commands supported by the driver. The list also contains a short description of each command, its literal and the possible special error codes sent in case of an error. Default, maximum and minimum values for parameters are stated in the controller manuals [2]. These values are in many cases different for each controller version.
Before a command is executed by the driver, the access rights and several states of the Maccon board are checked. Also a timer is started before and stopped after command execution to control the temporal run down of command execution. In case of an error the command is rejected.
For all commands passed to the controller board the following return codes are possible:
· mconERROR_STATUS_DRIVE_FAULT
The controller detected that the drive-fault signal is active (e.g. amplifier not in normal-mode)
See chapter 5 for a complete list. For read-commands the returned value is in general undefined if an error is reported. Only in case of the error-codes beginning with mconERROR_STATUS_ the user-status (see page 51) is returned instead of the requested value.
3.3.1 General Commands
To acknowledge an error condition in the controller and to clear all status error flags. It is automatically appended by the driver to an issued command if a status error occurs.
To start a positioning or change of mode or to activate written parameters. It is automatically appended by the driver to all "Set ... Mode" commands. See section 5.2 for details.
This command will reset all devices on the board and is equivalent to a hardware reset to the controller. This command should be used with care, as not only this device (axis) but also the other devices controlled by the board, are reset. All controller data will be lost, only parameters necessary for basic communication will be re-initialized.
The execution time for the Reset is longer than for other commands, therefore a timeout error will normally occur if the timeout-value specified at driver-installation is less than needed for this command. The error can then be avoided by increasing the timeout-value temporarily (see 3.3.20 on page 53).
This command must be given before modifying system specific parameters, see [2], if the axis is already initialized.
3.3.2 Speed and Brake Mode
In this mode the axis will accelerate with the defined acceleration ramp (given by the parameter <sa>) until it reaches the maximum speed defined by the parameter <sv>. The axis will continue until it is stopped by a command or reaches the limit- or stop-switch.
An axis running in speed mode will start braking with the defined deceleration ramp (defined by <sd>) until the axis has stopped.
Command literal: mconCMD_WRITE_SPEED_MODE_ACCEL
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_SPEED_MODE_SPEED
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_SPEED_MODE_DECEL
Argument: pointer to an integer containing the value to be set
3.3.3 Positioning Mode
In this mode the axis will move to the position given by the parameter <ap> with a trapezoidal profile. Acceleration is defined by the parameter <pa>, the speed by the parameter <pv> and the deceleration by the parameter <pd>. The absolute position can be given absolute or relative.
Command literal: mconCMD_WRITE_POS_ACCEL
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_POS_SPEED
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_POS_DECEL
Argument: pointer to an integer containing the value to be set
Command literal (absolute): mconCMD_WRITE_ABSOLUTE_POS
Command literal (relative): mconCMD_WRITE_RELATIVE_POS
Argument: pointer to an integer containing the value to be set
3.3.4 Search Index Coarse Mode
This mode is not available for the MAC4-SSI controller version.
The axis will search for the next index pulse. The acceleration, speed and deceleration is defined by the parameters <ca>, <cv> resp. <cd>. The axis will stop when the index pulse is found. The accuracy depends on the speed selected. Compare also 'Search index mode'.
Command literal: mconCMD_WRITE_COARSE_SPEED
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_COARSE_ACCEL
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_COARSE_DECEL
Argument: pointer to an integer containing the value to be set
3.3.5 Search Index Mode
This mode is not available for the MAC4-SSI controller version.
The axis will search for the next index pulse from the incremental encoder. The acceleration, speed and deceleration is defined by the parameters <ia>, <iv> resp. <id>. In the last phase the speed defined by <lv> is used (`low-velocity', see page 48). The position of the index pulse will be determined with an accuracy depending on the value of <lv>.
Command literal: mconCMD_WRITE_INDEX_SPEED
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_INDEX_ACCEL
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_INDEX_DECEL
Argument: pointer to an integer containing the value to be set
3.3.6 Home Mode
This mode is not available for the MAC4-SSI controller version.
The axis moves to the reference switch. The acceleration, speed and deceleration is defined by the parameters <ha>, <hv> resp. <hd>. In the last phase the speed defined by <lv> is used (`low-velocity', see page 48).
Command literal: mconCMD_WRITE_HOME_SPEED
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_HOME_ACCEL
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_HOME_DECEL
Argument: pointer to an integer containing the value to be set
3.3.7 Find Edge Mode
The axis will go to a predefined reference. The speed and for search reference switch the direction is defined by <fv>, acceleration and deceleration by <fa> resp. <fd>. For the last phase <lv> is used (`low-velocity', see page 48). The parameter <dl> defines the destination to search:
Command literal: mconCMD_WRITE_DEFINE_LIMIT
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_FIND_EDGE_SPEED
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_FIND_EDGE_ACCEL
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_FIND_EDGE_DECEL
Argument: pointer to an integer containing the value to be set
3.3.8 Velocity Tracking Mode
The parameter <vt> specifies the velocity which the axis shall reach within the next sampling period. Can be used for user-defined speed profiles.
Command literal: mconCMD_WRITE_TRACK_SPEED
Argument: pointer to an integer containing the value to be set
3.3.9 Position Tracking Mode
The parameter <at> specifies the position which the axis shall reach within the next sampling period.
Command literal (absolute): mconCMD_WRITE_TRACK_POS
Command literal (relative): mconCMD_WRITE_TRACK_POS_REL
Argument: pointer to an integer containing the value to be set
3.3.10 Test Mode
Command literal: mconCMD_WRITE_DAC_OFFSET
Argument: pointer to an integer containing the value to be set
3.3.11 Axis Configuration
Command literal: mconCMD_WRITE_AXIS_TYPE
Argument: pointer to an integer containing the value to be set
A linear axis is limited by software in positive and negative direction by values defined in parameters <lp> and <ln>, with <lp> > <ln>.
Command literal: mconCMD_WRITE_MAX_POSITIVE
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_MAX_NEGATIVE
Argument: pointer to an integer containing the value to be set
A circular axis does not have a positive or negative software limit. However, the number of increments for the total range is defined by the parameter <cr>.
Command literal: mconCMD_WRITE_CIRC_RANGE
Argument: pointer to an integer containing the value to be set
3.3.12 Encoder Configuration
The values for this parameter are defined differently for each controller version. See the corresponding controller manual [2],.
Command literal: mconCMD_WRITE_ENC_TYPE
Argument: pointer to an integer containing the value to be set
This value - if not default - defines the controller-internal address where the actual encoder position shall be read, instead of using the on-board encoder interface.
Command literal: mconCMD_WRITE_EXT_ENCODER_ADDR
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_ENC_BITS
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_ENC_OFFSET
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_ENC_COUNTS
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_ENC_SHIFT
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_ENC_STEPS
Argument: pointer to an integer containing the value to be set
3.3.13 Control Loop Configuration
Information about the control-loop can be found in [2]. Not applicable to the MAC4-STP controller version.
Command literal: mconCMD_WRITE_PROPOR_GAIN
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_ZERO_FACTOR
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_INTEGRATION_GAIN
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_INT_GAIN_SHIFT
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_POLE_FACTOR
Argument: pointer to an integer containing the value to be set
The calculated current value given to the DAC and then to the motor can be limited by the following command:
Command literal: mconCMD_WRITE_MAX_VELOCITY_REF
Argument: pointer to an integer containing the value to be set
3.3.14 Signal Configuration
Commands for the configuration of limit switches, reference switches, and "drive fault" signals. By default all switch-signals are "low-active". This can be changed by the argument passed to the commands:
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_LOWER_LIMIT_LEVEL
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_REF_SWITCH_LEVEL
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_DRIVE_FAULT_LEVEL
Argument: pointer to an integer containing the value to be set
3.3.15 Interrupt Configuration
Three interrupts are available for user-defined routines:
Each interrupt can be independently configured, enabled and disabled. Because every command can have only one parameter, the argument to all interrupt `config' commands is the address of a data structure of type mconCONFIG_INT, which contains the fields:
By default (without a config-command) a dummy handler routine is executed in case of an enabled interrupt, which prints a message on the screen.
The interrupt-vectors are defined at device-installation and cannot be changed by the user.
A description to configure the board-hardware for interrupts can be found in [2].
Another interrupt is also available when the encoder data are given by the host to the MAC4 controller (see command mconCMD_WRITE_ENCODER_VALUE, section 3.3.19).
The interrupt can be independently configured, enabled and disabled. Because every command can have only one parameter, the argument to the interrupt `config' commands is the address of a data structure of type mconINT_ENC_VAL, which contains the fields:
· routine - the routine to be executed in case of an interrupt. This routine executes on interrupt level.
When enabled will give an interrupt when the Drive Fault input of the MAC4 is activated. Input parameter is the address of a user supplied routine to be called on the interrupt. The interrupt vector is defined at the installation of the device. The user routine will run in task level context.
When enabled will give an interrupt when the `in position' or `adjusting finished' status bit in the user-status of the MAC4 is activated (see section 3.3.18). Input parameter is the address of a user supplied routine to be called on the interrupt. The interrupt vector is defined at the installation of the device. The user routine will run in task level context.
When enabled will give an interrupt when the STOP input of the MAC4 is activated. Input parameter is the address of a user supplied routine to be called on the interrupt. The interrupt vector is defined at the installation of the device. The user routine will run in task level context.
The emergency stop interrupt is common to all devices of one controller board! Therefore only one configuration is allowed that applies automatically to all devices of a board.
When enabled will give an interrupt each time the MAC4 controller has performed the control loop, e.g. every 2.5 ms for the present version of the controller. The interrupt must be configured and enabled and the correct encoder configuration must be set before the mconCMD_INIT command is given.
Enabling and disabling of interrupts is done with the following commands:
IMPORTANT: like any other parameter value, the interrupt enable-status (i.e. the interrupt vector) remains unchanged in the controller until an explicit EXECUTE command is issued. This is not done automatically by the driver. The value obtained by a "read interrupt vector" command represents only the current parameter setting, and not necessarily the enable-status of the controller.
This command returns the present setting of the interrupt vector parameter, i.e. either 0 or the value predefined at installation (range 1..255). Note that this value might not reflect the controller's current enable-status!
This command returns the present setting of the interrupt vector parameter, i.e. either 0 or the value predefined at installation (range 1..255). Note that this value might not reflect the controller's current enable-status!
This command returns the present setting of the interrupt vector parameter, i.e. either 0 or the value predefined at installation (range 1..255). Note that this value might not reflect the controller's current enable-status!
This command returns the present setting of the interrupt vector parameter, i.e. either 0 or the value set at interrupt configuration (range 1..255). Note that this value might not reflect the controller's current enable-status!
The interrupt vector parameters for "command buffer empty" (parameter <irq_vec1>) and "answer available" (parameter <irq_vec2>) are used by the driver internally and are not foreseen for user interactions.
3.3.16 Auxiliary Parameters and Commands
If an axis is moving and no command is issued to the controller within the time specified by this parameter, then all axes will be stopped. The time-unit is milli-seconds. A value of zero turns the watchdog off (default).
Command literal: mconCMD_WRITE_WATCHDOG
Argument: pointer to an integer containing the value to be set
When this value is exceeded the axis will be stopped (also called following error). The position error is the difference between the actual position and the calculated profile. Value in increments.
Command literal: mconCMD_WRITE_MAX_POS_ERROR
Argument: pointer to an integer containing the value to be set
This command returns the value of the maximum allowed deviation between the actual position and the calculated profile. If this value is exceeded the axis will be stopped. Value in increments.
Command literal: mconCMD_WRITE_EM_DECEL
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_CORR_SPEED
Argument: pointer to an integer containing the value to be set
Set the target radius defining a window around the target position. If the difference between the calculated position and the target position is smaller than this parameter for a duration longer than <trt> (see below), then the bit 'in position' in the user-status word will be set (see section 3.3.18). The target radius is only valid in mode POSITIONING (see section 3.3.3).
Command literal: mconCMD_WRITE_TARGET_RADIUS
Argument: pointer to an integer containing the value to be set
This parameter specifies the time in milliseconds that the axis must stay within the target radius before the user-status bit `in position' (see section 3.3.18) is set and the interrupt `motion end' (see sections 3.3.15 and 3.5) is issued. Note that it may happen that the described condition cannot be met, e.g. in case of an instable axis, and the `in position' status is never reached.
Command literal: mconCMD_WRITE_TARGET_SETTLING_TIME
Argument: pointer to an integer containing the value to be set
CAUTION: If <sf> is set to a non-zero value then most parameters (speed, acceleration, deceleration) will be scaled!
Command literal: mconCMD_WRITE_SCALE_FACTOR
Argument: pointer to an integer containing the value to be set
The argument passed with this command is assigned to the current position. An explicit EXECUTE command is needed in order to make the new setting valid.
Command literal: mconCMD_WRITE_INIT_POS
Argument: pointer to an integer containing the value to be set
This command reverses the polarity of the velocity reference. This can be used during test of the first setup if the amplifier or encoder is not properly connected.
3.3.17 Stepper Motor Specific Parameters
These parameters are additionally available for the MAC4-STP controller version. Detailed information can be found in [2].
Command literal: mconCMD_WRITE_MOTOR_STEPS
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_START_STOP_FREQ
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_BOOST_TIME
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_CREEP_DIST
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_WRITE_SERVO_WAIT_TIME
Argument: pointer to an integer containing the value to be set
Command literal: mconCMD_STP_TURBO_MODE
Argument: pointer to an integer containing the value to be set
3.3.18 Status Commands
Command literal: mconCMD_READ_USER_STATUS
Argument: pointer to an integer value, which has the following meaning:
value 0: Disable
value 1: Enable
value 2: Search Index Coarse
value 3: Search Index
value 4: Home mode
value 5: Find Edge
value 6: Speed mode
value 7: Brake mode
value 8: Positioning mode
value 9: Velocity Tracking
value 10: Test mode
value 11: Position Tracking
value 12: Reset
Command literal: mconCMD_READ_SYSTEM_STATUS
Argument: pointer to an integer value, which has the following meaning:
Command literal: mconCMD_READ_COMMON_STATUS
Argument: pointer to an integer value, which has the following meaning:
This command reads the current value from the DAC (for INC and SSI) resp. the current output value in steps per sampling period (for STP).
3.3.19 Direct Controller Access
These commands bypass the normal queue mechanism of the controller. They operate directly with the dual-ported RAM.
The host-system can provide an external encoder information (32-bit value) to the controller. In this case the address containing this value must be set in the parameter <ea> (see sections 3.3.12 and 3.3.15) to:
Command literal: mconCMD_WRITE_ENCODER_VALUE
Argument: pointer of an integer value containing the value to be set
This command resets the reply-queue back to a defined state. It should only be used when the reply-queue got corrupted, indicated by the error mconERROR_WRONG_REPLY (see section 5.4.2).
3.3.20 Driver-related Commands
These commands are processed inside the driver and work independently from the controller.
This command returns the driver version as an integer value in the format:
Bit 31-16: major version number, Bit 15-0: minor version number.
Command literal: mconCMD_GET_DRIVER_VERSION
Argument: pointer to an integer value, e.g. 0x00020003 means version `2.3'.
Note: The driver timeout is totally independent from the controller and its watchdog. It is only used to check if the controller responds to a command within the specified time.
Command literal: mconCMD_SET_TIMEOUT_TICK
Argument: pointer of an integer value containing the value to be set
This command can be used to simulate a task which blocks the access to the controller for a time specified by the given argument in ticks.
Command literal: mconCMD_BLOCK_SEMAPHORE
Argument: pointer of an integer value containing the value to be set
The purpose of this command is to free the device when a process which has opened the device in exclusive read/write mode is blocked or has terminated without closing the device. In this case it is not possible to send a write command to the device. This command frees the device and enables another process to open the device in read/write mode. The intention is that this command shall only be used 'manually' by an operator, to free the device and should not be used by processes which wants to send ioctl write commands to the device.
3.4 Logging
The MAC4 driver makes use of the common logging facility, i.e. the lculog module for debugging and tracing purposes. Therefore the lculog task must be loaded and spawned before the MAC4 driver is used.
The logging facility simply prints messages to the VxWorks shell. There are several different types of messages:
The debug- and trace-option can be switched on by issuing the following commands to the VxWorks shell: LCU_debug and LCU_trace. Both functions should return the value 1.
To switch the logging and tracing facilities off just issue the corresponding commands again and this time they should return the value 0.
3.5 Interrupts
The emergency stop, drive fault and motion end events are configured to generate interrupts. By default, they are disabled, and for each device, dummy interrupt routines are previously connected at start-up.
If applications use interrupts, they must first provide interrupt handler routines, which are installed by the commands:
Then they can be enabled/disabled by the commands:
The interrupt vector parameters can be read by the commands:
IMPORTANT: See the notes in section 3.3.15 about these commands!
Applications can provide one interrupt routine per event and per device, except for the "emergency stop" interrupt, which is common to all devices on the same controller board2. The handler routines are executed in task context, not in interrupt context.
Unlike the previous version 1.2, when an interrupt occurs, it will NOT be disabled by the driver.
3.6 Tools
The MAC4 driver includes a number of tools which can be used from the VxWorks shell. These tools are intended to be used by a system manager to ease maintenance and troubleshooting. All tools take one argument except otherwise noted, namely the number of the device (e.g. `2' for device "/mcon2"). The VxWorks shell sets unspecified arguments automatically to zero.
· mconSt, mconSSt, mconCSt
prints the user/system/common status data structure of the device specified.
· mconPar, mconParMode, mconParDC, mconParSSI, mconParStep, mconParAux
performs a read of several configurations parameters from the controller and prints them. The command has different versions for printing common parameters, only mode-relevant parameters, additional specialized parameters for the several controller versions (DC-motors, SSI-encoders, Stepper-motors), and additional auxiliary parameters.
All the tools require that the MAC4 driver is already installed and at that the specified device is created.
All output is directed on the standard output, i.e. either to the system console or to a host terminal.
The following sections give more detailed information for the usage of the tools.
void mconVersion (int axis);
void mconSt (int axis);
void mconSSt (int axis);
void mconCSt (int axis);
void mconStAll ();
void mconPos (int axis);
void mconPar (int axis);
void mconParMode (int axis);
void mconParDC (int axis);
void mconParStep (int axis);
void mconParSSI (int axis);
void mconParAux (int axis);
void mconDevShow (void);
void mconSizeofPrint ();
void mconErrorPrint (int err);
STATUS mconProbe (int device);
These functions represent a number of tools enabling the user
to get comprehensive information about a MACCON (axis) device
and driver.
mconVersion () - print the versions of controller and driver
mconSt () - print user status data structure of device
mconSSt () - print system status data structure of device
mconCSt () - print common status data structure of device
mconStAll () - print status data structure of all devices
mconPos () - print the position, position command, position
error and actual velocity of axis
mconPar () - print all parameters of an axis
mconParMode () - dto. but only parameters of the current mode
mconParDC () - dto. for DC motor parameters
mconParStep () - dto. for stepper parameters
mconParSSI () - dto. for SSI parameters
mconParAux () - dto. for auxiliary parameters
mconDevShow () - print the devices and adresses of the driver
mconSizeofPrint () - print size of data structures of MCON driver
mconErrorPrint () - print error message belonging to error code err
mconProbe () - test if address exists for device
err - error code
axis, device - device number = axis number
int mconTest (char *devName, int req, int *argPtr)
int mconTest0 (int req, int argum_0, int argum_1)
int mconTest1 (int req, int argum_0, int argum_1)
int mconTest2 (int req, int argum_0, int argum_1)
int mconTest3 (int req, int argum_0, int argum_1)
int mconTestOpen ( char *fileName, int openMode)
int mconTestIoctl (int fd, int command, int value)
void mconTestLoop1 (char * devName)
void mconTestLoop2 (char * devName)
STATUS mconTestClose (int fd)
STATUS mconTestInterrupt (int fd, int command,
VOIDFUNCPTR routine, int parameter)
These functions represent a sum of tools to test the MACCON driver.
mconTest () - open any device, execute specified command, close device
mconTest0 () - open "/mcon0"-device , execute command, close device
mconTest1 () - open "/mcon1"-device , execute command, close device
mconTest2 () - open "/mcon2"-device , execute command, close device
mconTest3 () - open "/mcon3"-device , execute command, close device
mconTestLoop1 () - open specified device, execute read/write commands,
compare input-output
mconTestLoop2 () - open specified device, execute ....
mconTestOpen () - open specified device
mconTestClose () - close specified device
mconTestIoctl () - execute specified command
mconTestInterrupt () - test interrupt handling
devName - device name
req - command code
argPtr - pointer to argument data structure to be passed to
command function
argnum_i - arguments (1,2,..i)
fileName - device name to open
openMode - open mode
fd - file descriptor
value - argument to be passed to command function
routine - routine to be executed in case of an interrupt
parameter - parameter to be passed to the interrupt routine
OK - successful completion
ERROR - error occured during operation
IOCTL specific errors - see USER MANUAL
3.7 Include Files
Beside VxWorks include files, driver applications must include "mcon.h" to interface the MAC4 driver. Board dependent, this file declares as prototypes the operations provided by the driver library, and includes other files themselves.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|