apsbss: IOC Startup and Management

The apsbss software provides information from the APS Proposal and ESAF (experiment safety approval form) databases as PVs to the local controls network. The aps-dm-api (dm for short) package 1 is used to access the APS databases as read-only. The information in the PVs can be used as metadata for inclusion in data files produced

No information is written back to the APS databases from this software.

1

dm: https://anaconda.org/search?q=aps-dm-api

Overview

1. Create the PVs in an EPICS IOC

2. Initialize PVs with beam line name and APS run cycle number

3. Set PV with the Proposal ID number

4. Set PV with the ESAF ID number

5. Retrieve (& update PVs) information from APS databases

Start EPICS IOC

The EPICS Process Variables (PVs) that support this software are provided by an EPICS PV server (IOC). The PVs are defined by including the apsbss.db database file in the startup of the IOC. The database can be add to an existing IOC or run as a stand-alone IOC using the softIoc application from EPICS base.

To ensure that we create PVs with unique names, decide what prefix to use with the EPICS database. Such as, for APS beam line 9-ID, you might pick: 9id:bss: (making sure to end the prefix with the customary :).

Add EPICS database to existing IOC

To include apsbss.db in an existing IOC, copy the file (see Downloads below) into the IOC’s startup directory (typically the directory with st.cmd). Edit the st.cmd file and a line like this just before the call to iocInit:

dbLoadRecords("apsbss.db", "P=9id:bss:")

Once the IOC is started, these PVs should be available to any EPICS client on the local network.

Run EPICS database in softIoc from EPICS Base

For this example, we pick a unique name for this process, (ioc9idbss) based on the PV prefix (9id:bss:).

TIP

If you customize your copy of apsbss_ioc.sh and pre-define the two lines:

# change the program defaults here
DEFAULT_SESSION_NAME=apsbss
DEFAULT_IOC_PREFIX=ioc:bss:

then you do not need to supply these terms as command-line arguments. The usage command will show these the default names you provided.

Start the IOC using the apsbss_ioc.sh tool (as described below), with this command:

$ apsbss_ioc.sh start ioc9idbss 9id:bss:
Starting ioc9idbss with IOC prefix 9id:bss:

Stop the IOC with this command:

$ apsbss_ioc.sh stop ioc9idbss 9id:bss:
ioc9idbss is not running

The IOC restart command, will first stop the IOC (if it is running), then start it.

Report whether or not the IOC is running with this command:

$ apsbss_ioc.sh status ioc9idbss 9id:bss:
ioc9idbss is not running

To interact with the console of an IOC running in a screen session:

$ apsbss_ioc.sh console ioc9idbss 9id:bss:

To end this interaction, type ^A then D which will leave the IOC running. Type exit to stop the IOC from the console.

For diagnostic (or other) purposes, you can also run the IOC without using a screen session. This is the command:

$ apsbss_ioc.sh run ioc9idbss 9id:bss:
dbLoadDatabase("/home/beams1/JEMIAN/.conda/envs/bluesky_2020_5/epics/bin/linux-x86_64/../../dbd/softIoc.dbd")
softIoc_registerRecordDeviceDriver(pdbbase)
dbLoadRecords("apsbss.db", "P=9id:bss:")
iocInit()
Starting iocInit
############################################################################
## EPICS R7.0.4
## Rev. 2020-05-29T13:39+0000
############################################################################
cas warning: Configured TCP port was unavailable.
cas warning: Using dynamically assigned TCP port 39809,
cas warning: but now two or more servers share the same UDP port.
cas warning: Depending on your IP kernel this server may not be
cas warning: reachable with UDP unicast (a host's IP in EPICS_CA_ADDR_LIST)
iocRun: All initialization complete
epics>

You should see the IOC shell prompt:

``epics> ``

If you type exit or otherwise close the session, the IOC will exit.

Shell Script to manage softIoc

To run a stand-alone IOC using the softIoc application from EPICS base, use the supplied IOC management shell script apsbss_ioc.sh:

$ apsbss_ioc.sh
Usage: apsbss_ioc.sh {start|stop|restart|status|checkup|console|run} [NAME [PREFIX]]

        COMMANDS
                console   attach to IOC console if IOC is running in screen
                checkup   check that IOC is running, restart if not
                restart   restart IOC
                run       run IOC in console (not screen)
                start     start IOC
                status    report if IOC is running
                stop      stop IOC

        OPTIONAL TERMS
                NAME      name of IOC session (default: apsbss)
                PREFIX    IOC prefix (default: ioc:bss:)

• apsbss.db

• apsbss_ioc.sh

Note

The shell script assumes that a working softIoc application (from EPICS base) is in your executable $PATH. You should confirm this first before trying to start the IOC.

Note

The softIoc application is run within a screen session so that it remains running even if you close the console session. Confirm that you have the screen application first before trying to start the IOC.

Here’s an example starter script for the IOC from APS 9-ID-C (USAXS). This shell script is stored as file ~/bin/ioc9idcbss.sh with executable permissions:

#!/bin/bash

PROCESS_NAME=ioc9idcbss
IOC_PREFIX=9idc:bss:

# activate the bluesky environment
BLUESKY=/APSshare/anaconda3/Bluesky
source ${BLUESKY}/bin/activate base

# need shell script and EPICS database file
APSBSS=$(dirname $(python -c "import apsbss; print(apsbss.__file__)"))

# need EPICS base/bin/softIoc from this path
export PATH=${PATH}:/APSshare/epics/base-7.0.3/bin/${EPICS_HOST_ARCH}

cd "${APSBSS}"
./apsbss_ioc.sh  "${@}"  "${PROCESS_NAME}" "${IOC_PREFIX}"

Here’s an example cron task for the IOC from APS 9-ID-C (USAXS) to keep the softIoc running (and start the IOC after system reboot):

*/2 * * * * /home/beams/USAXS/bin/ioc9idcbss.sh checkup 2>&1 > /dev/null