maxVelocity is not unused!

Also introduced graceful error handling when trying to access
interactive mode on Windows.

.gitignore

@@ -0,0 +1,4 @@
+O.*
+.cvsignore
+.vscode
+utils/__pycache__

Makefile

@@ -30,7 +30,8 @@ DBDS += sinqMotor/src/sinqMotor.dbd
 DBDS += src/masterMacs.dbd
 
 USR_CFLAGS += -Wall -Wextra -Wunused-result -Wextra -Werror
+USR_CXXFLAGS += -Wall -Wextra -Wunused-result
 
 # These flags define the expected firmware version. See README.md, section
 # "Firmware version checking" for details.
-USR_CXXFLAGS += -DFIRMWARE_MAJOR_VERSION=2 -DFIRMWARE_MINOR_VERSION=2 -Wall -Wextra -Weffc++ -Wunused-result -Wextra
+USR_CXXFLAGS += -DFIRMWARE_MAJOR_VERSION=2 -DFIRMWARE_MINOR_VERSION=2

README.md

@@ -17,23 +17,50 @@ The folder "utils" contains utility scripts for working with masterMacs motor co
 - decodeError.py: Take the return message of a R11 (read error) command and print it in human-readable form.
 - writeRead.py: Send messages to the controller and receive answers.
 
-## Developer guide
+These scripts can be run from anywhere. On Linux, the shebang (#!) automatically
+calls the system Python 3 executable:
 
-### Usage in IOC shell
+```bash
+# To show the help, use either flag -h or --help (works on all scripts)
+/path/to/mastermacs_repo/utils/decodeStatus.py -h 
+/path/to/mastermacs_repo/utils/decodeError.py --help
+/path/to/mastermacs_repo/utils/writeRead.py -h
 
-masterMacs exposes the following IOC shell functions (all in masterMacsController.cpp):
+# To run in non-interactive mode, give the value as an argument
+/path/to/mastermacs_repo/utils/decodeStatus.py 1234
+/path/to/mastermacs_repo/utils/decodeError.py 5678
+/path/to/mastermacs_repo/utils/writeRead.py "R11"
+
+# To run in interactive mode, don't give any argument. This only works on Linux
+/path/to/mastermacs_repo/utils/decodeStatus.py
+/path/to/mastermacs_repo/utils/decodeError.py
+/path/to/mastermacs_repo/utils/writeRead.py
+```
+
+To use these scripts on Windows, prefix the Python 3 executable:
+```bash
+C:/path/to/python3.exe C:/path/to/mastermacs_repo/utils/decodeStatus.py 1234
+```
+
+### IOC startup script
+
+masterMacs exposes the following IOC shell functions:
 - `masterMacsController`: Create a new controller object.
 - `masterMacsAxis`: Create a new axis object.
 
-The full mcu.cmd file looks like this:
+The full masterMacsX.cmd file looks like this:
 
-```
+```bash
 # Define the name of the controller and the corresponding port
 epicsEnvSet("NAME","mcu")
 epicsEnvSet("ASYN_PORT","p$(NAME)")
 
-# Create the TCP/IP socket used to talk with the controller. The socket can be adressed from within the IOC shell via the port name
-drvAsynIPPortConfigure("$(ASYN_PORT)","172.28.101.24:1025")
+# Create the TCP/IP socket used to talk with the controller. The socket can be
+# adressed from within the IOC shell via the port name
+# We do not use the standard asyn port driver here, but a PMAC-specific one
+# which enables the usage of StreamDevices for
+# communicating with the controller directly.
+masterMacsAsynIPPortConfigure("$(ASYN_PORT)","172.28.101.24:1025")
 
 # Create the controller object with the defined name and connect it to the socket via the port name.
 # The other parameters are as follows:
@@ -62,6 +89,8 @@ dbLoadTemplate("$(TOP)/$(NAME).substitutions", "INSTR=$(INSTR)$(NAME):,CONTROLLE
 dbLoadRecords("$(masterMacs_DB)/asynRecord.db","P=$(INSTR)$(NAME),PORT=$(ASYN_PORT)")
 ```
 
+## Developer guide
+
 ### Versioning
 
 Please see the documentation for the module sinqMotor: https://git.psi.ch/sinq-epics-modules/sinqmotor/-/blob/main/README.md.

db/masterMacs.db

@@ -5,3 +5,13 @@ record(longout, "$(INSTR)$(M):NodeReset") {
     field(OUT, "@asyn($(CONTROLLER),$(AXIS),1) NODE_RESET")
     field(PINI, "NO")
 }
+
+# Overrides the default value for the "Connected" record provided by sinqMotor.
+record(longin, "$(INSTR)$(M):Connected")
+{
+    field(DTYP, "asynInt32")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_CONNECTED")
+    field(SCAN, "I/O Intr")
+    field(PINI, "NO")
+    field(VAL, "0")
+}

src/masterMacsAxis.cpp

@@ -215,6 +215,10 @@ asynStatus masterMacsAxis::init() {
         }
     }
 
+    // Initially assume that the axis is disconnected. It will be set to
+    // connected after the first communication attempted succeeded.
+    setAxisParamChecked(this, motorConnected, false);
+
     // Read out the current position
     pl_status = pC_->read(axisNo_, 12, response);
     if (pl_status != asynSuccess) {
@@ -327,9 +331,10 @@ asynStatus masterMacsAxis::doPoll(bool *moving) {
 
     // =========================================================================
 
-    // Does the axis need to be intialized?
+    // Does the axis need to be initialized?
     if (needInit()) {
-	// Perform the rest of the poll, but remember if sth. failed in the init.
+        // Perform the rest of the poll, but remember if sth. failed in the
+        // init.
         poll_status = init();
     }
 
@@ -687,7 +692,6 @@ asynStatus masterMacsAxis::doMove(double position, int relative,
 
     // Suppress unused variable warning
     (void)minVelocity;
-    (void)maxVelocity;
     (void)acceleration;
 
     // Status of read-write-operations of ASCII commands to the controller
@@ -916,7 +920,7 @@ asynStatus masterMacsAxis::readEncoderType() {
 
     /*
     Defined encoder IDs:
-    0=INC (Incremental)
+    0=INC (Incremental or no encoder)
     1=SSI (Absolute encoder with SSI interface)
     2=SSI (Absolute encoder with BiSS interface)
      */
@@ -953,9 +957,7 @@ asynStatus masterMacsAxis::enable(bool on) {
     doPoll(&moving);
 
     // If the axis is currently moving, it cannot be disabled. Ignore the
-    // command and inform the user. We check the last known status of the
-    // axis instead of "moving", since status -6 is also moving, but the
-    // motor can actually be disabled in this state!
+    // command and inform the user.
     if (moving) {
         asynPrint(pC_->pasynUser(), ASYN_TRACE_ERROR,
                   "Controller \"%s\", axis %d => %s, line %d:\nAxis is not "

src/masterMacsAxis.h

@@ -148,163 +148,191 @@ class HIDDEN masterMacsAxis : public sinqAxis {
 
     /**
      * @brief Read the Master MACS status with the xR10 command and store
-     * the result in axisStatus_
+     * the result in axisStatus (see masterMacsAxisImpl redefinition in
+     * masterMacsAxis.cpp)
      *
      */
     asynStatus readAxisStatus();
 
     /*
-    The functions below read the specified status bit from the axisStatus
-    bitset. Since a bit can either be 0 or 1, the return value is given as a
-    boolean.
+    The functions below read the specified status bit from the axisStatus (see
+    masterMacsAxisImpl redefinition in masterMacsAxis.cpp) bitset. Since a bit
+    can either be 0 or 1, the return value is given as a boolean.
     */
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool readyToBeSwitchedOn();
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool switchedOn();
 
     // Bit 2 is unused
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool faultConditionSet();
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool voltagePresent();
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool quickStopping();
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool switchOnDisabled();
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool warning();
 
     // Bit 8 is unused
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool remoteMode();
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool targetReached();
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool internalLimitActive();
 
     // Bits 12 and 13 are unused
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool setEventHasOcurred();
 
     /**
-     * @brief Read the property from axisStatus_
+     * @brief Read the property from axisStatus (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool powerEnabled();
 
     /**
-     * @brief Read the Master MACS status with the xR10 command and store
-     * the result in axisStatus_
+     * @brief Read the Master MACS error with the xR10 command and store
+     * the result in axisError (see masterMacsAxisImpl redefinition in
+     * masterMacsAxis.cpp)
      *
      */
     asynStatus readAxisError();
 
     /*
-    The functions below read the specified error bit from the axisError_
-    bitset. Since a bit can either be 0 or 1, the return value is given as a
-    boolean.
+    The functions below read the specified error bit from the axisError (see
+    masterMacsAxisImpl redefinition in masterMacsAxis.cpp) bitset. Since a bit
+    can either be 0 or 1, the return value is given as a boolean.
     */
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool shortCircuit();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool encoderError();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool followingError();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool communicationError();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool feedbackError();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool positiveLimitSwitch();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool negativeLimitSwitch();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool positiveSoftwareLimit();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool negativeSoftwareLimit();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool overCurrent();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool overTemperature();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool overVoltage();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool underVoltage();
 
     /**
-     * @brief Read the property from axisError_
+     * @brief Read the property from axisError (see masterMacsAxisImpl
+     * redefinition in masterMacsAxis.cpp)
      */
     bool stoFault();
 

src/masterMacsController.cpp

@@ -429,8 +429,6 @@ asynStatus masterMacsController::parseResponse(
         getAxisParamChecked(axis, motorConnected, &prevConnected);
     }
 
-    // We don't use strlen here since the C string terminator 0x00
-    // occurs in the middle of the char array.
     for (uint32_t i = 0; i < MAXBUF_; i++) {
         if (fullResponse[i] == '\x19') {
             responseStart = i;

utils/decodeError.py

@@ -9,6 +9,8 @@ To read the manual, simply run this script without any arguments.
 Stefan Mathis, January 2025
 """
 
+import platform
+
 from decodeCommon import interactive, decode, print_decoded
 
 # List of tuples which encodes the states given in the file description.
@@ -32,20 +34,7 @@ interpretation = [
     ("Ok", "STO fault (STO input is on disable state)"),  # Bit 15
 ]
 
-if __name__ == "__main__":
-    from sys import argv
-
-    if len(argv) == 1:
-        # Start interactive mode
-        interactive()
-    else:
-
-        number = None
-        try:
-            number = int(float(argv[1]))
-
-        except:
-            print("""
+help = """
 Decode R11 message of MasterMACs
 ------------------
     
@@ -63,19 +52,39 @@ if __name__ == "__main__":
 'value' is the return value of a R11 command. This value is interpreted
 bit-wise and the result is printed out.
 
-            Option 2: CLI Mode
-            ------------------       
+Option 2: CLI Mode (Linux-only)
+-------------------------------
 
 Usage: decodeError.py
 
+ONLY AVAILABLE ON LINUX!
+
 A prompt will be opened. Type in the return value of a R11 command, hit
 enter and the interpretation will be printed in the prompt. After that,
 the next value can be typed in. Type 'quit' to close the prompt.
-            """)
+"""
 
+if __name__ == "__main__":
+    from sys import argv
 
+    if "-h" or "--help" in argv:
+        print(help)
+
+    if len(argv) == 1:
+        # Start interactive mode
+        if platform.system() == "Linux":
+            interactive()
+        else:
+            print(help)
+    else:
+
+        number = None
+        try:
+            number = int(float(argv[1]))
+        except:
+            print(help)
         if number is not None:
             print("Motor error")
-            print("============")
+            print("===========")
             (bit_list, interpreted) = decode(number, interpretation)
             print_decoded(bit_list, interpreted)

utils/decodeStatus.py

@@ -9,6 +9,8 @@ To read the manual, simply run this script without any arguments.
 Stefan Mathis, December 2024
 """
 
+import platform
+
 from decodeCommon import interactive, decode, print_decoded
 
 # List of tuples which encodes the states given in the file description.
@@ -23,7 +25,8 @@ interpretation = [
     ("Switch on enabled", "Switch on disabled"),  # Bit 6
     ("Ok", "Warning: Movement function was called while motor is still moving. The function call is ignored"),  # Bit 7
     ("Not specified", "Not specified"),  # Bit 8
-    ("Motor does not execute command messages (local mode)", "Motor does execute command messages (remote mode)"), # Bit 9
+    ("Motor does not execute command messages (local mode)",
+     "Motor does execute command messages (remote mode)"),  # Bit 9
     ("Target not reached", "Target reached"),  # Bit 10
     ("Ok", "Internal limit active (current, voltage, velocity or position)"),  # Bit 11
     ("Not specified", "Not specified"),  # Bit 12
@@ -32,20 +35,7 @@ interpretation = [
     ("Not specified", "Not specified"),  # Bit 15
 ]
 
-if __name__ == "__main__":
-    from sys import argv
-
-    if len(argv) == 1:
-        # Start interactive mode
-        interactive()
-    else:
-
-        number = None
-        try:
-            number = int(float(argv[1]))
-
-        except:
-            print("""
+help = """
 Decode R10 message of MasterMACs
 ------------------
     
@@ -63,17 +53,37 @@ if __name__ == "__main__":
 'value' is the return value of a R10 command. This value is interpreted
 bit-wise and the result is printed out.
 
-            Option 2: CLI Mode
-            ------------------       
+Option 2: CLI Mode (Linux-only)
+-------------------------------
 
 Usage: decodeStatus.py
 
+ONLY AVAILABLE ON LINUX!
+
 A prompt will be opened. Type in the return value of a R10 command, hit
 enter and the interpretation will be printed in the prompt. After that,
 the next value can be typed in. Type 'quit' to close the prompt.
-            """)
+"""
 
+if __name__ == "__main__":
+    from sys import argv
 
+    if "-h" or "--help" in argv:
+        print(help)
+
+    if len(argv) == 1:
+        # Start interactive mode
+        if platform.system() == "Linux":
+            interactive()
+        else:
+            print(help)
+    else:
+
+        number = None
+        try:
+            number = int(float(argv[1]))
+        except:
+            print(help)
         if number is not None:
             print("Motor status")
             print("============")

utils/writeRead.py

@@ -6,9 +6,32 @@ To read the manual, simply run this script without any arguments.
 Stefan Mathis, April 2025
 """
 
+import platform
+
 import struct
 import socket
-import curses
+
+help = """
+Send commands to and receive replies from MasterMACS controllers
+
+Option 1: Single Command
+------------------------
+
+Usage: writeRead.py pmachost:port command
+This then returns the response for command. 
+
+Option 2: CLI Mode (Linux-only)
+-------------------------------
+
+Usage: writeRead.py pmachost:port
+
+ONLY AVAILABLE ON LINUX!
+
+You can then type in a command, hit enter, and the response will see
+the reponse, before being prompted to again enter a command. Type
+'quit' to close prompt.
+"""
+
 
 def packMasterMacsCommand(command):
     # 0x0D = Carriage return
@@ -16,6 +39,7 @@ def packMasterMacsCommand(command):
     buf = bytes(command, 'utf-8') + buf
     return bytes(command, 'utf-8')
 
+
 def readMasterMacsReply(input):
     msg = bytearray()
     expectAck = True
@@ -33,24 +57,21 @@ def readMasterMacsReply(input):
             else:
                 msg.append(bint)
 
+
 if __name__ == "__main__":
     from sys import argv
 
-    try:
-
+    if "-h" or "--help" in argv:
+        print(help)
+    else:
         addr = argv[1].split(':')
         s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         s.connect((addr[0], int(addr[1])))
 
-        if len(argv) == 3:
-            buf = packMasterMacsCommand(argv[2])
-            s.send(buf)
-            reply = readMasterMacsReply(s)
-            print(reply.decode('utf-8') + '\n')
+        if len(argv) == 2:
 
-        else:
-
-            try:
+            if platform.system() == "Linux":
+                import curses
 
                 stdscr = curses.initscr()
                 curses.noecho()
@@ -125,7 +146,8 @@ if __name__ == "__main__":
                             if len(history[ptr]) == 0:
                                 continue
                             (y, x) = stdscr.getyx()
-                            history[ptr] = history[ptr][0:x-4] + history[ptr][x-3:]
+                            history[ptr] = history[ptr][0:x-4] + \
+                                history[ptr][x-3:]
                             stdscr.addch("\r")
                             stdscr.clrtoeol()
                             stdscr.addstr(">> " + history[ptr])
@@ -134,38 +156,24 @@ if __name__ == "__main__":
 
                         else:
                             (y, x) = stdscr.getyx()
-                            history[ptr] = history[ptr][0:x-3] + chr(c) + history[ptr][x-3:]
+                            history[ptr] = history[ptr][0:x-3] + \
+                                chr(c) + history[ptr][x-3:]
                             stdscr.addch("\r")
                             stdscr.clrtoeol()
                             stdscr.addstr(">> " + history[ptr])
                             stdscr.move(y, x+1)
                             stdscr.refresh()
-
-            finally:
-
                     # to quit
                     curses.nocbreak()
                     stdscr.keypad(False)
                     curses.echo()
                     curses.endwin()
-
-    except:
-        print("""
-        Invalid Arguments
-
-        Option 1: Single Command
-        ------------------------
-
-        Usage: writeRead.py pmachost:port command
-        This then returns the response for command. 
-
-        Option 2: CLI Mode
-        ------------------
-
-        Usage: writeRead.py pmachost:port
-
-        You can then type in a command, hit enter, and the response will see
-        the reponse, before being prompted to again enter a command. Type
-        'quit' to close prompt.
-        """)
-
+            else:
+                print(help)
+        elif len(argv) == 3:
+            buf = packMasterMacsCommand(argv[2])
+            s.send(buf)
+            reply = readMasterMacsReply(s)
+            print(reply.decode('utf-8') + '\n')
+        else:
+            print(help)