Included the possibility to vary the motor speed.

some records into sinqMotor

Makefile

@@ -11,7 +11,7 @@ REQUIRED+=asynMotor
 REQUIRED+=sinqMotor
 
 # Specify the version of sinqMotor we want to build against
-sinqMotor_VERSION=0.3.0
+sinqMotor_VERSION=0.4.0
 
 # These headers allow to depend on this library for derived drivers.
 HEADERS += src/pmacv3Axis.h

README.md

@@ -4,50 +4,39 @@
 
 This is a driver for the pmacV3 motion controller with the SINQ communication protocol. It is based on the sinqMotor shared library (https://git.psi.ch/sinq-epics-modules/sinqmotor). The header files contain detailed documentation for all public functions. The headers themselves are exported when building the library to allow other drivers to depend on this one.
 
-## Usage in IOC shell
+## User guide
+
+This driver is a standard sinqMotor-derived driver and does not need any specific configuration. For the general configuration, please see https://git.psi.ch/sinq-epics-modules/sinqmotor/-/blob/main/README.md.
+
+## Developer guide
+
+### Usage in IOC shell
 
 pmacv3 exposes the following IOC shell functions (all in pmacv3Controller.cpp):
 - `pmacv3Controller`: Create a new controller object.
 - `pmacv3Axis`: Create a new axis object.
-The function arguments are documented directly within the source code or are available from the help function of the IOC shell.
-
-## Database
-
-The pmacV3 module provides additional PVs in the database template  db/pmacv3.db. It can be parametrized with the `dbLoadTemplate` function from the IOC shell:
-
+These functions are parametrized as follows:
 ```
-require sinqMotor, y.y.y # The sinqMotor module is needed for the pmacv3 module. The version y.y.y is defined in the Makefile (line sinqMotor_VERSION=x.x.x)
-require pmacv3, x.x.x # This is the three-digit version number of the pmacv3 module
-dbLoadTemplate "motor.substitutions"
+pmacv3Controller(
+    "$(NAME)", # Name of the MCU, e.g. mcu1. This parameter should be provided by an environment variable.
+    "$(ASYN_PORT)", # IP-Port of the MCU. This parameter should be provided by an environment variable.
+    8, # Maximum number of axes
+    0.05, # Busy poll period in seconds
+    1, # Idle poll period in seconds
+    0.05 # Communication timeout in seconds
+    );
+```
+```
+pmacv3Axis(
+    "$(NAME)", # Name of the associated MCU, e.g. mcu1. This parameter should be provided by an environment variable.
+    1 # Index of the axis.
+    );
 ```
 
-The substitutions file can be concatenated with that of sinqMotor:
-```
-file "$(sinqMotor_DB)/sinqMotor.db"
-{
-pattern
-...
-}
-
-file "$(pmacv3_DB)/pmacv3.db"
-{
-pattern
-{ AXIS,     M}
-{ 1,   "lin1"}
-{ 2,   "rot1"}
-}
-```
-The sinqMotor pattern "..." is documented in https://git.psi.ch/sinq-epics-modules/sinqmotor/-/blob/main/README.md.
-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
-
-The axis name should correspond to that of the sinqMotor pattern with the same respective index.
-
-## Versioning
+### Versioning
 
 Please see the documentation for the module sinqMotor: https://git.psi.ch/sinq-epics-modules/sinqmotor/-/blob/main/README.md.
 
-## How to build it
+### How to build it
 
 Please see the documentation for the module sinqMotor: https://git.psi.ch/sinq-epics-modules/sinqmotor/-/blob/main/README.md.

db/pmacv3.db

@@ -1,5 +1,7 @@
-# Encoder type
-record(waveform, "$(P)$(M):Encoder_Type") {
+# Read out the encoder type in human-readable form. The output numbers can be 
+# interpreted as ASCII.
+# This record is coupled to the parameter library via encoderType -> ENCODER_TYPE.
+record(waveform, "$(INSTR)$(M):Encoder_Type") {
     field(DTYP, "asynOctetRead")
     field(INP, "@asyn($(CONTROLLER),$(AXIS),1) ENCODER_TYPE")
     field(FTVL, "CHAR")
@@ -7,53 +9,22 @@ record(waveform, "$(P)$(M):Encoder_Type") {
     field(SCAN, "I/O Intr")
 }
 
-# reread encoder
-record(longout, "$(P)$(M):Reread_Encoder") {
+# Trigger a rereading of the encoder. This action is sometimes necessary for 
+# absolute encoders after enabling them. For incremental encoders, this is a no-op.
+# This record is coupled to the parameter library via rereadEncoderPosition_ -> REREAD_ENCODER_POSITION.
+record(longout, "$(INSTR)$(M):Reread_Encoder") {
     field(DTYP, "asynInt32")
     field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) REREAD_ENCODER_POSITION")
     field(PINI, "NO")
 }
 
-# reread encoder
-record(longout, "$(P)$(M):Read_Config") {
+# The pmacV3 driver reads certain configuration parameters (such as the velocity
+# and the acceleration) directly from the MCU. This reading procedure is performed
+# once at IOC startup during atFirstPoll. However, it can be triggered manually
+# by setting this record value to 1.
+# This record is coupled to the parameter library via readConfig_ -> READ_CONFIG.
+record(longout, "$(INSTR)$(M):Read_Config") {
     field(DTYP, "asynInt32")
     field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) READ_CONFIG")
     field(PINI, "NO")
-}
-
-# ===================================================================
-# The following records read acceleration and velocity from the driver 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_VELOCITY-RBV")
-{
-    field(DTYP, "asynFloat64")
-    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_VELOCITY_FROM_DRIVER")
-    field(SCAN, "I/O Intr")
-    field(FLNK, "$(P)$(M):PUSH_VELO_TO_FIELD")
-}
-
-# Push the value into the field of the main motor record
-record(ao, "$(P)$(M):PUSH_VELO_TO_FIELD") {
-    field(DOL,  "$(P)$(M):MOTOR_VELOCITY-RBV CP")
-    field(OUT,  "$(P)$(M).VELO")
-    field(OMSL, "closed_loop") # This configuration keeps the PV and the field in sync
-}
-
-# Helper record for the low limit which is filled in by the driver
-record(ai, "$(P)$(M):MOTOR_ACCL-RBV")
-{
-    field(DTYP, "asynFloat64")
-    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_ACCEL_FROM_DRIVER")
-    field(SCAN, "I/O Intr")
-    field(FLNK, "$(P)$(M):PUSH_ACCL_TO_FIELD")
-}
-
-# Push the value into the field of the main motor record
-record(ao, "$(P)$(M):PUSH_ACCL_TO_FIELD") {
-    field(DOL,  "$(P)$(M):MOTOR_ACCL-RBV CP")
-    field(OUT,  "$(P)$(M).ACCL")
-    field(OMSL, "closed_loop") # This configuration keeps the PV and the field in sync
 }

src/pmacv3Axis.cpp

@@ -87,6 +87,7 @@ asynStatus pmacv3Axis::readConfig() {
     double motorRecResolution = 0.0;
     double motorPosition = 0.0;
     double motorVelocity = 0.0;
+    double motorVmax = 0.0;
     double motorAccel = 0.0;
     int acoDelay = 0.0; // Offset time for the movement watchdog caused by
                         // the air cushions in milliseconds.
@@ -103,14 +104,14 @@ asynStatus pmacv3Axis::readConfig() {
 
     // Software limits and current position
     snprintf(command, sizeof(command),
-             "P%2.2d00 Q%2.2d10 Q%2.2d04 Q%2.2d06 P%2.2d22", axisNo_, axisNo_,
-             axisNo_, axisNo_, axisNo_);
-    status = pC_->writeRead(axisNo_, command, response, 5);
+             "P%2.2d00 Q%2.2d10 Q%2.2d03 Q%2.2d04 Q%2.2d06 P%2.2d22", axisNo_,
+             axisNo_, axisNo_, axisNo_, axisNo_, axisNo_);
+    status = pC_->writeRead(axisNo_, command, response, 6);
     if (status != asynSuccess) {
         return status;
     }
-    nvals = sscanf(response, "%d %lf %lf %lf %d", &axStatus, &motorPosition,
-                   &motorVelocity, &motorAccel, &acoDelay);
+    nvals = sscanf(response, "%d %lf %lf %lf %lf %d", &axStatus, &motorPosition,
+                   &motorVmax, &motorVelocity, &motorAccel, &acoDelay);
 
     // The acoDelay is given in milliseconds -> Convert to seconds, rounded up
     offsetMovTimeout_ = std::ceil(acoDelay / 1000.0);
@@ -120,7 +121,7 @@ asynStatus pmacv3Axis::readConfig() {
     // here to mm/s^2.
     motorAccel = motorAccel * 1000;
 
-    if (nvals != 5) {
+    if (nvals != 6) {
         return pC_->errMsgCouldNotParseResponse(command, response, axisNo_,
                                                 __PRETTY_FUNCTION__, __LINE__);
     }
@@ -135,25 +136,14 @@ asynStatus pmacv3Axis::readConfig() {
                                          __PRETTY_FUNCTION__, __LINE__);
     }
 
-    status =
-        pC_->setDoubleParam(axisNo_, pC_->motorVelocityRBV_, motorVelocity);
+    // Write to the motor record fields
+    status = setVeloFields(motorVelocity, 0.0, motorVmax);
     if (status != asynSuccess) {
-        return pC_->paramLibAccessFailed(status, "motorVelocityRBV_",
-                                         __PRETTY_FUNCTION__, __LINE__);
+        return status;
     }
-
-    status = pC_->setDoubleParam(axisNo_, pC_->motorAccelRBV_, motorAccel);
+    status = setAcclField(motorAccel);
     if (status != asynSuccess) {
-        return pC_->paramLibAccessFailed(status, "motorAccelRBV_",
-                                         __PRETTY_FUNCTION__, __LINE__);
-    }
-
-    // Set the initial enable based on the motor status value
-    status =
-        setIntegerParam(pC_->enableMotor_, (axStatus != -3 && axStatus != -5));
-    if (status != asynSuccess) {
-        return pC_->paramLibAccessFailed(status, "enableMotor_",
-                                         __PRETTY_FUNCTION__, __LINE__);
+        return status;
     }
 
     // Update the parameter library immediately
@@ -618,10 +608,10 @@ asynStatus pmacv3Axis::doPoll(bool *moving) {
         }
     }
 
-    pl_status = setIntegerParam(pC_->enableMotorRBV_,
+    pl_status = setIntegerParam(pC_->motorEnableRBV_,
                                 (axStatus != -3 && axStatus != -5));
     if (pl_status != asynSuccess) {
-        return pC_->paramLibAccessFailed(pl_status, "enableMotorRBV_",
+        return pC_->paramLibAccessFailed(pl_status, "motorEnableRBV_",
                                          __PRETTY_FUNCTION__, __LINE__);
     }
 
@@ -681,12 +671,15 @@ asynStatus pmacv3Axis::doMove(double position, int relative, double minVelocity,
 
     char command[pC_->MAXBUF_], response[pC_->MAXBUF_];
     double motorCoordinatesPosition = 0.0;
-    int enabled = 0;
     double motorRecResolution = 0.0;
+    double motorVelocity = 0.0;
+    int enabled = 0;
+    int motorCanSetSpeed = 0;
+    int writeOffset = 0;
 
     // =========================================================================
 
-    pl_status = pC_->getIntegerParam(axisNo_, pC_->enableMotorRBV_, &enabled);
+    pl_status = pC_->getIntegerParam(axisNo_, pC_->motorEnableRBV_, &enabled);
     if (pl_status != asynSuccess) {
         return pC_->paramLibAccessFailed(pl_status, "enableMotorRBV_",
                                          __PRETTY_FUNCTION__, __LINE__);
@@ -708,18 +701,43 @@ asynStatus pmacv3Axis::doMove(double position, int relative, double minVelocity,
 
     // Convert from EPICS to user / motor units
     motorCoordinatesPosition = position * motorRecResolution;
+    motorVelocity = maxVelocity * motorRecResolution;
 
     asynPrint(pC_->pasynUserSelf, ASYN_TRACE_FLOW,
               "%s => line %d:\nStart of axis %d to position %lf.\n",
               __PRETTY_FUNCTION__, __LINE__, axisNo_, position);
 
-    // Perform handshake, Set target position and start the move command
+    // Check if the speed is allowed to be changed
+    pl_status = pC_->getIntegerParam(axisNo_, pC_->motorCanSetSpeed_,
+                                     &motorCanSetSpeed);
+    if (pl_status != asynSuccess) {
+        return pC_->paramLibAccessFailed(pl_status, "motorCanSetSpeed_",
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    // Prepend the new motor speed, if the user is allowed to set the speed.
+    // Mind the " " (space) before the closing "", as the command created here
+    // is prepended to the one down below.
+    if (motorCanSetSpeed != 0) {
+        snprintf(command, sizeof(command), "Q%2.2d04=%lf ", axisNo_,
+                 motorVelocity);
+        writeOffset = strlen(command);
+
+        asynPrint(pC_->pasynUserSelf, ASYN_TRACE_FLOW,
+                  "%s => line %d:\nSetting speed of axis %d to %lf.\n",
+                  __PRETTY_FUNCTION__, __LINE__, axisNo_, motorVelocity);
+    }
+
+    // Perform handshake, Set target position (and speed, if allowed) and start
+    // the move command
     if (relative) {
-        snprintf(command, sizeof(command), "P%2.2d23=0 Q%2.2d02=%lf M%2.2d=2",
-                 axisNo_, axisNo_, motorCoordinatesPosition, axisNo_);
+        snprintf(&command[writeOffset], sizeof(command) - writeOffset,
+                 "P%2.2d23=0 Q%2.2d02=%lf M%2.2d=2", axisNo_, axisNo_,
+                 motorCoordinatesPosition, axisNo_);
     } else {
-        snprintf(command, sizeof(command), "P%2.2d23=0 Q%2.2d01=%lf M%2.2d=1",
-                 axisNo_, axisNo_, motorCoordinatesPosition, axisNo_);
+        snprintf(&command[writeOffset], sizeof(command) - writeOffset,
+                 "P%2.2d23=0 Q%2.2d01=%lf M%2.2d=1", axisNo_, axisNo_,
+                 motorCoordinatesPosition, axisNo_);
     }
 
     // We don't expect an answer
@@ -933,24 +951,13 @@ asynStatus pmacv3Axis::rereadEncoder() {
 
     // Abort if the axis is incremental
     if (strcmp(encoderType, IncrementalEncoder) == 1) {
-        asynPrint(pC_->pasynUserSelf, ASYN_TRACE_WARNING,
-                  "%s => line %d:\nTrying to reread absolute encoder of "
-                  "axis %d on controller %s, but it is a relative encoder.\n",
-                  __PRETTY_FUNCTION__, __LINE__, axisNo_, pC_->portName);
-        pl_status = setStringParam(pC_->motorMessageText_,
-                                   "Cannot reread an incremental encoder.");
-        if (pl_status != asynSuccess) {
-            return pC_->paramLibAccessFailed(pl_status, "motorMessageText_",
-                                             __PRETTY_FUNCTION__, __LINE__);
-        }
-
-        return asynError;
+        return asynSuccess;
     }
 
     // Check if the axis is disabled. If not, inform the user that this
     // is necessary
     int enabled = 0;
-    pl_status = pC_->getIntegerParam(axisNo_, pC_->enableMotorRBV_, &enabled);
+    pl_status = pC_->getIntegerParam(axisNo_, pC_->motorEnableRBV_, &enabled);
     if (pl_status != asynSuccess) {
         return pC_->paramLibAccessFailed(pl_status, "enableMotorRBV_",
                                          __PRETTY_FUNCTION__, __LINE__);
@@ -1031,13 +1038,6 @@ asynStatus pmacv3Axis::enable(bool on) {
                                              __PRETTY_FUNCTION__, __LINE__);
         }
 
-        // Reset the value in the param lib.
-        pl_status = setIntegerParam(pC_->enableMotor_, 1);
-        if (pl_status != asynSuccess) {
-            return pC_->paramLibAccessFailed(pl_status, "enableMotor_",
-                                             __PRETTY_FUNCTION__, __LINE__);
-        }
-
         return asynError;
     }
 
@@ -1051,6 +1051,14 @@ asynStatus pmacv3Axis::enable(bool on) {
         return asynSuccess;
     }
 
+    // Reread the encoder, if the axis is going to be enabled
+    if (on != 0) {
+        rw_status = rereadEncoder();
+        if (rw_status != asynSuccess) {
+            return rw_status;
+        }
+    }
+
     // Enable / disable the axis if it is not moving
     snprintf(command, sizeof(command), "M%2.2d14=%d", axisNo_, on);
     asynPrint(pC_->pasynUserSelf, ASYN_TRACE_FLOW,
@@ -1066,7 +1074,6 @@ asynStatus pmacv3Axis::enable(bool on) {
         return pC_->paramLibAccessFailed(pl_status, "motorMessageText_",
                                          __PRETTY_FUNCTION__, __LINE__);
     }
-
     rw_status = pC_->writeRead(axisNo_, command, response, 0);
     if (rw_status != asynSuccess) {
         return rw_status;
@@ -1120,4 +1127,4 @@ asynStatus pmacv3Axis::enable(bool on) {
 asynStatus pmacv3Axis::isEnabled(bool *on) {
     *on = (axisStatus_ != -3 && axisStatus_ != -5);
     return asynSuccess;
-}
+}

src/pmacv3Controller.cpp

@@ -54,10 +54,9 @@ pmacv3Controller::pmacv3Controller(const char *portName,
           - ENCODER_TYPE
           - REREAD_ENCODER_POSITION
           - READ_CONFIG
-          - MOTOR_VELOCITY_FROM_DRIVER
-          - MOTOR_ACCEL_FROM_DRIVER
+          - ACCEL_FROM_DRIVER
           */
-          5)
+          4)
 
 {
 
@@ -114,26 +113,6 @@ pmacv3Controller::pmacv3Controller(const char *portName,
         exit(-1);
     }
 
-    status = createParam("MOTOR_VELOCITY_FROM_DRIVER", asynParamFloat64,
-                         &motorVelocityRBV_);
-    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_ACCEL_FROM_DRIVER", asynParamFloat64,
-                         &motorAccelRBV_);
-    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);
-    }
-
     /*
     Define the end-of-string of a message coming from the device to EPICS.
     It is not necessary to append a terminator to outgoing messages, since

src/pmacv3Controller.h

@@ -51,10 +51,9 @@ class pmacv3Controller : public sinqController {
     pmacv3Axis *getAxis(int axisNo);
 
     /**
-     * @brief Overloaded function of asynMotorController
+     * @brief Overloaded function of sinqController
      *
-     * The function is overloaded to allow enabling / disabling the motor and
-     * rereading the encoder.
+     * The function is overloaded to allow rereading the encoder and config.
      *
      * @param pasynUser           Specify the axis via the asynUser
      * @param value               New value
@@ -132,13 +131,6 @@ class pmacv3Controller : public sinqController {
     int readConfig_;
     int encoderType_;
 
-    /*
-    Same strategy as with the limits in sinqController -> Use additional PVs to
-    write speed and acceleration from the driver to the record.
-     */
-    int motorVelocityRBV_;
-    int motorAccelRBV_;
-
     friend class pmacv3Axis;
 };