The uniserv application¶

uniserv is the program that runs on UniDrive devices that control motors of several undulators at Bessy and the MLS.

uniserv communicates by a CAN bus with the undulator control IOC which runs the IDCP application.

The UniDrive device is programmed in the DPL language. The uniserv program for each axle for each undulator is generated from a common source.

Finding the source code that is in use at an insertion device¶

In general you get a version number of an undulator axle by querying the process variable [undulator]:AdiUn[no]GblVer. Here, “undulator” is the Bessy devicename of the undulator and “no” is the number of the axle starting with 1. The script “idcp-drive-info” makes this easy. For example to get all program versions for the axles of the UE112 undulator just enter:

idcp-drive-info versions ue112

The program replies with:

This number is build from the scheme “yymmddHHMM” where “yy” are the last two digits of the year, “mm” is the month number, “dd” the day of the month, “HH” the hour (24 hour format) and “MM” are minutes. So the given example corresponds to the date:

2013-08-27 09:38

Another script shows information about this version:

uniserv-restore --info 2106281047

The program’s reply is:

ISOVERSION      : 2021-06-28T10:48:04
SHORTVERSION    : 2106281047
Install location: /opt/IOC/uniserv/dist/2021-06-28T10:48:04 on host nfs.blc.bessy.de

You find the DPL source code of this version by logging on to host nfs.blc.bessy.de for example as user idadm, and the changing to the uniserv distribution directory:

ssh idadm@nfs.blc.bessy.de
cd /opt/IOC/uniserv/dist/2021-06-28T10:48:04

For the UE112 undulator the dpl files for all axles are in the sub directory “dpl/UE112”:

ls dpl/UE112

gives this result:

CTNet0_Node_11.DPL  CTNet0_Node_13.DPL  CTNet0_Node_15.DPL
CTNet0_Node_12.DPL  CTNet0_Node_14.DPL  CTNet0_Node_16.DPL

Rebuilding the source directory for an installed version¶

If you have the SHORTVERSION (e.g. “2106281047”) or the ISOVERSION (e.g. “2021-06-28T10:48:04”) of the program, you can recover the source code working copy like this:

uniserv-restore  2106281047

After the program is finished you find the source code in directory “2106281047/uniserv”.

You can now have a look at the file uniserv.dpl like this:

less uniserv/src/uniserv.dpl

Note that you can turn pages in “less” with “b” and “<space>” and leave the program with “q”. For more help see “man less”.

Get and install uniserv¶

uniserv.dpl cannot be installed directly on a UniDrive device. Instead, DPL files have to be created from the file “uniserv.dpl”.

Get a working copy from the central repository¶

First you have to check out uniserv.dpl from the central mercurial repository, if you have the password of user “idadm” you can do it like this:

hg clone http://repo.acc.bessy.de/hg/id-drive/uniserv

If you don’t have access to the “idadm” account you can get a working copy with this command:

hg clone http://repo.acc.bessy.de/hg/id-drive/uniserv

This creates a directory “uniserv” in your current working directory. Now change to this directory:

cd uniserv

Configure the application¶

The first thing you have to do is to configure the working copy. uniserv depends on the “bii_scripts” and “id_scripts” modules. You can use these directly if they are globally installed or use local working copies. This is configured in file “config/config.yaml”. You may have to change “config/config.yaml” in order to continue.

Here we show what to change in file “config/config.yaml” if you are user “idadm” on host repo.acc.bessy.de:

DARCSROOT    : http://repo.acc.bessy.de/darcs
HGROOT       : http://repo.acc.bessy.de/hg

Now you can start the configure script:

./configure

Create a local build¶

Now we build all the DPL files from uniserv.dpl with this command:

make local

Install on the version server¶

Note that the following command does not install the DPL files on the UniDrive device, it just copies the DPL files to the directory /opt/IOC/uniserv/dist on host nfs.blc.bessy.de.

However, if you want to install some of the DPL files in the UniDrive devices, this step is important. It ensures that you can later always get the source of the program if you only know the version number. Since the distribution process uses rsync you have to have the ssh-agent program running even if your ssh key is not pass phrase protected. As user “idadm” just enter agent to start this program. “agent” is an alias for the correct command that is already configured for user idadm at host elbe.

You create a distribution with the command:

make

At the end, you will see a message like:

2013-09-24T10:19:47 was created

This is the name of the directory that was created. In the example above you would find the DPL files at:

/opt/IOC/Releases/uniserv/dist/2013-09-24T10:19:47/dpl/[undulator-name]

Install the DPL files on the UniDrive devices¶

First time installation¶

You need a program to set parameters. For older devices with an “SM-Application” module, this is CTSoft, for newer devices with an “SI-Application” module this is Connect.

UniDrive parameters always have a major and a minor index, e.g. ‘#15.11’ has major index ‘15’ and minor index ‘11’.

The unidrive device also has option modules. The two relevant modules here are:

SM-Application or SI-Application
CANOpen

Each module has a major index that depends on the slot it is plugged in. The major index of a module is either 15, 16 or 17. You see this under “option modules” in CTSoft or Connect.

In the following text, “APPIDX” means the major index of the Application module (either ‘SM’ or ‘SI’) and “CANIDX” the major index of the CANOpen module.

Set these parameters:

#18.11 : Set to the drive number, so 1 for the first, 2 for the second and so on. If this parameter is 0, uniserv will not initialize drive parameters, this is intended for testing/debugging only.
#APPIDX.12 : Set to 4. This number means that the position task runs every 2ms.
#APPIDX.13 : Set to 1. This means to automatically start the program after power-up.

For the SI-Application module you additionally need to set these parameters:

#CANIDX.01.004 : set to axle number (1..n) plus can-node-offset. Currently can-node-offset is always 0.
#CANIDX.01.005 : set to 0, meaning baud rate 1Mbit
#CANIDX.01.008 : set to 1, meaning ‘PDO configuration by master’
#CANIDX.01.010 : set to 0, meaning ‘no timeout’
#CANIDX.01.011 : set to 4, meaning ‘no action at timeout’
#CANIDX.01.021 : set to 3, meaning ‘UNIDRIVE M’

Process with with “Normal installation” below and do save parameters in drive with CTSoft or Connect after this procedure.

A reset also stores parameters in the drives permanent memory.

Normal installation¶

You have to have to have a project for the program “sypt”. Before sypt is started, copy all the DPL files to the project directory. Overwrite the existing DPL files.

Then start sypt, open the project and select “rebuild all”. When this is finished, go online and select “download to drive”, select all drives.

After the download has finished, you have to reboot the IOC.

Troubleshooting¶

If later on the “CAN/IO OK” light in the undulator panel toggles between red and green, you may have forgotten to set parameter #18.11.

In this case, the uniserv program does initialize drive variables.

When this happens, re-run the parameter setup shown above. Then reboot the UniDrive device twice. Only then the position task schedule time will be right.