Added new feature to set deadband

The field SPDB can now be populated via either the substitutions file or
from inside the driver (using the motorPositionDeadband paramLib entry).

README.md

@@ -204,7 +204,7 @@ transferred to (motor_record_pv_name).MRES or to
 
 ## Developer guide
 
-### Base classes
+### File structure
 
 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 (except for `forcedPoll`, which is called in `poll`).
 
@@ -257,12 +257,27 @@ This method should not be called in the driver code itself if a poll is needed -
 - `startMovTimeoutWatchdog`: Starts a watchdog for the movement time. 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.
 - `checkMovTimeoutWatchdog`: Check if the watchdog timed out.
 - `setWatchdogEnabled`: Enables / disables the watchdog. This function is also available in the IOC shell.
-- `setOffsetMovTimeout`: Set a linear offset for the expected movement time. This function is also available in the IOC shell.
+- `setOffsetMovTimeout`: Set a constant 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.
 
 #### msgPrintControl.h
 In addition to the two extension classes this library also includes a mechanism which prevents excessive repetitions of the same error message to the IOC shell via the classes `msgPrintControl` and `msgPrintControlKey`. A detailed description of the mechanism can be found in the docstring of `msgPrintControl`. The implementation of the `poll` function of `sinqAxis` also contains an example how to use it. Using this feature in derived drivers is entirely optional.
 
+#### macros.h
+Contains macros used in `sinqMotor` and derived drivers:
+
+- **HIDDEN**
+
+  By default, the symbols of classes and functions are hidden to avoid symbol clashes when loading
+  multiple shared libraries which use `sinqMotor`. In order to compile this library with exported
+  symbols, specifiy `-DHIDDEN= ` as a compiler flag (if using the given Makefile, this
+  needs to be added to the `USR_CFLAGS`).
+
+  Derived libraries can use the same mechanism via the macro `HIDDEN` (defined in `macros.h`):
+  ```
+  class HIDDEN turboPmacController : public sinqController
+  ```
+
 ### 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.
@@ -310,15 +325,3 @@ If your driver uses another driver as a static dependency via git submodule whic
 - `git submodule update --init --recursive`
 
 This will update sinqMotor to the version specified in the 1.0 commit of turboPmac.
-
-### Exporting symbols
-
-By default, the symbols of classes and functions are hidden to avoid symbol clashes when loading
-multiple shared libraries which use `sinqMotor`. In order to compile this library with exported
-symbols, specifiy `-DHIDDEN= ` as a compiler flag (if using the given Makefile, this
-needs to be added to the `USR_CFLAGS`).
-
-Derived libraries can use the same mechanism via the macro `HIDDEN` (defined in `msgPrintControl.h`):
-```
-class HIDDEN turboPmacController : public sinqController
-```

db/sinqMotor.db

@@ -41,6 +41,7 @@ record(motor,"$(INSTR)$(M)")
     field(PINI,"NO")
     field(DHLM, "$(DHLM=0)")
     field(DLLM, "$(DLLM=0)")
+    field(SPDB, "$(SPDB=0)")
     field(TWV,"1")
     field(RTRY,"0")
     field(RDBD, "$(RDBD=10e300)") # Suppress retries and overshoot stop commands
@@ -238,6 +239,27 @@ record(ao, "$(INSTR)$(M):PushDLLM2Field") {
     field(PINI, "NO")
 }
 
+# This record pair reads the parameter library value for "motorPositionDeadband"
+# and pushes it to the motor record field "SPDP". This can be used to the position
+# deadband from the hardware
+# The implementation strategy is taken from https://epics.anl.gov/tech-talk/2022/msg00464.php.
+# This record is coupled to the parameter library via motorPositionDeadband -> MOTOR_POSITION_DEADBAND.
+record(ai, "$(INSTR)$(M):SPDB_RBV")
+{
+    field(DTYP, "asynFloat64")
+    field(VAL, "$(SPDP=0)")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_POSITION_DEADBAND")
+    field(SCAN, "I/O Intr")
+    field(FLNK, "$(INSTR)$(M):PushSPDB2Field")
+    field(PINI, "NO")
+}
+record(ao, "$(INSTR)$(M):PushSPDB2Field") {
+    field(DOL,  "$(INSTR)$(M):SPDB_RBV NPP")
+    field(OUT,  "$(INSTR)$(M).SPDB")
+    field(OMSL, "closed_loop")
+    field(PINI, "NO")
+}
+
 # This record pair reads the parameter library value for "motorVeloFromDriver_"
 # and pushes it to the motor record field "VELO". This can be used to read the speed value
 # from the hardware and correspondingly update the motor record from the driver.

src/macros.h

@@ -0,0 +1,22 @@
+// Collection of macros used in sinqMotor and derived classes
+
+#ifndef macros_H
+#define macros_H
+
+/*
+The macro "HIDDEN" hides the symbol of the annotated class / function. This is
+useful to avoid symbol clashes when loading multiple shared libraries in a
+single IOC. To override the hiding, add `-DHIDDEN= ` to your compiler
+flags (in this case, the symbols will be exported with their default
+visibility).
+*/
+#ifndef HIDDEN
+#if defined(_WIN32) || defined(__CYGWIN__)
+#define HIDDEN
+#else
+#define HIDDEN __attribute__((visibility("hidden")))
+#endif
+#endif
+
+// macros_H
+#endif

src/msgPrintControl.h

@@ -6,25 +6,11 @@
 #define DefaultMaxRepetitions 4
 
 #include <asynDriver.h>
+#include <macros.h>
 #include <string.h>
 #include <string>
 #include <unordered_map>
 
-/*
-The macro "HIDDEN" hides the symbol of the annotated class / function. This is
-useful to avoid symbol clashes when loading multiple shared libraries in a
-single IOC. To override the hiding, add `-DHIDDEN= ` to your compiler
-flags (in this case, the symbols will be exported with their default
-visibility).
-*/
-#ifndef HIDDEN
-#if defined(_WIN32) || defined(__CYGWIN__)
-#define HIDDEN
-#else
-#define HIDDEN __attribute__((visibility("hidden")))
-#endif
-#endif
-
 /**
  * @brief Class to identify a message print location. See the docstring of
  * `msgPrintControl` on how to use this key.

src/sinqAxis.cpp

@@ -283,9 +283,12 @@ asynStatus sinqAxis::forcedPoll(bool *moving) {
         pSinqA_->wasMoving = *moving;
     }
 
-    // Check and update the watchdog
-    if (checkMovTimeoutWatchdog(*moving) != asynSuccess) {
-        return asynError;
+    // Check and update the watchdog as well as the general poll status IF the
+    // poll did not fail already.
+    if (poll_status == asynSuccess) {
+        if (checkMovTimeoutWatchdog(*moving) != asynSuccess) {
+            poll_status = asynError;
+        }
     }
 
     // According to the function documentation of asynMotorAxis::poll, this

src/sinqAxis.h

@@ -9,7 +9,7 @@ Stefan Mathis, November 2024
 #ifndef sinqAxis_H
 #define sinqAxis_H
 #include "asynMotorAxis.h"
-#include "msgPrintControl.h"
+#include <macros.h>
 #include <memory>
 #include <type_traits>
 

src/sinqController.cpp

@@ -92,6 +92,7 @@ struct sinqControllerImpl {
     int motorAcclFromDriver;
     int motorHighLimitFromDriver;
     int motorLowLimitFromDriver;
+    int motorPositionDeadband;
     int adaptivePolling;
     int encoderType;
 };
@@ -267,6 +268,17 @@ sinqController::sinqController(const char *portName,
         exit(-1);
     }
 
+    status = createParam("MOTOR_POSITION_DEADBAND", asynParamFloat64,
+                         &pSinqC_->motorPositionDeadband);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUser(), ASYN_TRACE_ERROR,
+                  "Controller \"%s\" => %s, line %d\nFATAL ERROR (creating a "
+                  "parameter failed with %s).\nTerminating IOC",
+                  portName, __PRETTY_FUNCTION__, __LINE__,
+                  stringifyAsynStatus(status));
+        exit(-1);
+    }
+
     status = createParam("MOTOR_ENABLE_MOV_WATCHDOG", asynParamInt32,
                          &pSinqC_->motorEnableMovWatchdog);
     if (status != asynSuccess) {
@@ -699,6 +711,9 @@ int sinqController::motorHighLimitFromDriver() {
 int sinqController::motorLowLimitFromDriver() {
     return pSinqC_->motorLowLimitFromDriver;
 }
+int sinqController::motorPositionDeadband() {
+    return pSinqC_->motorPositionDeadband;
+}
 int sinqController::adaptivePolling() { return pSinqC_->adaptivePolling; }
 int sinqController::encoderType() { return pSinqC_->encoderType; }
 

src/sinqController.h

@@ -12,6 +12,7 @@ Stefan Mathis, November 2024
 #include "asynMotorController.h"
 #include "msgPrintControl.h"
 #include <initHooks.h>
+#include <macros.h>
 #include <memory>
 
 #define motorMessageIsFromDriverString "MOTOR_MESSAGE_DRIVER"
@@ -314,6 +315,7 @@ class HIDDEN sinqController : public asynMotorController {
     int motorAcclFromDriver();
     int motorHighLimitFromDriver();
     int motorLowLimitFromDriver();
+    int motorPositionDeadband();
     int adaptivePolling();
     int encoderType();