NSLS2 Deploy Docs

Welcome to the NSLS2 areaDetector binary distribution documentation.

This document will explain how to create new distribution packages, and will also explain how to use existing packages to deploy areaDetector IOCs.

Introduction
Creating an areaDetector binary bundle
Deploying IOCs using a binary bundle
Example usage for initIOC
Using installSynApps
Using ioc_deploy
Using updateIOC

Important Links

Introduction

Return

In order to simplify the deployment of new areaDetector IOCs, scripts have been developed that can rapidly build EPICS base, synApps, and areaDetector without requiring user intervention for editing any configuration files. The scripts then extract all required binary files from the compilation directory and place them into a gzip tar archive. This archive can then be unpacked on any machine running the correct operating system and used to run EPICS detector IOCs.

Building EPICS and its associated modules can often be a lengthy affair, and version control regarding which exact version of each module was compiled is often lost soon after the compilation is completed. In addition, it is often the case that each IOC server has a compiled version of areaDetector that is not updated for a very lengthy period. Consequently, this project aims to alleviate these problems by providing a solution in the form of a universally mounted NFS server, with unpacked binary bundles for each in-use operating system. Detector IOCs need only be re-pointed to the binaries on the NFS server, and rebooted.

Following this approach, updating IOCs to newer EPICS or areaDetector versions will be as simple as rebooting them provided they run off of the production binaries, or as simple as re-pointing the executable to a different version's directory. IOCs can now be deployed without having to recompile sources each time, and all detector driver versions can be standardized, as they will be run from the same binaries.

Creating a New Bundle

Return

There are a series of steps required to create a new areaDetector binary bundle.

Setting up dev. environment

Before you begin building any source code, you must first set up your development environment by installing all required dependencies. On linux, the simplest way to do so is via the package manager. For example, on a debian based system, run the following in the terminal:

sudo apt install git wget python3 python3-tk
sudo apt install gcc g++ make perl
sudo python3 -m pip install distro
sudo apt install tar

The distro python module is used for the installSynApps integrated packager, and if this feature is not required then the module is optional.

In addition to these packages which are required for the building process, it is recommended to run the dependencyInstall.sh script prior to building in order to collect all remaining apt packages required by EPICS. The build program/scripts can also run it during the build process, but this will require you to enter your sudo passoword during execution, which limits the automation possibilities of the process. Note that not all of these packages are required for each detector driver or plugin, but it is simplest to install them all.

On windows, you may find most dependencies online:

git + tar - Make sure to select UNIX tools to get access to tar
perl
make - From MinGW you will need to get make and wget, as the EPICS build system uses Makefiles
Visual Studio - On windows we use the Visual Studio compiler.
re2c
python - Used by scripts + build programs (python 3.* required)

In both cases, make sure that these downloaded dependencies are in the system path. On linux, provided they were downloaded with the package manager, this should already be the case. On windows, this can be done by typing Environment Variables into the start bar, and selecting Edit Environment Variables -> Path. To check if each module is in the path, open a command prompt and type the program name. If you receive a message that it is not a known program or batch file, please check again if it is correctly placed in the Path.

Building from source

Once dependencies have been installed, and are in the system path, the build process can proceed. You can compile EPICS and synApps sources in any way you choose, though we have developed a utility for simplifying the process in installSynApps.

To use this program, start by cloning its github repository. This can be done with:

git clone https://github.com/epicsNSLS2-deploy/installSynApps

on either Linux or Windows. If on Linux, you may want to take this time to enter the scripts directory and run the dependencyInstall.sh script as discussed in the earlier section. On windows, you must run the Visual Studio build environment setup script at this point, in the command prompt you will use to run the installSynApps program. Assuming a default installation of Visual Studio, this can be done with:

"C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64
set MAKEFLAGS=-w

Keep in mind that the year will change depending on your version of Visual Studio.

Next, you may choose to either run the GUI based installer, or run everything through the command line.

GUI Installer

To start the GUI installer, enter the root installSynApps directory, and type ./installGUI.py on Linux, and python installGUI.py on windows. This will open a window with several buttons, a log, and a panel describing a loaded install configuration.

From here, you may edit any detail of the installation from the Edit tab at the top of the window. Edit Install Config allows you to choose which modules to clone and build, of which versions, and the install location. Edit Injectors allows you to edit what contents will be injected into certain configuration files, including ADCore/iocBoot/commonPlugins.cmd, ADCore/iocBoot/commonPlugin_settings.req, and more. Finally, Edit Build Flags allows you to enforce areaDetector build configuration flags through the installation programs. For example, if compiling with an external JPEG library rather than the one in ADSupport, simply write JPEG_EXTERNAL=YES into the Edit Build Flags window and press apply.

If you wish to save any edits made to the Install Configuration, select File -> Save As, and give the new install configuration a name. You may also open an existing install configuration by selecting Load Configuration, or File -> Open.

In the Edit tab, there is also an option to toggle popup alerts, as well as a toggle which allows for running the dependencyInstall.sh script during the build process (Linux only - it will require a sudo password in the terminal).

Once the loaded install configuration is to your liking, you may press Autorun to execute the entirety of the build process, or execute each step individually with the appropriate options. The process runs in the following order: Clone -> Update Releases -> Inject files -> Build.

Provided all dependencies are in the system path, the build process should proceed successfully, and build EPICS Base, synApps, and areaDetector plus any selected drivers and plugins.

CLI Installer

If you prefer to run through the command line and not a GUI, you may use installCLI.py. Prior to running the script, enter the configure/ directory in installSynApps, and edit all files within, according to your specifications. Most important is the INSTALL_CONFIG file, which defines which modules and which versions are to be built.

From there, simply run the script, and follow the instructions.

At this point EPICS base, synApps, and areaDetector should be built on your local machine.

Bundling

As of version R2-1 of installSynApps, a packager has been built into the program. It uses the same install configuration to know which items to package, and the location of the compiled binaries. After you have run the build process, set which modules you would like to package in the Edit Install Config window, set the package output directory if you would like (defaults to ./DEPLOYMENTS), and then select 'Package'. The package should be outputted into the selected directory as a .tar.gz tarball. The installSynApps integrated packager requires the python module distro. It can be installed with:

python3 -m pip install distro

If it is not installed, you will see an error message displayed:

ERROR - Could not generate binary bundle, missing "distro" python module

For older versions of installSynApps, or without the integrated packager, or if you wish to have a dedicated packaging tool, you may use ioc_deploy. Instructions on usage can be found in the README of that repository.

Unpacking

Once you have a release tarball generated by the ioc_deploy script, simply copy it to its desired destination, and untar with

tar -xvzf TARBALL_NAME.tgz

On windows, 7zip can be used for untarring.

Deploying IOCs using the binary bundle

Return

Intro

There are two approaches to deploying IOCs using the new binary bundle system. The first, is to download the bundles from the website. This will download a pre-packaged tarball to your local machine which can be unpacked using:

tar -xvzf TARBALL.tgz

on linux, or using 7zip on windows.

Alternatively, you may point your IOC to a set of already unpacked binaries located on a central NFS server linked to each IOC server. These binaries are located under /ad-nfs/epics/prod, followed by the selected operating system, and then a binary distribution version. The directory titled production will be updated periodically to new binaries representing the newest version of areaDetector and ADCore. Other directories with release numbers will be kept static for those users who wish to utilize a constant version.

Each unpacked binary has a README.txt file detailing the included modules and their versions.

Deploying new IOCs using binary tarballs

Step 1 - Setup

Once you have chosen an ADCore version and have unpacked a bundle tarball downloaded from the website, or selected an NFS binary distribution, the simplest way to get started deploying new IOCs is to use the initIOC script, which should be downloaded onto the server on which the new IOCs will be deployed. initIOC requires python3 and git to run, so make sure that you have these installed on your system. You may check this with:

python3 --version
git --version

If the version number is displayed then they are installed.

NOTE - On windows, python3 may be placed into the system path as python. In this case running python --version should be run instead of python3 --version

If you see an error message stating that python or git were not found, you must install them and place them in the system path. On linux this can be done with:

sudo apt install python3-dev git

On windows download these modules from their respective websites: python and git. Make sure to check the option to add each module to the system path.

Step 2 - Download and configure `initIOC`

Once the dependencies are installed, you may download initIOC onto the target IOC server with:

git clone https://github.com/epicsNSLS2-deploy/initIOC

Then enter the script directory:

cd initIOC

The next step is to open the CONFIGURE file in this directory with whichever editor you prefer, and to edit all options to suit your IOC deployment. Below is a detailed explanation of what each option refers to and how to use them.

Option	Description
IOC_DIR	Set this to the target location for iocs on the server. Usually `/epics/iocs`. Note that this location can often provide limited write permissions. If this is the case, running the script with `sudo` will give the ability to deploy an IOC, but may require a change of ownership afterwords.
TOP_BINARY_DIR	Location of unpacked binary tarball. You may point this to the locally unpacked binaries downloaded from the website, or the location of an nfs distribution. You may also point this to a set of locally compiled sources.
ENGINEER	The engineer deploying the IOC. Simply set this to your name and phone extention/email if applicable
PREFIX	IOC PV Prefix for the camera. - Note that this is not the full PV prefix. This option will simply be the start of each PV Prefix. The script will attempt to autoassign a unique portion of the prefix into the form PREFIX{CAMERATYPE-Cam:#}, where PREFIX is this option, CAMERATYPE is taken from the IOC type, and # is a unique identifier that counts up from 1 and goes up by one for each camera deployed.
HOSTNAME	Hostname of server on which the IOC is located
CA_ADDRESS	The channel access address list IP

Step 3 - Add IOCs to `initIOC` deployment

Once all of these options have been updated, you must define which IOCs you wish to actually deploy. This is done in the table also located in the CONFIGURE file:

# IOC Type    IOC Name      AsynPort      IOC Port     Cam Connection
#-------------------------------------------------------------------
ADUVC         cam-uvc        UVC1           4000          25344
ADProsilica   cam-ps1        PS1            4001       EX.AM.PLE.IP
ADAndor3      cam-andor3     AD3            4002       /exam/ple/path

For each IOC you wish to deploy, add a line to the table filling out all of the pertinent information. Each item is described below:

Parameter	Description
IOC Type	Should be the same as its areaDetector repository name. `ADProsilica`, `ADPointGrey` etc. Note that `AD` must be at the start of this parameter
IOC Name	Name of the IOC to be deployed. Usually `cam-` followed by a camera type and number. ex `cam-uvc1`
Asyn Port	Name of the asyn port to which the NDArrays from the driver will be piped. Usually an all-caps shorthand of the driver name followed by a number ex. PS1 for Prosilica cameras.
IOC Port	The telnet port that the IOC will run on when started by procServer. Make sure to not set this to an existing IOC port - use `manage-iocs report` to see the existing IOC ports in use.
Cam Connection	A general parameter for whatever connection format the camera uses. Can be serial number, config path, IP etc. `initIOCs` will attempt to use this parameter to set up the connection for the camera. For some driver types it is able to do this and the IOC will start without any further input from the deployer, while some more complex IOCs will still require some user input.

Step 5 - Run the Script

Once the CONFIGURE file has been edited with whatever options you wish for your IOC deployment, simply run the script with

./initIOCs.py

on Linux, or

python initIOCs.py

on Windows to initialize the IOCs. Note that the initIOC script depends on ioc-template, and thus has a limited set of supported detector IOCs:

ADAndor3
ADLambda
ADUVC
ADProsilica
ADPilatus
ADPerkinElmer
ADMerlin
ADSpinnaker
ADPointGrey
ADSimDetector

After running initIOC, each IOC defined will have been cloned to the specified IOC directory, and initial configuration would have been performed. The st.cmd file will contain a call to running the ioc binary, and the unique.cmd file will contain all of the parameters that may require editing. The envPaths included with these generated IOCs are all dependent on the definition of $SUPPORT_DIR in the unique.cmd file, which should simplify re-pointing to newer versions.

Further details on running initIOC

Once all tweaks have been made, the IOC should be able to start with:

./st.cmd

on Linux or simply

st.cmd

on Windows.

initIOC Options

You may also run initIOCs with the `-i` option for a guided command line setup, or `-g` for a GUI version.

Dependancies

Depending on their contents, it is possible that there are additional external dependencies required to run IOCs from the binary distributions (Generally only on Linux). To fix a missing library error, you may simply run the dependencyInstall.sh script from the IOC server. This script is available on the binary NFS at /ad-nfs/epics/prod/dependencyInstall.sh

If you run into an error along the lines of

libflycapture.so was not found

when attempting to run the IOC, start by running the dependency script as described above. If the error persists, it is most likely that the vendor library SDK needs to be placed into the system library path. initIOC should have generated either a dllPath.bat or a ldpath.sh script in the IOC directory. Run this script before starting the IOC to include the path to these vendor libraries. These libraries are also located on the NFS server in /ad-nfs/epics/prod/$OS/$VERSION/areaDetector/$DRIVER/lib/linux-x86_64, with $OS representing the Debian version, VERSION representing the binary bundle version, and DRIVER representing the IOC type, ex. ADProsilica.

Alternatively - another solution is to copy the missing vendor libraries into a location on the local machine - typically /usr/local/lib, and adding that location to the /etc/ld.so.conf.d/ directory. Create a file with:

sudo touch /etc/ld.so.conf.d/ioc.conf

open the file with whichever editor you prefer and type in the location of the copied vendor libraries. Then run

sudo ldconfig

to refresh the library path. Note that the /usr/local/lib location is generally already added in the libc.conf file. At this point your IOC should be able to find the missing binaries.

Updating existing IOCs to the new binary distribution format

In order to update existing IOCs to the new binary format, it should be enough to re-point their executable call and envPaths to point to the selected binary location. This process can be automated for iocs for post areaDetector 2-0 drivers with the updateIOC script. This program will re-point the binary and envPaths as required for every ioc starting with a certain prefix in the iocs directory (usually cam-).

Usage details are available with the README file on the script's github page.

If not using updateIOC, follow the steps below to update IOCs:

Locate the call to run the binary - usually located in st.cmd. On linux this will most likely start with #!, and the executable generally has App at the end of its name.
Repoint this binary path to the same executable in the binary distribution. This will require you to edit the start of the path up to the driver name, as the section such as ADProsilica/iocs/prosilicaIOC/bin/linux-x86_64/prosilicaApp will most likely remain constant.
Open the envPaths, and make sure that they are pointing to the new binaries as well. It is easiest to set a new variable ex. epicsEnvSet("AD_BINARY_LOCATION", "/ad-nfs/epics/prod/Deb7/R3-6") and repoint the envPaths using this variable and relative paths. This will simplify updating the IOC again in the future.
Next, edit the st.cmd file to account for any special IOC-specific configurations that may no longer be found due to the edited envPaths. Most often this will be the commonPlugins.cmd file or the auto_settings.req file. The simplest solution is to copy these into the IOC directory and add them with < commonPlugins.cmd for example, or alternatively add another variable to the envPaths.
The IOC should now be ready to be run again!

initIOC Step-by-Step Example

Return

On this page I will go step by step deploying several IOCs using the initIOC script and will attach the output. Follow these steps when using initIOC.

Step 0 - `initIOC` dependancies

We start by installing the dependencies for the script.

sudo apt install python3-dev git

I test the installation:

jwlodek@HP-Z6-G4-Workstation:~$ git --version
git version 2.17.1
jwlodek@HP-Z6-G4-Workstation:~$ python3 --version
Python 3.6.8

both modules are installed and in the system path.

Step 1 - Download/Locate binary bundle

Next we must locate a binary bundle to use. We can download one from the website, or we can point to one on the nfs, which is mounted on each IOC server at /ad-nfs/epics/prod. For this example I will be using an Ubuntu18 machine, and I have downloaded an Ubuntu18.04 binary bundle into /ad-nfs/epics/prod/Ubuntu18.

jwlodek@HP-Z6-G4-Workstation:/ad-nfs/epics/prod/Ubuntu18$ wget -q https://epics.nsls2.bnl.gov/bundle/ubuntu/NSLS2_Pack_AD_3.6_Ubuntu_18.04.2_LTS_2019-06-07.tgz
jwlodek@HP-Z6-G4-Workstation:/ad-nfs/epics/prod/Ubuntu18$ ls
NSLS2_Pack_AD_3.6_Ubuntu_18.04.2_LTS_2019-06-07.tgz
jwlodek@HP-Z6-G4-Workstation:/ad-nfs/epics/prod/Ubuntu18$ tar -xzf NSLS2_Pack_AD_3.6_Ubuntu_18.04.2_LTS_2019-06-07.tgz 
jwlodek@HP-Z6-G4-Workstation:/ad-nfs/epics/prod/Ubuntu18$ ls
areaDetector  calc                                                 README.txt
asyn          generateEnvPaths.sh                                  seq
autosave      iocStats                                             sscan
base          modbus
busy          NSLS2_Pack_AD_3.6_Ubuntu_18.04.2_LTS_2019-06-07.tgz
jwlodek@HP-Z6-G4-Workstation:/ad-nfs/epics/prod/Ubuntu18$

Note that if your are using a bundle from the NFS server, you do not need to download and unpack it, you just need to identify a release version that suits your needs that is already unpacked on the server.

jwlodek@HP-Z6-G4-Workstation:/ad-nfs/epics/prod/Ubuntu18$ more README.txt 
NSLS2_Pack_AD_3.6_Ubuntu_18.04.2_LTS_2019-06-07.tgz

Versions used in this deployment
[folder name] : [git tag]

base : R7.0.2.2
modbus : R2-10-1
ADProsilica : R2-5
ADSimDetector : R2-9
ADPluginBar : R2-1
ADCompVision : R1-1-18-g02b0110
ADPluginEdge : R1-2-12-geff0f71
ADUVC : R1-1
ADAndor3 : R2-2-11-gb5a0d98
ADPilatus : R2-7
ADPluginDmtx : R0-2-1-g15c778b
areaDetector : R3-6
asyn : R4-35
autosave : R5-9
busy : R1-7
calc : R3-7-2
iocStats : 3.1.15
sscan : R2-11-1
seq : R6-0

The README file tells me what versions and what modules are included in the distribution I selected. The one I am using has base R7.0.2.2, ADSimDetector R2-9, etc.

Step 2 - Download `initIOC`

Next we need to download initIOC. I will do this in my ~/utils directory, though you may do it where ever.

jwlodek@HP-Z6-G4-Workstation:~/Documents$ git clone https://github.com/epicsNSLS2-deploy/initIOC
Cloning into 'initIOC'...
remote: Enumerating objects: 103, done.
remote: Counting objects: 100% (103/103), done.
remote: Compressing objects: 100% (71/71), done.
remote: Total 103 (delta 55), reused 69 (delta 30), pack-reused 0
Receiving objects: 100% (103/103), 21.57 KiB | 5.39 MiB/s, done.
Resolving deltas: 100% (55/55), done.
jwlodek@HP-Z6-G4-Workstation:~/Documents$ cd initIOC/
jwlodek@HP-Z6-G4-Workstation:~/Documents/initIOC$ ls
CONFIGURE  initIOCs.py  README.md

Step 3 - Edit `CONFIGURE`

Next we must edit the CONFIGURE file. Open it using whichever text editor you prefer - I will use nano.

nano CONFIGURE

First, I set the location for the generated IOCs. For me this will be /epics/iocs.

# Top Level IOC directory (Where all your IOCs will be located)
IOC_DIR=/epics/iocs

Next, I set the TOP_BINARY_DIR variable to the location of my previously unpacked binaries:

# Top Level dir containing compiled binaries.
TOP_BINARY_DIR=/ad-nfs/epics/prod/Ubuntu18

Next, I set the PREFIX Variable to XF:10IDC-BI. Note that I did not include the second portion of the prefix in the brackets - this is autopopulated by the script to ensure each camera gets a unique prefix.

# All Camera PVs will be $Prefix{$(IOC Type)-Cam:#}
# Ex: XF:10IDC-BI{UVC-Cam:2}
PREFIX=XF:10IDC-BI

Looking toward the bottom of the file, I set the remaining variables for my distribution. Because I am deploying the IOCs on a local machine - my HOSTNAME is localhost, though this should be the name of the IOC server they are being deployed on. The CA_ADDRESS should be the channel access IP address , and the ENGINEER should be the IOC deployer.

# User or Engineer responsible for the IOC
ENGINEER=J. Wlodek

# Name of IOC host server (added to config file)
HOSTNAME=localhost

# Channel access address list IP
CA_ADDRESS=127.0.0.255

Step 4 - Select IOCs to Deploy

While you have the CONFIGURE file open, note the table contained within it that describes which IOCs to deploy. For this example, I will deploy 3 ADSimDetector IOCs, and ADUVC IOC, and 2 ADProsilica IOCs. I will also deploy an ADLambda IOC despite my bundle distribution not having a compiled ADLambda driver, in order to demonstrate the behavior when the script cannot find the executable.

Below is the table after I added all of the information to deploy these IOCs:

# IOC Type    IOC Name        Asyn Port      IOC Port      Cam Connection
#-------------------------------------------------------------------------
ADSimDetector  cam-sim1         SIM1           4000              NA
ADSimDetector  cam-sim2         SIM1           4001              NA
ADSimDetector  cam-sim3         SIM1           4002              NA
ADUVC          cam-uvc1         UVC1           4003             25344
ADProsilica    cam-ps1          PS1            4004          EX.AM.PLE.IP
ADProsilica    cam-ps2          PS1            4005          IP.EXA.MPL.E
ADLambda       cam-lambda       LAMBDA1        4006          /exam/ple/path

The fully edited CONFIGURE file for this example can be seen here. Note that ADSimDetector does not require a connection parameter, and my test UVC camera uses its product ID of 25344 to connect. For Prosilica Cameras I would enter their IP address for the Cam Connection field, for Point Grey Cameras I would put their serial number etc.

Step 5 - Running the script

Now that I have set all required options for my deployment, I must still run the script. As I am on Linux, I can do this with ./initIOCs.py

jwlodek@HP-Z6-G4-Workstation:~/Documents/initIOC$ ./initIOCs.py 
+----------------------------------------------------------------+
+ initIOCs, Version: v0.0.4                                      +
+ Author: Jakub Wlodek                                           +
+ Copyright (c): Brookhaven National Laboratory 2018-2019        +
+ This software comes with NO warranty!                          +
+----------------------------------------------------------------+

IOC Dir already exits.

-------------------------------------------
Setup process for IOC cam-sim1
-------------------------------------------
IOC template cloned, converting st.cmd
Generating auto_settings.req file for IOC cam-sim1.
Updating unique file based on configuration
Updating config file for procServer connection
Performing cleanup for cam-sim1

-------------------------------------------
Setup process for IOC cam-sim2
-------------------------------------------
IOC template cloned, converting st.cmd
Generating auto_settings.req file for IOC cam-sim2.
Updating unique file based on configuration
Updating config file for procServer connection
Performing cleanup for cam-sim2

-------------------------------------------
Setup process for IOC cam-sim3
-------------------------------------------
IOC template cloned, converting st.cmd
Generating auto_settings.req file for IOC cam-sim3.
Updating unique file based on configuration
Updating config file for procServer connection
Performing cleanup for cam-sim3

-------------------------------------------
Setup process for IOC cam-uvc1
-------------------------------------------
ERROR - IOC with name cam-uvc1 already exists.
-------------------------------------------
Setup process for IOC cam-ps1
-------------------------------------------
IOC template cloned, converting st.cmd
Generating auto_settings.req file for IOC cam-ps1.
Updating unique file based on configuration
Updating config file for procServer connection
Performing cleanup for cam-ps1

-------------------------------------------
Setup process for IOC cam-ps2
-------------------------------------------
IOC template cloned, converting st.cmd
Generating auto_settings.req file for IOC cam-ps2.
Updating unique file based on configuration
Updating config file for procServer connection
Performing cleanup for cam-ps2

-------------------------------------------
Setup process for IOC cam-lambda
-------------------------------------------
IOC template cloned, converting st.cmd
ERROR - Could not identify a compiled IOC binary for ADLambda, skipping

Note that I had already had an IOC with a name cam-uvc1, so that IOC was not generated. Also, because the ADLambda executable was not found, full configuration for the IOC was not completed. The remaining ADSimDetector IOCs and ADProsilica IOCs were generated as expected into the /epics/iocs directory:

jwlodek@HP-Z6-G4-Workstation:/epics/iocs$ ls
cam-lambda  cam-ps1  cam-ps2  cam-sim1  cam-sim2  cam-sim3  cam-uvc1
jwlodek@HP-Z6-G4-Workstation:/epics/iocs$ cd cam-sim1/
jwlodek@HP-Z6-G4-Workstation:/epics/iocs/cam-sim1$ ls
autosave  auto_settings.req  config  envPaths  st.cmd  unique.cmd

If you would like to see the generated IOCs from running this example in more detail, please see them here

Step 6 - Cleanup and testing

Once the script has been run and the IOCs have been deployed we are ready to do some cleanup and testing. Certain simpler IOCs such as ADSimDetector should be able to start without any further configuration. Let's take a look at the setup done by initIOC. Looking at the top of st.cmd, we see the path to the binary executable that actually starts the IOC process:

jwlodek@HP-Z6-G4-Workstation:/epics/iocs/cam-sim1$ more st.cmd
#!/ad-nfs/epics/prod/Ubuntu18/areaDetector/ADSimDetector/iocs/simDetectorIOC/bin/linux-x86_64/simDetectorApp

< unique.cmd
errlogInit(20000)

< envPaths

Note that the script located the executable in the unpacked binary location I had unpacked earlier. Next, if we take a look at the unique.cmd file, we can see all of the parameters that may require editing:

epicsEnvSet("SUPPORT_DIR", "/ad-nfs/epics/prod/Ubuntu18")

This environment variable is used by envPaths for relative paths for each of the modules required by the IOC. as a result, editing this location will repoint the location for each variable in envPaths.

epicsEnvSet("PREFIX", "XF:10IDC-BI{SimDetector-Cam:1}")
epicsEnvSet("HOSTNAME", "localhost")
epicsEnvSet("IOCNAME", "cam-sim1")

These environment variables describe the IOC name, location, and PV prefix. Note that the script autogenerated the {} portion of the PREFIX and appended it to the end of the prefix I had given. The number at the end of the prefix is meant to be unique per IOC.

epicsEnvSet("XSIZE",                    "1024")
epicsEnvSet("YSIZE",                    "1024")

By default these parameters are both set to 1024. Some cameras (like ADSimDetector) use these to determine image size, while others read maximum image size from the camera.

Looking next at the config file, we see:

jwlodek@HP-Z6-G4-Workstation:/epics/iocs/cam-sim1$ more config
NAME=cam-sim1
PORT=4000
USER=softioc
HOST=localhost

Whichever hostname you selected will be entered here along with the specified IOC name and port. The auto_settings.req autosave file is also generated with detector specific parameters:

jwlodek@HP-Z6-G4-Workstation:/epics/iocs/cam-sim1$ more auto_settings.req
file "simDetector_settings.req",    P=$(P),  R=cam1:
file "simDetector_settings.req",    P=$(P),  R=cam2:
file "NDStdArrays_settings.req",    P=$(P),  R=image1:
file "NDStdArrays_settings.req",    P=$(P),  R=image2:
file "commonPlugin_settings.req", P=$(P)

For more complex IOCs, other dependency files may be required. For example, ADPointGrey uses a .substitutions file. initIOC should be able to handle these dependencies as well, and will update them accordingly.

At this point, we should be ready to start the IOC. at this point, running ./st.cmd will run the executable:

jwlodek@HP-Z6-G4-Workstation:/epics/iocs/cam-sim1$ ./st.cmd 
#!/ad-nfs/epics/prod/Ubuntu18/areaDetector/ADSimDetector/iocs/simDetectorIOC/bin/linux-x86_64/simDetectorApp
< unique.cmd
# ########################################
# File containing Unique IOC parameters  #
# Author: K. Gofron                      #
# ########################################
# Set this to the folder for support.
# Two supported formats: 
# base and support in one directory (must edit envPaths)
# base inside support
epicsEnvSet("SUPPORT_DIR", "/ad-nfs/epics/prod/Ubuntu18")
# Maintainer
epicsEnvSet("ENGINEER", "J. Wlodek")
# IOC Information
.
.
.
epics >

Looks like our IOC starts correctly!

Looking at one of the generated ADProsilica IOCs, we see a similiar structure, however because these GigE cameras require an IP to connect, the Cam Connection Parameter that was set in the CONFIGURE file comes into play. In the st.cmd file we see:

prosilicaConfig("$(PORT)", "$(CAM-CONNECT)",  50, 0)

and in the unique.cmd file we see:

epicsEnvSet("CAM-CONNECT", "EX.AM.PLE.IP")

which was the dummy IP I provided in the CONFIGURE file. This is what allows initIOC to create an IOC that is able to connect to the camera, and this CAM_CONNECT variable is used by each connection type, including IP, serial number, or configuration file path. We can check to see if the IOC will start (though obviously no camera will connect with IP EX.AM.PLE.IP):

jwlodek@HP-Z6-G4-Workstation:/epics/iocs/cam-ps1$ ./st.cmd 
#!/ad-nfs/epics/prod/Ubuntu18/areaDetector/ADProsilica/iocs/prosilicaIOC/bin/linux-x86_64/prosilicaApp
errlogInit(20000)
< unique.cmd
# ########################################
# File containing Unique IOC parameters  #
# Author: K. Gofron                      #
# ########################################
# Set this to the folder for support.
# Two supported formats: 
# base and support in one directory (must edit envPaths)
# base inside support
epicsEnvSet("SUPPORT_DIR", "/ad-nfs/epics/prod/Ubuntu18")
# Maintainer
epicsEnvSet("ENGINEER", "J. Wlodek")
# IOC Information
epicsEnvSet("PORT", "PS1")
epicsEnvSet("IOC", "iocADProsilica")
.
.
.
auto_settings.sav: 1274 of 1274 PV's connected
epics >

Looks like it worked!

Guided Usage

If you would like to have a guided usage for initIOCs, simply run the following:

./initIOCs.py -i

This will prompt you to enter all required information, and thus does not require the CONFIGURE file.

Using the GUI

When using the GUI version of initIOC, make sure you have tkinter installed for python3, then run:

./initIOCs.py -g

This will open a tkinter window with fields to enter all necessary options. Simply fill them out as you would the CONFIGURE file, and select RUN.

Conclusion - Some notes and further resources

initIOC is meant to accelerate new IOC deployment at NSLS2 beamlines. Though it is designed to be used with the new areaDetector binary bundle distribution, it can be used to rapidly prototype IOCs for any compiled location of epics base.

If you wish to report an issue with initIOC, please create a ticket on the issues page. When creating a ticket, please specify whether it is an issue with running the script or with running the IOC after the script has completed. If requesting a new Driver to be supported, please label the ticket as such and describe which driver is required.

If you wish to contribute to initIOC feel free to create a fork and make a pull request.

Using installSynApps

Return

More detailed usage docs can be found here: https://epicsNSLS2-deploy.github.io/installSynApps

installSynApps is a python3 module meant for cloning and building EPICS, synApps, and areaDetector with one command.

This development is based on bash EPICS distribution scripts developed primarly for building on the UNIX/Linux environment, and prior work related to synApps packaging which is utilized by installSynApps is currently hosted at https://github.com/EPICS-synApps

Usage

There are two recommended usage procedures for the module, through the use of installCLI.py and installGUI.py. The first will perform all operations through the terminal, while the other will display a GUI written in Tkinter.

installCLI

To use the command line option, simply run this file either with:

./installCLI.py

python3 installCLI.py

For information on the available options, run with the -h flag. After running the file, simply follow the instructions as they guide you through the build process.

installGUI

The GUI requires Tkinter to be installed for operation. Tkinter is a standard module included with python3, though if it is not it can be installed via pip or the package manager as python3-tk.

Similar to installCLI.py, to use the GUI, simply run it with python3. You will then see the option for each individual operation, along with an autorun that will perform them all sequentially. You may also load another configuration directory, provided that it follows the same file format as the given default configure directory.

The GUI version also allowes finer control of install configurations. In the open window, select the Edit menu, then choose one of the three options. From there, a window will open allowing you to edit any portion of the install process. You may also save the install configuration with it's edits by selecting the File -> Save As option.

In addition, the GUI keeps a log of the operations completed, which can be saved to an arbitrary location. Note that if a process is running (as indicated by the animated process status message), you will be unable to run another process.

For further details on using installGUI, please check the documentation.

Running on Linux vs. Windows

The installSynApps module requires the following to be in the environment PATH in the terminal in which it is running for proper execution:

git
make
wget
tar

If these packages are available, then the script should be able to run through the entirety of the build process. The only caveat is that when building on windows, the dependency install script (which uses apt and bash) will not be able to run. This means that modules requiring external packages as dependencies will need these to be compiled and placed in the system path prior to compilation.

In addition, it is possible that on windows the downloaded python 3 .exe file will actually simply be called python. Thus, the scripts must be executed with

python installCLI.py
python installGUI.py

Included Configuration files

Configuration file	Use
INSTALL_CONFIG	The main configuration file for installSynApps. Use this file to decide which modules to clone and build
AD_RELEASE_CONFIG	Adds paths to external plugins developed for area detector into the area detector build process.
MAKEFILE_CONFIG	Injects contents into `ADCore/ADApp/commonDriverMakefile`. Used to build against additional libraries
PLUGIN_CONFIG	Injects contents into `ADCore/iocBoot/commonPlugins.cmd`. Used to load additional plugins at IOC startup
AUTOSAVE_CONFIG	Injects contents into `ADCore/iocBoot/commonPlugin_settings.req`. Used to configure IOC autosave feature
BUILD_FLAG_CONFIG	Allows for manually setting Area Detector build flags ex. `JPEG_EXTERNAL=YES`.

External Configure

It is possible to use different configure directories when using installSynApps. To do so, it is required that there is an INSTALL_CONFIG file within the selected directory. Additionally, the fixedRELEASEFiles directory should be copied as well. The remaining two directories are optional, though a warning will be displayed on load if they are missing.

BELOW ARE INSTRUCTIONS FOR RUNNING THE LEGACY VERSION OF INSTALLSYNAPPS

Auto Build - Legacy

For most purposes, it is simplest to run the auto-build script, which will give you a guided process through building the modules. To do this, run:

./auto_build.sh

The script will first ask if you wish to keep the default build config, which in most cases is yes. Next, it will ask if the curret install location is OK. If no, simply enter the new install location.

Included scripts - Legacy

Script name	Script Function
auto_build.sh	Recommended script that gives a guided build process
installSynApps.sh	top level bash script that runs the remaining scripts sequentially
clone_and_checkout.py	Clones all required repositories and checks out correct versions
read_install_config.py	Script that reads the data in the INSTALL_CONFIG file
update_release_file.py	Script that updates the release files in support and area detector
ad_config_setup.py	Script based on adConfigSetup, that replaces area detector configuration files
dependencyInstall.sh	bash script that installs all required packages for EPICS and synApps
script_generator.py	script that creates bash scripts for installing and uninstalling, so that compilation for other operating systems is simplified.

Usage - Legacy

For more granular control over the build process, do the following:

There are only 2 locations with files that need to be edited before running the script. These are the configure/* files, and the scripts/dependencyInstall.sh file. In the first, edit the install configurations for your installation. In most cases, you may simply change the MODULE_INSTALL tag in the INSTALL_CONFIG file for the modules you wish to build and those you don't wish to build, and you must also edit the line

INSTALL=/epics

to point to the top level directory in which you wish to install EPICS and synApps. The other files in the configure/ directory contain other configurations, with each one being inserted into a different Area Detector build file. Details can be found in comments in the files themselves.

In the only other file that you must edit (scripts/dependencyInstall.sh). In addition, if there are any other dependencies for your build of EPICS and synApps, add them here. For example, to auto-build the ADUVC driver, libuvc must be built, so I added a condition for building and installing libuvc.

From here, you are ready to run the script, and this is done simply by running:

./installSynApps.sh

from the /scripts directory. Note that you will be prompted for a sudo password to install the dependency packages. Once the script completes, a new directory autogenerated is created, and install.sh and uninstall.sh files are placed within each. Run the appropriate file to uninstall or recompile the packages appropriately. This should simplify building the same sources on multiple operating systems.

Using ioc_deploy

Return

Online manual can be found here

This script is a modified version of Mark Rivers's makeADPrebuilt script, which can be found at https://github.com/areaDetector/areaDetector/blob/master/makeADPrebuilt

This script create a portable deployment of an areaDetector plugin that was previously compiled locally. The script creates a tarball archive of all the necessary files for an IOC in a target directory. The tarball also contains a generateEnvPaths bash script which can create a usable envPaths file for any external IOC that needs to use this deployment. In the same folder as the tarball will be a README file which documents the version for each component that was used in the deployment.

Requirements

ADSupport, ADCore, and any detectors to be copied must be compiled already.
The EPICS modules that these plugins depend on must be compiled already.
- asyn, autosave, busy, calc, seq, sscan, (dev)iocStats
EPICS base must be compiled already
Note: Any envPaths files generated use absolute paths; thus, moving the deployment will break the IOC unless the envPaths file is modified or re-generated.

Usage

Before using the script, it is necessary to define the macros which define the folder names for area detector and EPICS modules, the path to the support folder which contains them, and the location of the EPICS base installation. Additionally, the destination macro must be defined to tell the script where to put the tarball. The script takes three arguments: (1) The areaDetector driver to add, (2) the version of the driver, and (3) the EPICS_HOST_ARCH architecture. The script will ask for additional drivers to add, if you want to deploy multiple drivers in one tarball; to bypass this prompt, use the -f flag prior to the arguments. Examples:

bash deploy.sh ADProsilica R2-2 linux_x86-64

bash deploy.sh -f aravisGigE R1-0 linux-x86_64

To deploy multiple drivers at once, define the array "det" in deploy.sh to include the names of all drivers you want to add. Then run the script with the -a flag. (Note: the first two command line arguments are arbitrary when deploying this way, and there is no prompt to add additional drivers)

bash deploy.sh -a NSLS2 master linux_x86-64

Using updateIOC

Return

updateIOC is a collection of scripts designed to update exsisting IOCs to use the new binary distribution format.

NOTE: For updateIOC to run correctly, the binary executable must be located at the top of the st.cmd file in the target IOC.

Installation

updateIOC requires python3, install it with

sudo apt install python3

You may clone this repository with:

git clone https://github.com/epicsNSLS2-deploy/updateIOC

Usage

To use updateIOC, there are several configuration options, which are edited in the CONFIGURATION file:

Option	Description
IOC_LOCATION	Dir containting all iocs (usually `/epics/iocs`)
CAMERA_IOC_PREFIX	Prefix for directories contiaining AreaDetector IOCs (`cam` or `det`)
BINARY_LOCATION	Path to precompiled binaries
BINARIES_FLAT	`YES` or `NO`, if base is in same dir as synApps modules set to `YES` otherwise `NO`
IOC_OWNER	Set this to the desired owner of all IOC files (ex. `softioc`)
SINGLE_IOC	If set to yes, the script will attempt to match an IOC directly with prefix, and only convert that IOC

In order to use the module, set up the CONFIGURATION file with the correct parameters. In order to target an individual IOC rather than the entire directory, set the SINGLE_IOC option to YES.

To run the script, navigate to the updateIOC directory that contains it, and type either

./updateIOCs.py

python3 updateIOCs.py

Note that sudo may be required in order to run the script if the IOC_LOCATION is set to a dir that is not owned by the user running the script.

You should now have reorganized IOCs!

Usage notes

When using the script with iocs created with areaDetector 1-9-1, there is an issue with identifying the correct binary location in st.cmd. The reason for this is that the script identifies the camera type by reading the existing st.cmd file and finding the name of the driver, ex: ADProsilica. In areaDetector 1-9-1, all drivers were built into one bin/ directory, and thus the driver cannot be identified.

NSLS2 Deploy Docs

Table of Contents

Important Links

Introduction

Creating a New Bundle

Setting up dev. environment

Building from source

Bundling

Unpacking

Deploying IOCs using the binary bundle

Intro

Deploying new IOCs using binary tarballs

Step 1 - Setup

Step 2 - Download and configure initIOC

Step 3 - Add IOCs to initIOC deployment

Step 5 - Run the Script

initIOC Options

Dependancies

Updating existing IOCs to the new binary distribution format

initIOC Step-by-Step Example

Step 0 - initIOC dependancies

Step 1 - Download/Locate binary bundle

Step 2 - Download initIOC

Step 3 - Edit CONFIGURE

Step 4 - Select IOCs to Deploy

Step 5 - Running the script

Step 6 - Cleanup and testing

Guided Usage

Using the GUI

Conclusion - Some notes and further resources

Using installSynApps

Usage

installCLI

installGUI

Running on Linux vs. Windows

Included Configuration files

External Configure

Auto Build - Legacy

Included scripts - Legacy

Usage - Legacy

Using ioc_deploy

Requirements

Usage

Using updateIOC

Installation

Usage

Usage notes

Step 2 - Download and configure `initIOC`

Step 3 - Add IOCs to `initIOC` deployment

Step 0 - `initIOC` dependancies

Step 2 - Download `initIOC`

Step 3 - Edit `CONFIGURE`