Substantial rRework of 0.2.0 after the CAMEA test showed multiple

problems. Also improved the documentation.

Makefile

@@ -17,6 +17,10 @@ SOURCES += src/sinqController.cpp
 HEADERS += src/sinqAxis.h
 HEADERS += src/sinqController.h
 
-USR_CFLAGS += -Wall -Wextra # -Werror
+# Store the record files
+TEMPLATES += db/asynRecord.db
+TEMPLATES += db/sinqMotor.db
+
+USR_CFLAGS += -Wall -Wextra -Weffc++ -Wunused-result # -Werror
 
 # MISCS  would be the place to keep the stream device template files

README.md

@@ -4,35 +4,77 @@
 
 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.
 
-## Features
+## 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-file. All of these functions can be overwritten manually if e.g. a completely different implementation of `poll` is required
+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
+- `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 (and retry, if that failed)
+  - 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`, where X.X is the name of your version. To create a new tag, use `git tag -a X.X`.
+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 -f Makefile` from the terminal.
+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.
+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.`

db/asynRecord.db

@@ -0,0 +1,9 @@
+record(asyn,"$(P)")
+{
+    field(DTYP,"asynRecordDevice")
+    field(PORT,"$(PORT)")
+    field(ADDR,"0")
+    field(OMAX,"80")
+    field(IMAX,"80")
+}
+

db/sinqMotor.db

@@ -0,0 +1,103 @@
+record(motor,"$(P)$(M)")
+{
+    field(DESC,"$(DESC)")
+    field(DTYP,"asynMotor")
+    field(DIR,"$(DIR)")
+    field(OUT,"@asyn($(CONTROLLER),$(AXIS))")
+    field(MRES,"$(MRES)")
+    field(EGU,"$(EGU)")
+    field(INIT,"")
+    field(PINI, "NO")
+    field(TWV,"1")
+    field(RTRY, "0")
+}
+
+# The message text
+record(waveform, "$(P)$(M)-MsgTxt") {
+    field(DTYP, "asynOctetRead")
+    field(INP, "@asyn($(CONTROLLER),$(AXIS),1) MOTOR_MESSAGE_TEXT")
+    field(FTVL, "CHAR")
+    field(NELM, "$(MsgTxtSize=200)") # Should be the same as MAXBUF in the driver code
+    field(SCAN, "I/O Intr")
+}
+
+# Provides the motor resolution MRES via an additional PV as explained here:
+# https://epics.anl.gov/tech-talk/2020/msg00378.php
+record(ao,"$(P)$(M):Resolution") {
+    field(DESC, "$(M) resolution")
+    field(DOL,  "$(P)$(M).MRES CP MS")
+    field(OMSL, "closed_loop")
+    field(DTYP, "asynFloat64")
+    field(OUT,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_REC_RESOLUTION")
+}
+
+record(longout, "$(P)$(M):Enable") {
+    field(DTYP, "asynInt32")
+    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) ENABLE_AXIS")
+    field(PINI, "NO")
+}
+
+record(longin, "$(P)$(M):Enable_RBV") {
+    field(DTYP, "asynInt32")
+    field(INP, "@asyn($(CONTROLLER),$(AXIS),1) ENABLE_AXIS_RBV")
+    field(PINI, "NO")
+    field(SCAN, "I/O Intr")
+}
+
+record(longout, "$(P)$(M):EnableWatchdog") {
+    field(DTYP, "asynInt32")
+    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) ENABLE_MOV_WATCHDOG")
+    field(PINI, "YES")
+    field(VAL, "$(MOVWATCHDOG)")
+}
+
+# The high and low limits of the axis are read
+# out directly from the MCU. However, since the axis might slightly
+# "overshoot" when moving to a position next to the limits, the MCU might go
+# into the "limits hit" error state. To prevent this, this value allows adding
+# a small offset, which is  subtracted from the high limit and added to the
+# low limit.
+record(ao, "$(P)$(M):LimitsOffset") {
+    field(DTYP, "asynFloat64")
+    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) LIMITS_OFFSET")
+    field(PINI, "YES")
+    field(ASG, "READONLY") # Field is initialized during IOC startup
+    field(VAL, "$(LIMITSOFFSET)")
+}
+
+# ===================================================================
+# The following records read the high / low limits from the parameter
+# library and copy those values into the corresponding fields of the main motor record.
+# This strategy is described here: https://epics.anl.gov/tech-talk/2022/msg00464.php
+
+# Helper record for the high limit which is filled in by the driver
+record(ai, "$(P)$(M):MOTOR_HIGH_LIMIT-RBV")
+{
+    field(DTYP, "asynFloat64")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_HIGH_LIMIT_FROM_DRIVER")
+    field(SCAN, "I/O Intr")
+    field(FLNK, "$(P)$(M):PUSH_DHLM_TO_FIELD")
+}
+
+# Push the value into the field of the main motor record
+record(ao, "$(P)$(M):PUSH_DHLM_TO_FIELD") {
+    field(DOL,  "$(P)$(M):MOTOR_HIGH_LIMIT-RBV CP")
+    field(OUT,  "$(P)$(M).DHLM")
+    field(OMSL, "closed_loop") # This configuration keeps the input value $(P)$(M):HLM_ADD_OFFSET and the output field $(P)$(M).DHLM in sync
+}
+
+# Helper record for the low limit which is filled in by the driver
+record(ai, "$(P)$(M):MOTOR_LOW_LIMIT-RBV")
+{
+    field(DTYP, "asynFloat64")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_LOW_LIMIT_FROM_DRIVER")
+    field(SCAN, "I/O Intr")
+    field(FLNK, "$(P)$(M):PUSH_DLLM_TO_FIELD")
+}
+
+# Push the value into the field of the main motor record
+record(ao, "$(P)$(M):PUSH_DLLM_TO_FIELD") {
+    field(DOL,  "$(P)$(M):MOTOR_LOW_LIMIT-RBV CP")
+    field(OUT,  "$(P)$(M).DLLM")
+    field(OMSL, "closed_loop") # This configuration keeps the input value $(P)$(M):LLM_ADD_OFFSET and the output field $(P)$(M).DLLM in sync
+}

src/sinqAxis.cpp

@@ -1,12 +1,16 @@
 #include "sinqAxis.h"
 #include "sinqController.h"
+#include <math.h>
 #include <unistd.h>
 
-sinqAxis::sinqAxis(class sinqController *pC, int axis)
-    : asynMotorAxis((asynMotorController *)pC, axis), pC_(pC) {
+sinqAxis::sinqAxis(class sinqController *pC, int axisNo)
+    : asynMotorAxis((asynMotorController *)pC, axisNo), pC_(pC) {
 
-    bool initial_poll_ = true;
-    int init_poll_counter_ = 0;
+    initial_poll_ = true;
+    watchdogMovActive_ = false;
+    init_poll_counter_ = 0;
+    scaleMovTimeout_ = 2.0;
+    offsetMovTimeout_ = 30;
 }
 
 asynStatus sinqAxis::atFirstPoll() { return asynSuccess; }
@@ -19,12 +23,13 @@ asynStatus sinqAxis::poll(bool *moving) {
     // =========================================================================
 
     // If this poll is the initial poll, check if the parameter library has
-    // already been initialized. If not, force EPCIS to repeat the poll until
+    // already been initialized. If not, force EPICS to repeat the poll until
     // the initialization is complete (or until a timeout is reached). Once the
     // parameter library has been initialized, read configuration data from the
     // motor controller into it.
     if (initial_poll_) {
         poll_status = atFirstPoll();
+
         if (poll_status == asynSuccess) {
             initial_poll_ = false;
         } else {
@@ -33,7 +38,7 @@ asynStatus sinqAxis::poll(bool *moving) {
             if (init_poll_counter_ % 10 == 0) {
                 asynPrint(pC_->pasynUserSelf, ASYN_TRACE_ERROR,
                           "%s => line %d:\nRunning function 'atFirstPoll' "
-                          "failed %d times with error %s.",
+                          "failed %d times with error %s.\n",
                           __PRETTY_FUNCTION__, __LINE__, init_poll_counter_,
                           pC_->stringifyAsynStatus(poll_status));
             }
@@ -50,6 +55,11 @@ asynStatus sinqAxis::poll(bool *moving) {
     // return.
     poll_status = doPoll(moving);
 
+    // Check and update the watchdog
+    if (checkMovTimeoutWatchdog(*moving) != asynSuccess) {
+        return asynError;
+    }
+
     // If the poll status is ok, reset the error indicators in the parameter
     // library
     if (poll_status == asynSuccess) {
@@ -71,6 +81,30 @@ asynStatus sinqAxis::poll(bool *moving) {
         }
     }
 
+    // Update the enable RBV
+    bool axisIsEnabled = false;
+
+    pl_status = isEnabled(&axisIsEnabled);
+    if (pl_status != asynSuccess) {
+        asynPrint(pC_->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFunction isEnabled failed with %s.\n",
+                  __PRETTY_FUNCTION__, __LINE__,
+                  pC_->stringifyAsynStatus(poll_status));
+        pl_status = setStringParam(pC_->motorMessageText_,
+                                   "Could not check whether the motor is "
+                                   "enabled or not. Please call the support");
+        if (pl_status != asynSuccess) {
+            return pC_->paramLibAccessFailed(pl_status, "motorMessageText_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+    } else {
+        pl_status = setIntegerParam(pC_->enableMotorRBV_, axisIsEnabled);
+        if (pl_status != asynSuccess) {
+            return pC_->paramLibAccessFailed(pl_status, "enableMotorRBV_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+    }
+
     // According to the function documentation of asynMotorAxis::poll, this
     // function should be called at the end of a poll implementation.
     pl_status = callParamCallbacks();
@@ -88,4 +122,306 @@ asynStatus sinqAxis::poll(bool *moving) {
     return poll_status;
 }
 
-asynStatus sinqAxis::doPoll(bool *moving) { return asynSuccess; }
+asynStatus sinqAxis::doPoll(bool *moving) { return asynSuccess; }
+
+asynStatus sinqAxis::move(double position, int relative, double minVelocity,
+                          double maxVelocity, double acceleration) {
+
+    double targetPosition = 0.0;
+
+    // Status of parameter library operations
+    asynStatus pl_status = asynSuccess;
+
+    // =========================================================================
+
+    // Calculate the (absolute) target position
+    if (relative) {
+
+        double motorPosition = 0.0;
+        pl_status =
+            pC_->getDoubleParam(axisNo_, pC_->motorPosition_, &motorPosition);
+        if (pl_status != asynSuccess) {
+            return pC_->paramLibAccessFailed(pl_status, "motorPosition_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+
+        targetPosition = position + motorPosition;
+    } else {
+        targetPosition = position;
+    }
+
+    // Set the target position
+    pl_status = setDoubleParam(pC_->motorTargetPosition_, targetPosition);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "motorTargetPosition_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    return doMove(position, relative, minVelocity, maxVelocity, acceleration);
+}
+
+asynStatus sinqAxis::doMove(double position, int relative, double minVelocity,
+                            double maxVelocity, double acceleration) {
+    return asynSuccess;
+}
+
+asynStatus sinqAxis::home(double minVelocity, double maxVelocity,
+                          double acceleration, int forwards) {
+
+    double targetPosition = 0.0;
+    double position = 0.0;
+    double highLimit = 0.0;
+    double lowLimit = 0.0;
+
+    // Status of parameter library operations
+    asynStatus pl_status = asynSuccess;
+
+    // =========================================================================
+
+    pl_status = pC_->getDoubleParam(axisNo_, pC_->motorPosition_, &position);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "motorPosition_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    pl_status = pC_->getDoubleParam(axisNo_, pC_->motorHighLimit_, &highLimit);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "motorHighLimit_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    pl_status = pC_->getDoubleParam(axisNo_, pC_->motorLowLimit_, &lowLimit);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "motorLowLimit_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    if (std::fabs(position - highLimit) > std::fabs(position - lowLimit)) {
+        targetPosition = highLimit;
+    } else {
+        targetPosition = lowLimit;
+    }
+
+    // Set the target position
+    pl_status = setDoubleParam(pC_->motorTargetPosition_, targetPosition);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "motorTargetPosition_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    return doHome(minVelocity, maxVelocity, acceleration, forwards);
+}
+
+asynStatus sinqAxis::doHome(double minVelocity, double maxVelocity,
+                            double acceleration, int forwards) {
+    return asynSuccess;
+}
+
+asynStatus sinqAxis::enable(bool on) { return asynSuccess; }
+
+asynStatus sinqAxis::isEnabled(bool *on) {
+    *on = true;
+    return asynSuccess;
+}
+
+asynStatus sinqAxis::setWatchdogEnabled(bool enable) {
+    return pC_->setIntegerParam(axisNo_, pC_->enableMovWatchdog_, enable);
+}
+
+asynStatus sinqAxis::startMovTimeoutWatchdog() {
+    asynStatus pl_status;
+    int enableMovWatchdog = 0;
+
+    pl_status = pC_->getIntegerParam(axisNo_, pC_->enableMovWatchdog_,
+                                     &enableMovWatchdog);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "enableMovWatchdog_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    if (enableMovWatchdog == 1) {
+        // These parameters are only needed in this branch
+        double motorPosition = 0.0;
+        double motorPositionRec = 0.0;
+        double motorTargetPositionRec = 0.0;
+        double motorTargetPosition = 0.0;
+        double motorVelocity = 0.0;
+        double motorVelocityRec = 0.0;
+        double motorAccel = 0.0;
+        double motorAccelRec = 0.0;
+        double motorRecResolution = 0.0;
+        time_t timeContSpeed = 0;
+        time_t timeAccel = 0;
+
+        // Activate the watchdog
+        watchdogMovActive_ = true;
+
+        /*
+        The motor record resolution (index motorRecResolution_ in the parameter
+        library, MRES in the motor record) is NOT a conversion factor between
+        user units (e.g. mm) and motor units (e.g. encoder steps), but a scaling
+        factor defining the resolution of the position readback field RRBV. This
+        is due to an implementation detail inside EPICS described here:
+        https://epics.anl.gov/tech-talk/2018/msg00089.php
+        https://github.com/epics-modules/motor/issues/8
+
+        Basically, the position value in the parameter library is a double which
+        is then truncated to an integer in devMotorAsyn.c (because it was
+        originally meant for converting from engineering units to encoder steps,
+        which are by definition integer values). Therefore, if we want a
+        precision of 1 millimeter, we need to set MRES to 1. If we want one of
+        1 micrometer, we need to set MRES to 0.001. The readback value needs to
+        be multiplied with MRES to get the actual value.
+
+        In the driver, we use user units. Therefore, when we interact with the
+        parameter library, we need to account for MRES. This means:
+        - When writing position or speed to the parameter library, we divide the
+        value by the motor record resolution.
+        - When reading position or speed from the parameter library, we multiply
+        the value with the motor record resolution.
+
+        Index and motor record field are coupled as follows:
+        The parameter motorRecResolution_ is coupled to the field MRES of the
+        motor record in the following manner:
+        - In sinqMotor.db, the PV (motor_record_pv_name) MOTOR_REC_RESOLUTION
+        is defined as a copy of the field (motor_record_pv_name).MRES:
+
+            record(ao,"$(P)$(M):Resolution") {
+                field(DESC, "$(M) resolution")
+                field(DOL,  "$(P)$(M).MRES CP MS")
+                field(OMSL, "closed_loop")
+                field(DTYP, "asynFloat64")
+                field(OUT,  "@asyn($(PORT),$(ADDR))MOTOR_REC_RESOLUTION")
+                field(PREC, "$(PREC)")
+            }
+
+        - The PV name MOTOR_REC_RESOLUTION is coupled in asynMotorController.h
+        to the constant motorRecResolutionString
+        - ... which in turn is assigned to motorRecResolution_ in
+        asynMotorController.cpp This way of making the field visible to the
+        driver is described here:
+        https://epics.anl.gov/tech-talk/2020/msg00378.php This is a one-way
+        coupling, changes to the parameter library via setDoubleParam are NOT
+        transferred to (motor_record_pv_name).MRES or to
+        (motor_record_pv_name):Resolution.
+
+        NOTE: This function must not be called in the constructor (e.g. in order
+        to save the read result to the member variable earlier), since the
+        parameter library is updated at a later stage!
+        */
+        pl_status = pC_->getDoubleParam(axisNo_, pC_->motorRecResolution_,
+                                        &motorRecResolution);
+        if (pl_status != asynSuccess) {
+            return pC_->paramLibAccessFailed(pl_status, "motorRecResolution_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+
+        pl_status = pC_->getDoubleParam(axisNo_, pC_->motorPosition_,
+                                        &motorPositionRec);
+        if (pl_status != asynSuccess) {
+            return pC_->paramLibAccessFailed(pl_status, "motorPosition",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+
+        motorPosition = motorPositionRec * motorRecResolution;
+
+        /*
+        We use motorVelocity, which corresponds to the record field VELO.
+        From https://epics.anl.gov/docs/APS2015/14-Motor-Record.pdf:
+        * VELO = motorVelocity_ = Slew velocity
+        * VBAS = motorVelBase_ = Only used for stepper motors to minimize
+        resonance.
+        As documented in
+        https://epics.anl.gov/docs/APS2015/17-Motor-Driver.pdf, the
+        following relations apply: motorVelBase = VBAS / MRES motorVelocity
+        = VELO / MRES motorAccel = (motorVelocity - motorVelBase) / ACCL
+        Therefore, we need to correct the values from the parameter library.
+         */
+
+        // Read the velocity
+        pl_status = pC_->getDoubleParam(axisNo_, pC_->motorVelocity_,
+                                        &motorVelocityRec);
+
+        // Only calculate timeContSpeed if the motorVelocity has been populated
+        // with a sensible value (e.g. > 0)
+        if (pl_status == asynSuccess && motorVelocityRec > 0.0) {
+            // Convert back to the value in the VELO field
+            motorVelocity = motorVelocityRec * motorRecResolution;
+
+            pl_status = pC_->getDoubleParam(axisNo_, pC_->motorTargetPosition_,
+                                            &motorTargetPositionRec);
+            motorTargetPosition = motorTargetPositionRec * motorRecResolution;
+            if (pl_status == asynSuccess) {
+
+                timeContSpeed =
+                    std::ceil(std::fabs(motorTargetPosition - motorPosition) /
+                              motorVelocity);
+            }
+        }
+
+        pl_status =
+            pC_->getDoubleParam(axisNo_, pC_->motorAccel_, &motorAccelRec);
+        if (pl_status == asynSuccess && motorVelocityRec > 0.0 &&
+            motorAccelRec > 0.0) {
+
+            // Convert back to the value in the ACCL field
+            motorAccel = motorVelocityRec / motorAccelRec;
+
+            // Calculate the time
+            timeAccel = 2 * std::ceil(motorVelocity / motorAccel);
+        }
+
+        // Calculate the expected arrival time
+        expectedArrivalTime_ =
+            time(NULL) + offsetMovTimeout_ +
+            scaleMovTimeout_ * (timeContSpeed + 2 * timeAccel);
+    } else {
+        watchdogMovActive_ = false;
+    }
+    return asynSuccess;
+}
+
+asynStatus sinqAxis::checkMovTimeoutWatchdog(bool moving) {
+    asynStatus pl_status;
+    int enableMovWatchdog = 0;
+
+    pl_status = pC_->getIntegerParam(axisNo_, pC_->enableMovWatchdog_,
+                                     &enableMovWatchdog);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "enableMovWatchdog_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    // Not moving or watchdog not active / enabled
+    if (enableMovWatchdog == 0 || !moving || !watchdogMovActive_) {
+        watchdogMovActive_ = false;
+        return asynSuccess;
+    }
+
+    // Check if the expected time of arrival has been exceeded.
+    if (expectedArrivalTime_ < time(NULL)) {
+        // Check the watchdog
+        asynPrint(pC_->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nAxis %d exceeded the expected arrival time "
+                  "(%ld).\n",
+                  __PRETTY_FUNCTION__, __LINE__, axisNo_, expectedArrivalTime_);
+
+        pl_status = setStringParam(
+            pC_->motorMessageText_,
+            "Exceeded expected arrival time. Check if the axis is blocked.");
+        if (pl_status != asynSuccess) {
+            return pC_->paramLibAccessFailed(pl_status, "motorMessageText_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+
+        pl_status = setIntegerParam(pC_->motorStatusProblem_, true);
+        if (pl_status != asynSuccess) {
+            pC_->paramLibAccessFailed(pl_status, "motorStatusProblem_",
+                                      __PRETTY_FUNCTION__, __LINE__);
+        }
+
+        // Even if the movement timed out, the rest of the poll should continue.
+        return asynSuccess;
+    }
+    return asynSuccess;
+}

src/sinqAxis.h

@@ -3,28 +3,248 @@ This class extends asynMotorAxis by some features used in SINQ.
 
 Stefan Mathis, November 2024
 */
+
 #ifndef __SINQDRIVER
 #define __SINQDRIVER
 #include "asynMotorAxis.h"
 
 class epicsShareClass sinqAxis : public asynMotorAxis {
   public:
-    sinqAxis(class sinqController *pC_, int axis);
+    /**
+     * @brief Construct a new sinqAxis object
+     *
+     * @param pC_                 Pointer to the controller of the axis
+     * @param axis                Index of the axis
+     */
+    sinqAxis(class sinqController *pC_, int axisNo);
 
     /**
-    This function is executed at the very first poll after the IOC startup. If
-    it returns anything else than 'asynSuccess', the function is evaluated again
-    after 100 ms until it succeeds. Every 10 trials a warning is emitted.
+     * @brief This function is executed once during the very first poll.
+     *
+     * This function is executed at the very first poll after the IOC startup.
+    If it returns anything else than 'asynSuccess', the function is evaluated
+    again after 100 ms until it succeeds. Every 10 trials a warning is emitted.
+    The default implementation just returns asynSuccess and is meant to be
+    overwritten by concrete driver implementations.
+     *
+     * @return asynStatus
      */
-    asynStatus atFirstPoll();
+    virtual asynStatus atFirstPoll();
 
+    /**
+     * @brief Perform some standardized operation before and after the concrete
+    `doPoll` implementation.
+     *
+     * Wrapper around doPoll which performs the following operations:
+    Before calling doPoll:
+    - Try to execute atFirstPoll once (and retry, if that failed)
+
+    After calling doPoll:
+    - Reset motorStatusProblem_, motorStatusCommsError_ and motorMessageText_ if
+    doPoll returned asynSuccess
+    - If the movement timeout watchdog has been started, check it.
+    - Update the parameter library entry enableMotorRBV_ by calling isEnabled.
+    - Run `callParamCallbacks`
+    - Return the status of `doPoll`
+     *
+     * @param moving              Forwarded to `doPoll`.
+     * @return asynStatus         Forward the status of `doPoll`, unless one of
+    the parameter library operation fails (in that case, returns the failed
+    operation status).
+     */
     asynStatus poll(bool *moving);
 
     /**
-    Implementation of the "proper", device-specific poll method. This method
-    should be implemented by a child class of sinqAxis.
+     * @brief Implementation of the "proper", device-specific poll method. This
+    method should be implemented by a child class of sinqAxis.
+     *
+     * @param moving            Should be set to true, if the axis is moving,
+     * and false otherwise.
+     * @return asynStatus
      */
-    asynStatus doPoll(bool *moving);
+    virtual asynStatus doPoll(bool *moving);
+
+    /**
+     * @brief Perform some standardized operation before and after the concrete
+    `doMove` implementation.
+
+    * Wrapper around `doMove` which calculates the (absolute) target position
+    and stores it in the parameter library. After that, it calls and returns
+    `doMove`.
+     *
+     * @param position            Forwarded to `doMove`.
+     * @param relative            Forwarded to `doMove`.
+     * @param minVelocity         Forwarded to `doMove`.
+     * @param maxVelocity         Forwarded to `doMove`.
+     * @param acceleration        Forwarded to `doMove`.
+     * @return asynStatus         Forward the status of `doMove`, unless one of
+    the parameter library operation fails (in that case, returns the failed
+    operation status).
+     */
+    asynStatus move(double position, int relative, double minVelocity,
+                    double maxVelocity, double acceleration);
+
+    /**
+     * @brief Implementation of the "proper", device-specific move method. This
+    method should be implemented by a child class of sinqAxis.
+     *
+     * @param position            Target position `VAL` from the motor record
+     * @param relative            Specifies, whether the target position is
+    relative or absolute.
+     * @param minVelocity         Minimum velocity VMIN from the motor record
+     * @param maxVelocity         Maximum velocity VMAX from the motor record
+     * @param acceleration        Acceleration ACCEL from the motor record
+     * @return asynStatus
+     */
+    virtual asynStatus doMove(double position, int relative, double minVelocity,
+                              double maxVelocity, double acceleration);
+
+    /**
+     * @brief Perform some standardized operation before and after the concrete
+    `doHome` implementation.
+    *
+    * Wrapper around move which calculates the (absolute) target position and
+    stores it in the parameter library. The target position in a homing maneuver
+    is calculated as follows:
+
+    if abs(current position - high limit) > abs(current position - low limit)
+    {
+    high limit
+    }
+    else
+    {
+    low limit
+    }
+
+    After that, it calls and returns doHome.
+     *
+     * @param minVelocity         Forwarded to `doHome`.
+     * @param maxVelocity         Forwarded to `doHome`.
+     * @param acceleration        Forwarded to `doHome`.
+     * @param forwards            Forwarded to `doHome`.
+     * @return asynStatus         Forward the status of `doHome`, unless one of
+    the parameter library operation fails (in that case, returns the failed
+    operation status).
+     */
+    asynStatus home(double minVelocity, double maxVelocity, double acceleration,
+                    int forwards);
+
+    /**
+     * @brief Implementation of the "proper", device-specific home method. This
+    method should be implemented by a child class of sinqAxis.
+     *
+     * @param minVelocity         Minimum velocity VMIN from the motor record
+     * @param maxVelocity         Maximum velocity VMAX from the motor record
+     * @param acceleration        Acceleration ACCEL from the motor record
+     * @param forwards            Is 1, if the motor record field HOMF was used
+    to trigger the homing, and 0, if HOMR was used.
+     * @return asynStatus
+     */
+    virtual asynStatus doHome(double minVelocity, double maxVelocity,
+                              double acceleration, int forwards);
+
+    /**
+     * @brief This function enables / disables an axis. It should be implemented
+     * by a child class of sinqAxis.
+     *
+     * @param on
+     * @return asynStatus
+     */
+    virtual asynStatus enable(bool on);
+
+    /**
+     * @brief This function should set "on" to true, if the motor is enabled,
+     * and false otherwise. It should be implemented by a child class of
+     * sinqAxis.
+     *
+     * @param on
+     * @return asynStatus
+     */
+    virtual asynStatus isEnabled(bool *on);
+
+    /**
+     * @brief Start the watchdog for the movement, if the watchdog is not
+    disabled. See the documentation of checkMovTimeoutWatchdog for more details.
+     *
+     * @return asynStatus         If one of the parameter library operations
+    used to get the values for the timeout calculation failed, return that
+    status, otherwise return asynSuccess.
+     */
+    asynStatus startMovTimeoutWatchdog();
+
+    /**
+     * @brief Check if the watchdog timed out
+     *
+    Manages a timeout mechanism for the movement:
+    If the axis is moving and the movement takes too long, create an error
+    message and return asynError. The watchdog is started when moving switches
+    from "false" to "true" and stopped when moving switches from "true" to
+    "false". At the watchdog start, the estimated movement time is calculated as
+
+    t = offsetMovTimeout_ + scaleMovTime_ * [timeContSpeed + 2*timeAccel]
+
+    with
+
+    timeContSpeed = abs(motorTargetPosition - motorPosition) / motorVelBase
+    timeAcc = motorVelBase / motorAccel
+
+    The values motorTargetPosition, motorVelBase, motorAccel and
+    positionAtMovementStart are taken from the parameter library. Therefore it
+    is necessary to populate them before using this function. If they are not
+    given, both speed and velocity are assumed to be infinite. This means that
+    timeContSpeed and/or timeAcc are set to zero. motorTargetPosition is
+    populated automatically when using the doMove function.
+
+    The values offsetMovTimeout_ and scaleMovTimeout_ can be set directly from
+    the IOC shell with the functions setScaleMovTimeout and setOffsetMovTimeout,
+    if sinqMotor is loaded via the "require" mechanism.
+     *
+     * @param moving              Should be the "moving" status from `poll` /
+    `doPoll`.
+     * @return asynStatus         Return asynError, if the watchdog timed out,
+    and asynSuccess otherwise.
+     */
+    asynStatus checkMovTimeoutWatchdog(bool moving);
+
+    /**
+     * @brief Enable / disable the watchdog. Also available in the IOC shell
+     * (see "extern C" section in sinqController.cpp).
+     *
+     * If enable is set to false and the watchdog is currently running, this
+     * function stops it immediately.
+     *
+     * @param enabled
+     * @return asynStatus
+     */
+    virtual asynStatus setWatchdogEnabled(bool enable);
+
+    /**
+     * @brief Set the offsetMovTimeout. Also available in the IOC shell
+     * (see "extern C" section in sinqController.cpp).
+     *
+    See documentation of `checkMovTimeoutWatchdog` for details.
+     *
+     * @param offsetMovTimeout    Offset (in seconds)
+     * @return asynStatus
+     */
+    virtual asynStatus setOffsetMovTimeout(time_t offsetMovTimeout) {
+        offsetMovTimeout_ = offsetMovTimeout;
+        return asynSuccess;
+    }
+
+    /**
+     * @brief Set the scaleMovTimeout. Also available in the IOC shell
+     * (see "extern C" section in sinqController.cpp).
+     *
+    See documentation of `checkMovTimeoutWatchdog` for details.
+     *
+     * @param scaleMovTimeout     Scaling factor (in seconds)
+     * @return asynStatus
+     */
+    virtual asynStatus setScaleMovTimeout(time_t scaleMovTimeout) {
+        scaleMovTimeout_ = scaleMovTimeout;
+        return asynSuccess;
+    }
 
     friend class sinqController;
 
@@ -32,6 +252,12 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
     bool initial_poll_;
     int init_poll_counter_;
 
+    // Helper variables for movementTimeoutWatchdog
+    time_t expectedArrivalTime_;
+    time_t offsetMovTimeout_;
+    double scaleMovTimeout_;
+    bool watchdogMovActive_;
+
   private:
     sinqController *pC_;
 };

src/sinqController.cpp

@@ -1,33 +1,200 @@
-/*
-  This class contains the necessary changes to have an additional text fields
-  for messages with each axis.
-
-  Code lifted from Torsten Boegershausen ESS code.
-
-  Mark Koennecke, March 2017
-
-  Added code to manage an interMessageSleep
-
-  Mark Koennecke, February 2024
-*/
-
 #include "sinqController.h"
 #include "asynMotorController.h"
+#include "asynOctetSyncIO.h"
 #include "epicsExport.h"
 #include "iocsh.h"
+#include "sinqAxis.h"
 #include <errlog.h>
 
-sinqController::sinqController(const char *portName, const char *SINQPortName,
-                               int numAxes, const int &extraParams)
+sinqController::sinqController(const char *portName,
+                               const char *ipPortConfigName, int numAxes,
+                               double movingPollPeriod, double idlePollPeriod,
+                               int numExtraParams)
     : asynMotorController(
-          portName, numAxes + 1, NUM_MOTOR_DRIVER_PARAMS + extraParams,
+          portName,
+          // As described in the function documentation, an offset of 1 is
+          // added for better readability of the configuration.
+          numAxes + 1,
+          /*
+          4 Parameters are added in sinqController:
+          - MOTOR_MESSAGE_TEXT
+          - MOTOR_TARGET_POSITION
+          - ENABLE_AXIS
+          - ENABLE_AXIS_RBV
+          - ENABLE_MOV_WATCHDOG
+          - LIMITS_OFFSET
+          */
+          NUM_MOTOR_DRIVER_PARAMS + NUM_SINQMOTOR_DRIVER_PARAMS +
+              numExtraParams,
           0, // No additional interfaces beyond those in base class
           0, // No additional callback interfaces beyond those in base class
           ASYN_CANBLOCK | ASYN_MULTIDEVICE,
-          1,    // autoconnect
-          0, 0) // Default priority and stack size
+          1, // autoconnect
+          0,
+          0) // Default priority and stack size
 {
-    createParam(motorMessageTextString, asynParamOctet, &motorMessageText_);
+
+    // Initialization of local variables
+    asynStatus status = asynSuccess;
+
+    // Initialization of all member variables
+    lowLevelPortUser_ = nullptr;
+
+    // =========================================================================;
+
+    /*
+    We try to connect to the port via the port name provided by the constructor.
+    If this fails, the function is terminated via exit.
+    */
+    pasynOctetSyncIO->connect(ipPortConfigName, 0, &lowLevelPortUser_, NULL);
+    if (status != asynSuccess || lowLevelPortUser_ == nullptr) {
+        errlogPrintf(
+            "%s => line %d:\nFATAL ERROR (cannot connect to MCU controller).\n"
+            "Terminating IOC",
+            __PRETTY_FUNCTION__, __LINE__);
+        exit(-1);
+    }
+
+    // =========================================================================;
+
+    // MOTOR_MESSAGE_TEXT corresponds to the PV definition inside sinqMotor.db.
+    // This text is used to forward status messages to NICOS and in turn to the
+    // user.
+    status =
+        createParam("MOTOR_MESSAGE_TEXT", asynParamOctet, &motorMessageText_);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFATAL ERROR (creating a parameter failed "
+                  "with %s).\nTerminating IOC",
+                  __PRETTY_FUNCTION__, __LINE__, stringifyAsynStatus(status));
+        exit(-1);
+    }
+
+    // Internal parameter library entry which stores the movement target
+    status = createParam("MOTOR_TARGET_POSITION", asynParamFloat64,
+                         &motorTargetPosition_);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFATAL ERROR (creating a parameter failed "
+                  "with %s).\nTerminating IOC",
+                  __PRETTY_FUNCTION__, __LINE__, stringifyAsynStatus(status));
+        exit(-1);
+    }
+
+    status = createParam("ENABLE_AXIS", asynParamInt32, &enableMotor_);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFATAL ERROR (creating a parameter failed "
+                  "with %s).\nTerminating IOC",
+                  __PRETTY_FUNCTION__, __LINE__, stringifyAsynStatus(status));
+        exit(-1);
+    }
+
+    status = createParam("ENABLE_AXIS_RBV", asynParamInt32, &enableMotorRBV_);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFATAL ERROR (creating a parameter failed "
+                  "with %s).\nTerminating IOC",
+                  __PRETTY_FUNCTION__, __LINE__, stringifyAsynStatus(status));
+        exit(-1);
+    }
+
+    /*
+    We need to introduce 2 new parameters in order to write the limits from the
+    driver to the EPICS record. See the comment in sinqController.h next to
+    the declaration of motorHighLimitFromDriver_.
+    */
+    status = createParam("MOTOR_HIGH_LIMIT_FROM_DRIVER", asynParamFloat64,
+                         &motorHighLimitFromDriver_);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFATAL ERROR (creating a parameter failed "
+                  "with %s).\nTerminating IOC",
+                  __PRETTY_FUNCTION__, __LINE__, stringifyAsynStatus(status));
+        exit(-1);
+    }
+
+    status = createParam("MOTOR_LOW_LIMIT_FROM_DRIVER", asynParamFloat64,
+                         &motorLowLimitFromDriver_);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFATAL ERROR (creating a parameter failed "
+                  "with %s).\nTerminating IOC",
+                  __PRETTY_FUNCTION__, __LINE__, stringifyAsynStatus(status));
+        exit(-1);
+    }
+
+    status =
+        createParam("ENABLE_MOV_WATCHDOG", asynParamInt32, &enableMovWatchdog_);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFATAL ERROR (creating a parameter failed "
+                  "with %s).\nTerminating IOC",
+                  __PRETTY_FUNCTION__, __LINE__, stringifyAsynStatus(status));
+        exit(-1);
+    }
+
+    status =
+        createParam("LIMITS_OFFSET", asynParamFloat64, &motorLimitsOffset_);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFATAL ERROR (creating a parameter failed "
+                  "with %s).\nTerminating IOC",
+                  __PRETTY_FUNCTION__, __LINE__, stringifyAsynStatus(status));
+        exit(-1);
+    }
+
+    // Poller configuration
+    status = startPoller(movingPollPeriod, idlePollPeriod, 1);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nFATAL ERROR (starting the poller failed "
+                  "with %s).\nTerminating IOC",
+                  __PRETTY_FUNCTION__, __LINE__, stringifyAsynStatus(status));
+        pasynOctetSyncIO->disconnect(lowLevelPortUser_);
+        exit(-1);
+    }
+}
+
+sinqController::~sinqController(void) {
+    /*
+    Cleanup of the memory allocated in the asynMotorController constructor
+    */
+    free(this->pAxes_);
+}
+
+asynStatus sinqController::writeInt32(asynUser *pasynUser, epicsInt32 value) {
+    int function = pasynUser->reason;
+
+    // =====================================================================
+
+    asynMotorAxis *asynAxis = getAxis(pasynUser);
+    sinqAxis *axis = dynamic_cast<sinqAxis *>(asynAxis);
+    if (axis == nullptr) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "%s => line %d:\nAxis %d is not an instance of sinqAxis",
+                  __PRETTY_FUNCTION__, __LINE__, axis->axisNo_);
+        return asynError;
+    }
+
+    // Handle custom PVs
+    if (function == enableMotor_) {
+        return axis->enable(value != 0);
+    } else {
+        return asynMotorController::writeInt32(pasynUser, value);
+    }
+}
+
+/*
+Overloaded from asynMotorController to cover the readback value of enableMotor.
+*/
+asynStatus sinqController::readInt32(asynUser *pasynUser, epicsInt32 *value) {
+    if (pasynUser->reason == enableMotorRBV_) {
+        // Value is updated in the poll function of an axis
+        return asynSuccess;
+    } else {
+        return asynMotorController::readInt32(pasynUser, value);
+    }
 }
 
 asynStatus sinqController::errMsgCouldNotParseResponse(const char *command,
@@ -35,14 +202,14 @@ asynStatus sinqController::errMsgCouldNotParseResponse(const char *command,
                                                        int axisNo_,
                                                        const char *functionName,
                                                        int lineNumber) {
+
     asynPrint(lowLevelPortUser_, ASYN_TRACE_ERROR,
               "%s => line %d:\n Could not interpret response %s for "
               "command %s.\n",
               functionName, lineNumber, response, command);
 
     setStringParam(motorMessageText_,
-                   "Could not interpret MCU response. Please "
-                   "call the software support");
+                   "Could not interpret MCU response. Please call the support");
     setIntegerParam(motorStatusCommsError_, 1);
     return asynError;
 }
@@ -56,11 +223,11 @@ asynStatus sinqController::paramLibAccessFailed(asynStatus status,
         // Log the error message and try to propagate it
         asynPrint(lowLevelPortUser_, ASYN_TRACE_ERROR,
                   "%s => line %d:\n Accessing the parameter library failed for "
-                  "parameter %s",
-                  functionName, lineNumber, parameter);
-        setStringParam(
-            motorMessageText_,
-            "Accessing paramLib failed. Please call the software support.");
+                  "parameter %s with error %s.\n",
+                  functionName, lineNumber, parameter,
+                  stringifyAsynStatus(status));
+        setStringParam(motorMessageText_,
+                       "Accessing paramLib failed. Please call the support.");
     }
 
     return status;
@@ -69,18 +236,21 @@ asynStatus sinqController::paramLibAccessFailed(asynStatus status,
 // Static pointers (valid for the entire lifetime of the IOC). The number behind
 // the strings gives the integer number of each variant (see also method
 // stringifyAsynStatus)
-const char *asynSuccessStringified = "success";                             // 0
-const char *asynTimeoutStringified = "timeout";                             // 1
-const char *asynOverflowStringified = "overflow";                           // 2
-const char *asynErrorStringified = "error";                                 // 3
-const char *asynDisconnectedStringified = "disconnected";                   // 4
-const char *asynDisabledStringified = "disabled";                           // 5
-const char *asynParamAlreadyExistsStringified = "parameter already exists"; // 6
-const char *asynParamNotFoundStringified = "parameter not found";           // 7
-const char *asynParamWrongTypeStringified = "wrong type";                   // 8
-const char *asynParamBadIndexStringified = "bad index";                     // 9
-const char *asynParamUndefinedStringified = "parameter undefined"; // 10
-const char *asynParamInvalidListStringified = "invalid list";      // 11
+const char asynSuccessStringified[] = "success";           // 0
+const char asynTimeoutStringified[] = "timeout";           // 1
+const char asynOverflowStringified[] = "overflow";         // 2
+const char asynErrorStringified[] = "error";               // 3
+const char asynDisconnectedStringified[] = "disconnected"; // 4
+const char asynDisabledStringified[] = "disabled";         // 5
+const char asynParamAlreadyExistsStringified[] =
+    "parameter already exists";                                     // 6
+const char asynParamNotFoundStringified[] = "parameter not found";  // 7
+const char asynParamWrongTypeStringified[] = "wrong type";          // 8
+const char asynParamBadIndexStringified[] = "bad index";            // 9
+const char asynParamUndefinedStringified[] = "parameter undefined"; // 10
+const char asynParamInvalidListStringified[] = "invalid list";      // 11
+const char inputDidNotMatchAsynStatus[] =
+    "Input did not match any variant of asynStatus";
 
 const char *sinqController::stringifyAsynStatus(asynStatus status) {
     // See
@@ -88,6 +258,9 @@ const char *sinqController::stringifyAsynStatus(asynStatus status) {
     // and
     // https://github.com/epics-modules/asyn/blob/master/asyn/asynPortDriver/paramErrors.h
     // for the definition of the error codes
+    // The pragma is necessary since the param lib error codes are "tacked onto"
+    // the enum, which results in compiler warnings otherwise.
+#pragma GCC diagnostic ignored "-Wswitch"
     switch (status) {
     case asynSuccess:
         return asynSuccessStringified;
@@ -115,7 +288,162 @@ const char *sinqController::stringifyAsynStatus(asynStatus status) {
         return asynParamInvalidListStringified;
     }
 
-    errlogPrintf("%s => line %d:\nReached unreachable code.",
-                 __PRETTY_FUNCTION__, __LINE__);
-    return "unreachable code reached";
-}
+    asynPrint(
+        pasynUserSelf, ASYN_TRACE_ERROR,
+        "%s => line %d:\nInput did not match any variant of asynStatus.\n",
+        __PRETTY_FUNCTION__, __LINE__);
+
+    return inputDidNotMatchAsynStatus;
+}
+
+// =============================================================================
+// Provide the setters to IOC shell
+extern "C" {
+
+/**
+ * @brief Enable / disable the watchdog (FFI implementation)
+ *
+ * @param portName                Name of the controller
+ * @param axisNo                  Axis number
+ * @param enable                  If 0, disable the watchdog, otherwise enable
+ * it
+ * @return asynStatus
+ */
+asynStatus setWatchdogEnabled(const char *portName, int axisNo, int enable) {
+
+    sinqController *pC;
+    pC = (sinqController *)findAsynPortDriver(portName);
+    if (pC == nullptr) {
+        errlogPrintf("%s => line %d:\nPort %s not found.", __PRETTY_FUNCTION__,
+                     __LINE__, portName);
+        return asynError;
+    }
+
+    asynMotorAxis *asynAxis = pC->getAxis(axisNo);
+    sinqAxis *axis = dynamic_cast<sinqAxis *>(asynAxis);
+    if (axis == nullptr) {
+        errlogPrintf("%s => line %d:\nAxis %d does not exist or is not an "
+                     "instance of sinqAxis.",
+                     __PRETTY_FUNCTION__, __LINE__, axisNo);
+    }
+
+    return axis->setWatchdogEnabled(enable != 0);
+}
+
+static const iocshArg setWatchdogEnabledArg0 = {"Controller port name",
+                                                iocshArgString};
+static const iocshArg setWatchdogEnabledArg1 = {"Axis number", iocshArgInt};
+static const iocshArg setWatchdogEnabledArg2 = {
+    "Enabling / disabling the watchdog", iocshArgInt};
+static const iocshArg *const setWatchdogEnabledArgs[] = {
+    &setWatchdogEnabledArg0, &setWatchdogEnabledArg1, &setWatchdogEnabledArg2};
+static const iocshFuncDef setWatchdogEnabledDef = {"setWatchdogEnabled", 3,
+                                                   setWatchdogEnabledArgs};
+
+static void setWatchdogEnabledCallFunc(const iocshArgBuf *args) {
+    setWatchdogEnabled(args[0].sval, args[1].ival, args[2].ival);
+}
+
+// =============================================================================
+
+/**
+ * @brief Set the offsetMovTimeout (FFI implementation)
+ *
+ * @param portName                Name of the controller
+ * @param axisNo                  Axis number
+ * @param offsetMovTimeout        Offset (in seconds)
+ * @return asynStatus
+ */
+asynStatus setOffsetMovTimeout(const char *portName, int axisNo,
+                               double offsetMovTimeout) {
+
+    sinqController *pC;
+    pC = (sinqController *)findAsynPortDriver(portName);
+    if (pC == nullptr) {
+        errlogPrintf("%s => line %d:\nPort %s not found.", __PRETTY_FUNCTION__,
+                     __LINE__, portName);
+        return asynError;
+    }
+
+    asynMotorAxis *asynAxis = pC->getAxis(axisNo);
+    sinqAxis *axis = dynamic_cast<sinqAxis *>(asynAxis);
+    if (axis == nullptr) {
+        errlogPrintf("%s => line %d:\nAxis %d does not exist or is not an "
+                     "instance of sinqAxis.",
+                     __PRETTY_FUNCTION__, __LINE__, axisNo);
+    }
+
+    return axis->setOffsetMovTimeout(offsetMovTimeout);
+}
+
+static const iocshArg setOffsetMovTimeoutArg0 = {"Controller port name",
+                                                 iocshArgString};
+static const iocshArg setOffsetMovTimeoutArg1 = {"Axis number", iocshArgInt};
+static const iocshArg setOffsetMovTimeoutArg2 = {"Offset timeout for movement",
+                                                 iocshArgDouble};
+static const iocshArg *const setOffsetMovTimeoutArgs[] = {
+    &setOffsetMovTimeoutArg0, &setOffsetMovTimeoutArg1,
+    &setOffsetMovTimeoutArg2};
+static const iocshFuncDef setOffsetMovTimeoutDef = {"setOffsetMovTimeout", 3,
+                                                    setOffsetMovTimeoutArgs};
+
+static void setOffsetMovTimeoutCallFunc(const iocshArgBuf *args) {
+    setOffsetMovTimeout(args[0].sval, args[1].ival, args[2].dval);
+}
+
+// =============================================================================
+
+/**
+ * @brief Set the setScaleMovTimeout (FFI implementation)
+ *
+ * @param portName                Name of the controller
+ * @param axisNo                  Axis number
+ * @param scaleMovTimeout         Scaling factor (in seconds)
+ * @return asynStatus
+ */
+asynStatus setScaleMovTimeout(const char *portName, int axisNo,
+                              double scaleMovTimeout) {
+
+    sinqController *pC;
+    pC = (sinqController *)findAsynPortDriver(portName);
+    if (pC == nullptr) {
+        errlogPrintf("%s => line %d:\nPort %s not found.", __PRETTY_FUNCTION__,
+                     __LINE__, portName);
+        return asynError;
+    }
+
+    asynMotorAxis *asynAxis = pC->getAxis(axisNo);
+    sinqAxis *axis = dynamic_cast<sinqAxis *>(asynAxis);
+    if (axis == nullptr) {
+        errlogPrintf("%s => line %d:\nAxis %d does not exist or is not an "
+                     "instance of sinqAxis.",
+                     __PRETTY_FUNCTION__, __LINE__, axisNo);
+    }
+
+    return axis->setScaleMovTimeout(scaleMovTimeout);
+}
+
+static const iocshArg setScaleMovTimeoutArg0 = {"Controller port name",
+                                                iocshArgString};
+static const iocshArg setScaleMovTimeoutArg1 = {"Axis number", iocshArgInt};
+static const iocshArg setScaleMovTimeoutArg2 = {
+    "Multiplier for calculated move time", iocshArgDouble};
+static const iocshArg *const setScaleMovTimeoutArgs[] = {
+    &setScaleMovTimeoutArg0, &setScaleMovTimeoutArg1, &setScaleMovTimeoutArg2};
+static const iocshFuncDef setScaleMovTimeoutDef = {"setScaleMovTimeout", 3,
+                                                   setScaleMovTimeoutArgs};
+
+static void setScaleMovTimeoutCallFunc(const iocshArgBuf *args) {
+    setScaleMovTimeout(args[0].sval, args[1].ival, args[2].dval);
+}
+
+// =============================================================================
+
+static void sinqControllerRegister(void) {
+    iocshRegister(&setOffsetMovTimeoutDef, setOffsetMovTimeoutCallFunc);
+    iocshRegister(&setScaleMovTimeoutDef, setScaleMovTimeoutCallFunc);
+    iocshRegister(&setWatchdogEnabledDef, setWatchdogEnabledCallFunc);
+}
+epicsExportRegistrar(sinqControllerRegister);
+
+} // extern C

src/sinqController.h

@@ -1,10 +1,7 @@
 /*
-  This class contains the necessary changes to have an additional text fields
-  for messages with each axis.
+This class extends asynMotorController by some features used in SINQ.
 
-  Code lifted from Torsten Boegershausens ESS code.
-
-  Mark Koennecke, March 2017
+Stefan Mathis, November 2024
 */
 
 #ifndef __sinqController
@@ -16,23 +13,98 @@
 
 class epicsShareClass sinqController : public asynMotorController {
   public:
+    /**
+   * @brief Construct a new sinqController object
+   *
+   * @param portName              Controller can be found by findAsynPortDriver
+   * with this name
+   * @param ipPortConfigName      IP adress and port configuration of the
+   * controller unit, used to connect via pasynOctetSyncIO->connect
+   * @param numAxes               Pointers to the axes are stored in the array
+   pAxes_ which has the length specified here. When getting an axis, the
+   `getAxis` function indexes into this array. A length of 8 would therefore
+   mean that the axis slots 0 to 7 are available. However, in order to keep the
+   axis enumeration in sync with the electronics counting logic, we start
+   counting the axes with 1 and end at 8. Therefore, an offset of 1 is added
+   when forwarding this number to asynMotorController.
+   * @param movingPollPeriod      Time between polls when moving (in seconds)
+   * @param idlePollPeriod        Time between polls when not moving (in
+   seconds)
+   * @param extraParams           Number of extra parameter library entries
+   * created in a concrete driver implementation
+   */
     sinqController(const char *portName, const char *SINQPortName, int numAxes,
-                   const int &extraParams = 2);
-
-    friend class sinqAxis;
+                   double movingPollPeriod, double idlePollPeriod,
+                   int numExtraParams);
 
     /**
-    If accessing the parameter library failed (return status != asynSuccess),
-    calling this function writes a standardized message to both the IOC shell
-    and the motor message text PV. It then returns the input status.
+     * @brief Destroy the sinqController object
+     *
+     * In general, there is no real memory cleanup strategy in asynMotor,
+     * because objects are expected to be alive for the entire lifetime of the
+     * IOC. We just clean up the allocated axes array here.
+     */
+    virtual ~sinqController(void);
+
+    /**
+     * @brief Overloaded function of asynMotorController
+     *
+     * The function is overloaded to allow enabling / disabling the motor.
+     *
+     * @param pasynUser           Specify the axis via the asynUser
+     * @param value               New value
+     * @return asynStatus
+     */
+    asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
+
+    /**
+     * @brief Overloaded function of asynMotorController
+     *
+     * The function is overloaded to get readback values for the enabling /
+     * disabling status.
+     *
+     * @param pasynUser           Specify the axis via the asynUser
+     * @param value               Read-out value
+     * @return asynStatus
+     */
+    asynStatus readInt32(asynUser *pasynUser, epicsInt32 *value);
+
+    /**
+     * @brief Error handling in case accessing the parameter library failed.
+     *
+     * If accessing the parameter library failed (return status !=
+    asynSuccess), calling this function writes a standardized message to both
+    the IOC shell and the motor message text PV. It then returns the input
+    status.
+     *
+     * @param status              Status of the failed parameter library access
+     * @param parameter           Name of the parameter, used to create the
+    error messages.
+     * @param functionName        Name of the caller function. It is recommended
+    to use a macro, e.g. __func__ or __PRETTY_FUNCTION__.
+     * @param lineNumber          Source code line where this function is
+    called. It is recommended to use a macro, e.g. __LINE__.
+     * @return asynStatus         Returns input status.
      */
     asynStatus paramLibAccessFailed(asynStatus status, const char *parameter,
                                     const char *functionName, int lineNumber);
 
     /**
-    This function writes a standardized message to both the IOC shell and
+     * @brief Error handling in case parsing a command response failed.
+     *
+     * This function writes a standardized message to both the IOC shell and
     the motor message text PV in case parsing a response (e.g. via sscanf)
-    failed. It always returns asynError.
+    failed. It always returns asynError. This is convenience feature so the
+    function call can be used as a return value in an error handling branch.
+     *
+     * @param command             Command which led to the unparseable message
+     * @param response            Response which wasn't parseable
+     * @param axisNo_             Axis where the problem occurred
+     * @param functionName        Name of the caller function. It is recommended
+    to use a macro, e.g. __func__ or __PRETTY_FUNCTION__.
+     * @param lineNumber          Source code line where this function is
+    called. It is recommended to use a macro, e.g. __LINE__.
+     * @return asynStatus         Returns asynError.
      */
     asynStatus errMsgCouldNotParseResponse(const char *command,
                                            const char *response, int axisNo_,
@@ -40,14 +112,38 @@ class epicsShareClass sinqController : public asynMotorController {
                                            int lineNumber);
 
     /**
-    Convert an asynStatus into a descriptive string. This string can then e.g.
-    be used to create debugging messages.
+     * @brief Convert an asynStatus into a descriptive string.
+     *
+     * @param status              Status which should be converted to a string.
+     * @return const char*
      */
     const char *stringifyAsynStatus(asynStatus status);
 
+    friend class sinqAxis;
+
   protected:
     asynUser *lowLevelPortUser_;
+
+#define FIRST_SINQMOTOR_PARAM motorMessageText_
     int motorMessageText_;
+    int motorTargetPosition_;
+    int enableMotor_;
+    int enableMotorRBV_;
+    int enableMovWatchdog_;
+    int motorLimitsOffset_;
+
+    /*
+    These parameters are here to write the high and low limits from the MCU to
+    the EPICS motor record. Using motorHighLimit_ / motorLowLimit_ does not
+    work: https://epics.anl.gov/tech-talk/2023/msg00576.php.
+    Therefore, some additional records are introduced which read from these
+    parameters and write into the motor record. See the sinq_asyn_motor.db file.
+    */
+    int motorHighLimitFromDriver_;
+    int motorLowLimitFromDriver_;
+#define LAST_SINQMOTOR_PARAM motorLowLimitFromDriver_
 };
+#define NUM_SINQMOTOR_DRIVER_PARAMS                                            \
+    (&LAST_SINQMOTOR_PARAM - &FIRST_SINQMOTOR_PARAM + 1)
 
 #endif

src/sinqMotor.dbd

@@ -0,0 +1,4 @@
+#---------------------------------------------
+# SINQ specific DB definitions
+#---------------------------------------------
+registrar(sinqControllerRegister)