sinqmotor

Overview

This library offers base classes for EPICS motor drivers (sinqAxis and sinqController) of PSI SINQ. These classes are extensions of the classes asynMotorAxis and asynMotorController from the asynMotor framework (https://github.com/epics-modules/motor/tree/master/motorApp/MotorSrc) and bundle some common functionalities.

Base classes

sinqMotor offers a variety of additional methods for children classes to standardize certain patterns (e.g. writing messages to the IOC shell and the motor message PV). For a detailed description, please see the respective function documentation in the .h-files. All of these functions can be overwritten manually if e.g. a completely different implementation of poll is required. Some functions are marked as virtual, because they are called from other functions of sinqMotor and therefore need runtime polymorphism. Functions without that marker are not called anywhere in sinqMotor.

sinqController

• stringifyAsynStatus: Convert the enum asynStatus into a human-readable string.
• errMsgCouldNotParseResponse: Write a standardized message if parsing a device response failed.
• paramLibAccessFailed: Write a standardized message if accessing the parameter library failed.

sinqAxis

• atFirstPoll: This function is executed once before the first poll. If it returns anything but asynSuccess, it retries.

• setWatchdogEnabled: Enables / disables the watchdog. This function is also available in the IOC shell.

• checkMovTimeoutWatchdog: Manages a watchdog mechanism for movement operations. This watchdog compares the actual time spent in a movement operation with an expected time, which is calculated based on the distance of the current and the target position.

• setOffsetMovTimeout: Set a linear offset for the expected movement time. This function is also available in the IOC shell.

• setScaleMovTimeout: Set a scaling factor for the expected movement time. This function is also available in the IOC shell.

• enable: This function is called if the "Enable" PV from db/sinqMotor.db is set. This is an empty function which should be overwritten by concrete driver implementations.

• isEnabled: This function returns whether the axis is currently enabled or not. This is an empty function which should be overwritten by concrete driver implementations.

• move: This function sets the absolute target position in the parameter library and then calls doMove.

• doMove: This is an empty function which should be overwritten by concrete driver implementations.

• home: This function sets the absolute target position in the parameter library and then calls doHome. The target position is assumed to be the high limit, if the distance of the current position to it is larger than that to the low limit, and the low limit otherwise.

• doHome: This is an empty function which should be overwritten by concrete driver implementations.

• poll: This is a wrapper around doPoll which performs some bookkeeping tasks before and after calling doPoll:

  Before calling doPoll:

  • Try to execute atFirstPoll once during the lifetime of the IOC (and retry, if that failed)

  After calling doPoll:

  • Call checkMovTimeoutWatchdog. If the movement timed out, create an error message for the user
  • Update the readback-value for the axis enablement.
  • Reset motorStatusProblem_, motorStatusCommsError_ and motorMessageText_ if doPoll returned asynSuccess
  • Run callParamCallbacks
  • Return the status of doPoll

• doPoll: This is an empty function which should be overwritten by concrete driver implementations.

Database

Besides the base classes, this EPICS module also offers an accompanying db/sinqMotor.db file. It can be parametrized with the dbLoadTemplate function from the IOC shell:

require sinqMotor, x.x.x # This is the three-digit version number of the sinqMotor module
dbLoadTemplate "motor.substitutions"

with motor.substitutions looking like this:

file "$(sinqMotor_DB)/sinqMotor.db"
{
pattern
{ AXIS,      M, DESC,   EGU,    DIR, MRES,  MOVWATCHDOG, LIMITSOFFSET }
{ 1,    "lin1", "lin1", mm,     Pos, 0.001, 1,         , 1.0          }
{ 2,    "rot1", "rot1", degree, Neg, 0.001, 0,         , 1.0          }
}

The variable sinqMotor_DB is generated automatically by require and corresponds to the module database path. The other parameters have the following meaning:

• AXIS: Index of the axis, corresponds to the physical connection of the axis to the MCU
• M: Name of the motor as shown in EPICS
• DESC: Description of the motor. This field is just for documentation and is not needed for operating a motor.
• EGU: Engineering units. For a linear motor, this is mm, for a rotaty motor, this is degree
• DIR: If set to "Neg", the axis direction is inverted
• MRES: This is a scaling factor determining the resolution of the position readback value. For example, 0.001 means a precision of 1 um. A detailed discussion of this value can be found in sinqAxis.cspp/startMovTimeoutWatchdog.
• MOVWATCHDOG: Sets setWatchdogEnabled during IOC startup to the given value.
• LIMITSOFFSET: If the motor limits are read out from the controller, they can be further reduced by this offset in order to avoid errors due to slight overshoot on the motor controller. For example, if this value is 1.0 and the read-out limits are [-10.0 10.0], the EPICS limits are set to [-9.0 9.0].

Versioning

The versioning is done via git tags. Git tags are recognized by the PSI build system: If you tag a version as 1.0, it will be built into the directory /ioc/modules/sinqMotor/1.0. The tag is directly coupled to a commit so that it is always clear which source code was used to build which binary.

All existing tags can be listed with git tag in the sinqMotor directory. Detailed information (author, data, commit number, commit message) regarding a specific tag can be shown with git show x.x.x, where x.x.x is the name of your version. To create a new tag, use git tag x.x.x. If the tag x.x.x is already used by another commit, git will show a corresponding error.

How to build it

The makefile in the top directory includes all necessary steps for compiling a shared library together with the header files into /ioc/modules (using the PSI EPICS build system).Therefore it is sufficient to run make install from the terminal.

To use the library when writing a concrete motor driver, include it in the makefile of your application /library the same way as other libraries such as e.g. asynMotor by adding REQUIRED+=sinqMotor to your Makefile. The version can be specified with sinqMotor_VERSION=x.x.x.