From 62a3d8c834ce8fcfa444faf98e7397343dc42c4d Mon Sep 17 00:00:00 2001
From: smathis <stefan.mathis@psi.ch>
Date: Tue, 29 Jul 2025 11:50:34 +0200
Subject: [PATCH] Added documenation for enableDisable flag

---
 src/turboPmacAxis.cpp | 35 +++++++++++++++++++++++------------
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/src/turboPmacAxis.cpp b/src/turboPmacAxis.cpp
index 4e9294b..627576d 100644
--- a/src/turboPmacAxis.cpp
+++ b/src/turboPmacAxis.cpp
@@ -15,7 +15,14 @@
 
 struct turboPmacAxisImpl {
     bool waitForHandshake;
-    bool waitForEnable;
+    /*
+    This flag is set to true, if the controller is currently enabling /
+    disabling the motor and false otherwise. This flag is used in the doPoll
+    method to check if the enableRBV PV should be set or not in order to prevent
+    a premature change of state (controller reports that the motor is already
+    enabled / disabled while it is not ready yet to receive new commands).
+    */
+    bool enableDisable;
     time_t timeAtHandshake;
     // The axis status is used when enabling / disabling the motor
     int axisStatus;
@@ -65,7 +72,7 @@ turboPmacAxis::turboPmacAxis(turboPmacController *pC, int axisNo,
 
     pTurboPmacA_ = std::make_unique<turboPmacAxisImpl>(
         (turboPmacAxisImpl){.waitForHandshake = false,
-                            .waitForEnable = false,
+                            .enableDisable = false,
                             .timeAtHandshake = 0,
                             .axisStatus = 0,
                             .needInit = false});
@@ -366,8 +373,9 @@ asynStatus turboPmacAxis::doPoll(bool *moving) {
     // Store the axis status
     pTurboPmacA_->axisStatus = axStatus;
 
-    // Update the enablement PV
-    if (!(pTurboPmacA_->waitForEnable)) {
+    // Update the enablement PV, if we are not in the middle of a enabling /
+    // disabling procedure.
+    if (!(pTurboPmacA_->enableDisable)) {
         setAxisParamChecked(this, motorEnableRBV,
                             (axStatus != -3 && axStatus != -5));
     }
@@ -1066,8 +1074,6 @@ asynStatus turboPmacAxis::enable(bool on) {
 
     // =========================================================================
 
-    pTurboPmacA_->waitForEnable = true;
-
     /*
     Continue regardless of the status returned by the poll; we just want to
     find out whether the motor is currently moving or not. If the poll
@@ -1095,7 +1101,7 @@ asynStatus turboPmacAxis::enable(bool on) {
 
         setAxisParamChecked(this, motorMessageText,
                             "Axis cannot be disabled while it is moving.");
-        pTurboPmacA_->waitForEnable = false;
+        pTurboPmacA_->enableDisable = false;
         return asynError;
     }
 
@@ -1107,7 +1113,6 @@ asynStatus turboPmacAxis::enable(bool on) {
             "Controller \"%s\", axis %d  => %s, line %d\nAxis is already %s.\n",
             pC_->portName, axisNo_, __PRETTY_FUNCTION__, __LINE__,
             on ? "enabled" : "disabled");
-        pTurboPmacA_->waitForEnable = false;
         return asynSuccess;
     }
 
@@ -1115,11 +1120,13 @@ asynStatus turboPmacAxis::enable(bool on) {
     if (on != 0) {
         status = rereadEncoder();
         if (status != asynSuccess) {
-            pTurboPmacA_->waitForEnable = false;
             return status;
         }
     }
 
+    // Now the actual enabling / disabling starts
+    pTurboPmacA_->enableDisable = true;
+
     // Enable / disable the axis
     snprintf(command, sizeof(command), "M%2.2d14=%d", axisNo_, on);
     asynPrint(pC_->pasynUser(), ASYN_TRACE_FLOW,
@@ -1144,7 +1151,8 @@ asynStatus turboPmacAxis::enable(bool on) {
         // Read the axis status
         status = pC_->writeRead(axisNo_, command, response, 1);
         if (status != asynSuccess) {
-            pTurboPmacA_->waitForEnable = false;
+            // Enabling / disabling procedure failed
+            pTurboPmacA_->enableDisable = false;
             return status;
         }
         nvals = sscanf(response, "%d", &pTurboPmacA_->axisStatus);
@@ -1159,7 +1167,8 @@ asynStatus turboPmacAxis::enable(bool on) {
             bool moving = false;
             forcedPoll(&moving);
 
-            pTurboPmacA_->waitForEnable = false;
+            // Enabling / disabling procedure is completed (successfully)
+            pTurboPmacA_->enableDisable = false;
             return asynSuccess;
         }
     }
@@ -1176,7 +1185,9 @@ asynStatus turboPmacAxis::enable(bool on) {
     snprintf(command, sizeof(command), "Failed to %s within %d seconds",
              on ? "enable" : "disable", timeout_enable_disable);
     setAxisParamChecked(this, motorMessageText, command);
-    pTurboPmacA_->waitForEnable = false;
+
+    // Enabling / disabling procedure failed
+    pTurboPmacA_->enableDisable = false;
     return asynError;
 }