This documentation describes version 1.95 of the EPICS motor record, and related EPICS software required to build and use it.
The motor record is intended to support motors of all kinds, but currently supports only the following varieties of stepper-motor controller: Oregon Microsystems VME58, VME8, and VME44 series; and Highland Technologies V540. The record maintains two coordinate systems for motor position ("user" and "dial" coordinates); displays drive and readback values; enforces limits to motor motion and maintains those limits in both coordinate systems; displays the states of limit switches; can use a home switch; optionally takes out backlash in a user-defined direction; and provides a mechanism by which the user and other EPICS records can recalibrate the motor position in either coordinate system. The record also supports "tweak", "jog", and "home" motions, and supports both absolute and relative motions in user coordinates. Two "stop" switches are provided: a simple one for use by other records and by channel-access clients, and a more versatile one for interactive use.
Except where specified otherwise, fields associated with the motor position and its derivatives take values in user-specified "engineering units", such as degrees; the engineering unit name is contained in the field EGU. Thus, generally, speeds are expressed in EGU's per second. Accelerations, however, are expressed as the number of seconds taken to accelerate to full speed. However, additional fields are provided so that the motor position can be specified in steps and the speed in revolutions per second, and so that the step size can be set by specifying the number of steps per revolution and the number of EGU's per revolution.
The motor record can read motor position from the controller's readback register or encoder register, or from any other EPICS record, via an EPICS input link. While the motor is moving, the record can trigger an output link periodically, to send readback information to other EPICS records. When a complete motion (possibly including backlash takeout) is finished, the record can trigger a forward link to process other EPICS records.
The motor record can force its drive fields to agree with its readback fields, and it does so in a variety of circumstances (e.g., when the user tells a motor to stop, and when a limit switch is hit). Therefore, if you are driving the motor record's VAL or DVAL field with the output of another record, and you want that record always to contain the same value as the motor record, you must handle this behavior in the database. One way to do this is to forward link the motor record to a soft analog output record, and to cause that AO record to grab the motor record's VAL or DVAL field and poke it into your record.
The motor record is unlike most other EPICS records in that its
processing is neither "synchronous" nor "asynchronous", as these terms
are used in the EPICS Record Reference Manual. Currently, the PACT
field is always FALSE after record processing has completed, even
though a motor motion may be in progress. This means the record always
responds to channel-access puts, and can be stopped or retargeted at
any time. The record's forward link is not executed until the motor has
stopped and no motion requests are pending.
Field Descriptions
In addition to fields common to all record types (see the EPICS Record Reference Manual for these) the motor record has the fields described below.
| Name | Access | Prompt | Data type | Comment | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ACCL | R/W | Seconds to Velocity | FLOAT | acceleration time | ||||||||
| ADEL | R/W | Archive Deadband | FLOAT | currently ignored | ||||||||
| ALST | R | Last Value Archived | DOUBLE | currently ignored | ||||||||
| ATHM | R | At HOME | SHORT | uses the HOME switch | ||||||||
| BACC | R/W | BL Seconds to Veloc. | FLOAT | backlash acceleration time | ||||||||
| BDST | R/W | BL Distance (EGU) | FLOAT | backlash distance | ||||||||
| BVEL | R/W | BL Velocity (EGU/s) | FLOAT | backlash speed | ||||||||
| CARD | R | Card Number | SHORT | EPICS card # | ||||||||
| CVEL | R | Constant Velocity | SHORT | not used | ||||||||
| DHLM | R/W* | Dial High Limit | FLOAT | |||||||||
| DIFF | R | Difference dval-drbv | DOUBLE | |||||||||
| DIR | R/W* | User Direction | RECCHOICE | (0:"Pos", 1:"Neg") | ||||||||
| DLLM | R/W* | Dial Low Limit | FLOAT | |||||||||
| DMOV | R | Done moving to value | SHORT | The "done" flag | ||||||||
| DOL | R | Desired Output Loc | INLINK | only for closed-loop mode | ||||||||
| DRBV | R | Dial Readback Value | DOUBLE | |||||||||
| DVAL | R/W* | Dial Desired Value | DOUBLE | |||||||||
| EGU | R/W | Engineering Units | STRING | |||||||||
| ERES | R/W* | Encoder Step Size (EGU) | FLOAT | |||||||||
| FOF | R/W | Freeze Offset | SHORT | |||||||||
| FOFF | R/W | Offset-Freeze Switch | RECCHOICE | (0:"Variable", 1:"Frozen") | ||||||||
| FRAC | R/W | Move Fraction | FLOAT | |||||||||
| HHSV | R/W* | Hihi Severity | GBLCHOICE | |||||||||
| HIGH | R/W* | High Alarm Limit | FLOAT | |||||||||
| HIHI | R/W* | Hihi Alarm Limit | FLOAT | |||||||||
| HLM | R/W* | User High Limit | FLOAT | |||||||||
| HLS | R | At High Limit Switch | SHORT | |||||||||
| HLSV | R/W* | HW Lim. Violation Svr | GBLCHOICE | |||||||||
| HOMF | R/W* | Home Forward | SHORT | |||||||||
| HOMR | R/W* | Home Reverse | SHORT | |||||||||
| HOPR | R/W | High Operating Range | FLOAT | |||||||||
| HSV | R/W* | High Severity | GBLCHOICE | |||||||||
| JOGF | R/W* | Jog motor Forward | SHORT | careful! | ||||||||
| JOGR | R/W* | Jog motor Reverse | SHORT | careful! | ||||||||
| LDVL | R | Last Dial Des Val | DOUBLE | |||||||||
| LLM | R/W* | User Low Limit | FLOAT | |||||||||
| LLS | R | At Low Limit Switch | SHORT | |||||||||
| LLSV | R/W* | Lolo Severity | GBLCHOICE | |||||||||
| LOLO | R/W* | Lolo Alarm Limit | FLOAT | |||||||||
| LOPR | R/W | Low Operating Range | FLOAT | |||||||||
| LOW | R/W* | Low Alarm Limit | FLOAT | |||||||||
| LRLV | R | Last Rel Value | DOUBLE | |||||||||
| LRVL | R | Last Raw Des Val | DOUBLE | |||||||||
| LSPG | R | Last SPMG | RECCHOICE | (See SPMG) | ||||||||
| LSV | R/W* | Low Severity | GBLCHOICE | |||||||||
| LVAL | R | Last User Des Val | DOUBLE | |||||||||
| LVIO | R | Limit violation | SHORT | |||||||||
| MDEL | R/W | Monitor Deadband | FLOAT | |||||||||
| MIP | R | Motion In Progress | SHORT | |||||||||
| MISS | R | Ran out of retries | SHORT | |||||||||
| MLST | R | Last Value Monitored | DOUBLE | |||||||||
| MMAP | R | Monitor Mask | ULONG | |||||||||
| MODE | R/W | Operating Mode | RECCHOICE | (0:"Position", 1:"Velocity") | ||||||||
| MOVN | R | Motor is moving | SHORT | Don't confuse with DMOV | ||||||||
| MRES | R/W* | Motor Step Size (EGU) | FLOAT | |||||||||
| MSTA | R | Motor Status | ULONG | |||||||||
| NMAP | R | Monitor Mask | ULONG | |||||||||
| OFF | R/W | User Offset (EGU) | DOUBLE | |||||||||
| OMSL | R/W | Output Mode Select | GBLCHOICE | |||||||||
| OUT | R | Output Specification | OUTLINK | |||||||||
| PERL | R/W | Periodic Limits | RECCHOICE | (0:"No", 1:"Yes") | ||||||||
| POSM | R | Positive motion | SHORT | |||||||||
| PP | R | Post process command | SHORT | |||||||||
| PREC | R/W | Display Precision | SHORT | |||||||||
| RBV | R | User Readback Value | DOUBLE | |||||||||
| RCNT | R | Retry count | SHORT | |||||||||
| RDBD | R/W | Retry Deadband (EGU) | FLOAT | |||||||||
| RDBL | R | Readback Location | INLINK | |||||||||
| RDIF | R | Difference rval-rrbv | LONG | |||||||||
| REP | R | Raw Encoder Position | DOUBLE | |||||||||
| RES | R | Step Size (EGU) | FLOAT | |||||||||
| RHLS | R | Raw High Limit Switch | SHORT | |||||||||
| RLLS | R | Raw Low Limit Switch | SHORT | |||||||||
| RLNK | R | Readback OutLink | OUTLINK | |||||||||
| RLV | R/W* | Relative Value | DOUBLE | |||||||||
| RMP | R | Raw Motor Position | DOUBLE | |||||||||
| RRBV | R | Raw Readback Value | DOUBLE | |||||||||
| RRES | R/W | Readback Step Size (EGU) | FLOAT | |||||||||
| RTRY | R/W | Max retry count | SHORT | |||||||||
| RVAL | R/W* | Raw Desired Value | DOUBLE | |||||||||
| RVEL | R | Raw Velocity | LONG | |||||||||
| S | R/W | Speed (revs/sec) | FLOAT | |||||||||
| SBAK | R/W | BL Speed (RPS) | FLOAT | |||||||||
| SBAS | R/W | Base Speed (RPS) | FLOAT | |||||||||
| SET | R/W | Set/Use Switch | RECCHOICE | (0:"Use", 1:"Set") | ||||||||
| SPMG | R/W* | Stop/Pause/Move/Go | RECCHOICE | (0:"Stop", 1:"Pause", 2:"Move", 3:"Go") | ||||||||
| SREV | R/W* | Steps per Revolution | LONG | |||||||||
| SSET | R/W | Set SET Mode | SHORT | |||||||||
| STOP | R/W* | Stop | SHORT | |||||||||
| SUSE | R/W | Set USE Mode | SHORT | |||||||||
| TDIR | R | Direction of Travel | SHORT | |||||||||
| TRAK | R/W* | Make Readback=Value | RECCHOICE | (0:"No", 1:"Yes") | ||||||||
| TWF | R/W* | Tweak motor Forward | SHORT | |||||||||
| TWR | R/W* | Tweak motor Reverse | SHORT | |||||||||
| TWV | R/W* | Tweak Step Size (EGU) | FLOAT | |||||||||
| UEIP | R/W* | Use Encoder If Present | RECCHOICE | (0:"No", 1:"Yes") | ||||||||
| UREV | R/W* | EGU's per Revolution | FLOAT | |||||||||
| URIP | R/W* | Use RDBL Link If Present | RECCHOICE | (0:"No", 1:"Yes") | ||||||||
| VAL | R/W* | User Desired Value | DOUBLE | |||||||||
| VBAS | R/W | Base Velocity (EGU/s) | FLOAT | |||||||||
| VELO | R/W | Velocity (EGU/s) | FLOAT | |||||||||
| VERS | R | Code Version | FLOAT | e.g., "1.95" | ||||||||
| VOF | R/W | Variable Offset | SHORT | |||||||||
| ||||||||||||
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| DIR | R/W* | User Direction | RECCHOICE | (0:"Pos", 1:"Neg") |
User and dial values are related by the equation
userVAL = DialVAL * DIR + OFFsetThis field is the "DIR" in the above equation. | ||||
| OFF | R/W | User Offset (EGU) | DOUBLE | User and dial coordinates can differ by a sign (the DIR field) and
an offset (OFF), according to the following equation:
userVAL = DialVAL * DIR + OFFsetThis field is "OFFset" in the above equation. It is not normally written to directly by the user. |
| FOFF | R/W | Offset-Freeze Switch | RECCHOICE | (0:"Variable", 1:"Frozen") |
| VOF | R/W | Variable Offset | SHORT | value is irrelevant |
| FOF | R/W | Freeze Offset | SHORT | value is irrelevant |
| The user can cause the difference between user and dial coordinates to remain fixed (i.e., the record will not change it, although the user may) by setting FOFF to "Frozen." The fields VOF and FOF are intended for use in backup/restore operations; any write to them will drive the FOFF field to "Variable" (VOF) or "Frozen" (FOF). | ||||
| SET | R/W | Set/Use Switch | RECCHOICE | (0:"Use", 1:"Set") |
| SSET | R/W | Set SET Mode | SHORT | value is irrelevant |
| SUSE | R/W | Set USE Mode | SHORT | value is irrelevant |
| SET is a toggle switch used in calibrating the
motor's user and dial positions:
When SET = 0 ("Use"), writes to the user-coordinate drive field (VAL) cause the dial-coordinate drive field (DVAL) to change, and the motor to move. Writes to the dial-coordinate drive field (DVAL) cause the user-coordinate drive field (VAL) to change, and the motor to move. When SET = 1 ("Set"), writes to the dial-coordinate drive field (DVAL) and to the raw drive field (RVAL) cause a new raw motor position to be loaded into the hardware without any change to the user-coordinate drive field (VAL). Writes to other fields that would normally move the motor, change the user-coordinate drive field (VAL), and the offset between user and dial coordinates (the OFF field), with corresponding changes in the user-coordinate limit fields (HLM and LLM). When the offset is frozen (FOFF=1), writes to any drive field affect both user and dial values, and also load the hardware position register. | ||||
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| MRES | R/W* | Motor Step Size (EGU) | FLOAT | |
| SREV | R/W* | Steps per Revolution | LONG | |
| UREV | R/W* | EGU's per Revolution | FLOAT | |
| MRES, and (SREV,UREV) represent two ways of specifying the motor resolution,
MRES, which is the distance or angle, in engineering units, associated
with a single motor step. SREV initially has the value 200, the number
of full steps per revolution for most stepper motors; the record never
changes this field. If the user changes MRES, the record will set UREV
equal to MRES*SREV. If the user changes UREV, the record will set MRES
equal to UREV/SREV. In both cases, the record will also load the
hardware with the number that most closely approximates the current
position, and will set readback fields to agree with the new hardware
value.
MRES and UREV may be either positive or negative. SREV must be strictly positive. | ||||
| ERES | R/W* | Encoder Step Size (EGU) | FLOAT | Encoder resolution: the distance or angle, in engineering units, associated with a single encoder step. ERES may be positive or negative, but currently it must have the same sign as MRES. |
| RRES | R/W | Readback Step Size (EGU) | FLOAT | Readback-device resolution: the distance or angle, in engineering units, associated with a unit change of the number retrieved via the readback- location input link (RDBL). RRES may be either positive or negative. |
| RES | R | Step Size (EGU) | FLOAT | The motor or encoder resolution, in engineering units, as selected by the presence of an encoder supported by the hardware and by the switch UEIP ("Use Encoder If Present"). If an encoder is present, and UEIP=1, then RES will be set equal to ERES, otherwise RES will be set equal to MRES. |
| UEIP | R/W* | Use Encoder If Present | RECCHOICE (0:"No", 1:"Yes") | Switch: nonzero value tells the record to read the encoder (if the hardware indicates an encoder is present) and to ignore the value read back from the hardware's step-count register. |
| URIP | R/W* | Use RDBL Link If Present | RECCHOICE (0:"No", 1:"Yes") | Switch: nonzero value tells the record to get the motor position from the readback-location link (RDBL) (if it contains valid EPICS link information, and if no error occurs in the attempt to read from the link) and to ignore values read back from the hardware's step-count and encoder registers. |
| These switches also direct the record to calculate destinations in relative, rather than absolute, terms, since the ratio of encoder and readback units to motor steps may not actually be constant. | ||||
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| VELO | R/W | Velocity (EGU/s) | FLOAT | |
| S | R/W | Speed (revs/sec) | FLOAT | |
| VELO is the speed, in engineering units per second, at which the motor is move after the acceleration phase of a motion is finished. S is the same speed expressed in revolutions per second. The record makes sure that VELO and S are consistent, using the equation S = VELO/UREV. Neither VELO nor S may be negative or zero. | ||||
| VBAS | R/W | Base Velocity (EGU/s) | FLOAT | |
| SBAS | R/W | Base Speed (RPS) | FLOAT | |
| VBAS is the minimal speed, in engineering units per second, at which the
motor can be commanded to move. SBAS is the same speed expressed in
revolutions per second. Writes to fields that specify motor speeds
(VELO, BVEL, S, and SBAK) will be silently clipped at this lower limit.
The intent of these fields is to prevent the motor from moving at speeds slow enough to excite its resonance, which can cause the motor to miss steps. The motor is expected to accelerate from a stand-still to VBAS in one motor pulse. | ||||
| ACCL | R/W | Seconds to Velocity | FLOAT | The length, in seconds, of the acceleration and deceleration phases of a motor motion. |
| The motor record expects the hardware to produce a trapezoidal speed profile. That is, the motor speed is expected to increase linearly with time from the base speed, VBAS, to the full speed, VELO, in ACCL seconds. At the end of a motion, the speed is expected to decrease similarly to VBAS. | ||||
| BDST | R/W | BL Distance (EGU) | FLOAT | The signed distance, in dial coordinates, used for backlash takeout. |
| The algorithm used in moves to a (dial-coordinate) position called
"TARGET" follows:
1) If the motor is to move a distance greater than the magnitude of BDST, or if the motor is to move in a direction opposite to the sign of BDST, then the motor will move first to position (TARGET-BDST), at an acceleration specified by ACCL and speed VELO, and then to position TARGET, at an acceleration specified by BACC and speed BVEL. 2) If the motor is to move a distance smaller than the magnitude of BDST, and if the motor is to move in the same direction as the sign of BDST, then backlash is assumed already to have been taken out, and the motor will move to position TARGET at an acceleration specified by BACC and speed BVEL. | ||||
| BVEL | R/W | BL Velocity (EGU/s) | FLOAT | |
| SBAK | R/W | BL Speed (RPS) | FLOAT | |
| BVEL is the speed, in engineering units per second, at which the motor is move after the acceleration phase of a backlash-takeout motion is finished. SBAK is the same speed expressed in revolutions per second. Neither BVEL nor SBAK may be negative or zero. | ||||
| BACC | R/W | BL Seconds to Veloc. | FLOAT | The length, in seconds, of the acceleration and deceleration phases of a backlash-takeout motion. See discussion of the acceleration field ACCL for more specific information. |
| FRAC | R/W | Move Fraction | FLOAT | |
| This field supports closed-loop control of pathological
devices for which drive values are not expected to compare reproducibly
with readback values. (Inchworms and other friction-driven devices are
good examples: the number of steps taken by an inchworm motor is a very
poor indicator of the distance it has travelled.)
In a move from position CURRENT to position TARGET, the motor record will ask hardware to move a distance FRAC*(TARGET-CURRENT). When that motion is complete, the record will request a motion of FRAC*(remaining distance), and so on until the target position has been reached. | ||||
| MODE | R/W | Operating Mode | RECCHOICE | (0:"Position", 1:"Velocity")
Currently, the record ignores this field. |
| RDBD | R/W | Retry Deadband (EGU) | FLOAT | When the motor has finished a complete motion, possibly including backlash takeout, the motor record will compare its current position with the desired position. If the magnitude of the difference is greater than RDBD, the motor will try again, as if the user had requested a move from the now current position to the desired position. Only a limited number of retries will be performed (see RTRY). |
| RTRY | R/W | Max retry count | SHORT | The maximum number of times the motor record will try again to move to the desired position. When the retry limit is reached, the motor record will declare the motion finished. If the desired position was not reached, the field MISS will be set to 1. |
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| OUT | R | Output Specification | OUTLINK | This field specifies the hardware to be controlled. |
| RDBL | R | Readback Location | INLINK | This field specifies the field (of this or any other EPICS record) from which the motor's current position is to be read when the field URIP (Use Readback If Present) has the value "Yes" (1). If this field does not contain a valid EPICS link, the URIP may as well have the value "No" (0). |
| DOL | R | Desired Output Loc | INLINK | If this field contains a valid EPICS link, and the OMSL field has the value "closed_loop" (1), then every time the the motor record is processed, it will get a value for the VAL field from the link and move to that location, ignoring all other drive fields. Closed-loop mode has not been tested extensively. |
| OMSL | R/W | Output Mode Select | GBLCHOICE | (0:"supervisory", 1:"closed_loop")
If this field has the value "closed_loop" (1), and the field DOL contains a valid EPICS link, then every time the the motor record is processed, it will get a value for the VAL field from the link and move to that location, ignoring all other drive fields. Closed-loop mode has not been tested extensively. |
| RLNK | R | Readback OutLink | OUTLINK | If this field contains a valid EPICS link, then every time the motor record is processed, it will put the (engineering-unit) readback value RBV to that link. |
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| HLM | R/W* | User High Limit | FLOAT | The maximum allowed value of the VAL field. If HLM changes so that VAL is no longer less than HLM, then the record will set the field LVIO to 1. If the DIR field has the value "Pos", then HLM will always be consistent with DHLM, otherwise HLM will always be consistent with DLLM. |
| LLM | R/W* | User Low Limit | FLOAT | The minimum allowed value of the VAL field. If LLM changes so that VAL is no longer greater than LLM, then the record will set the field LVIO to 1. If the DIR field has the value "Pos", then LLM will always be consistent with DLLM, otherwise LLM will always be consistent with DHLM. |
| DHLM | R/W* | Dial High Limit | FLOAT | The maximum allowed value of the DVAL field. If DHLM changes so that DVAL is no longer less than DHLM, then the record will set the field LVIO to 1.. If the DIR field has the value "Pos", then DHLM will always be consistent with HLM, otherwise DHLM will always be consistent with LLM. |
| DLLM | R/W* | Dial Low Limit | FLOAT | The minimum allowed value of the DVAL field. If DLLM changes so that DVAL is no longer greater than DLLM, then the record will set the field LVIO to 1. If the DIR field has the value "Pos", then DLLM will always be consistent with LLM, otherwise DLLM will always be consistent with HLM. |
| LVIO | R | Limit violation | SHORT | A value of 1 indicates that the dial-value drive field, DVAL, or the dial-value readback field, DRBV, is outside of the limits (DHLM, DLLM), and this prevents the motor from moving. If the backlash distance, BDST, is non-zero, it further restricts the allowable range of DVAL. When a JOG button is hit, LVIO goes to 1 and stops the motor if/when DVAL gets to within one second's travel time of either limit. |
| PERL | R/W | Periodic Limits | RECCHOICE | (0:"No", 1:"Yes")
Not implemented. Originally intended to support periodic "limits" on the VAL field (such as those associated with a rotation stage--e.g., [0...360] or [-180...180]) independently of the actual soft limits HLM and LLM. |
| HOPR | R/W | High Operating Range | FLOAT | Not used. See HLM and DHLM. |
| LOPR | R/W | Low Operating Range | FLOAT | Not used. See LLM and DLLM. |
| HLS | R | At High Limit Switch | SHORT | |
| RHLS | R | Raw High Limit Switch | SHORT | |
| If either of these fields is nonzero, then the motor is at the positive-limit switch, where the positive sense is that of the user-coordinate system for HLS, and that of the raw (step-number) coordinate system for RHLS. | ||||
| LLS | R | At Low Limit Switch | SHORT | |
| RLLS | R | Raw Low Limit Switch | SHORT | |
| If either of these fields is nonzero, then the motor is at the negative-limit switch, where the positive sense is that of the user-coordinate system for LLS, and that of the raw (step-number) coordinate system for RLLS. | ||||
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| SPMG | R/W* | Stop/Pause/Move/Go | RECCHOICE | (0:"Stop", 1:"Pause", 2:"Move", 3:"Go") |
| This field is intended primarily for interactive use, and normally has
the value "Go."
If the user sets this field to "Stop," the motor will decelerate to a stop, the VAL field will be set equal to the RBV field, and the DVAL field will be set equal to the DRBV field. (These actions ensure that the motor will not start moving again until a drive field is changed.) In any case, the motor will not move while SPMG has the value "Stop" or "Pause." If "SPMG" has the value "Move," the motor record will reset SPMG to "Pause" when a motion completes. This behavior supports users who want a motor to sit still until they say "Move", no matter what changes occur in the drive fields. | ||||
| STOP | R/W* | Stop | SHORT | |
| When this field is set to 1, the record will immediately reset it to 0, and the motor will decelerate to a stop. When the motor has stopped, VAL will be set equal to RBV, and DVAL will be set equal to DRBV. (This ensures that the motor will not start moving the next time the record is processed, unless a drive field is explicitly changed. If you want the motor to pause, use the SPMG field.) | ||||
| HOMF | R/W* | Home Forward | SHORT | |
| HOMR | R/W* | Home Reverse | SHORT | |
| When one of these fields is set to 1, the motor will decelerate to a stop if already moving, move in the indicated direction (in dial coordinates) at the acceleration specified by ACCL and a speed of 1000 motor pulses per second, until the hardware detects the "home" switch has become active. Then the hardware will do something hardware dependent in response to its "home" command, if any. (The OMS hardware causes the motor to decelerate to a stop.) When the motor stops, the VAL field will be set equal to the RBV field, and the DVAL field will be set equal to the DRBV field. | ||||
| JOGF | R/W* | Jog motor Forward | SHORT | |
| JOGR | R/W* | Jog motor Reverse | SHORT | |
| When one of these fields is set to 1, the motor will
decelerate to a stop if already moving, and move in the indicated direction
(in user coordinates) at an acceleration specified by ACCL and speed VELO,
until the field goes to 0. Then the motor will set VAL to RBV and DVAL to DRBV,
decelerate to a stop, and execute a (backlash-corrected, if BDST is
nonzero) move to the position at which the field went to 0.
These fields are dangerous when used over channel access, because the motor does not stop moving until a second message is received. If a very busy network should cause that second message to be lost, the motor will travel to its limit switch or hard stop. | ||||
| TWF | R/W* | Tweak motor Forward | SHORT | |
| TWR | R/W* | Tweak motor Reverse | SHORT | |
| When one of these fields is set to 1, the record will immediately reset it to 0, and the motor will move (with backlash takeout if BDST is nonzero) by a distance TWV (in user coordinates) at the acceleration specified by ACCL and at speed VELO. | ||||
| TWV | R/W* | Tweak Step Size (EGU) | FLOAT | This field contains the distance the motor is to move in response to the TWF and TWR buttons. |
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| VAL | R/W* | User Desired Value | DOUBLE | This is the desired position in user coordinates. When this field is written to, DVAL and RVAL will be changed correspondingly, and the motor will move (with backlash takeout if BDST is nonzero) to the newly written position. |
| DVAL | R/W* | Dial Desired Value | DOUBLE | This is the desired position in dial coordinates. When this field is written to, VAL and RVAL will be changed correspondingly, and the motor will move (with backlash takeout if BDST is nonzero) to the newly written position. |
| RVAL | R/W* | Raw Desired Value | DOUBLE | This is the desired position in raw coordinates. When this field is written to, VAL and DVAL will be changed correspondingly, and the motor will move (with backlash takeout if BDST is nonzero) to the newly written position. |
| RLV | R/W* | Relative Value | DOUBLE | When this field is changed, its value will be added to VAL, the field itself will immediately be reset to 0, and the motor record will behave as though the VAL field had been changed directly. |
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| RBV | R | User Readback Value | DOUBLE | The current motor position, in user coordinates, from the motor hardware (default), or from the encoder supported by the motor-controller hardware (if UEIP is nonzero), or from the readback link RDBL (if URIP is nonzero). |
| DRBV | R | Dial Readback Value | DOUBLE | The current motor position, in dial coordinates, from the motor hardware (default), or from the encoder supported by the motor-controller hardware (if UEIP is nonzero), or from the readback link RDBL (if URIP is nonzero). |
| DMOV | R | Done moving to value | SHORT | |
| This field is set to 0 when the motor record begins a motion, and remains 0 through any retries and backlash corrections that may be required until the motor record has completely finished that motion, whereupon the field is set to 1. DMOV is guaranteed to execute and post a 1/0/1 pulse when the motor is commanded to move--even if no motion actually occurs because the motor was commanded to move to its current position. | ||||
| MOVN | R | Motor is moving | SHORT | This field is set to 1 while the record believes that the motor actually is moving. This field is not the inverse of DMOV, since it may go to zero during a complex motion, if that motion includes a momentary stop. |
| DIFF | R | Difference dval-drbv | DOUBLE | DIFF is the difference, in engineering units, between the desired motor position, and the readback device's report of the current position. RDIF is the same difference in "raw" units (normally, steps). |
| RDIF | R | Difference rval-rrbv | LONG | |
| RRBV | R | Raw Readback Value | DOUBLE | The current position of the motor, encoder, or readback link, as received from whatever source has been selected to provide position information. The units associated with this field depend on the source. |
| RMP | R | Raw Motor Position | DOUBLE | The contents of the hardware's step-count register. This field contains the same information as the dial value, but in steps, rather than in engineering units. |
| REP | R | Raw Encoder Position | DOUBLE | The contents of the hardware's encoder-count register. Ideally, this field contains the same information as the dial value, but in encoder counts, rather than in engineering units. |
| MSTA | R | Motor Status | ULONG | The motor status as received from the hardware. |
| TDIR | R | Direction of Travel | SHORT | The direction in which the motor is currently travelling (or was most recently travelling), as received from the hardware. If 0, the raw readback value should be decreasing. |
| ATHM | R | At HOME | SHORT | The state of the hardware's "home" switch. If 1, the motor has hit the switch. |
| CVEL | R | Constant Velocity | SHORT | Not used. |
| POSM | R | Positive motion | SHORT | Not used. |
| RCNT | R | Retry count | SHORT | The number of times the motor record has detected failure of the motor to land within the retry-deadband distance of the desired position. |
| MISS | R | Ran out of retries | SHORT | If 1, the motor has failed to land on the desired position more than the allowed number of times. This field will be reset the next time the motor succeeds in reaching the desired position. |
| RVEL | R | Raw Velocity | LONG | Speed in steps per second that the motor actually is moving. |
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| HIHI | R/W* | Hihi Alarm Limit | FLOAT | |
| LOLO | R/W* | Lolo Alarm Limit | FLOAT | |
| HIGH | R/W* | High Alarm Limit | FLOAT | |
| LOW | R/W* | Low Alarm Limit | FLOAT | |
| HHSV | R/W* | Hihi Severity | GBLCHOICE | |
| LLSV | R/W* | Lolo Severity | GBLCHOICE | |
| HSV | R/W* | High Severity | GBLCHOICE | |
| LSV | R/W* | Low Severity | GBLCHOICE | |
| HLSV | R/W* | HW Lim. Violation Svr | GBLCHOICE | |
| None of these fields are used, at present. | ||||
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| PREC | R/W | Display Precision | SHORT | The number of digits to the right of the decimal that are to be displayed by MEDM and other channel-access clients. |
| EGU | R/W | Engineering Units | STRING | String sent to channel-access clients who ask for engineering units. |
| VERS | R | Code Version | FLOAT | Version number of the recMotor.c code. |
| TRAK | R/W* | Make Readback=Value | RECCHOICE (0:"No", 1:"Yes") | Not implemented. Originally intended to support closed-loop control. |
| MDEL | R/W | Monitor Deadband | FLOAT | Not used. |
| ADEL | R/W | Archive Deadband | FLOAT | Not used. |
| CARD | R | Card Number | SHORT | The VME card number, derived from the output link. Cards are numbered from zero according to their VME addresses. Oregon Microsystems series VME8 and VME44 cards occur in the same series, since they are handled by the same driver. Oregon Microsystems VME58 cards are numbered separately, as are Highland Technology V540 cards. |
| Name | Access | Prompt | Data type | Comments |
|---|---|---|---|---|
| LVAL | R | Last User Des Val | DOUBLE | |
| LDVL | R | Last Dial Des Val | DOUBLE | |
| LRVL | R | Last Raw Des Val | DOUBLE | |
| LRLV | R | Last Rel Value | DOUBLE | |
| ALST | R | Last Value Archived | DOUBLE | |
| MLST | R | Last Value Monitored | DOUBLE | |
| PP | R | Post process command | SHORT | |
| MIP | R | Motion In Progress | SHORT | |
| MMAP | R | Monitor Mask | ULONG | |
| NMAP | R | Monitor Mask | ULONG | |
| LSPG | R | Last SPMG | RECCHOICE | (see SPMG) |
Files, device support
The following table briefly describes all of the files required to implement
and use the motor record. The reader is assumed to be familiar with the
EPICS Application Source/Release Control document
which describes how to build an
EPICS application tree into which these files are to be placed, and how to run
"makesdr" and "gnumake" to build the record support. These files can all be
obtained from the EPICS Software Distribution (in the custom-software section).
|
SOURCE CODE files to be placed in <top>/<app>App/src/
| |
|---|---|
| recMotor.c | Record support for the motor record |
| motor.h | Header included by all .c files |
| devOms.c | Device support for Oregon Microsystems VME8 and VME44 series boards |
| drvOms.c | Driver for Oregon Microsystems VME8 and VME44 series boards |
| drvOms.h | Header included by devOms.c and drvOms.c |
| devOms58.c | Device support for Oregon Microsystems VME58 series boards |
| drvOms58.c | Driver for Oregon Microsystems VME58 series boards |
| drvOms58.h | Header included by devOms58.c and drvOms58.c |
| devV544.c | Device support for Highland Technologies boards |
| drvV544.c | Driver for Highland Technologies boards |
| drvV544.h | Header included by devV544.c and drvV544.c |
| Makefile.Vx | This file is not included in the distribution. However, the user must edit
this file and add lines similar to the following:
MOTOR_OBJS = recMotor.o devOms.o drvOms.o devOms58.o drvOms58.o LIBNAME = mylib.o LIBOBJS = $(MOTOR_OBJS) $(other objects here) |
| ASCII FILES files to be placed in <top>/cat_ascii/
| |
|---|---|
| motorRecord.ascii | This file defines all of the fields for the motor record. |
| choiceRecMotor.ascii | This file defines all of the choice values for the motor record. |
| choiceMotor.h | This file is included by choiceRecMotor.ascii and by recMotor.c. |
| choiceRec.ascii | This file is not included in the distribution. However, the user must edit
this file and add the line:
#include <choiceRecMotor.ascii> |
| dbRecType.ascii | This file is not included in the distribution. However, the user must edit
this file and add the line:
"motor" |
| devSup.ascii | This file is not included in the distribution. However, the user must edit
this file and add the following lines:
! Device Support for motor record "motor" VME_IO "devOMS" "OMS VME8, VME44" "motor" VME_IO "devOms58" "OMS VME58" "motor" VME_IO "devV544" "Highland V544" |
| MEDM DISPLAY SCREENS files to be placed in <top>/<app>App/op/adl/
| |
|---|---|
| motorx.adl | Small motor-control screen |
| motorx_tiny.adl | Tiny motor-control screen |
| motorx_more.adl | Medium motor-control screen |
| motorx_setup.adl | Setup screen for a single motor |
| motorx_all.adl | Debug screen for a single motor |
These files build medm screens to access the motor record.
To use one of them from the command line, type, for example
medm -x -macro "P=XXX:,M=m1" motorx.adl
where
These files can also be used as related displays from other |
|
| EPICS STARTUP FILES files to be placed in <top>/ioc/ioc<name>/
| |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| st.cmdmv167 | Startup script | ||||||||||||||
A sample startup script, containing excerpts relevant to motors, is
included in the distribution. Here is an annotated copy:
####################################################################### # vxWorks startup script to load and execute system (iocCore) software.Load standard EPICS software # the following should be loaded first - BEGIN ld < targetmv167/iocCore ld < targetmv167/drvSup ld < targetmv167/devSup ld < targetmv167/recSup # the following should be loaded first - ENDLoad custom EPICS software (including motor support) ld < ../../stdApp/src/O.mv167/stdlib.oMotor-related debug switches recMotordebug = 0 #OMS vme8/vme44 debug switches devOMSdebug = 0 drvOMSdebug = 0 #OMS vme58 debug switches devOms58debug = 0 drvOms58debug = 0 #Highland Technology V544 debug switches devV544ebug = 0 drvV544debug = 0Motor-related databases
# load this before loading any databases
dbLoad "../../default.dctsdr"
#allstop
dbLoadRecords("../../stdApp/gDb/allstop.db","P=tmm:")
#motors
dbLoadRecords("../../stdApp/gDb/m16.db","P=tmm:")
Specify motor-controller board address, interrupt vector, etc.
# OMS VME8, VME44, VMEX driver setup parameters: omsSetup(5, 8, 0xFC00, 180, 5, 10) # OMS VME58 driver setup parameters: oms58Setup(5, 8, 0x2000, 190, 5, 10) # Highland Technology V544 driver setup parameters: v544Setup(5, 4, 0xDD00, 200, 5, 10)Start EPICS iocInit |
|||||||||||||||
| BACKUP/RESTORE (BURT) REQUEST FILES files to be placed in <top>/<app>App/op/burt/
| |
|---|---|
| settings.req | sample request file to save settings of all motors. Edit this file, supplying names of the motor records whose settings you want saved. (The sample file also saves the states of other records in the sample database, m16.db, that enable or disable the motor records.) |
| yyMotorSettings.req | save settings of a specified motor.
This file is #include'd (once for each motor) by settings.req.
|
| positions.req | sample request file to save positions of all motors. Edit this file, supplying names of the motor records whose positions you want saved. |
| yyMotorPositions.req | save position of a specified motor,
This file is #include'd (once for each motor) by positions.req.
|
These files tell the backup/restore tool how to save motor
settings and positions. To use them from the command line, type, for example
burtrb -f settings.req -o myMotorSettings.snapTo restore the motor settings and positions saved by the above commands, type burtwb -f myMotorSettings.snap |
|
There is no way to ask for a reading of the motor's position register, encoder, or limit switches. These are read only while the motor is moving.
Because of the way limit-switch information is conveyed by the OMS hardware, the motor record cannot know the states of both limit switches at the same time. It only knows the state of the switch toward which the motor is moving.
If a move is requested while the motor already is in motion, the original move will still receive a (useless) backlash correction.
Changing MRES (the motor resolution) should change VELO (the speed in engineering units per second), and leave S (the speed in revolutions per second) unchanged. Currently, neither VELO nor S appears to change, but the record behaves as though S had been changed to agree with VELO. A similar thing happens with SBAK and SBAS.