synApps: tpmac

Module Owners: Oleg Makarov and Sergey Stepanov, Argonne National Laboratory
Nick Rees and Matthew Pearson, Diamond Light Source
License: This software is distributed under EPICS Open License

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:

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:

Module Version Release Date Filename Notes
3-12 01/2017 tpmac3-12.zip Implemented some stability fixes and workarounds for Turbo PMAC2 VME UltraLite firmware bugs. Also included the latest up-to-date changes and bug fixes to pmacAsynCoordSrc, pmacAsynIPPortSrc, and pmacAsynMotorSrc from the Diamond Light Source tpmac and pmacCoord distributions. See Release Notes for additional details.
3-11 08/2012 tpmac3-11.zip Added support for Ethernet-accessed PMACs (see src_eth) with the same-style EPICS DBs as for VME PMAC; replaced tsDef.h by epicsTime.h; fixed name conflict with win32 in tsub, and included the latest up-to-date changes and bug fixes to pmacAsynCoordSrc, pmacAsynIPPortSrc, and pmacAsynMotorSrc from the Diamond Light Source tpmac and pmacCoord distributions. See Release Notes for additional details.
3-10 11/2011 tpmac3-10.zip A number of changes and bug fixes to pmacAsynCoordSrc, pmacAsynIPPortSrc, and pmacAsynMotorSrc produced at the Diamond Light Source. See Release Notes for additional details.
3-9 10/2011 tpmac3-9.zip The TSUB (Transformation Subroutine) Record was made portable (independent of VxWorks) so that now it can be used independently from the TPMAC distribution. Note that it requires few minor tweaks of user-supplied subroutines. Additional detais are provided in Release Notes.
3-8 10/2010 tpmac3-8.zip Essentially same as 3-7, but a few examples of coordinate system DBs added/updated, more documentation, boot tree examples (xxx) added, and the directory changed from 3-x to synApps/tpmac/3-x reflecting that the package is a part of synApps.
3-7 05/2010 tpmac3-7.zip A small fix to statusRecord.c allowing for compilation with EPICS base 3.14.11. Added support for waveform PVs and a mechanism to post PMAC error messages previoulsy only available on IOC console into a waveform PVs. A patch by Lewis Muir to devPmacRam.c avoiding potential crash on IOC reboots. See Release Notes for additional details.
3-6 02/2009 tpmac3-6.zip New versions of pmacAsynCoordSrc, pmacAsynIPPort and pmacAsynMotorSrc by Matthew Pearson and Nick Reese from the Diamond Light Source. Also, a few patches to databases including those to AssyGeneric_scanrec.db and bkgfix1pcs_scanrec.db by Lewis Muir. See Release Notes for details.
3-5 03/2008 tpmac3-5.zip The main motivation for this release is the addition of new IP driver produced by Pete Leicester and Nick Reese at the Diamond Light Source. This driver should allow communicating with Ethernet based Delta Tau controllers. See Release Notes for details.
3-4 06/2007 tpmac3-4.zip Fixed a long-standing bug from the initial 1996 implementation. The bug related to improper mutexing was causing pmacMbox task to crash occasionally, especially under high IOC load. Respectively, the only updated directory in this release compared to 3-3 is pmacApp/src.
3-3 12/2006 tpmac3-3.zip Switched to EPICS asyn driver for communicating with PMAC and replaced PMAC Mailbox communications by PMAC DPRAM ASCII communications. The new driver is mostly due to Nick Reese at the Diamond Light Source. Also, added the support for PMAC ADC/DAC (ACC-59E) and Digital IO (ACC-65E), revised some DBs, Tcl/Tk menus and MEDM screens.
2-3 02/2006 tpmac2-3.zip Added DB and tsub support for non-integer counts produced by encoder interpolator.
2-2 05/2004 tpmac2-2.zip Converted the driver to work with EPICS-3.14.
2-0 05/2003 tpmac2-0.zip The first release supporting Turbo PMAC2 Ultralite (as distinct from PMAC1 for which the initial driver was written by Tom Coleman)

Required Modules

Module Version Requires module Release needed Required for
3-5, 3-6, 3-7 EPICS base 3.14.8 and up, asyn 4.9 and up, Tornado 2.0 or 2.2 Base support
3-3, 3-4 EPICS base 3.14.8 and asyn 4.6 Base support
2-3 EPICS base 3.14.4 - 3.14.8 Base support
2-2 EPICS base 3.14.4 Base support
2-0 EPICS base 3.13.7 Base support

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

  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.
  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

This software was derived from the EPICS support for PMAC1 motion controllers originally developed by Thomas Coleman at Argonne National Lab and successfully used for a number of years by both SBC and BIO CATs at the APS.

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

Other sites devoted to EPICS and PMAC