123 lines
5.3 KiB
Markdown
123 lines
5.3 KiB
Markdown
# masterMacs
|
|
|
|
## <span style="color:red">Please read the documentation of sinqMotor first: https://git.psi.ch/sinq-epics-modules/sinqmotor</span>
|
|
|
|
## Overview
|
|
|
|
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:
|
|
|
|
```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
|
|
|
|
# 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
|
|
```
|
|
|
|
### 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.
|