motorDSM is a submodule of [motor](https://github.com/epics-modules/motor). When motorDSM is built in the ``motor/modules`` directory, no manual configuration is needed.
motorDSM can also be built outside of motor by copying it's ``configure/EXAMPLE_RELEASE.local`` file to ``RELEASE.local`` and defining the paths to ``EPICS_BASE``, ``MOTOR``, and itself.
motorDSM contains an example IOC that is built if ``configure/CONFIG_SITE.local`` sets ``BUILD_IOCS = YES``. The example IOC can be built outside of the driver module. Copy ``iocs/dsmIOC/configure/EXAMPLE_RELEASE.local`` to ``RELEASE.local`` and uncomment and set the paths for the appropriate lines depending on whether motorDSM was built inside the motor module or independently.
In ``motorDSM/iocs/dsmIOC/configure``, copy ``EXAMPLE_RELEASE.local`` to ``RELEASE.local``. Comment out the "if built inside motor" lines, uncomment the "if built outside motor" lines, and set the path for ``MOTOR_DSM``.
The directory `$SUPPORT/motorDSM/iocs/dsmIOC/iocBoot/iocDSM` contains example configurations for the IOC server that runs on the computer the motor controllers are attached to. The `st.cmd.md90` and `motor.substitutions.md90` files provide an example to configure and run one attached MD-90. The `st.cmd.md90.multi` and `motor.substitutions.md90.multi` files provide an example to configure and run eight attached MD-90s connected on ports `dev/ttyUSB0` through `/dev/ttyUSB7`. Add or remove lines from the `*.multi` files as necessary to configure a different number of attached MD-90s.
After the call to `iocInit` (still in the st.cmd.md90[.multi] file), set up some default values for EPICS process variables for each motor. The example below uses `DSM:m0`, but they should also be set for each motor configured in the IOC startup script if connecting more than one.
In the motor substitutions file (motor.substitutions.md90[.multi]), ensure the values in the `pattern` block's `PORT` field match the names used in the `std.cmd.md90[.multi]` file. Note that, despite this field being called "Port", it usese the names of the MD90 Controller object defined above (by default, MD900, MD901, etc). Do __not__ use the direct serial port names (by default, serial0, serial1, etc.).
1. After building, run the example IOC described above in one terminal window.
2. Open another terminal window on either the same computer as the IOC or another computer on the LAN and navigate to `[EPICS install directory]/epics-base/bin/linux-x86_64/` (or wherever you built EPICS base). You could alternatively add this directory to your PATH.
3. Set the "EPICS_CA_ADDR_LIST" environment variable to include the IP address of the server. If it's running on the same computer, you can use the loopback IP address:
`$ export EPICS_CA_ADDR_LIST='127.0.0.1'`
4. Use the `caget` and `caput` programs to read and set process variables, respectively.
This reads the REP variable, which is the "Raw Encoder Position". Additionally, change `m0` to `m1`, `m2`, etc. to read the values from other motors when running more than one.
This sets the velocity target to 0.5 mm/s. (Note that velocity targets are approximate only. They adjust the step rate of the motor and are not guaranteed to be exact.)
The I-20 motor driven by the MD-90 is a closed loop "step and repeat" motor that takes full steps towards its position target until it is close, then will perform linear extensions to close the loop on the target position. This is handled internally on the MD-90, not by EPICS.
The velocity target parameter sets the step frequency at which the motor operates on its way to the target position. The speed is not closed loop, and will depend on external loads, environmental conditions, etc. A speed target of 1 mm/s will generate a roughly 1 mm/s motion, but it is not guaranteed.
Additionally, due to the way EPICS operates, setting `VELO` will not immediately send a command to the MD-90. Instead, EPICS remembers the last value you set, and will set this new velocity target when it sends the next move command. **However, the motor must not be in servo mode to accept a new velocity target.**
The motor enters servo mode when you send a new position target, and stays in servo mode until you issue a Stop command (by setting the `DSM:m0.STOP` parameter to 1).
If you do not disable servo prior to issuing a Move command at the new velocity, then `VELO` will become out of sync with the actual motor velocity, and EPICS will return error 3 "Cannot execute while moving" in its console each time you issue a Move command. This is because each Move command internally sends a "Set step frequency" command, which will error if you do not Stop the motor first. Reading the VELO parameter at this point will return the wrong value--it returns the value you requested, not the actual speed setting on the motor. To fix this, you must Stop the motor, then send a new Move command.
