synApps: tpmac

This page is a home of tpmac. The most recent version of it can be found at www.gmca.aps.anl.gov/TPMAC2/. There is also a Github page maintained by Matthew Pearson at Diamond Light Source (github.com/epics-modules/tpmac), which allows to post the DLS extensions (such as the motorRecord support) to the tpmac support module more promptly. Finally, there are plans to start a public code repository at Github, Launchpad, or Sourceforge, but we are not there yet.

tpmac supports Turbo PMAC2-VME Ultralite by Delta Tau which is a programmable 32-axis motion controller. Some features of it are:

• capability to perform synchronous coordinated motions of several drives thus allowing for fast on-the-fly scans of motor groups,
• modular design with fiber link greatly simplifying cabling (Fig.1),
• capability to drive virtually any type of motors -- DC brush & DC brushless servo, stepper, piezo, and etc.
• provisions to write custom motion programs, define custom servo cycles and generally tweak any motion parameter.
• programmable I/O for synchronizing motions with external devices.

Figure 1: Layout of Turbo PMAC2-VME Ultralite with remote MACRO stations

The module consists of:

1. PMAC ASCII (PMAC mailbox) driver support for ai, ao, bi, bo, longin, longout, mbbi, mbbo, stringin, and stringout records. This provides the basic functionality of PMAC console. In principle, just one DB file pmacApp/Db/pmacDb/AsciiPmac_basic.db will be enough to start communicating with PMAC. However, such a communication will obviously be not fast enough to gain the full functionality of PMAC.
    
2. PMAC DPRAM (dual ported RAM) driver support for ai, ao, bi, bo, longin, longout, mbbi, mbbo, and status records. This provides fast communications with PMAC, but the DPRAM must be properly configured (mapped) so that the EPICS databases access required PMAC parameters.
    
3. Status record with PMAC DPRAM driver support. This is used for decoding PMAC servo status bits.
    
4. Tsub record -- a soft record not communicating with any hardware (i.e. strictly speaking it is not directly related to PMAC). In this module tsub records are used to perform transformations between coordinates on combined motion axes (e.g. monochromator energy or mirror angle) and individual drives (e.g. monochromator rotary or mirror support). Each instance of Tsub record must be supplied with a transformation routine which is a small program written in C and performing the transformations. See examples in pmacApp/tsubSrc.
    
5. Extensive set of EPICS databases consisting of files in pmacApp/Db/pmacDb (the databases directly communicating with PMAC console or DPRAM), files in pmacApp/Db/softDb (generic soft databases for all types of PMAC coordinate systems), and files in pmacApp/Db/csDb, hsDb, mdDb, miDb, moDb, tbDb, xyDb (soft databases per each type of PMAC coordinate system). The databases constitute quite essential part of the module -- one can expect loading about 100 EPICS DB records per PMAC motion axis. Due to the complexity and flexibility of PMAC where one deals with coordinated motions of 1,2,3,4,... and etc. motors a generic solution like Motor Record used with the OMS-58 controller would not be able to access much of PMAC functionality.
    
6. PMAC motion programs and example PMAC configuration files (see the "pmc" directory).
    
7. MEDM screens (see the "adl" directory). The MEDM screens can be called from a root GUI written in Tcl.Tk (see the "GUI_controls" folder).
    

Databases and how it works

A schematic of operating PMAC controller with EPICS DPRAM driver and databases is shown on Fig.2.

Figure 2: Operation of EPICS databases with PMAC DPRAM driver.

The final goal is to execute PMAC motion program on a coordinate system (see the examples of motion programs in pmc/3_motion-prg/). Several motion programs (Slew, Position and Backlash) are provided with this distribution and more can be added. Each motion program takes its parameters (like motors destinations and assembly acceleration time) from the Q70-Q80 variables that are available in PMAC for every coordinate system. In the their turn Q-variables are mapped to a global set of M-variables that point to the locations of PMAC DPRAM accessible by EPICS databases via the DPRAM driver (see the files 2_m3300_xxx.pmc and 3_q70_xxx.pmc in the pmc/2_ioc-specific/xxx directories).

On the EPICS side, the requested motors positions and other motion parameters are copied to the DPRAM with the help of Ram_nnn.db databases (see the pmacApp/Db/pmacDb/ directory) using the DPRAM driver in their device support. In the inverse direction the motors encoders data reported by PMAC are read with the help of mtrdat.db that contains status records with the DPRAM driver in their DTYP field.

PMAC controllers communicate motors data in raw units like steps or encoder pulses. Therefore, on top of "motors" databases another EPICS database layer is built called "drives". The positions of "drives" are in engineering units and typical relations between motors and drives are:

d = m * scale + offset

NOTE: Newer generation of PMAC controllers like Turbo PMAC2 provide a way to hide the "motors" level. i.e. to communicate with PMAC in engineering unit. In that case "scale" and "offset" become PMAC I-variables. The current set of databases is not designed to support this feature, but it could be done in the future. At present the decision to exclude "motors" from EPICS databases is not yet taken because in some cases it is convenient to communicate with motors in raw units.

If a PMAC coordinate system provides any combined motion (e.g. a slit size being determined by a combined motion of two jaws), then one more level is added called "axes". Both "drives" and "axes" are all soft databases and they are linked to each other and "motors" with the help of tsub records. The relation between "drives" and "axes" is specific for an assembly and requires a custom database and MEDM screen. If there are no combined motions, then "axes" DB is not loaded and the database remains two-level as distinct from the three-level one for combined motions. Both of these cases are illustrated on Fig.2.

Fig.3 shows the MEDM screen for XY-positioner coordinate system which is a two-level DB. Here "X1" and "Y1" are drives and "mtr x1" and "mtr y1" are motors. Fig.4 presents the MEDM screen for a slit which is a three-level database. Here "Z-center" and "Z-size" are axes (combined motions), "Z-top" and "Z-bottom" are drives, and "top" and "btm" are motors.

Figure 3: MEDM screen for XY-positioner (two independent drives with common start and abort).

Figure 4: MEDM screen for collimator slits (two drives are combined to provide slit center and size).

The coordinate system specific databases in pmacApp/Db/csDb, hsDb, mdDb, miDb, moDb, tbDb, xyDb consist of the following parts:

1. nn_Calibrate.db contain parameters (scale, offset, and etc.) for linking "axes", "drives" and "motors".
2. nn_Tsub.db performs recalculations between requested positions on "axes", "drives" and "motors".
3. nn_TsubRbk.db performs recalculations from actual positions on "motors" to actual positions on "axes" and "drives".
4. nn_LimAmp.db performs propagation of limit switch and amplifier enable/disable signals from "motors" to "axes" and "drives".
5. nn_TsubSpeed.db performs recalculations between motion speeds on "axes", "drives" and "motors".

Those databases must be designed for any new type of motors assembly.

Where to find it

You can download the software from the links in the table below:

Required Modules

Installation and Building

After obtaining a copy of the distribution, it must be installed and built for use at your site. These steps only need to be performed once for the site (unless versions of the module running under different releases of EPICS and/or the other required modules are needed).

1. Create an installation directory for the module, usually this will end with
   
   .../synApps/
    
2. Place the distribution file on top of this directory. Then issue the command (Unix style):

   unzip tpmacX-Y.zip
   

   where X-Y is the release.
    
3. This creates a <top> application.
   

   .../synApps/tpmac/X-Y/
   

4. Edit the configure/RELEASE file and set the paths to your installation of EPICS base.
5. Run gnumake in the top level directory and check for any compilation errors.
6. Prepare PMAC I-, M-, and Q-variables, define coordinate systems and motion programs. Also map your PMAC's dual-ported RAM as it will be accessed by EPICS databases. Some examples of PMAC preparation files are given in the pmc directory of this distribution. Then load and save all the settings in the PMAC. This can be done by connecting PMAC serial port to a serial port of Windows computer and using PMAC executable software (PEWIN32) by Delta Tau.
7. Prepare PMAC-related EPICS databases. Some examples of PMAC databases (slits, mirror support, monochromator energy, XY-positioner, 3-support table, modular drive) are given in the pmacApp/Db directories. In the case you need a new type of coordinated motion, you will have to design a new version of the following files: nn_Calibrate.db nn_LimAmp.db, nn_Tsub.db, nn_TsubRbk.db, nn_TsubSpeed.db and a new transformation routine pmacApp/tsubSrc/tsub_nn.c.
8. Prepare IOC startup files to load all the necessary EPICS databases interacting with PMAC -- see examples in the iocBoot/iocgmca1/st_pmac.cmd file and iocBoot/iocgmca1/dbLoad directory.
9. Please email to Oleg Makarov or Sergey Stepanov so that a record can be kept of what sites are using this software.

In Use

The tpmac is in use at all three GM/CA @ APS beamlines. From two to three PMAC2-VME cards per one beamline provide controls for all motors. Since the fall of 2006 the system is also operational at four LS-CAT beamlines at the APS and since 2009 it is used at IMCA-CAT. At Diamond several hundred PMACs are in used (VME Turbo PMAC2 Ultralite and Geobrick LVM with ethernet interface). While using the EPICS tpmac driver, Diamond prefers to build EPICS Motor Records and Coordinate System Records instead of servicing PMAC communication via multiple standard EPICS records as at the GM/CA and LS-CAT control systems.

Please submit any comments and bug reports to Oleg Makarov (PMAC driver and PMAC configuration), Sergey Stepanov (structure of EPICS layer and PMAC databases), or Nick Reese (EPICS driver, asyn support, and Motor Record for PMAC).

More info

• Notes on PMAC board preparation before using it with EPICS.
• Notes on installing SBC-BIO-GMCA-LS-style EPICS support for PMAC VME boards.
• A short overview of Turbo PMAC2-VME Ultralite features (details can be found in the Delta Tau PMAC Catalog).
• Old notes on configuring PMAC1 to work with EPICS driver.
• Old notes on tuning PMAC1 motors servo loops under EPICS.
• Turbo PMAC Software Reference Manual at the Delta Tau web site.
• All PMAC manuals and PMAC Technical Notes at the Delta Tau web site.
• PMAC software by Delta Tau download page.

Other sites devoted to EPICS and PMAC

• Linux 2.6 Driver at the Observatory Sciences web site in UK.
   
• pmacCoord and pmacUtil distributions at Diamond Light Source.