Merge branch 'main' of https://git.psi.ch/sinq-epics-modules/sinqmotor

(https://forge.frm2.tum.de/review/c/frm2/nicos/nicos/+/35285)

Makefile

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

README.md

@@ -4,44 +4,197 @@
 
 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
+## User guide
+
+### Architecture of EPICS motor drivers at SINQ
+
+As mentioned before, the asyn-framework offers two base classes `asynMotorAxis` and `asynMotorController`. At SINQ, we extend those classes by two children classes `sinqAxis` and `sinqController` which are not complete drivers on their own, but serve as an additional framework for writing drivers. The concrete drivers are then created as separated libraries, an example is the pmacv3-driver: https://git.psi.ch/sinq-epics-modules/pmacv3
+
+The full inheritance chain for two different motor drivers "a" and "b" looks for a  like this:
+`asynController -> sinqController -> aController`
+`asynAxis -> sinqAxis -> aAxis`
+
+`asynController -> sinqController -> bController`
+`asynAxis -> sinqAxis -> bAxis`
+
+Those inheritance chains are created at runtime by loading shared libraries. Therefore, it is important to load compatible versions. At SINQ, the version management is SemVer-compatible (https://semver.org/lang/de/) in order to ensure compatibility. 
+For example, if driver "a" depends on version 2.1.0 of "sinqMotor", then it is safe to use version 2.5.3 since 2.5.3 is backwards compatible to 2.1.0. However, it is not allowed to use e.g. version 1.9.0 or 2.0.0 or 3.0.1 instead. For more details on SemVer, please refer to the official documentation.
+
+To find out which version of sinqMotor is needed by driver "a", refer to its Makefile (line `sinqMotor_VERSION=x.x.x`, where x.x.x is the minimum required version).
+
+### IOC startup script
+
+An EPICS IOC for motor control at SINQ is started by executing a script with the IOC shell. In its simplest form, an IOC for two controllers is a file looking like this:
+```
+#!/usr/local/bin/iocsh  
+
+# Load libraries needed for the IOC
+require sinqMotor, 1.0.0
+require pmacv3, 1.2.0
+
+# Define environment variables used later to parametrize the individual controllers
+epicsEnvSet("TOP","/ioc/sinq-ioc/sinqtest-ioc/")
+epicsEnvSet("INSTR","SQ:SINQTEST:")
+
+# Include other scripts for the controllers 1 and 2
+< mcu1.cmd 
+< mcu2.cmd 
+
+iocInit()
+```
+The first line is a so-called shebang which instructs Linux to execute the file with the executable located at the given path - the IOC shell in this case. The controller script "mcu1.cmd" looks like this:
+```
+# Define some needed parameters (they can be safely overwritten in e.g. mcu2.cmd)
+epicsEnvSet("NAME","mcu1")
+epicsEnvSet("ASYN_PORT","p$(NAME)")
+
+# Define the IP adress of the controller
+drvAsynIPPortConfigure("$(ASYN_PORT)","172.28.101.24:1025")
+
+# Create the controller object in EPICS. The function "pmacv3Controller" is 
+# provided by loading the shared library pmacv3 earlier.
+pmacv3Controller("$(NAME)","$(ASYN_PORT)",8,0.05,1,0.05);
+
+# Create four axes objects on slots 1, 2, 3 and 5 of the controller.
+pmacv3Axis("$(NAME)",1);
+pmacv3Axis("$(NAME)",2);
+pmacv3Axis("$(NAME)",3);
+pmacv3Axis("$(NAME)",5);
+
+# Create some general PVs of an asynRecord, substituting the macro P by concatenating INSTR and NAME and PORT by ASYN_PORT.
+dbLoadRecords("$(sinqMotor_DB)/asynRecord.db","P=$(INSTR)$(NAME),PORT=$(ASYN_PORT)")
+
+# Create PVs provided by the sinqMotor database template. This template is parametrized by the substitution file "mcu1.substitutions" (see below)
+epicsEnvSet("SINQDBPATH","$(sinqMotor_DB)/sinqMotor.db")
+dbLoadTemplate("$(TOP)/mcu1.substitutions", "INSTR=$(INSTR)$(NAME):,CONTROLLER=$(NAME)")
+
+# Create PVs specific for pmacv3. Again, we load a database template and parametrize it with the substitution file "mcu1.substitutions"
+epicsEnvSet("SINQDBPATH","$(pmacv3_DB)/pmacv3.db")
+dbLoadTemplate("$(TOP)/mcu1.substitutions", "INSTR=$(INSTR)$(NAME):,CONTROLLER=$(NAME)")
+```
+
+### Substitution file
+
+The substitution file is a table containing axis-specific information which is used to create the axis-specific PVs.
+To work with sinqMotor, "mcu1.substitutions" needs to look like this (the order of columns does not matter):
+```
+file "$(SINQDBPATH)"
+{
+pattern
+{ AXIS,      M, DESC,                              EGU, DIR, MRES,  MSGTEXTSIZE, ENABLEMOVWATCHDOG, LIMITSOFFSET, CANSETSPEED }
+{ 1,    "lin1", "Linear motor doing whatever",      mm, Pos, 0.001,         200,                 1,          1.0,           1 }
+{ 2,    "rot1", "First rotary motor",           degree, Neg, 0.001,         200,                 0,          1.0,           0 }
+{ 3,    "rot2", "Second rotary motor",          degree, Pos, 0.001,         200,                 0,          0.0,           1 }
+{ 5,    "rot3", "Surprise: Third rotary motor", degree, Pos, 0.001,         200,                 1,          2.0,           0 }
+}
+```
+The variable `SINQDBPATH` has been set in "mcu1.cmd" before calling `dbLoadTemplate`.
+
+#### Mandatory parameters
+
+- `AXIS`: Index of the axis, corresponds to the physical connection of the axis to the MCU.
+- `M`: The full PV name is created by concatenating the variables INSTR, NAME and M. For example, the PV of the first axis would be "SQ:SINQTEST:mcu1:lin1".
+- `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 description can be found in section [Motor record resolution MRES](#motor-record-resolution-mres).
+
+#### Optional parameters
+The default values for those parameters are given for the individual records in db/sinqMotor.db
+- `DESC`: Description of the motor. This field is just for documentation and is not needed for operating a motor.
+- `MSGTEXTSIZE`: Buffer size for the motor message record in characters
+- `ENABLEMOVWATCHDOG`: 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]. This parameter uses engineering units (EGU).
+- `CANSETSPEED`: If set to 1, the motor speed can be modified by the user.
+
+### Motor record resolution MRES
+
+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 of 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 .
+- 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.
+
+## Developer guide
+
+### 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.
+#### sinqController
 - `errMsgCouldNotParseResponse`: Write a standardized message if parsing a device response failed.
 - `paramLibAccessFailed`: Write a standardized message if accessing the parameter library failed.
+- `stringifyAsynStatus`: Convert the enum `asynStatus` into a human-readable string.
 
-### sinqAxis
+#### sinqAxis
 - `atFirstPoll`: This function is executed once before the first poll. If it returns anything but `asynSuccess`, it retries.
+- `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.
-- `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.
+- `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.
-- `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.
-- `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.
+- `setVeloFields`: Populates the motor record fields VELO (actual velocity), VBAS (minimum allowed velocity) and VMAX (maximum allowed velocity) from the driver.
+- `setAcclField`: Populates the motor record field ACCL from the driver.
 
-## Versioning
+### 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 X.X`. If the tag `X.X` is already used by another commit, git will show a corresponding error.
+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
+### 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/sinqMotor.db

@@ -1,8 +1,20 @@
-record(motor,"$(P)$(M)")
+# The main asyn motor record. Some fields are populated from the substitution 
+# files via macros:
+# - INSTR: Name of the instrument, e.g. "SQ:SINQTEST:"
+# - M: Name of the motor in EPICS, e.g. "lin1"
+# - DESC: Short description of the motor. If not given, this is equal to M
+# - DIR: This value is usually set to "Pos". If the motor axis direction 
+# should be inverted, this value can be set to "Neg"
+# - CONTROLLER: Name of the motor controller, e.g. "mcu1"
+# - AXIS: Number of the axis, e.g. "1"
+# - MRES: Motor record resolution. See the README.md for a detailed discussion
+# - EGU: Engineering units. In case of a rotary axis, this is "degree", in 
+# case of a linear axis this is "mm".
+record(motor,"$(INSTR)$(M)")
 {
-    field(DESC,"$(DESC)")
+    field(DESC,"$(DESC=$(M))")
     field(DTYP,"asynMotor")
-    field(DIR,"$(DIR)")
+    field(DIR,"$(DIR=Pos)")
     field(OUT,"@asyn($(CONTROLLER),$(AXIS))")
     field(MRES,"$(MRES)")
     field(EGU,"$(EGU)")
@@ -12,102 +24,216 @@ record(motor,"$(P)$(M)")
     field(RTRY, "0")
 }
 
-# The message text
-record(waveform, "$(P)$(M)-MsgTxt") {
+# This record forwards the motor record resolution MRES to the parameter library
+# entry "MOTOR_REC_RESOLUTION" (solution from https://epics.anl.gov/tech-talk/2020/msg00378.php)
+# The value of MRES is needed inside the driver for various calculations (e.g.
+# for calculating the estimated time of arrival inside the watchdog).
+record(ao,"$(INSTR)$(M):RecResolution") {
+    field(DESC, "$(M) resolution")
+    field(DOL,  "$(INSTR)$(M).MRES CP MS")
+    field(OMSL, "closed_loop")
+    field(DTYP, "asynFloat64")
+    field(OUT,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_REC_RESOLUTION")
+}
+
+# This record contains messages from the driver (usually error messages).
+# The macro MSGTEXTSIZE can be used to set the maximum length of the message.
+# if not provided, a default value of 200 is used.
+# This record is coupled to the parameter library via motorMessageText_ -> MOTOR_MESSAGE_TEXT.
+record(waveform, "$(INSTR)$(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(NELM, "$(MSGTEXTSIZE=200)") # Should be the same as MAXBUF in the driver code
     field(SCAN, "I/O Intr")
 }
 
-# Encoder type
-record(waveform, "$(P)$(M):Encoder_Type") {
+# User-writable switch which disables the motor for an input of zero and enables
+# it otherwise. Some motors can't be disabled in certain states (e.g. during 
+# movement). This behaviour has to be implemented inside the driver.
+# This record is coupled to the parameter library via motorEnable_ -> MOTOR_ENABLE.
+record(longout, "$(INSTR)$(M):Enable") {
+    field(DTYP, "asynInt32")
+    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) MOTOR_ENABLE")
+    field(PINI, "NO")
+}
+
+# Readback value which returns 1 if the motor is disabled and 0 otherwise.
+# This record is coupled to the parameter library via motorEnableRBV_ -> MOTOR_ENABLE_RBV.
+record(longin, "$(INSTR)$(M):EnableRBV") {
+    field(DTYP, "asynInt32")
+    field(INP, "@asyn($(CONTROLLER),$(AXIS),1) MOTOR_ENABLE_RBV")
+    field(PINI, "NO")
+    field(SCAN, "I/O Intr")
+}
+
+# Some (older) motors cannot be disabled. This property has to be specified in
+# the driver by setting the corresponding parameter library entry motorCanDisable_
+# to 0 (its default value is 1).
+# This record is coupled to the parameter library via motorCanDisable_ -> MOTOR_CAN_DISABLE.
+record(longin, "$(INSTR)$(M):CanDisable") {
+    field(DTYP, "asynInt32")
+    field(INP, "@asyn($(CONTROLLER),$(AXIS),1) MOTOR_CAN_DISABLE")
+    field(PINI, "NO")
+    field(SCAN, "I/O Intr")
+}
+
+# For some motors, the user might be allowed to adjust the speed within the 
+# limits specified in the motor record as VBAS and VMAX. This functionality  can
+# be enabled by setting CANSETSPEED to 1. It is disabled by default.
+# This record is coupled to the parameter library via motorCanSetSpeed_ -> MOTOR_CAN_SET_SPEED.
+record(longout, "$(INSTR)$(M):CanSetSpeed") {
+    field(DTYP, "asynInt32")
+    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) MOTOR_CAN_SET_SPEED")
+    field(PINI, "YES")
+    field(ASG, "READONLY") # Field is initialized during IOC startup
+    field(VAL, "$(CANSETSPEED=0)")
+}
+
+# The timeout mechanism for movements can be enabled / disabled by setting 
+# this PV to 1 / 0.
+# This record is coupled to the parameter library via motorEnableMovWatchdog -> MOTOR_ENABLE_MOV_WATCHDOG.
+record(longout, "$(INSTR)$(M):EnableMovWatchdog") {
+    field(DTYP, "asynInt32")
+    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) MOTOR_ENABLE_MOV_WATCHDOG")
+    field(PINI, "YES")
+    field(VAL, "$(ENABLEMOVWATCHDOG=0)")
+}
+
+# For modern controllers, the high and low limits of the axis are read out 
+# directly from the hardware. However, since the axis might slightly
+# "overshoot" when moving to a position next to the limits, the hardware might
+# go into a "limits hit" error state. To prevent this, this value allows adding
+# a small offset in EGU, which is  subtracted from the high limit and added to the
+# low limit.
+# This record is coupled to the parameter library via motorLimitsOffset_ -> MOTOR_LIMITS_OFFSET.
+record(ao, "$(INSTR)$(M):LimitsOffset") {
+    field(DTYP, "asynFloat64")
+    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) MOTOR_LIMITS_OFFSET")
+    field(PINI, "YES")
+    field(ASG, "READONLY") # Field is initialized during IOC startup
+    field(VAL, "$(LIMITSOFFSET=0)")
+}
+
+# This record pair reads the parameter library value for "motorHighLimitFromDriver_"
+# and pushes it to the motor record field "DHLM". This can be used to read limits
+# from the hardware and correspondingly update the motor record from the driver.
+# The implementation strategy is taken from https://epics.anl.gov/tech-talk/2022/msg00464.php.
+# This record is coupled to the parameter library via motorHighLimitFromDriver_ -> MOTOR_HIGH_LIMIT_FROM_DRIVER.
+record(ai, "$(INSTR)$(M):DHLM_RBV")
+{
+    field(DTYP, "asynFloat64")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_HIGH_LIMIT_FROM_DRIVER")
+    field(SCAN, "I/O Intr")
+    field(FLNK, "$(INSTR)$(M):PushDHLM2Field")
+}
+record(ao, "$(INSTR)$(M):PushDHLM2Field") {
+    field(DOL,  "$(INSTR)$(M):DHLM_RBV CP")
+    field(OUT,  "$(INSTR)$(M).DHLM")
+    field(OMSL, "closed_loop")
+}
+
+# This record pair reads the parameter library value for "motorLowLimitFromDriver_"
+# and pushes it to the motor record field "DLLM". This can be used to read limits
+# from the hardware and correspondingly update the motor record from the driver.
+# The implementation strategy is taken from https://epics.anl.gov/tech-talk/2022/msg00464.php.
+# This record is coupled to the parameter library via motorLowLimitFromDriver_ -> MOTOR_LOW_LIMIT_FROM_DRIVER.
+record(ai, "$(INSTR)$(M):DLLM_RBV")
+{
+    field(DTYP, "asynFloat64")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_LOW_LIMIT_FROM_DRIVER")
+    field(SCAN, "I/O Intr")
+    field(FLNK, "$(INSTR)$(M):PushDLLM2Field")
+}
+record(ao, "$(INSTR)$(M):PushDLLM2Field") {
+    field(DOL,  "$(INSTR)$(M):DLLM_RBV CP")
+    field(OUT,  "$(INSTR)$(M).DLLM")
+    field(OMSL, "closed_loop")
+}
+
+# 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.
+# The implementation strategy is taken from https://epics.anl.gov/tech-talk/2022/msg00464.php.
+# This record is coupled to the parameter library via motorVeloFromDriver_ -> MOTOR_VELO_FROM_DRIVER.
+record(ai, "$(INSTR)$(M):VELO_RBV")
+{
+    field(DTYP, "asynFloat64")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_VELO_FROM_DRIVER")
+    field(SCAN, "I/O Intr")
+    field(FLNK, "$(INSTR)$(M):PushVELO2Field")
+}
+record(ao, "$(INSTR)$(M):PushVELO2Field") {
+    field(DOL,  "$(INSTR)$(M):VELO_RBV CP")
+    field(OUT,  "$(INSTR)$(M).VELO")
+    field(OMSL, "closed_loop")
+}
+
+# This record pair reads the parameter library value for "motorVbasFromDriver_"
+# and pushes it to the motor record field "VBAS". This can be used to read the lower speed limit
+# from the hardware and correspondingly update the motor record from the driver.
+# The implementation strategy is taken from https://epics.anl.gov/tech-talk/2022/msg00464.php.
+# This record is coupled to the parameter library via motorVbasFromDriver_ -> MOTOR_VBAS_FROM_DRIVER.
+record(ai, "$(INSTR)$(M):VBAS_RBV")
+{
+    field(DTYP, "asynFloat64")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_VBAS_FROM_DRIVER")
+    field(SCAN, "I/O Intr")
+    field(FLNK, "$(INSTR)$(M):PushVBAS2Field")
+}
+record(ao, "$(INSTR)$(M):PushVBAS2Field") {
+    field(DOL,  "$(INSTR)$(M):VBAS_RBV CP")
+    field(OUT,  "$(INSTR)$(M).VBAS")
+    field(OMSL, "closed_loop")
+}
+
+# This record pair reads the parameter library value for "motorVmaxFromDriver_"
+# and pushes it to the motor record field "VMAX". This can be used to read the upper speed limit
+# from the hardware and correspondingly update the motor record from the driver.
+# The implementation strategy is taken from https://epics.anl.gov/tech-talk/2022/msg00464.php.
+# This record is coupled to the parameter library via motorVmaxFromDriver_ -> MOTOR_VMAX_FROM_DRIVER.
+record(ai, "$(INSTR)$(M):VMAX_RBV")
+{
+    field(DTYP, "asynFloat64")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_VMAX_FROM_DRIVER")
+    field(SCAN, "I/O Intr")
+    field(FLNK, "$(INSTR)$(M):PushVMAX2Field")
+}
+record(ao, "$(INSTR)$(M):PushVMAX2Field") {
+    field(DOL,  "$(INSTR)$(M):VMAX_RBV CP")
+    field(OUT,  "$(INSTR)$(M).VMAX")
+    field(OMSL, "closed_loop")
+}
+
+# This record pair reads the parameter library value for "motorAcclFromDriver_"
+# and pushes it to the motor record field "ACCL". This can be used to read the acceleration
+# from the hardware and correspondingly update the motor record from the driver.
+# The implementation strategy is taken from https://epics.anl.gov/tech-talk/2022/msg00464.php.
+# This record is coupled to the parameter library via motorAcclFromDriver_ -> MOTOR_ACCL_FROM_DRIVER.
+record(ai, "$(INSTR)$(M):ACCL_RBV")
+{
+    field(DTYP, "asynFloat64")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_ACCL_FROM_DRIVER")
+    field(SCAN, "I/O Intr")
+    field(FLNK, "$(INSTR)$(M):PushACCL2Field")
+}
+record(ao, "$(INSTR)$(M):PushACCL2Field") {
+    field(DOL,  "$(INSTR)$(M):ACCL_RBV CP")
+    field(OUT,  "$(INSTR)$(M).ACCL")
+    field(OMSL, "closed_loop")
+}
+
+# Read out the encoder type in human-readable form. The output numbers are ASCII
+# codes and can be converted to chars in order to get the encoder type.
+# EPICS prepends the ASCII code with 80
+# The following encoder types are defined:
+# - "Absolute encoder" (array 80 65 98 115 111 108 117 116 101 32 101 110 99 111 100 101 114)
+# - "Incremental encoder" (array 80 73 110 99 114 101 109 101 110 116 97 108 32 101 110 99 111 100 101 114)
+# This record is coupled to the parameter library via encoderType -> ENCODER_TYPE.
+record(waveform, "$(INSTR)$(M):EncoderType") {
     field(DTYP, "asynOctetRead")
     field(INP, "@asyn($(CONTROLLER),$(AXIS),1) ENCODER_TYPE")
     field(FTVL, "CHAR")
     field(NELM, "80")
     field(SCAN, "I/O Intr")
 }
-
-# enable axis
-record(longout, "$(P)$(M):Enable") {
-    field(DTYP, "asynInt32")
-    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) ENABLE_AXIS")
-    field(PINI, "NO")
-}
-
-# enable axis
-record(longin, "$(P)$(M):Enable_RBV") {
-    field(DTYP, "asynInt32")
-    field(INP, "@asyn($(CONTROLLER),$(AXIS),1) AXIS_ENABLED")
-    field(PINI, "YES")
-}
-
-# reread encoder
-record(longout, "$(P)$(M):Reread_Encoder") {
-    field(DTYP, "asynInt32")
-    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) REREAD_ENCODER_POSITION")
-    field(PINI, "NO")
-}
-
-# reread encoder
-record(longin, "$(P)$(M):Reread_Encoder_RBV") {
-    field(DTYP, "asynInt32")
-    field(INP, "@asyn($(CONTROLLER),$(AXIS),1) REREAD_ENCODER_POSITION_RBV")
-    field(PINI, "YES")
-}
-
-# reread encoder
-record(longout, "$(P)$(M):Read_Config") {
-    field(DTYP, "asynInt32")
-    field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) READ_CONFIG")
-    field(PINI, "NO")
-}
-
-# 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")
-}
-
-# ===================================================================
-# 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

@@ -9,9 +9,62 @@ sinqAxis::sinqAxis(class sinqController *pC, int axisNo)
     initial_poll_ = true;
     watchdogMovActive_ = false;
     init_poll_counter_ = 0;
+    scaleMovTimeout_ = 2.0;
+    offsetMovTimeout_ = 30;
 }
 
-asynStatus sinqAxis::atFirstPoll() { return asynSuccess; }
+asynStatus sinqAxis::atFirstPoll() {
+    asynStatus status = asynSuccess;
+    int variableSpeed = 0;
+
+    // Motor is assumed to be enabled
+    status = pC_->setIntegerParam(axisNo_, pC_->motorEnableRBV_, 1);
+    if (status != asynSuccess) {
+        return pC_->paramLibAccessFailed(status, "motorEnableRBV_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    // By default, motors cannot be disabled
+    status = pC_->setIntegerParam(axisNo_, pC_->motorCanDisable_, 0);
+    if (status != asynSuccess) {
+        return pC_->paramLibAccessFailed(status, "motorCanDisable_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    status =
+        pC_->getIntegerParam(axisNo_, pC_->motorCanSetSpeed_, &variableSpeed);
+    if (status != asynSuccess) {
+        return pC_->paramLibAccessFailed(status, "motorCanSetSpeed_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    if (variableSpeed == 1) {
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVbasFromDriver_, 0.0);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVbasFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVmaxFromDriver_,
+                                     1000000000.0);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVmaxFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+    } else {
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVbasFromDriver_, 0.0);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVbasFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVmaxFromDriver_, 0.0);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVmaxFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+    }
+
+    return status;
+}
 
 asynStatus sinqAxis::poll(bool *moving) {
     // Local variable declaration
@@ -47,27 +100,58 @@ asynStatus sinqAxis::poll(bool *moving) {
         }
     }
 
+    /*
+    At the beginning of the poll, it is assumed that the axis has no status
+    problems and therefore all error indicators are reset. This does not affect
+    the PVs until callParamCallbacks has been called!
+
+    The motorStatusProblem_ field changes the motor record fields SEVR and STAT.
+    */
+    pl_status = setIntegerParam(pC_->motorStatusProblem_, false);
+    if (pl_status != asynSuccess) {
+        pC_->paramLibAccessFailed(pl_status, "motorStatusProblem_",
+                                  __PRETTY_FUNCTION__, __LINE__);
+    }
+    pl_status = setIntegerParam(pC_->motorStatusCommsError_, false);
+    if (pl_status != asynSuccess) {
+        pC_->paramLibAccessFailed(pl_status, "motorStatusCommsError_",
+                                  __PRETTY_FUNCTION__, __LINE__);
+    }
+    pl_status = setStringParam(pC_->motorMessageText_, "");
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "motorMessageText_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
     // The poll function is just a wrapper around doPoll and
     // handles mainly the callParamCallbacks() function. This wrapper is used
     // to make sure callParamCallbacks() is called in case of a premature
     // return.
     poll_status = doPoll(moving);
 
-    // If the poll status is ok, reset the error indicators in the parameter
-    // library
-    if (poll_status == asynSuccess) {
-        pl_status = setIntegerParam(pC_->motorStatusProblem_, false);
+    // The poll did not succeed: Something went wrong and the motor has a status
+    // problem.
+    if (poll_status != asynSuccess) {
+        pl_status = setIntegerParam(pC_->motorStatusProblem_, true);
         if (pl_status != asynSuccess) {
             pC_->paramLibAccessFailed(pl_status, "motorStatusProblem_",
                                       __PRETTY_FUNCTION__, __LINE__);
         }
-        pl_status = setIntegerParam(pC_->motorStatusCommsError_, false);
-        if (pl_status != asynSuccess) {
-            pC_->paramLibAccessFailed(pl_status, "motorStatusCommsError_",
-                                      __PRETTY_FUNCTION__, __LINE__);
-        }
+    }
 
-        pl_status = setStringParam(pC_->motorMessageText_, "");
+    // Check and update the watchdog
+    if (checkMovTimeoutWatchdog(*moving) != asynSuccess) {
+        return asynError;
+    }
+
+    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__);
@@ -186,66 +270,229 @@ asynStatus sinqAxis::doHome(double minVelocity, double maxVelocity,
     return asynSuccess;
 }
 
+asynStatus sinqAxis::enable(bool on) { return asynSuccess; }
+
+asynStatus sinqAxis::setVeloFields(double velo, double vbas, double vmax) {
+    asynStatus status = asynSuccess;
+    int variableSpeed = 0;
+
+    // Can the speed of the motor be varied?
+    status =
+        pC_->getIntegerParam(axisNo_, pC_->motorCanSetSpeed_, &variableSpeed);
+    if (status != asynSuccess) {
+        return pC_->paramLibAccessFailed(status, "motorCanSetSpeed_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+    if (variableSpeed == 1) {
+
+        // Check the inputs and create corresponding error messages
+        if (vbas > vmax) {
+            asynPrint(pC_->lowLevelPortUser_, ASYN_TRACE_ERROR,
+                      "%s => line %d:\nLower speed limit vbas=%lf must not be "
+                      "smaller than upper limit vmax=%lf.\n",
+                      __PRETTY_FUNCTION__, __LINE__, vbas, vmax);
+
+            status = setStringParam(
+                pC_->motorMessageText_,
+                "Lower speed limit must not be smaller than upper speed limit");
+            if (status != asynSuccess) {
+                return pC_->paramLibAccessFailed(status, "motorMessageText_",
+                                                 __PRETTY_FUNCTION__, __LINE__);
+            }
+            return asynError;
+        }
+        if (velo < vbas || velo > vmax) {
+            asynPrint(pC_->lowLevelPortUser_, ASYN_TRACE_ERROR,
+                      "%s => line %d:\nActual speed velo=%lf must be between "
+                      "lower limit vbas=%lf and upper limit vmx=%lf.\n",
+                      __PRETTY_FUNCTION__, __LINE__, velo, vbas, vmax);
+
+            status = setStringParam(pC_->motorMessageText_,
+                                    "Speed is not inside limits");
+            if (status != asynSuccess) {
+                return pC_->paramLibAccessFailed(status, "motorMessageText_",
+                                                 __PRETTY_FUNCTION__, __LINE__);
+            }
+            return asynError;
+        }
+
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVbasFromDriver_, vbas);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVbasFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVeloFromDriver_, velo);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVeloFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVmaxFromDriver_, vmax);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVmaxFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+    } else {
+        // Set minimum and maximum speed equal to the set speed
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVbasFromDriver_, velo);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVbasFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVeloFromDriver_, velo);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVeloFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+
+        status = pC_->setDoubleParam(axisNo_, pC_->motorVmaxFromDriver_, velo);
+        if (status != asynSuccess) {
+            return pC_->paramLibAccessFailed(status, "motorVmaxFromDriver_",
+                                             __PRETTY_FUNCTION__, __LINE__);
+        }
+    }
+    return status;
+}
+
+asynStatus sinqAxis::setAcclField(double accl) {
+
+    if (accl <= 0.0) {
+        return asynError;
+    }
+
+    asynStatus status =
+        pC_->setDoubleParam(axisNo_, pC_->motorAcclFromDriver_, accl);
+    if (status != asynSuccess) {
+        return pC_->paramLibAccessFailed(status, "motorAcclFromDriver_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+    return status;
+}
+
 asynStatus sinqAxis::setWatchdogEnabled(bool enable) {
-    watchdogEnabled_ = enable;
-    return asynSuccess;
+    return pC_->setIntegerParam(axisNo_, pC_->motorEnableMovWatchdog_, enable);
 }
 
 asynStatus sinqAxis::startMovTimeoutWatchdog() {
-    if (watchdogEnabled_) {
+    asynStatus pl_status;
+    int enableMovWatchdog = 0;
+
+    pl_status = pC_->getIntegerParam(axisNo_, pC_->motorEnableMovWatchdog_,
+                                     &enableMovWatchdog);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "motorEnableMovWatchdog_",
+                                         __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 motorVelBase = 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;
-        asynStatus pl_status;
 
         // Activate the watchdog
         watchdogMovActive_ = true;
 
-        pl_status =
-            pC_->getDoubleParam(axisNo_, pC_->motorPosition_, &motorPosition);
+        /*
+        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__);
         }
 
-        pl_status =
-            pC_->getDoubleParam(axisNo_, pC_->motorVelBase_, &motorVelBase);
-        // Only calculate timeContSpeed if the motorVelBase_ has been populated
+        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 && motorVelBase > 0.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_,
-                                            &motorTargetPosition);
+                                            &motorTargetPositionRec);
+            motorTargetPosition = motorTargetPositionRec * motorRecResolution;
             if (pl_status == asynSuccess) {
+
                 timeContSpeed =
                     std::ceil(std::fabs(motorTargetPosition - motorPosition) /
-                              motorVelBase);
+                              motorVelocity);
             }
         }
 
-        pl_status = pC_->getDoubleParam(axisNo_, pC_->motorAccel_, &motorAccel);
-        if (pl_status == asynSuccess && motorVelBase > 0.0 &&
-            motorAccel > 0.0) {
-            timeAccel = 2 * std::ceil(motorVelBase / motorAccel);
+        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;
 
-    // Not moving or watchdog not active
-    if (!watchdogEnabled_ || !moving) {
+    pl_status = pC_->getIntegerParam(axisNo_, pC_->motorEnableMovWatchdog_,
+                                     &enableMovWatchdog);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "motorEnableMovWatchdog_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    // Not moving or watchdog not active / enabled
+    if (enableMovWatchdog == 0 || !moving || !watchdogMovActive_) {
         watchdogMovActive_ = false;
         return asynSuccess;
     }
@@ -255,8 +502,9 @@ asynStatus sinqAxis::checkMovTimeoutWatchdog(bool moving) {
         // 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_);
+                  "%ld (current time is %ld).\n",
+                  __PRETTY_FUNCTION__, __LINE__, axisNo_, expectedArrivalTime_,
+                  time(NULL));
 
         pl_status = setStringParam(
             pC_->motorMessageText_,
@@ -272,7 +520,8 @@ asynStatus sinqAxis::checkMovTimeoutWatchdog(bool moving) {
                                       __PRETTY_FUNCTION__, __LINE__);
         }
 
-        return asynError;
+        // Even if the movement timed out, the rest of the poll should continue.
+        return asynSuccess;
     }
     return asynSuccess;
 }

src/sinqAxis.h

@@ -42,6 +42,8 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
     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 motorEnableRBV_ by calling isEnabled.
     - Run `callParamCallbacks`
     - Return the status of `doPoll`
      *
@@ -141,6 +143,53 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
     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 Populate the motor record fields VELO, VBAS and VMAX
+     *
+     * Populates the speed fields of the motor record. If the param lib
+     * entry motorCanSetSpeed_ (connected to the PV x:VariableSpeed) is set to
+     * 1, VBAS and VMAX are set to min and max respectively. Otherwise, they are
+     * set to val. Additionally, the speed itself is set to velo.
+     *
+     * The units of the inputs are engineering units (EGU) per second (e.g. mm/s
+     * if the EGU is mm).
+     *
+     * If the given configuration is invalid (min > max, velo < min, velo > max)
+     * and the motor is configured as a variable speed motor (param lib entry
+     * motorCanSetSpeed_ is 1), this function returns an asynError.
+     *
+     * @param velo                Actual velocity (EGU / s)
+     * @param vbas                Minimum allowed velocity (EGU / s)
+     * @param velo                Maximum allowed velocity (EGU / s)
+     *
+     * @return asynStatus
+     */
+    virtual asynStatus setVeloFields(double velo, double vbas, double vmax);
+
+    /**
+     * @brief Populate the ACCL field of the motor record
+     *
+     * Populates the acceleration field of the motor record with the given
+     * value. If accl is not positive, this function does not set the value and
+     * returns an asynError.
+     *
+     * The unit of the input is engineering units (EGU) per second squared (e.g.
+     * mm/s^2 if the EGU is mm).
+     *
+     * @param accl                Actual acceleration (EGU / s^2)
+     * @return asynStatus
+     */
+    virtual asynStatus setAcclField(double accl);
+
     /**
      * @brief Start the watchdog for the movement, if the watchdog is not
     disabled. See the documentation of checkMovTimeoutWatchdog for more details.
@@ -235,7 +284,6 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
     time_t expectedArrivalTime_;
     time_t offsetMovTimeout_;
     double scaleMovTimeout_;
-    bool watchdogEnabled_;
     bool watchdogMovActive_;
 
   private:

src/sinqController.cpp

@@ -16,11 +16,16 @@ sinqController::sinqController(const char *portName,
           // added for better readability of the configuration.
           numAxes + 1,
           /*
-          2 Parameters are added in sinqController:
+          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 + numExtraParams + 2,
+          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,
@@ -76,6 +81,138 @@ sinqController::sinqController(const char *portName,
         exit(-1);
     }
 
+    status = createParam("MOTOR_ENABLE", asynParamInt32, &motorEnable_);
+    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_ENABLE_RBV", asynParamInt32, &motorEnableRBV_);
+    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_CAN_DISABLE", asynParamInt32, &motorCanDisable_);
+    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_CAN_SET_SPEED", asynParamInt32, &motorCanSetSpeed_);
+    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_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);
+    }
+
+    /*
+    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("MOTOR_ENABLE_MOV_WATCHDOG", asynParamInt32,
+                         &motorEnableMovWatchdog_);
+    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_VELO_FROM_DRIVER", asynParamFloat64,
+                         &motorVeloFromDriver_);
+    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_VBAS_FROM_DRIVER", asynParamFloat64,
+                         &motorVbasFromDriver_);
+    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_VMAX_FROM_DRIVER", asynParamFloat64,
+                         &motorVmaxFromDriver_);
+    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_ACCL_FROM_DRIVER", asynParamFloat64,
+                         &motorAcclFromDriver_);
+    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("ENCODER_TYPE", asynParamOctet, &encoderType_);
+    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) {
@@ -95,20 +232,82 @@ sinqController::~sinqController(void) {
     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 == motorEnable_) {
+        return axis->enable(value != 0);
+    } else {
+        return asynMotorController::writeInt32(pasynUser, value);
+    }
+}
+
+asynStatus sinqController::readInt32(asynUser *pasynUser, epicsInt32 *value) {
+    if (pasynUser->reason == motorEnableRBV_) {
+        // Read out the parameter library
+        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;
+        }
+        return getIntegerParam(axis->axisNo_, motorEnableRBV_, value);
+    } else if (pasynUser->reason == motorCanDisable_) {
+        // Check if the motor can be disabled
+        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;
+        }
+        return getIntegerParam(axis->axisNo_, motorCanDisable_, value);
+    } else {
+        return asynMotorController::readInt32(pasynUser, value);
+    }
+}
+
 asynStatus sinqController::errMsgCouldNotParseResponse(const char *command,
                                                        const char *response,
-                                                       int axisNo_,
+                                                       int axisNo,
                                                        const char *functionName,
                                                        int lineNumber) {
+    asynStatus pl_status = asynSuccess;
+
     asynPrint(lowLevelPortUser_, ASYN_TRACE_ERROR,
-              "%s => line %d:\n Could not interpret response %s for "
+              "%s => line %d:\nCould not interpret response %s for "
               "command %s.\n",
               functionName, lineNumber, response, command);
 
-    setStringParam(
+    pl_status = setStringParam(
         motorMessageText_,
-        "Could not interpret MCU response. Please call the software support");
-    setIntegerParam(motorStatusCommsError_, 1);
+        "Could not interpret MCU response. Please call the support");
+    if (pl_status != asynSuccess) {
+        return paramLibAccessFailed(pl_status, "motorMessageText_",
+                                    __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    pl_status = setIntegerParam(motorStatusCommsError_, 1);
+    if (pl_status != asynSuccess) {
+        return paramLibAccessFailed(pl_status, "motorStatusCommsError_",
+                                    __PRETTY_FUNCTION__, __LINE__);
+    }
+
     return asynError;
 }
 
@@ -118,14 +317,15 @@ asynStatus sinqController::paramLibAccessFailed(asynStatus status,
                                                 int lineNumber) {
 
     if (status != asynSuccess) {
-        // Log the error message and try to propagate it
+        // Log the error message and try to propagate it. If propagating fails,
+        // there is nothing we can do here anyway.
         asynPrint(lowLevelPortUser_, ASYN_TRACE_ERROR,
                   "%s => line %d:\n Accessing the parameter library failed for "
-                  "parameter %s.\n",
-                  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;

src/sinqController.h

@@ -10,6 +10,9 @@ Stefan Mathis, November 2024
 
 #define motorMessageIsFromDriverString "MOTOR_MESSAGE_DRIVER"
 #define motorMessageTextString "MOTOR_MESSAGE_TEXT"
+#define IncrementalEncoder "incremental"
+#define AbsoluteEncoder "absolute"
+#define NoEncoder "none"
 
 class epicsShareClass sinqController : public asynMotorController {
   public:
@@ -46,7 +49,28 @@ class epicsShareClass sinqController : public asynMotorController {
      */
     virtual ~sinqController(void);
 
-    friend class sinqAxis;
+    /**
+     * @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
+     */
+    virtual 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.
@@ -86,7 +110,7 @@ class epicsShareClass sinqController : public asynMotorController {
      * @return asynStatus         Returns asynError.
      */
     asynStatus errMsgCouldNotParseResponse(const char *command,
-                                           const char *response, int axisNo_,
+                                           const char *response, int axisNo,
                                            const char *functionName,
                                            int lineNumber);
 
@@ -98,10 +122,37 @@ class epicsShareClass sinqController : public asynMotorController {
      */
     const char *stringifyAsynStatus(asynStatus status);
 
+    friend class sinqAxis;
+
   protected:
     asynUser *lowLevelPortUser_;
+
+#define FIRST_SINQMOTOR_PARAM motorMessageText_
     int motorMessageText_;
     int motorTargetPosition_;
+    int motorEnable_;
+    int motorEnableRBV_;
+    int motorCanDisable_;
+    int motorEnableMovWatchdog_;
+    int motorCanSetSpeed_;
+    int motorLimitsOffset_;
+    /*
+    These parameters are here to write values from the hardware 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.
+    */
+    int motorVeloFromDriver_;
+    int motorVbasFromDriver_;
+    int motorVmaxFromDriver_;
+    int motorAcclFromDriver_;
+    int motorHighLimitFromDriver_;
+    int motorLowLimitFromDriver_;
+    int encoderType_;
+#define LAST_SINQMOTOR_PARAM encoderType_
 };
+#define NUM_SINQMOTOR_DRIVER_PARAMS                                            \
+    (&LAST_SINQMOTOR_PARAM - &FIRST_SINQMOTOR_PARAM + 1)
 
 #endif