This is a driver for the masterMacs 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.

Compatible to MasterMACS software 2.0.0.

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.

The folder "utils" contains utility scripts for working with masterMacs motor controllers:

decodeStatus.py: Take the return message of a R10 (read status) command and print it in human-readable form.
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.

These scripts can be run from anywhere. On Linux, the shebang (#!) automatically calls the system Python 3 executable:

# 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

# 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:

C:/path/to/python3.exe C:/path/to/mastermacs_repo/utils/decodeStatus.py 1234

Usage in IOC shell

masterMacs exposes the following IOC shell functions:

masterMacsController: Create a new controller object.
masterMacsAxis: Create a new axis object.

The full masterMacsX.cmd file looks like this:

# 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 controller object with the defined name and connect it to the socket via the port name.
# The other parameters are as follows:
# 8: Maximum number of axes
# 0.05: Busy poll period in seconds
# 1: Idle poll period in seconds
# 1: Socket communication timeout in seconds
masterMacsController("$(NAME)", "$(ASYN_PORT)", 8, 0.05, 1, 1);

# Define some axes for the specified MCU at the given slot (1, 2 and 5). No slot may be used twice!
masterMacsAxis("$(NAME)",1);
masterMacsAxis("$(NAME)",2);
masterMacsAxis("$(NAME)",5);

# Set the number of subsequent timeouts 
setMaxSubsequentTimeouts("$(NAME)", 20);

# Configure the timeout frequency watchdog:
setThresholdComTimeout("$(NAME)", 100, 1);

# Parametrize the EPICS record database with the substitution file named after the MCU.
epicsEnvSet("SINQDBPATH","$(masterMacs_DB)/sinqMotor.db")
dbLoadTemplate("$(TOP)/$(NAME).substitutions", "INSTR=$(INSTR)$(NAME):,CONTROLLER=$(NAME)")
epicsEnvSet("SINQDBPATH","$(masterMacs_DB)/masterMacs.db")
dbLoadTemplate("$(TOP)/$(NAME).substitutions", "INSTR=$(INSTR)$(NAME):,CONTROLLER=$(NAME)")
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.

Firmware version checking

This driver expects a certain version of the firmware running on the controller itself. This is checked at IOC startup by reading the version directly from the hardware. If the firmware version is incompatible to the driver, the IOC will be shut down. If the firmware version cannot be read (e.g. because the variable used to do so does not exist yet on old firmware versions), the firmware is assumed to be compatible to the driver.

The version check is separated into a check of the major and the minor firmware version against expected values. The firmware is seen as compatible if the following conditions hold:

Read-out major version == Expected major version
Read-out read major version >= Expected minor version

The expected versions are defined via compiler flags in Makefile:

USR_CXXFLAGS += -DFIRMWARE_MAJOR_VERSION=1 -DFIRMWARE_MINOR_VERSION=0

Be aware that these flags are only used to compile C++-files (.cpp, .cxx) and not C-files (.c). For C-files, the Makefile variable USR_CFLAGS must be used.

In order to disable the checks, the flags can be set to -1 or just be removed entirely. If one of the flags is not given, both the major and the minor version checks are deactivated.

How to build it

Please see the documentation for the module sinqMotor: https://git.psi.ch/sinq-epics-modules/sinqmotor/-/blob/main/README.md.