.. index::
single: uniserv
=======================
The uniserv application
=======================
uniserv is the program that runs on
`UniDrive <https://acim.nidec.com/drives/control-techniques/products/ac-drives/unidrive-m>`_
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 <https://acim.nidec.com/drives/control-techniques/products/ac-drives/unidrive-m>`_
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::
UE112:
1: 2106281047
2: 2106281047
3: 2106281047
4: 2106281047
5: 2106281047
6: 2106281047
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 the uniserv project.
You get a working copy like this:
From the internal network of the
`Helmholtz-Zentrum Berlin <https://www.helmholtz-berlin.de>`_ at the
BESSY II site with this command::
hg clone http://repo.acc.bessy.de/hg/id-drive/uniserv
From anywhere else with this command::
hg clone http://hg.code.sf.net/p/idcs-uniserv/code 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 <https://bii-scripts.sourceforge.io/>`_ 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.