Bugfix for movTimeoutWatchdog

Update of README.md

src/sinqAxis.h

@@ -18,33 +18,29 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
      */
     sinqAxis(class sinqController *pC_, int axisNo);
 
-    /**
-     * @brief This function is executed once during the very first poll.
-     *
-     * This function is executed at the very first poll after the IOC startup.
-    If it returns anything else than 'asynSuccess', the function is evaluated
-    again after 100 ms until it succeeds. Every 10 trials a warning is emitted.
-    The default implementation just returns asynSuccess and is meant to be
-    overwritten by concrete driver implementations.
-     *
-     * @return asynStatus
-     */
-    virtual asynStatus atFirstPoll();
-
     /**
      * @brief Perform some standardized operation before and after the concrete
     `doPoll` implementation.
      *
      * Wrapper around doPoll which performs the following operations:
     Before calling doPoll:
+
     - Try to execute atFirstPoll once (and retry, if that failed)
 
     After calling doPoll:
+
     - Reset motorStatusProblem_, motorStatusCommsError_ and motorMessageText_ if
     doPoll returned asynSuccess
+
     - If the movement timeout watchdog has been started, check it.
-    - Update the parameter library entry motorEnableRBV_ by calling isEnabled.
-    - Run `callParamCallbacks`
+
+    - The flags `motorStatusHome_`, `motorStatusHomed_` and
+    `motorStatusAtHome_` are set to their idle values (0, 1 and 1 respectively)
+    in the `poll()` method once the homing procedure is finished. See the
+    documentation of the `home()` method for more details.
+
+    - Run `callParamCallbacks()`
+
     - Return the status of `doPoll`
      *
      * @param moving              Forwarded to `doPoll`.
@@ -100,23 +96,42 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
                               double maxVelocity, double acceleration);
 
     /**
-     * @brief Perform some standardized operation before and after the concrete
-    `doHome` implementation.
-    *
-    * Wrapper around move which calculates the (absolute) target position and
-    stores it in the parameter library. The target position in a homing maneuver
-    is calculated as follows:
+     * @brief Wrapper around doHome which handles the homing-related flags
+     *
+     * The homing procedure of the motor record is controlled by the following
+     * parameter library flags:
+     *
+     * - `motorMoveToHome_`: Setting this flag to `1` indicates to EPICS that a
+    homing procedure should start and can therefore be used to start homing from
+    within the driver.
 
-    if abs(current position - high limit) > abs(current position - low limit)
-    {
-    high limit
-    }
-    else
-    {
-    low limit
-    }
+     * - `motorStatusHome_`: This flag should be set to `1` while the motor is
+    actively moving toward its home position and to `0` when the home position
+    is reached.
+     *
+     * - `motorStatusHomed_`: This flag should be set to `0` at the start of a
+    homing command and to 1 once the home position is reached.
+     *
+     * - `motorStatusAtHome_`: This flag is similar to `motorStatusHomed_`, but
+    in addition it should also be `1` when the motor is at its home position,
+    but wasn't actively homed in order to get there.
+     *
+     * This function performs the following operations in the given order:
+     *
+     * - Call `doHome()` and forward the parameters
+     *
+     * - If `doHome()` returned asynSuccess: Set `motorStatusHome_` to `1`,
+    `motorStatusHomed_` to `0` and `motorStatusAtHome_` to `0`.
+     *
+     * - If `doHome()` returned asynError: This means that the motor cannot be
+    homed because the encoder is absolute. Set a corresponding error message,
+    but return asynSuccess in order to avoid any automatic retries by asyn.
 
-    After that, it calls and returns doHome.
+     * - If `doHome()` returned anything else: Forward the status.
+     *
+     * The flags `motorStatusHome_`, `motorStatusHomed_` and
+    `motorStatusAtHome_` are set to their idle values (0, 1 and 1 respectively)
+    in the `poll()` method once the homing procedure is finished.
      *
      * @param minVelocity         Forwarded to `doHome`.
      * @param maxVelocity         Forwarded to `doHome`.
@@ -131,7 +146,9 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
 
     /**
      * @brief Implementation of the "proper", device-specific home method. This
-    method should be implemented by a child class of sinqAxis.
+    method should be implemented by a child class of sinqAxis. If the motor
+    cannot be homed because it has an absolute encoder, this function should
+    return asynError.
      *
      * @param minVelocity         Minimum velocity VMIN from the motor record
      * @param maxVelocity         Maximum velocity VMAX from the motor record
@@ -280,11 +297,13 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
     bool initial_poll_;
     int init_poll_counter_;
 
-    // Helper variables for movementTimeoutWatchdog
+    // Internal variables used in the movement timeout watchdog
     time_t expectedArrivalTime_;
     time_t offsetMovTimeout_;
     double scaleMovTimeout_;
     bool watchdogMovActive_;
+    // Store the motor target position for the movement time calculation
+    double targetPosition_;
 
   private:
     sinqController *pC_;