EPICSWIKI - User contributions [en]

How to Set Up a Soft IOC Framework on Linux

2009-02-18T19:53:52Z

StefanHeim: Fix typo.

''This evolved from my notes when doing this for the soft IOCs at BESSY. Please add or correct things as you find them wrong or out-of-date.''

The following instructions are based on our Debian Linux machines. (Which version? I don't really care. ''Too stable'', I guess.) Other distributions (or other Unixes) might have different commands and different places for things. This is especially true for the Debian <tt>/etc/init.d</tt> script I'm attaching to this page. If you create a different script for a different distribution, please add it to this page. Others will be able to use it. The general steps will be the same on all distributions, though.

Knowledge of general system administration tasks (creating user accounts etc.) is assumed.

I was giving a talk on [ftp://ftp.desy.de/pub/EPICS/meeting-2007/SoftIOC_Admin.pdf Administration of Soft IOCs under Linux] at the [http://epics.desy.de/content/e2/e127/index_eng.html EPICS Collaboration Meeting in April 2007] that partly covered this issue.

= Introduction =
== Why are we doing this? ==

When using soft IOCs in production, they should be treated as important system services:
* Soft IOCs should be started and stopped by the system.
* There should be a fallback system you can easily switch over to in case of hardware failures.

Other objectives were:
In the same way as for VME IOCs, the application developer should be able to reset the soft IOC without needing root access to the host.
* The IOC application developer should be able to start and stop IOCs manually.

When multiple soft IOCs share the same host (and the same IP address), Channel Access can not tell them apart. Access Security will not be able to distiguish between CA connections coming from different soft IOCs. When debugging CA clients, CA will not be able to tell you which of the soft IOCs a connection goes to.
* Channel Access should be able to distinguish between different soft IOCs, even if they are hosted on the same machine.

I was considering using a virtualization layer (based on VMware) to allow running soft IOCs in an encapsulated environment. I found the effort too high, the layer too thick, and the expected performance hit too hard - only to get a separate IP address for each soft IOC.

When debugging and/or trying to look what is happening on an IOC, the developer does not necessarily know if the database is running on a VME based or on a host based soft IOC.
* Console access (and logging console output) should be uniform: working the same way for soft as for VME IOCs.

The setup necessary to achieve this is described in the document [[How to Set Up Console Access and Logging for VME and Soft IOCs]].

== Concept ==

To allow Access Security telling the soft IOCs apart, they are run under separate user names.

The <tt>procServ</tt> utility will be used as an environment that allows to start soft IOCs in the background and connect to their consoles later, much like the serial consoles of VME IOCs. (See the <tt>procServ</tt> link on the [http://www.aps.anl.gov/epics/extensions/index.php Extensions Page]. Formerly, the <tt>screen</tt> facility was used, but reported problems, e.g. IOCs hanging up after console access, made us change to something less complex.)

Attaching to a soft IOC console will be done through <tt>ssh</tt>, using a special console access key. Ssh is set up with the matching <tt>telnet</tt> commands that reattach to the soft IOCs. Opening an ssh connection using the console access key to the user <tt>ioc123</tt> on the soft IOC host will immediately attach to the console of the soft IOC named <tt>ioc123</tt> (that is running as user <tt>ioc123</tt>).

= Setting up Your Machine =
== Create User Accounts and ssh Access ==

=== Soft IOC Administrator Account ===

Create a generic user account that application developers will use to start/stop soft IOCs. (We call it <tt>iocadm</tt>.)

Put the public ssh keys of the application developers into <tt>~/.ssh/authorized_keys</tt> of <tt>iocadm</tt>.

=== ssh Key Pairs ===

As <tt>iocadm</tt>, create one key pair for this user, and another key pair for console access.

=== Soft IOCs ===

Create one user account for each soft IOC you intend to host. User name should be the IOC name, the group is not really important. (Maybe create a group <tt>iocs</tt> that you put all of them into?)

Into each of the <tt>~/.ssh/authorized_keys</tt> files, put two public keys:
# The public ssh key of <tt>iocadm</tt>.
# The public ssh key for console access.

In front of the console access key, put the <tt>telnet</tt> command to reattach to the soft IOC console. For a user/IOC <tt>ioc123</tt> that provides console access on port <tt>24703</tt>, the line should look like this:

command="telnet localhost 24703" ssh-rsa AAAAB3NzaC1yc2EAAAA.....

== Configure the sudo Facility ==

=== Allow the iocadm User to Start and Stop Soft IOCs ===

On the soft IOC host, allow iocadm to use sudo to execute commands as any of the soft IOC users. <tt>/etc/sudoers</tt> should have a line like:

iocadm ALL = (ioc123, ioc124, ioc125) NOPASSWD: ALL

== Setup the Start/Stop script ==

=== Create the /etc/init.d script ===

I'm attaching the script that we're using as <tt>/etc/init.d/softIOC</tt>. It got quite huge and complex - ''sorry!''. It has been modelled after Debian's skeleton scripts, you should probably adapt it to match the standards that your distribution implies.

It contains the local settings for where to find things, routines to read in the configuration file, the code necessary to start/stop a soft IOC as a different user under <tt>procServ</tt>, and the usual <tt>init.d</tt> script stuff that checks command line arguments and calls the other routines.

''If you have a script working for a different distribution, please add it to this page, as it could make life easier for others!''

=== Create the Configuration File ===

The configuration file contains a section for each of the soft IOCs. A section starts with the IOC name followed by a colon, and ends with an empty line.

Within a section you can set special variables used by the <tt>softIOC</tt> script as well as environment variables that will be set for the soft IOC.

The special section <tt>global:</tt> contains settings that will be applied to ''all'' soft IOCs (may be overridden by the IOC section).

The special line <tt>auto:</tt> contains the names of the soft IOCs that should be started when the script is run as part of the system boot-up process.

Section and IOC names are not case sensitive.

So a minimal configuration file could look like this (remember the empty line that is required after each section):

AUTO: ioc123

GLOBAL:

ioc123:

ioc124:

ioc125:

== Distribute the Required Stuff to the Soft IOC Host ==

=== EPICS Base ===

Soft IOCS will need libraries from EPICS base. Make sure these are existing and can be found.

=== Code and Databases ===

Add the soft IOC host to the code deployment scheme you are using. The soft IOC binaries, databases, and start up scripts must be available for the soft IOCs to be started.

= Start Your Soft IOCs =

== Start the IOCs using the startup script ==

Starting and stopping the soft IOCs should work now! Ssh to the soft IOC host as <tt>iocadm</tt> and try calling the startup script:

/etc/init.d/softIOC start ioc123

== Watch them run ==

Ssh to the soft IOC host using the console access key and see if you can get access to the IOC console:

ssh -i ~iocadm/.ssh/console_access -t ioc123@iochost

You should be directly connected to your IOC's console.

== Check if Starting IOCs at reboot works ==

If you made entries to the <tt>auto:</tt> section, reboot the machine to check that starting IOCs at boot time works.

'''''Good luck!'''''

[mailto:Ralph.Lange_at_bessy.de Ralph Lange (BESSY)]

created: [[User:RalphLange|Ralph]] 05:08, 26 Apr 2007 (CDT)

last edit: [[User:RalphLange|Ralph]] 11:17, 12 Feb 2009 (CDT)

----

= The Startup Script =

<tt>/etc/init.d/softIOC</tt> script for Debian Linux

<pre>
#! /bin/sh
# Author: <Ralph.Lange@bessy.de>
#
# History:
# 2006-03-12: Adapted from D. Herrendörfer's ca-gateway script
# 2006-04-04: Bugfix in config file parser
# 2008-05-20: Adapted to procServ

# Do NOT "set -e"

# !! This script is located on a mounted file system
# !! It must be run after the mountnfs.sh script

PATH=/sbin:/usr/sbin:/bin:/usr/bin
DESC="EPICS soft IOCs"
SCRIPTNAME=/etc/init.d/softIOC
HOST=`uname -n`

PROCSERV=/usr/local/bin/procServ
CONFFILE=/opt/IOC/softIOC/softiocs.$HOST
HOMEDIRS=/home/controls

# Check for config file
if [ ! -r $CONFFILE ]
then
echo "Error: Can't find configuration file $CONFFILE!"
exit 1
fi

#
# Functions that read in the configuration file
#
clear_options()
{
for option in "CA_AUTO" "CA_ADDR" "CA_PORT" "IOC_USER" "PORT"
do
unset $option;
done
}

evaluate_options()
{
while [ $# != 0 ]
do
TAG=`echo $1 | tr [:lower:] [:upper:]`
case "$TAG" in
"#") ;;
"CA_AUTO" | "CA_ADDR" | "CA_PORT" | "COREDUMPSIZE" | \
"HOMEDIR" | "BOOTDIR" | "IOC_USER" | "PORT" )
# Test the presence of values for the current option
OPTION=$TAG
shift
if [ -z $TAG -o $TAG = "#" ]
then
echo "$CONFFILE: Value(s) required for $TAG.";
exit 1
else
VALUE=$1
shift
fi
# If more values follow assign them too
while [ $1 != '#' -a $# != 0 ]
do
VALUE="$VALUE $1"
shift;
done
eval ${OPTION}=\$VALUE
;;
*) echo "$CONFFILE: Unknown option $1."
exit 1
esac
shift
done
}

default_options()
{
# Set IOC defaults for options
# (may be overridden in config file)
IOC_LC=$1
IOC_UC=`echo $1 | tr [:lower:] [:upper:]`

if [[ "$IOC_LC" = "mdi"* ]]
then
TOP=DiagR3.14.9.0.1-Tornado2.2.1
elif [[ "$IOC_LC" = *"p" ]]
then
TOP=MLS-Controls
else
TOP=BII-Controls/base-3-14
fi

BOOTDIR=/opt/IOC/$TOP/boot/$IOC_UC
HOMEDIR=$HOMEDIRS/$IOC_LC
PIDFILE=$HOMEDIR/$IOC_LC.pid
ENVFILE=$HOMEDIR/$IOC_LC.env
IOC_USER=$IOC_LC
}

assign_options()
{
# Find $TAG section
# Remove comments
# Remove leading and trailing whitespace
# Remove $TAG: tag
# Join lines ending with a "\"
# Mark end of option with a "#"
# Remove unnecessary whitespace
TAG=$1
SECTION=`sed -n "/^$TAG:/I,/^[\t ]*$/p" $CONFFILE | \
sed -n '/^[^#]/p' | \
sed -e 's/^[ \t]*//' -e 's/[ \t]*$//' \
-e "s/$TAG://I" \
-e :a -e '/\\\\$/N; s/\\\\\\n//; ta' \
-e 's/$/ \#/' \
-e 's/[\t ]/ /g'`
evaluate_options $SECTION
}

get_iocs()
{
# Get IOCs from command line or AUTO: entry in configuration file
# Test for matching section in configuration file
if [ $# = 0 ]
then
TEST_LIST=`grep -i '^AUTO:' "$CONFFILE" | cut -d: -f2- | tr [:upper:] [:lower:]`
else
TEST_LIST="$@"
fi

CHECKED_LIST=""
for IOC in $TEST_LIST
do
grep -qi "^$IOC:" $CONFFILE
if [ $? = 0 ]
then
CHECKED_LIST="$CHECKED_LIST $IOC"
fi
done
echo $CHECKED_LIST
}

set_cmdenvopts()
{
# Set up the environment setup string

SETENV="LINES=60 "`test ! -z "$CA_AUTO" && echo "export EPICS_CA_AUTO_ADDR_LIST=\"$CA_AUTO\";"`
SETENV="$SETENV "`test ! -z "$CA_ADDR" && echo "export EPICS_CA_ADDR_LIST=\"$CA_ADDR\";"`
SETENV="$SETENV "`test ! -z "$CA_PORT" && echo "export EPICS_CA_SERVER_PORT=\"$CA_PORT\";"`
SETENV="$SETENV "`test ! -z "$BOOTDIR" && echo "export BOOTDIR=\"$BOOTDIR\";"`

# Set up the options for the procserv program

PROCSERVOPTS=`test ! -z "$IOC_USER" && echo "-n \"$IOC_USER\""`
PROCSERVOPTS="$PROCSERVOPTS "`test ! -z "$COREDUMPSIZE" && echo "--coresize \"$COREDUMPSIZE\""`
PROCSERVOPTS="$PROCSERVOPTS -q -c $BOOTDIR -p $PIDFILE -i ^D^C^] $PORT"
}

#
# Function that starts the daemon/service
#
do_start()
{
# Return
# 0 if daemon has been started
# 1 if daemon was already running
# 2 if daemon could not be started
# Add code here, if necessary, that waits for the process to be ready
# to handle requests from services started subsequently which depend
# on this one. As a last resort, sleep for some time.

echo -n "Starting soft IOCs ... "
MYIOCS=`get_iocs $@`
[ "$MYIOCS" = "" ] && echo -n "<none> "
for IOC in $MYIOCS
do
echo -n "$IOC "
clear_options
default_options "$IOC"
assign_options "GLOBAL"
assign_options "$IOC"
set_cmdenvopts

if [ -d $BOOTDIR ]
then
if [ -d $HOMEDIR ]
then

sudo -H -u $IOC sh -c "$SETENV (env > $ENVFILE; /sbin/start-stop-daemon --start --quiet --chdir $BOOTDIR \
--pidfile $PIDFILE --startas $PROCSERV --name procServ --test > /dev/null)"
if [ "$?" = 1 ]
then
echo -n "<was running> "
else
sudo -H -u $IOC sh -c "$SETENV (env > $ENVFILE; /sbin/start-stop-daemon --start --quiet --chdir $BOOTDIR \
--pidfile $PIDFILE --startas $PROCSERV --name procServ -- $PROCSERVOPTS ./st.cmd)"
if [ "$?" = 1 ]
then
echo -n "<failed> "
fi
fi

else
echo -e "\nWarning: Home directory $HOMEDIR does not exist! Ignoring $IOC"
fi
else
echo -e "\nWarning: Boot directory $BOOTDIR does not exist! Ignoring $IOC"
fi
done
echo "... done."
}

#
# Function that stops the daemon/service
#
do_stop()
{
# Return
# 0 if daemon has been stopped
# 1 if daemon was already stopped
# 2 if daemon could not be stopped
# other if a failure occurred

echo -n "Stopping soft IOCs ... "
MYIOCS=`get_iocs $@`
[ "$MYIOCS" = "" ] && echo -n "<none> "
for IOC in $MYIOCS
do
echo -n "$IOC "
clear_options
default_options "$IOC"
assign_options "GLOBAL"
assign_options "$IOC"
set_cmdenvopts

sudo -H -u $IOC sh -c "/sbin/start-stop-daemon --stop --quiet --pidfile $PIDFILE --name procServ --test > /dev/null"
if [ $? = 1 ]
then
echo -n "<not running> "
else
sudo -H -u $IOC sh -c "/sbin/start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 --pidfile $PIDFILE --name procServ"
if [ $? = 1 ]
then
echo -n "<failed> "
else
sudo -H -u $IOC sh -c "rm -f $PIDFILE"
fi
fi
done
echo "... done."
}

#
# Function that sends a SIGHUP to the daemon/service
#
do_reload() {
#
# If the daemon can reload its configuration without
# restarting (for example, when it is sent a SIGHUP),
# then implement that here.
#
# start-stop-daemon --stop --signal 1 --quiet --pidfile $PIDFILE --name $NAME
# return 0

echo "Restarting soft IOCs ... "
STARTDIR=$PWD
IOCS=`get_iocs $@`
[ "$IOCS" = "" ] && echo -n "<none> "
for IOC in $IOCS
do
echo -n "$IOC "
clear_options
default_options "$IOC"
assign_options "GLOBAL"
assign_options "$IOC"
if [ -d $BOOTDIR ]
then
cd "$BOOTDIR"
# restart it!
echo -e "\ndebug: Reloading ioc $IOC"
cd "$STARTDIR"
else
echo -e "\nWarning: Boot directory $BOOTDIR does not exist! Entry for $NET ignored!"
fi
done
echo "... done."
}

COMMAND=$1
shift
IOCS=`echo $@ | tr [:upper:] [:lower:]`

case "$COMMAND" in
start)
do_start $IOCS
;;
stop)
do_stop $IOCS
;;
#reload|force-reload)
#
# If do_reload() is not implemented then leave this commented out
# and leave 'force-reload' as an alias for 'restart'.
#
#log_daemon_msg "Reloading $DESC" "$NAME"
#do_reload
#log_end_msg $?
#;;
restart|force-reload)
#
# If the "reload" option is implemented then remove the
# 'force-reload' alias
#
do_stop $IOCS
sleep 1
do_start $IOCS
;;
*)
#echo "Usage: $SCRIPTNAME {start|stop|restart|reload|force-reload}" >&2
echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload} [iocs ...]" >&2
exit 3
;;
esac
</pre>

How to Set Up a Soft IOC Framework on Linux

2009-02-18T16:56:04Z

StefanHeim: Break excessively long lines in init script. This time alter the correct lines.

''This evolved from my notes when doing this for the soft IOCs at BESSY. Please add or correct things as you find them wrong or out-of-date.''

The following instructions are based on our Debian Linux machines. (Which version? I don't really care. ''Too stable'', I guess.) Other distributions (or other Unixes) might have different commands and different places for things. This is especially true for the Debian <tt>/etc/init.d</tt> script I'm attaching to this page. If you create a different script for a different distribution, please add it to this page. Others will be able to use it. The general steps will be the same on all distributions, though.

Knowledge of general system administration tasks (creating user accounts etc.) is assumed.

I was giving a talk on [ftp://ftp.desy.de/pub/EPICS/meeting-2007/SoftIOC_Admin.pdf Administration of Soft IOCs under Linux] at the [http://epics.desy.de/content/e2/e127/index_eng.html EPICS Collaboration Meeting in April 2007] that partly covered this issue.

= Introduction =
== Why are we doing this? ==

When using soft IOCs in production, they should be treated as important system services:
* Soft IOCs should be started and stopped by the system.
* There should be a fallback system you can easily switch over to in case of hardware failures.

Other objectives were:
In the same way as for VME IOCs, the application developer should be able to reset the soft IOC without needing root access to the host.
* The IOC application developer should be able to start and stop IOCs manually.

When multiple soft IOCs share the same host (and the same IP address), Channel Access can not tell them apart. Access Security will not be able to distiguish between CA connections coming from different soft IOCs. When debugging CA clients, CA will not be able to tell you which of the soft IOCs a connection goes to.
* Channel Access should be able to distinguish between different soft IOCs, even if they are hosted on the same machine.

I was considering using a virtualization layer (based on VMware) to allow running soft IOCs in an encapsulated environment. I found the effort too high, the layer too thick, and the expected performance hit too hard - only to get a separate IP address for each soft IOC.

When debugging and/or trying to look what is happening on an IOC, the developer does not necessarily know if the database is running on a VME based or on a host based soft IOC.
* Console access (and logging console output) should be uniform: working the same way for soft as for VME IOCs.

The setup necessary to achieve this is described in the document [[How to Set Up Console Access and Logging for VME and Soft IOCs]].

== Concept ==

To allow Access Security telling the soft IOCs apart, they are run under separate user names.

The <tt>procServ</tt> utility will be used as an environment that allows to start soft IOCs in the background and connect to their consoles later, much like the serial consoles of VME IOCs. (See the <tt>procServ</tt> link on the [http://www.aps.anl.gov/epics/extensions/index.php Extensions Page]. Formerly, the <tt>screen</tt> facility was used, but reported problems, e.g. IOCs hanging up after console access, made us change to something less complex.)

Attaching to a soft IOC console will be done through <tt>ssh</tt>, using a special console access key. Ssh is set up with the matching <tt>telnet</tt> commands that reattach to the soft IOCs. Opening an ssh connection using the console access key to the user <tt>ioc123</tt> on the soft IOC host will immediately attach to the console of the soft IOC named <tt>ioc123</tt> (that is running as user <tt>ioc123</tt>).

= Setting up Your Machine =
== Create User Accounts and ssh Access ==

=== Soft IOC Administrator Account ===

Create a generic user account that application developers will use to start/stop soft IOCs. (We call it <tt>iocadm</tt>.)

Put the public ssh keys of the application developers into <tt>~/.ssh/authorized_keys</tt> of <tt>iocadm</tt>.

=== ssh Key Pairs ===

As <tt>iocadm</tt>, create one key pair for this user, and another key pair for console access.

=== Soft IOCs ===

Create one user account for each soft IOC you intend to host. User name should be the IOC name, the group is not really important. (Maybe create a group <tt>iocs</tt> that you put all of them into?)

Into each of the <tt>~/.ssh/authorized_keys</tt> files, put two public keys:
# The public ssh key of <tt>iocadm</tt>.
# The public ssh key for console access.

In front of the console access key, put the <tt>telnet</tt> command to reattach to the soft IOC console. For a user/IOC <tt>ioc123</tt> that provides console access on port <tt>24703</tt>, the line should look like this:

command="telnet localhost 24703" ssh-rsa AAAAB3NzaC1yc2EAAAA.....

== Configure the sudo Facility ==

=== Allow the iocadm User to Start and Stop Soft IOCs ===

On the soft IOC host, allow iocadm to use sudo to execute commands as any of the soft IOC users. <tt>/etc/sudoers</tt> should have a line like:

iocadm ALL = (ioc123, ioc124, ioc125) NOPASSWD: ALL

== Setup the Start/Stop script ==

=== Create the /etc/init.d script ===

I'm attaching the script that we're using as <tt>/etc/init.d/softIOC</tt>. It got quite huge and complex - ''sorry!''. It has been modelled after Debian's skeleton scripts, you should probably adapt it to match the standards that your distribution implies.

It contains the local settings for where to find things, routines to read in the configuration file, the code necessary to start/stop a soft IOC as a different user under <tt>procServ</tt>, and the usual <tt>init.d</tt> script stuff that checks command line arguments and calls the other routines.

''If you have a script working for a different distribution, please add it to this page, as it could make life easier for others!''

=== Create the Configuration File ===

The configuration file contains a section for each of the soft IOCs. A section starts with the IOC name followed by a colon, and ends with an empty line.

Within a section you can set special variables used by the <tt>softIOC</tt> script as well as environment variables that will be set for the soft IOC.

The special section <tt>global:</tt> contains settings that will be applied to ''all'' soft IOCs (may be overridden by the IOC section).

The special line <tt>auto:</tt> contains the names of the soft IOCs that should be started when the script is run as part of the system boot-up process.

Section and IOC names are not case sensitive.

So a minimal configuration file could look like this (remember the empty line that is required after each section):

AUTO: ioc123

GLOBAL:

ioc123:

ioc124:

ioc125:

== Distribute the Required Stuff to the Soft IOC Host ==

=== EPICS Base ===

Soft IOCS will need libraries from EPICS base. Make sure these are existing and can be found.

=== Code and Databases ===

Add the soft IOC host to the code deployment scheme you are using. The soft IOC binaries, databases, and start up scripts must be available for the soft IOCs to be started.

= Start Your Soft IOCs =

== Start the IOCs using the startup script ==

Starting and stopping the soft IOCs should work now! Ssh to the soft IOC host as <tt>iocadm</tt> and try calling the startup script:

/etc/init.d/softIOC start ioc123

== Watch them run ==

Ssh to the soft IOC host using the console access key and see if you can get access to the IOC console:

ssh -i ~iocadm/.ssh/console_access -t ioc123@iochost

You should be directly connected to your IOC's console.

== Check if Starting IOCs at reboot works ==

If you made entries to the <tt>auto:</tt> section, reboot the machine to check that starting IOCs at boot time works.

'''''Good luck!'''''

[mailto:Ralph.Lange_at_bessy.de Ralph Lange (BESSY)]

created: [[User:RalphLange|Ralph]] 05:08, 26 Apr 2007 (CDT)

last edit: [[User:RalphLange|Ralph]] 11:17, 12 Feb 2009 (CDT)

----

= The Startup Script =

<tt>/etc/init.d/softIOC</tt> script for Debian Linux

<pre>
#! /bin/sh
# Author: <Ralph.Lange@bessy.de>
#
# History:
# 2006-03-12: Adapted from D. Herrendörfer's ca-gateway script
# 2006-04-04: Bugfix in config file parser
# 2008-05-20: Adapted to procServ

# Do NOT "set -e"

# !! This script is located on a mounted file system
# !! It must be run after the mountnfs.sh script

PATH=/sbin:/usr/sbin:/bin:/usr/bin
DESC="EPICS soft IOCs"
SCRIPTNAME=/etc/init.d/softIOC
HOST=`uname -n`

PROCSERV=/usr/local/bin/procServ
CONFFILE=/opt/IOC/softIOC/softiocs.$HOST
HOMEDIRS=/home/controls

# Check for config file
if [ ! -r $CONFFILE ]
then
echo "Error: Can't find configuration file $CONFFILE!"
exit 1
fi

#
# Functions that read in the configuration file
#
clear_options()
{
for option in "CA_AUTO" "CA_ADDR" "CA_PORT" "IOC_USER" "PORT"
do
unset $option;
done
}

evaluate_options()
{
while [ $# != 0 ]
do
TAG=`echo $1 | tr [:lower:] [:upper:]`
case "$TAG" in
"#") ;;
"CA_AUTO" | "CA_ADDR" | "CA_PORT" | "COREDUMPSIZE" | \
"HOMEDIR" | "BOOTDIR" | "IOC_USER" | "PORT" )
# Test the presence of values for the current option
OPTION=$TAG
shift
if [ -z $TAG -o $TAG = "#" ]
then
echo "$CONFFILE: Value(s) required for $TAG.";
exit 1
else
VALUE=$1
shift
fi
# If more values follow assign them too
while [ $1 != '#' -a $# != 0 ]
do
VALUE="$VALUE $1"
shift;
done
eval ${OPTION}=\$VALUE
;;
*) echo "$CONFFILE: Unknown option $1."
exit 1
esac
shift
done
}

default_options()
{
# Set IOC defaults for options
# (may be overridden in config file)
IOC_LC=$1
IOC_UC=`echo $1 | tr [:lower:] [:upper:]`

if [[ "$IOC_LC" = "mdi"* ]]
then
TOP=DiagR3.14.9.0.1-Tornado2.2.1
elif [[ "$IOC_LC" = *"p" ]]
then
TOP=MLS-Controls
else
TOP=BII-Controls/base-3-14
fi

BOOTDIR=/opt/IOC/$TOP/boot/$IOC_UC
HOMEDIR=$HOMEDIRS/$IOC_LC
PIDFILE=$HOMEDIR/$IOC_LC.pid
ENVFILE=$HOMEDIR/$IOC_LC.env
IOC_USER=$IOC_LC
}

assign_options()
{
# Find $TAG section
# Remove comments
# Remove leading and trailing whitespace
# Remove $TAG: tag
# Join lines ending with a "\"
# Mark end of option with a "#"
# Remove unecessary whitespace
TAG=$1
SECTION=`sed -n "/^$TAG:/I,/^[\t ]*$/p" $CONFFILE | \
sed -n '/^[^#]/p' | \
sed -e 's/^[ \t]*//' -e 's/[ \t]*$//' \
-e "s/$TAG://I" \
-e :a -e '/\\\\$/N; s/\\\\\\n//; ta' \
-e 's/$/ \#/' \
-e 's/[\t ]/ /g'`
evaluate_options $SECTION
}

get_iocs()
{
# Get IOCs from command line or AUTO: entry in configuration file
# Test for matching section in configuration file
if [ $# = 0 ]
then
TEST_LIST=`grep -i '^AUTO:' "$CONFFILE" | cut -d: -f2- | tr [:upper:] [:lower:]`
else
TEST_LIST="$@"
fi

CHECKED_LIST=""
for IOC in $TEST_LIST
do
grep -qi "^$IOC:" $CONFFILE
if [ $? = 0 ]
then
CHECKED_LIST="$CHECKED_LIST $IOC"
fi
done
echo $CHECKED_LIST
}

set_cmdenvopts()
{
# Set up the environment setup string

SETENV="LINES=60 "`test ! -z "$CA_AUTO" && echo "export EPICS_CA_AUTO_ADDR_LIST=\"$CA_AUTO\";"`
SETENV="$SETENV "`test ! -z "$CA_ADDR" && echo "export EPICS_CA_ADDR_LIST=\"$CA_ADDR\";"`
SETENV="$SETENV "`test ! -z "$CA_PORT" && echo "export EPICS_CA_SERVER_PORT=\"$CA_PORT\";"`
SETENV="$SETENV "`test ! -z "$BOOTDIR" && echo "export BOOTDIR=\"$BOOTDIR\";"`

# Set up the options for the procserv program

PROCSERVOPTS=`test ! -z "$IOC_USER" && echo "-n \"$IOC_USER\""`
PROCSERVOPTS="$PROCSERVOPTS "`test ! -z "$COREDUMPSIZE" && echo "--coresize \"$COREDUMPSIZE\""`
PROCSERVOPTS="$PROCSERVOPTS -q -c $BOOTDIR -p $PIDFILE -i ^D^C^] $PORT"
}

#
# Function that starts the daemon/service
#
do_start()
{
# Return
# 0 if daemon has been started
# 1 if daemon was already running
# 2 if daemon could not be started
# Add code here, if necessary, that waits for the process to be ready
# to handle requests from services started subsequently which depend
# on this one. As a last resort, sleep for some time.

echo -n "Starting soft IOCs ... "
MYIOCS=`get_iocs $@`
[ "$MYIOCS" = "" ] && echo -n "<none> "
for IOC in $MYIOCS
do
echo -n "$IOC "
clear_options
default_options "$IOC"
assign_options "GLOBAL"
assign_options "$IOC"
set_cmdenvopts

if [ -d $BOOTDIR ]
then
if [ -d $HOMEDIR ]
then

sudo -H -u $IOC sh -c "$SETENV (env > $ENVFILE; /sbin/start-stop-daemon --start --quiet --chdir $BOOTDIR \
--pidfile $PIDFILE --startas $PROCSERV --name procServ --test > /dev/null)"
if [ "$?" = 1 ]
then
echo -n "<was running> "
else
sudo -H -u $IOC sh -c "$SETENV (env > $ENVFILE; /sbin/start-stop-daemon --start --quiet --chdir $BOOTDIR \
--pidfile $PIDFILE --startas $PROCSERV --name procServ -- $PROCSERVOPTS ./st.cmd)"
if [ "$?" = 1 ]
then
echo -n "<failed> "
fi
fi

else
echo -e "\nWarning: Home directory $HOMEDIR does not exist! Ignoring $IOC"
fi
else
echo -e "\nWarning: Boot directory $BOOTDIR does not exist! Ignoring $IOC"
fi
done
echo "... done."
}

#
# Function that stops the daemon/service
#
do_stop()
{
# Return
# 0 if daemon has been stopped
# 1 if daemon was already stopped
# 2 if daemon could not be stopped
# other if a failure occurred

echo -n "Stopping soft IOCs ... "
MYIOCS=`get_iocs $@`
[ "$MYIOCS" = "" ] && echo -n "<none> "
for IOC in $MYIOCS
do
echo -n "$IOC "
clear_options
default_options "$IOC"
assign_options "GLOBAL"
assign_options "$IOC"
set_cmdenvopts

sudo -H -u $IOC sh -c "/sbin/start-stop-daemon --stop --quiet --pidfile $PIDFILE --name procServ --test > /dev/null"
if [ $? = 1 ]
then
echo -n "<not running> "
else
sudo -H -u $IOC sh -c "/sbin/start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 --pidfile $PIDFILE --name procServ"
if [ $? = 1 ]
then
echo -n "<failed> "
else
sudo -H -u $IOC sh -c "rm -f $PIDFILE"
fi
fi
done
echo "... done."
}

#
# Function that sends a SIGHUP to the daemon/service
#
do_reload() {
#
# If the daemon can reload its configuration without
# restarting (for example, when it is sent a SIGHUP),
# then implement that here.
#
# start-stop-daemon --stop --signal 1 --quiet --pidfile $PIDFILE --name $NAME
# return 0

echo "Restarting soft IOCs ... "
STARTDIR=$PWD
IOCS=`get_iocs $@`
[ "$IOCS" = "" ] && echo -n "<none> "
for IOC in $IOCS
do
echo -n "$IOC "
clear_options
default_options "$IOC"
assign_options "GLOBAL"
assign_options "$IOC"
if [ -d $BOOTDIR ]
then
cd "$BOOTDIR"
# restart it!
echo -e "\ndebug: Reloading ioc $IOC"
cd "$STARTDIR"
else
echo -e "\nWarning: Boot directory $BOOTDIR does not exist! Entry for $NET ignored!"
fi
done
echo "... done."
}

COMMAND=$1
shift
IOCS=`echo $@ | tr [:upper:] [:lower:]`

case "$COMMAND" in
start)
do_start $IOCS
;;
stop)
do_stop $IOCS
;;
#reload|force-reload)
#
# If do_reload() is not implemented then leave this commented out
# and leave 'force-reload' as an alias for 'restart'.
#
#log_daemon_msg "Reloading $DESC" "$NAME"
#do_reload
#log_end_msg $?
#;;
restart|force-reload)
#
# If the "reload" option is implemented then remove the
# 'force-reload' alias
#
do_stop $IOCS
sleep 1
do_start $IOCS
;;
*)
#echo "Usage: $SCRIPTNAME {start|stop|restart|reload|force-reload}" >&2
echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload} [iocs ...]" >&2
exit 3
;;
esac
</pre>

How to Set Up a Soft IOC Framework on Linux

2009-02-18T16:51:19Z

StefanHeim: Break excessively long lines in init script.

''This evolved from my notes when doing this for the soft IOCs at BESSY. Please add or correct things as you find them wrong or out-of-date.''

The following instructions are based on our Debian Linux machines. (Which version? I don't really care. ''Too stable'', I guess.) Other distributions (or other Unixes) might have different commands and different places for things. This is especially true for the Debian <tt>/etc/init.d</tt> script I'm attaching to this page. If you create a different script for a different distribution, please add it to this page. Others will be able to use it. The general steps will be the same on all distributions, though.

Knowledge of general system administration tasks (creating user accounts etc.) is assumed.

I was giving a talk on [ftp://ftp.desy.de/pub/EPICS/meeting-2007/SoftIOC_Admin.pdf Administration of Soft IOCs under Linux] at the [http://epics.desy.de/content/e2/e127/index_eng.html EPICS Collaboration Meeting in April 2007] that partly covered this issue.

= Introduction =
== Why are we doing this? ==

When using soft IOCs in production, they should be treated as important system services:
* Soft IOCs should be started and stopped by the system.
* There should be a fallback system you can easily switch over to in case of hardware failures.

Other objectives were:
In the same way as for VME IOCs, the application developer should be able to reset the soft IOC without needing root access to the host.
* The IOC application developer should be able to start and stop IOCs manually.

When multiple soft IOCs share the same host (and the same IP address), Channel Access can not tell them apart. Access Security will not be able to distiguish between CA connections coming from different soft IOCs. When debugging CA clients, CA will not be able to tell you which of the soft IOCs a connection goes to.
* Channel Access should be able to distinguish between different soft IOCs, even if they are hosted on the same machine.

I was considering using a virtualization layer (based on VMware) to allow running soft IOCs in an encapsulated environment. I found the effort too high, the layer too thick, and the expected performance hit too hard - only to get a separate IP address for each soft IOC.

When debugging and/or trying to look what is happening on an IOC, the developer does not necessarily know if the database is running on a VME based or on a host based soft IOC.
* Console access (and logging console output) should be uniform: working the same way for soft as for VME IOCs.

The setup necessary to achieve this is described in the document [[How to Set Up Console Access and Logging for VME and Soft IOCs]].

== Concept ==

To allow Access Security telling the soft IOCs apart, they are run under separate user names.

The <tt>procServ</tt> utility will be used as an environment that allows to start soft IOCs in the background and connect to their consoles later, much like the serial consoles of VME IOCs. (See the <tt>procServ</tt> link on the [http://www.aps.anl.gov/epics/extensions/index.php Extensions Page]. Formerly, the <tt>screen</tt> facility was used, but reported problems, e.g. IOCs hanging up after console access, made us change to something less complex.)

Attaching to a soft IOC console will be done through <tt>ssh</tt>, using a special console access key. Ssh is set up with the matching <tt>telnet</tt> commands that reattach to the soft IOCs. Opening an ssh connection using the console access key to the user <tt>ioc123</tt> on the soft IOC host will immediately attach to the console of the soft IOC named <tt>ioc123</tt> (that is running as user <tt>ioc123</tt>).

= Setting up Your Machine =
== Create User Accounts and ssh Access ==

=== Soft IOC Administrator Account ===

Create a generic user account that application developers will use to start/stop soft IOCs. (We call it <tt>iocadm</tt>.)

Put the public ssh keys of the application developers into <tt>~/.ssh/authorized_keys</tt> of <tt>iocadm</tt>.

=== ssh Key Pairs ===

As <tt>iocadm</tt>, create one key pair for this user, and another key pair for console access.

=== Soft IOCs ===

Create one user account for each soft IOC you intend to host. User name should be the IOC name, the group is not really important. (Maybe create a group <tt>iocs</tt> that you put all of them into?)

Into each of the <tt>~/.ssh/authorized_keys</tt> files, put two public keys:
# The public ssh key of <tt>iocadm</tt>.
# The public ssh key for console access.

In front of the console access key, put the <tt>telnet</tt> command to reattach to the soft IOC console. For a user/IOC <tt>ioc123</tt> that provides console access on port <tt>24703</tt>, the line should look like this:

command="telnet localhost 24703" ssh-rsa AAAAB3NzaC1yc2EAAAA.....

== Configure the sudo Facility ==

=== Allow the iocadm User to Start and Stop Soft IOCs ===

On the soft IOC host, allow iocadm to use sudo to execute commands as any of the soft IOC users. <tt>/etc/sudoers</tt> should have a line like:

iocadm ALL = (ioc123, ioc124, ioc125) NOPASSWD: ALL

== Setup the Start/Stop script ==

=== Create the /etc/init.d script ===

I'm attaching the script that we're using as <tt>/etc/init.d/softIOC</tt>. It got quite huge and complex - ''sorry!''. It has been modelled after Debian's skeleton scripts, you should probably adapt it to match the standards that your distribution implies.

It contains the local settings for where to find things, routines to read in the configuration file, the code necessary to start/stop a soft IOC as a different user under <tt>procServ</tt>, and the usual <tt>init.d</tt> script stuff that checks command line arguments and calls the other routines.

''If you have a script working for a different distribution, please add it to this page, as it could make life easier for others!''

=== Create the Configuration File ===

The configuration file contains a section for each of the soft IOCs. A section starts with the IOC name followed by a colon, and ends with an empty line.

Within a section you can set special variables used by the <tt>softIOC</tt> script as well as environment variables that will be set for the soft IOC.

The special section <tt>global:</tt> contains settings that will be applied to ''all'' soft IOCs (may be overridden by the IOC section).

The special line <tt>auto:</tt> contains the names of the soft IOCs that should be started when the script is run as part of the system boot-up process.

Section and IOC names are not case sensitive.

So a minimal configuration file could look like this (remember the empty line that is required after each section):

AUTO: ioc123

GLOBAL:

ioc123:

ioc124:

ioc125:

== Distribute the Required Stuff to the Soft IOC Host ==

=== EPICS Base ===

Soft IOCS will need libraries from EPICS base. Make sure these are existing and can be found.

=== Code and Databases ===

Add the soft IOC host to the code deployment scheme you are using. The soft IOC binaries, databases, and start up scripts must be available for the soft IOCs to be started.

= Start Your Soft IOCs =

== Start the IOCs using the startup script ==

Starting and stopping the soft IOCs should work now! Ssh to the soft IOC host as <tt>iocadm</tt> and try calling the startup script:

/etc/init.d/softIOC start ioc123

== Watch them run ==

Ssh to the soft IOC host using the console access key and see if you can get access to the IOC console:

ssh -i ~iocadm/.ssh/console_access -t ioc123@iochost

You should be directly connected to your IOC's console.

== Check if Starting IOCs at reboot works ==

If you made entries to the <tt>auto:</tt> section, reboot the machine to check that starting IOCs at boot time works.

'''''Good luck!'''''

[mailto:Ralph.Lange_at_bessy.de Ralph Lange (BESSY)]

created: [[User:RalphLange|Ralph]] 05:08, 26 Apr 2007 (CDT)

last edit: [[User:RalphLange|Ralph]] 11:17, 12 Feb 2009 (CDT)

----

= The Startup Script =

<tt>/etc/init.d/softIOC</tt> script for Debian Linux

<pre>
#! /bin/sh
# Author: <Ralph.Lange@bessy.de>
#
# History:
# 2006-03-12: Adapted from D. Herrendörfer's ca-gateway script
# 2006-04-04: Bugfix in config file parser
# 2008-05-20: Adapted to procServ

# Do NOT "set -e"

# !! This script is located on a mounted file system
# !! It must be run after the mountnfs.sh script

PATH=/sbin:/usr/sbin:/bin:/usr/bin
DESC="EPICS soft IOCs"
SCRIPTNAME=/etc/init.d/softIOC
HOST=`uname -n`

PROCSERV=/usr/local/bin/procServ
CONFFILE=/opt/IOC/softIOC/softiocs.$HOST
HOMEDIRS=/home/controls

# Check for config file
if [ ! -r $CONFFILE ]
then
echo "Error: Can't find configuration file $CONFFILE!"
exit 1
fi

#
# Functions that read in the configuration file
#
clear_options()
{
for option in "CA_AUTO" "CA_ADDR" "CA_PORT" "IOC_USER" "PORT"
do
unset $option;
done
}

evaluate_options()
{
while [ $# != 0 ]
do
TAG=`echo $1 | tr [:lower:] [:upper:]`
case "$TAG" in
"#") ;;
"CA_AUTO" | "CA_ADDR" | "CA_PORT" | "COREDUMPSIZE" | \
"HOMEDIR" | "BOOTDIR" | "IOC_USER" | "PORT" )
# Test the presence of values for the current option
OPTION=$TAG
shift
if [ -z $TAG -o $TAG = "#" ]
then
echo "$CONFFILE: Value(s) required for $TAG.";
exit 1
else
VALUE=$1
shift
fi
# If more values follow assign them too
while [ $1 != '#' -a $# != 0 ]
do
VALUE="$VALUE $1"
shift;
done
eval ${OPTION}=\$VALUE
;;
*) echo "$CONFFILE: Unknown option $1."
exit 1
esac
shift
done
}

default_options()
{
# Set IOC defaults for options
# (may be overridden in config file)
IOC_LC=$1
IOC_UC=`echo $1 | tr [:lower:] [:upper:]`

if [[ "$IOC_LC" = "mdi"* ]]
then
TOP=DiagR3.14.9.0.1-Tornado2.2.1
elif [[ "$IOC_LC" = *"p" ]]
then
TOP=MLS-Controls
else
TOP=BII-Controls/base-3-14
fi

BOOTDIR=/opt/IOC/$TOP/boot/$IOC_UC
HOMEDIR=$HOMEDIRS/$IOC_LC
PIDFILE=$HOMEDIR/$IOC_LC.pid
ENVFILE=$HOMEDIR/$IOC_LC.env
IOC_USER=$IOC_LC
}

assign_options()
{
# Find $TAG section
# Remove comments
# Remove leading and trailing whitespace
# Remove $TAG: tag
# Join lines ending with a "\"
# Mark end of option with a "#"
# Remove unecessary whitespace
TAG=$1
SECTION=`sed -n "/^$TAG:/I,/^[\t ]*$/p" $CONFFILE | \
sed -n '/^[^#]/p' | \
sed -e 's/^[ \t]*//' -e 's/[ \t]*$//' \
-e "s/$TAG://I" \
-e :a -e '/\\\\$/N; s/\\\\\\n//; ta' \
-e 's/$/ \#/' \
-e 's/[\t ]/ /g'`
evaluate_options $SECTION
}

get_iocs()
{
# Get IOCs from command line or AUTO: entry in configuration file
# Test for matching section in configuration file
if [ $# = 0 ]
then
TEST_LIST=`grep -i '^AUTO:' "$CONFFILE" | cut -d: -f2- | tr [:upper:] [:lower:]`
else
TEST_LIST="$@"
fi

CHECKED_LIST=""
for IOC in $TEST_LIST
do
grep -qi "^$IOC:" $CONFFILE
if [ $? = 0 ]
then
CHECKED_LIST="$CHECKED_LIST $IOC"
fi
done
echo $CHECKED_LIST
}

set_cmdenvopts()
{
# Set up the environment setup string

SETENV="LINES=60 "`test ! -z "$CA_AUTO" && echo "export EPICS_CA_AUTO_ADDR_LIST=\"$CA_AUTO\";"`
SETENV="$SETENV "`test ! -z "$CA_ADDR" && echo "export EPICS_CA_ADDR_LIST=\"$CA_ADDR\";"`
SETENV="$SETENV "`test ! -z "$CA_PORT" && echo "export EPICS_CA_SERVER_PORT=\"$CA_PORT\";"`
SETENV="$SETENV "`test ! -z "$BOOTDIR" && echo "export BOOTDIR=\"$BOOTDIR\";"`

# Set up the options for the procserv program

PROCSERVOPTS=`test ! -z "$IOC_USER" && echo "-n \"$IOC_USER\""`
PROCSERVOPTS="$PROCSERVOPTS "`test ! -z "$COREDUMPSIZE" && echo "--coresize \"$COREDUMPSIZE\""`
PROCSERVOPTS="$PROCSERVOPTS -q -c $BOOTDIR -p $PIDFILE -i ^D^C^] $PORT"
}

#
# Function that starts the daemon/service
#
do_start()
{
# Return
# 0 if daemon has been started
# 1 if daemon was already running
# 2 if daemon could not be started
# Add code here, if necessary, that waits for the process to be ready
# to handle requests from services started subsequently which depend
# on this one. As a last resort, sleep for some time.

echo -n "Starting soft IOCs ... "
MYIOCS=`get_iocs $@`
[ "$MYIOCS" = "" ] && echo -n "<none> "
for IOC in $MYIOCS
do
echo -n "$IOC "
clear_options
default_options "$IOC"
assign_options "GLOBAL"
assign_options "$IOC"
set_cmdenvopts

if [ -d $BOOTDIR ]
then
if [ -d $HOMEDIR ]
then

sudo -H -u $IOC sh -c "$SETENV (env > $ENVFILE; /sbin/start-stop-daemon --start --quiet --chdir $BOOTDIR --pidfile $PIDFILE --startas $PROCSERV --name procServ --test > /dev/null)"
if [ "$?" = 1 ]
then
echo -n "<was running> "
else
sudo -H -u $IOC sh -c "$SETENV (env > $ENVFILE; /sbin/start-stop-daemon --start --quiet --chdir $BOOTDIR --pidfile $PIDFILE --startas $PROCSERV --name procServ -- $PROCSERVOPTS ./st.cmd)"
if [ "$?" = 1 ]
then
echo -n "<failed> "
fi
fi

else
echo -e "\nWarning: Home directory $HOMEDIR does not exist! Ignoring $IOC"
fi
else
echo -e "\nWarning: Boot directory $BOOTDIR does not exist! Ignoring $IOC"
fi
done
echo "... done."
}

#
# Function that stops the daemon/service
#
do_stop()
{
# Return
# 0 if daemon has been stopped
# 1 if daemon was already stopped
# 2 if daemon could not be stopped
# other if a failure occurred

echo -n "Stopping soft IOCs ... "
MYIOCS=`get_iocs $@`
[ "$MYIOCS" = "" ] && echo -n "<none> "
for IOC in $MYIOCS
do
echo -n "$IOC "
clear_options
default_options "$IOC"
assign_options "GLOBAL"
assign_options "$IOC"
set_cmdenvopts

sudo -H -u $IOC sh -c "/sbin/start-stop-daemon --stop --quiet \
--pidfile $PIDFILE --name procServ --test > /dev/null"
if [ $? = 1 ]
then
echo -n "<not running> "
else
sudo -H -u $IOC sh -c "/sbin/start-stop-daemon --stop \
--quiet --retry=TERM/30/KILL/5 --pidfile $PIDFILE --name procServ"
if [ $? = 1 ]
then
echo -n "<failed> "
else
sudo -H -u $IOC sh -c "rm -f $PIDFILE"
fi
fi
done
echo "... done."
}

#
# Function that sends a SIGHUP to the daemon/service
#
do_reload() {
#
# If the daemon can reload its configuration without
# restarting (for example, when it is sent a SIGHUP),
# then implement that here.
#
# start-stop-daemon --stop --signal 1 --quiet --pidfile $PIDFILE --name $NAME
# return 0

echo "Restarting soft IOCs ... "
STARTDIR=$PWD
IOCS=`get_iocs $@`
[ "$IOCS" = "" ] && echo -n "<none> "
for IOC in $IOCS
do
echo -n "$IOC "
clear_options
default_options "$IOC"
assign_options "GLOBAL"
assign_options "$IOC"
if [ -d $BOOTDIR ]
then
cd "$BOOTDIR"
# restart it!
echo -e "\ndebug: Reloading ioc $IOC"
cd "$STARTDIR"
else
echo -e "\nWarning: Boot directory $BOOTDIR does not exist! Entry for $NET ignored!"
fi
done
echo "... done."
}

COMMAND=$1
shift
IOCS=`echo $@ | tr [:upper:] [:lower:]`

case "$COMMAND" in
start)
do_start $IOCS
;;
stop)
do_stop $IOCS
;;
#reload|force-reload)
#
# If do_reload() is not implemented then leave this commented out
# and leave 'force-reload' as an alias for 'restart'.
#
#log_daemon_msg "Reloading $DESC" "$NAME"
#do_reload
#log_end_msg $?
#;;
restart|force-reload)
#
# If the "reload" option is implemented then remove the
# 'force-reload' alias
#
do_stop $IOCS
sleep 1
do_start $IOCS
;;
*)
#echo "Usage: $SCRIPTNAME {start|stop|restart|reload|force-reload}" >&2
echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload} [iocs ...]" >&2
exit 3
;;
esac
</pre>

How to use GPIB ports with linux-gpib and StreamDevice

2008-01-18T17:42:59Z

StefanHeim: Add my name, email address and date

This document evolved from a [[http://www.aps.anl.gov/epics/tech-talk/2008/msg00046.php|reply]] I sent to tech-talk to someone who was struggling with the setup of his GPIB device using devGpib.

= Introduction =
The following instructions explain the setup of an EPICS softIOC to talk to a GPIB device on Linux.

The instructions are based on Debian Linux, but should be easily adaptable to other flavors of Linux.

= Prerequisites =
You need linux-gpib[http://linux-gpib.sourceforge.net/], EPICS base[http://www.aps.anl.gov/epics/base/R3-14/index.php], asyn[http://www.aps.anl.gov/epics/modules/soft/asyn/], and StreamDevice[http://epics.web.psi.ch/software/streamdevice/].

== linux-gpib installation ==
On Debian, you can just do
apt-get install gpib-modules-source module-assistant
module-assistant auto-install gpib-modules-source
to build and install the kernel modules of the <tt>linux-gpib</tt> driver for your kernel. Similarly, by issuing
apt-get install libgpib0 libgpib0-dev libgpib-bin
you can install the user space part of <tt>linux-gpib</tt>.

On other distributions, check for the availability of <tt>linux-gpib</tt> packages. You can always resort to compiling linux-gpib youself. Refer to the linux-gpib documentation[http://linux-gpib.sourceforge.net/doc_html/index.html] for this.

Once you have linux-gpib installed, it's time to configure your interface board. Assuming you have a single GPIB interface board in your machine, you'll need to

* figure out the board type, i.e. find out what low-level driver from linux-gpib does support you board, e.g. <tt>ines_pci</tt>, and

* give the interface board an arbitrary name, e.g. <tt>L0</tt>. You'll need to use this name as the first parameter to the <tt>GpibBoardDriverConfig</tt> command in the <tt>st.cmd</tt> of your softIOC later on. There seems to be a convention for the name to start with "L".

To be able to use the interface board as <tt>/dev/gpib0</tt>, put something like

interface {
minor = 0 /* board index, minor = 0 is /dev/gpib0 */
board_type = "ines_pci" /* type of interface board being used */
name = "L0" /* board name */
pad = 0 /* primary address of interface */
sad = 0 /* secondary address of interface */
timeout = T3s /* timeout for commands */
eos = 0x0a /* EOS Byte, 0xa is LF and 0xd is CR */
set-reos = yes /* Terminate read if EOS */
set-bin = no /* Compare EOS 8-bit */
set-xeos = no /* Assert EOI whenever EOS byte is sent */
set-eot = yes /* Assert EOI with last byte on writes */
master = yes /* interface board is system controller */
}

in <tt>/etc/gpib_conf</tt>, load the kernel driver for your board
modprobe ines_pci
and finally run
gpib_config

=== Verify connection to GPIB board ===
Verify you can talk to the board using <tt>ibtest</tt>:

sheim@txm1:~$ ibtest
Do you wish to open a (d)evice or an interface (b)oard?
(you probably want to open a device): b
enter name of interface board (or device) you wish to open: L0
trying to open board named 'L0'
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: l
DAV off
NDAC on
NRFD off
IFC off
REN on
SRQ off
ATN off
EOI on
gpib status is:
ibsta = 0x164 < CMPL REM CIC LACS >
iberr= 0

ibcnt = 0
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: q
sheim@txm1:~$

=== Verify connection to the GPIB device===
Assuming your device has GPIB address 2 and will answer to the command ":FETC?", test it with <tt>ibtest</tt> like this:

sheim@brixen:~$ ibtest
Do you wish to open a (d)evice or an interface (b)oard?
(you probably want to open a device): d
enter primary gpib address for device you wish to open [0-30]: 2
trying to open pad = 2 on /dev/gpib0 ...
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: w
enter a string to send to your device: :FETC?
sending string: :FETC?

gpib status is:
ibsta = 0x2100 < END CMPL >
iberr= 0

ibcnt = 7
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: r
enter maximum number of bytes to read [1024]:
trying to read 1024 bytes from device...
received string: '-000.0003E-12ADC
'
Number of bytes read: 17
gpib status is:
ibsta = 0x2100 < END CMPL >
iberr= 0

ibcnt = 17
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: q
sheim@brixen:~$

If communication with the device works using <tt>ibtest</tt>, the setup of the softIOC is trivial if you stick to the 7-step recipe in section 3.

== EPICS installation ==
Since I maintain Debian packages for EPICS base, all support modules and all extensions I use, here I just do:

apt-get install epics-base epics-support-asyn epics-support-streamdevice

Until I find the time to publish my Debian EPICS archive (sid, lenny, etch, sarge and several Ubuntu versions available), or if you are using a different distribution anyway, you'll have to stick to compiling and installing EPICS base, asyn and StreamDevice yourself.

= The softIOC =
Now it's time to set up the actual softIOC.

== STEP 1: Create GPIB application ==
In a fresh and clean directory, do
makeBaseApp.pl -t example gpib
makeBaseApp.pl -t example -i -a linux-x86 -p gpib gpib

== STEP 2: Use asyn and StreamDevice support ==
Append to configure/RELEASE
ASYN=/opt/epics/support/asyn
STREAMS=/opt/epics/support/streamdevice

Make sure you have asyn and StreamDevice installed and supply the correct paths to your EPICS support directories.

== STEP 3: Create a protocol file ==
Create a protocol file
gpibApp/Db/yourdev.proto
like this:

=== gpibApp/Db/yourdev.proto ===
Terminator = CR LF;

getCurrentStep {
out ":CURR:STEP?";
in "%f";
}

setCurrentStep {
out ":CURR:STEP %f";
}
================================

You might want to consult the SCPI command reference for your device and
implement whatever part of the protocol you may need.

== STEP 4: Create a database ==
Create a database
gpibApp/Db/yourdev.db
matching the protocol from STEP 3 like this:

=== gpibApp/Db/yourdev.db ===
record (ai, "$(P)currentStep")
{
field (SCAN, "Passive")
field (DTYP, "stream")
field (INP, "@yourdev.proto getCurrentStep $(PORT) $(ADDR)")
}

record (ao, "$(P)setCurrentStep")
{
field (SCAN, "Passive")
field (DTYP, "stream")
field (OUT, "@yourdev.proto setCurrentStep $(PORT) $(ADDR)")
}
=============================

In order to register your database with the build system, add the line
DB += yourdev.db
in the middle of
gpibApp/Db/Makefile.

== STEP 5: Adapt application Makefile ==
Have
gpibApp/src/Makefile
read:

=== gpibApp/src/Makefile ===
TOP=../..
include $(TOP)/configure/CONFIG

# build an ioc application
PROD_IOC = gpib
PROD_LIBS += asyn
PROD_LIBS += stream

# gpib.dbd will be created and installed
DBD += gpib.dbd

# gpib.dbd will be made up from these files:
gpib_DBD += base.dbd
gpib_DBD += asyn.dbd
gpib_DBD += drvAsynIPPort.dbd
gpib_DBD += drvAsynSerialPort.dbd
gpib_DBD += drvLinuxGpib.dbd
gpib_DBD += stream.dbd

# softIOC house-keeping
gpib_SRCS += gpib_registerRecordDeviceDriver.cpp
gpib_SRCS_DEFAULT += gpibMain.cpp
gpib_LIBS += $(EPICS_BASE_IOC_LIBS)

include $(TOP)/configure/RULES
============================

== STEP 6: Create an IOC startup script ==
Have the IOC's st.cmd look like this:

=== iocBoot/iocgpib/st.cmd ===
#!../../bin/linux-x86/gpib

< envPaths
epicsEnvSet(STREAM_PROTOCOL_PATH, "../../gpibApp/Db")
cd ${TOP}

## 1 Register all support components
dbLoadDatabase("dbd/gpib.dbd")
gpib_registerRecordDeviceDriver(pdbbase)

## 2 Configure your asynPorts
# 2a GPIB: portname, autoConnect, boardId, timeout, 5th_arg
GpibBoardDriverConfig("L0", "1", "0", "3", "0")
# Note1: The portname has to match the interface name of your board
# from /etc/gpib.conf!
# Note2: boardId is the GPIB address *of your GPIB controller board*.
# The GPIB address of the _device_ itself is supplied to
# dbLoadRecords under step 3 below.
# 2b TCP/IP socket: IPaddress:port
#drvAsynIPPortConfigure("IPPORT","192.168.0.1:6789")
# 2c Serial: "COM1", 9600 bps, 8N1, flow contr.: XON/XOFF
#drvAsynSerialPortConfigure ("SERIALPORT", "/dev/ttyS0", 0, 0, 0)
#asynSetOption ("SERIALPORT", 0, "baud", "9600")
#asynSetOption ("SERIALPORT", 0, "bits", "8")
#asynSetOption ("SERIALPORT", 0, "parity", "none")
#asynSetOption ("SERIALPORT", 0, "stop", "1")
#asynSetOption ("SERIALPORT", 0, "clocal", "Y")
#asynSetOption ("SERIALPORT", 0, "crtscts", "N")
# 2d vxi11: ...

## 3 Load record instances
# Make sure you have your device's GPIB address right!
dbLoadRecords("db/yourdev.db", "P=${IOC}:,PORT=L0,ADDR=2")

cd ${TOP}/iocBoot/${IOC}
iocInit()

==============================

== STEP 7: Build and test IOC ==
Finally run
make
cd iocBoot/iocgpib
chmod +x st.cmd
./st.cmd

to get something like

Starting iocInit
############################################################################
## EPICS R3.14.9-3 $R3-14-9$ $2007/02/05 16:31:45$
## EPICS Base built Jan 17 2008
############################################################################
iocInit: All initialization complete
epics> dbl
iocgpib:currentStep
iocgpib:setCurrentStep
epics> dbpf iocgpib:currentStep.PROC 1
DBR_UCHAR: 1 0x1
epics> 2008/01/18 05:17:01.124 L0 addr 2 : device timed out.
2008/01/18 05:17:01.125 iocgpib:currentStep: Timeout after reading 17
bytes "-000.0007E-12ADC<0a>"
2008/01/18 05:17:01.125 iocgpib:currentStep: 4 bytes surplus input "ADC<0a>"
2008/01/18 05:17:01.125 iocgpib:currentStep: after 13 bytes: "-000.0007E-12"
epics>

The response here comes from my Keithley 6517A sitting at address 2 and
doesn't exactly match what we expect. In fact, not even our EOS terminator
setting is correct, that's why the device timeouts. With the exemplary
debugging information provided by StreamDevice at hand, it is a joy to
incrementally fix the "in" clauses in yourdev.proto to match what the device
_really_ sends. Here, the getCurrentStep protocol would need to be changed to

Terminator = LF;
getCurrentStep {
out ":CURR:STEP?";
in "%fADC";
}

You can reload the protocol in the iocsh via "streamReload", either for one or
for all records. Without rebooting the IOC. Without any recompilation.

Once the protocol works, do a dbpf/caput iocgpib:currentStep.SCAN ".1 second"
to have your IOC poll the device regularly. Or even better, have the device
send out readings on its own if possible and parse them in a protocol run
from an record with .SCAN="I/O Intr".

StreamDevice offers a broad range of so called format converters (the "%f" in
the in clause of the getCurrentStep protocol in yourdev.proto). There's even
a regular expression string converter that you can use to parse your favorite
stock quote from a web page into an EPICS variable.

-<i>Stefan Heim <tt><sheim@bessy.de></tt>, Jan 18 2008</i>

How to use GPIB ports with linux-gpib and StreamDevice

2008-01-18T17:40:19Z

StefanHeim: Small improvements.

How to use GPIB ports with linux-gpib and StreamDevice

2008-01-18T17:08:48Z

StefanHeim: Elaborate on low-level setup

This document evolved from a [[http://www.aps.anl.gov/epics/tech-talk/2008/msg00046.php|reply]] I sent to tech-talk to someone who was struggling with the setup of his GPIB device using devGpib.

= Introduction =
The following instructions explain the setup of an EPICS softIOC to talk to a GPIB device on Linux.

The instructions are based on Debian Linux, but should be easily adaptable to other flavors of Linux.

= Prerequisites =
You need linux-gpib[http://linux-gpib.sourceforge.net/], epics-base[http://www.aps.anl.gov/epics/base/R3-14/index.php], asyn[http://www.aps.anl.gov/epics/modules/soft/asyn/], and StreamDevice[http://epics.web.psi.ch/software/streamdevice/].

== linux-gpib installation ==
On Debian, you can just do
apt-get install gpib-modules-source module-assistant
module-assistant auto-install gpib-modules-source
to build and install the kernel modules of the linux-gpib driver for your kernel. Similarly, by issuing
apt-get install libgpib0 libgpib0-dev libgpib-bin
you can install the user space part of linux-gpib.

On other distributions, check for the availability of linux-gpib packages. You can always resort to compiling linux-gpib youself. Refer to the linux-gpib documentation[http://linux-gpib.sourceforge.net/doc_html/index.html] for this.

Once you have linux-gpib installed, it's time to configure your interface board. Assuming you have a single GPIB interface board in your machine, you'll need to

* figure out the board type, i.e. find out what low-level driver from linux-gpib does support you board, e.g. <tt>ines_pci</tt>, and

* give the interface board an arbitrary name, e.g. <tt>L0</tt>.

To be able to use the interface board as <tt>/dev/gpib0</tt>, put something like

interface {
minor = 0 /* board index, minor = 0 is /dev/gpib0 */
board_type = "ines_pci" /* type of interface board being used */
name = "L0" /* board name */
pad = 0 /* primary address of interface */
sad = 0 /* secondary address of interface */
timeout = T3s /* timeout for commands */
eos = 0x0a /* EOS Byte, 0xa is LF and 0xd is CR */
set-reos = yes /* Terminate read if EOS */
set-bin = no /* Compare EOS 8-bit */
set-xeos = no /* Assert EOI whenever EOS byte is sent */
set-eot = yes /* Assert EOI with last byte on writes */
master = yes /* interface board is system controller */
}

in <tt>/etc/gpib_conf</tt>, load the kernel driver for your board
modprobe ines_pci
and finally run
gpib_config

=== Verify connection to GPIB board ===
Verify you can talk to the board using <tt>ibtest</tt>:

sheim@txm1:~$ ibtest
Do you wish to open a (d)evice or an interface (b)oard?
(you probably want to open a device): b
enter name of interface board (or device) you wish to open: L0
trying to open board named 'L0'
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: l
DAV off
NDAC on
NRFD off
IFC off
REN on
SRQ off
ATN off
EOI on
gpib status is:
ibsta = 0x164 < CMPL REM CIC LACS >
iberr= 0

ibcnt = 0
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: q
sheim@txm1:~$

=== Verify connection to the GPIB device===
Assuming your device has GPIB address 2 and will answer to the command ":FETC?", test it with <tt>ibtest</tt> like this:

sheim@brixen:~$ ibtest
Do you wish to open a (d)evice or an interface (b)oard?
(you probably want to open a device): d
enter primary gpib address for device you wish to open [0-30]: 2
trying to open pad = 2 on /dev/gpib0 ...
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: w
enter a string to send to your device: :FETC?
sending string: :FETC?

gpib status is:
ibsta = 0x2100 < END CMPL >
iberr= 0

ibcnt = 7
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: r
enter maximum number of bytes to read [1024]:
trying to read 1024 bytes from device...
received string: '-000.0003E-12ADC
'
Number of bytes read: 17
gpib status is:
ibsta = 0x2100 < END CMPL >
iberr= 0

ibcnt = 17
You can:
w(a)it for an event
write (c)ommand bytes to bus (system controller only)
send (d)evice clear (device only)
change remote (e)nable line (system controller only)
(g)o to standby (release ATN line, system controller only)
send (i)nterface clear (system controller only)
ta(k)e control (assert ATN line, system controller only)
get bus (l)ine status (board only)
go to local (m)ode
change end (o)f transmission configuration
(q)uit
(r)ead string
perform (s)erial poll (device only)
change (t)imeout on io operations
request ser(v)ice (board only)
(w)rite data string
: q
sheim@brixen:~$

If communication with the device works using <tt>ibtest</tt>, the setup of the softIOC is trivial if you stick to the 7-step recipe in section 3.

== EPICS installation ==
Since I maintain Debian packages for EPICS base, all support modules and all extensions I use, here I just do:

apt-get install epics-base epics-support-asyn epics-support-streamdevice

Until I find the time to publish my Debian EPICS archive (sid, lenny, etch, sarge and several Ubuntu versions available), or if you are using a different distribution anyway, you'll have to stick to compiling and installing yourself.

= The softIOC =
Now it's time to set up the actual softIOC.

== STEP 1: Create GPIB application ==
In a fresh and clean directory, do
makeBaseApp.pl -t example gpib
makeBaseApp.pl -t example -i -a linux-x86 -p gpib gpib

== STEP 2: Use asyn and StreamDevice support ==
Append to configure/RELEASE
ASYN=/opt/epics/support/asyn
STREAMS=/opt/epics/support/streamdevice

Make sure you have asyn and StreamDevice installed and supply the correct paths to your EPICS support directories.

== STEP 3: Create a protocol file ==
Create a protocol file
gpibApp/Db/yourdev.proto
like this:

=== gpibApp/Db/yourdev.proto ===
Terminator = CR LF;

getCurrentStep {
out ":CURR:STEP?";
in "%f";
}

setCurrentStep {
out ":CURR:STEP %f";
}
================================

You might want to consult the SCPI command reference for your device and
implement whatever part of the protocol you may need.

== STEP 4: Create a database ==
Create a database
gpibApp/Db/yourdev.db
matching the protocol from STEP 3 like this:

=== gpibApp/Db/yourdev.db ===
record (ai, "$(P)currentStep")
{
field (SCAN, "Passive")
field (DTYP, "stream")
field (INP, "@yourdev.proto getCurrentStep $(PORT) $(ADDR)")
}

record (ao, "$(P)setCurrentStep")
{
field (SCAN, "Passive")
field (DTYP, "stream")
field (OUT, "@yourdev.proto setCurrentStep $(PORT) $(ADDR)")
}
=============================

In order to register your database with the build system, add the line
DB += yourdev.db
in the middle of
gpibApp/Db/Makefile.

== STEP 5: Adapt application Makefile ==
Have
gpibApp/src/Makefile
read:

=== gpibApp/src/Makefile ===
TOP=../..
include $(TOP)/configure/CONFIG

# build an ioc application
PROD_IOC = gpib
PROD_LIBS += asyn
PROD_LIBS += stream

# gpib.dbd will be created and installed
DBD += gpib.dbd

# gpib.dbd will be made up from these files:
gpib_DBD += base.dbd
gpib_DBD += asyn.dbd
gpib_DBD += drvAsynIPPort.dbd
gpib_DBD += drvAsynSerialPort.dbd
gpib_DBD += drvLinuxGpib.dbd
gpib_DBD += stream.dbd

# softIOC house-keeping
gpib_SRCS += gpib_registerRecordDeviceDriver.cpp
gpib_SRCS_DEFAULT += gpibMain.cpp
gpib_LIBS += $(EPICS_BASE_IOC_LIBS)

include $(TOP)/configure/RULES
============================

== STEP 6: Create an IOC startup script ==
Have the IOC's st.cmd look like this:

=== iocBoot/iocgpib/st.cmd ===
#!../../bin/linux-x86/gpib

< envPaths
epicsEnvSet(STREAM_PROTOCOL_PATH, "../../gpibApp/Db")
cd ${TOP}

## 1 Register all support components
dbLoadDatabase("dbd/gpib.dbd")
gpib_registerRecordDeviceDriver(pdbbase)

## 2 Configure your asynPorts
# 2a GPIB: portname, autoConnect, boardId, timeout, 5th_arg
GpibBoardDriverConfig("L0", "1", "0", "3", "0")
# Note: boardId is the GPIB address *of your GPIB controller board*. The
# GPIB address of the _device_ is supplied to dbLoadRecords in step 3.
# 2b TCP/IP socket:
#drvAsynIPPortConfigure("IPPORT","192.168.0.1:6789")
# 2c Serial: "COM1", 9600 bps, 8N1, flow contr.: XON/XOFF
#drvAsynSerialPortConfigure ("SERIALPORT", "/dev/ttyS0", 0, 0, 0)
#asynSetOption ("SERIALPORT", 0, "baud", "9600")
#asynSetOption ("SERIALPORT", 0, "bits", "8")
#asynSetOption ("SERIALPORT", 0, "parity", "none")
#asynSetOption ("SERIALPORT", 0, "stop", "1")
#asynSetOption ("SERIALPORT", 0, "clocal", "Y")
#asynSetOption ("SERIALPORT", 0, "crtscts", "N")
# 2d vxi11: ...

## 3 Load record instances
# make sure you have your device's GPIB address right!
dbLoadRecords("db/yourdev.db", "P=${IOC}:,PORT=L0,ADDR=2")

cd ${TOP}/iocBoot/${IOC}
iocInit()

==============================

== STEP 7: Build and test IOC ==
Finally run
make
cd iocBoot/iocgpib
chmod +x st.cmd
./st.cmd

to get something like

Starting iocInit
############################################################################
## EPICS R3.14.9-3 $R3-14-9$ $2007/02/05 16:31:45$
## EPICS Base built Jan 17 2008
############################################################################
iocInit: All initialization complete
epics> dbl
iocgpib:currentStep
iocgpib:setCurrentStep
epics> dbpf iocgpib:currentStep.PROC 1
DBR_UCHAR: 1 0x1
epics> 2008/01/18 05:17:01.124 L0 addr 2 : device timed out.
2008/01/18 05:17:01.125 iocgpib:currentStep: Timeout after reading 17
bytes "-000.0007E-12ADC<0a>"
2008/01/18 05:17:01.125 iocgpib:currentStep: 4 bytes surplus input "ADC<0a>"
2008/01/18 05:17:01.125 iocgpib:currentStep: after 13 bytes: "-000.0007E-12"
epics>

The response here comes from my Keithley 6517A sitting at address 2 and
doesn't exactly match what we expect. In fact, not even our EOS terminator
setting is correct, that's why the device timeouts. With the exemplary
debugging information provided by StreamDevice at hand, it is a joy to
incrementally fix the "in" clauses in yourdev.proto to match what the device
_really_ sends. Here, the getCurrentStep protocol would need to be changed to

Terminator = LF;
getCurrentStep {
out ":CURR:STEP?";
in "%fADC";
}

You can reload the protocol in the iocsh via "streamReload", either for one or
for all records. Without rebooting the IOC. Without any recompilation.

Once the protocol works, do a dbpf/caput iocgpib:currentStep.SCAN ".1 second"
to have your IOC poll the device regularly. Or even better, have the device
send out readings on its own if possible and parse them in a protocol run
from an record with .SCAN="I/O Intr".

StreamDevice offers a broad range of so called format converters (the "%f" in
the in clause of the getCurrentStep protocol in yourdev.proto). There's even
a regular expression string converter that you can use to parse your favorite
stock quote from a web page into an EPICS variable.

HowTo Documents

2008-01-18T15:40:38Z

StefanHeim: Add link to linux-gpib howto page

This is a directory of various How-To documents written by members of the EPICS collaboration. Contributions to this page are most welcome!

=== EPICS Base on Different Architectures and Operating Systems ===

* [http://www.aps.anl.gov/epics/base/RTEMS/tutorial/ Getting Started with EPICS on RTEMS]
* [[HowToPC104|Getting Started with R3.14.7 on a PC104 running Linux]]
* [[How To Port EPICS to a new OS/Architecture]]

=== Drivers and Device Support ===

* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-8/tutorial.html How To Do Serial (using Asyn Driver)]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/BeginnerGuideToASYN-VXI11.pdf Beginners Guide to using VXI-11 (with Asyn Driver)]
* [[How to make your EPICS driver operating system independent]]
* [[How To Write Device Support that uses Asyn Driver]] ''(Incomplete!)''
* [[How to use GPIB ports with linux-gpib and StreamDevice]]

=== Applications ===

* [[How To Install Channel Archiver On Scientific Linux]]
* [[What PV Save and Restore Tools are available]]

=== Infrastructure and Other Stuff ===

* [[How To Set Up a Linux Box as an IOC Boot Server]]
* [[How To Set Up a Mirror of the EPICS Web Site]]
* [[How to Set Up a Soft IOC Framework on Linux]]
* [[How to Set Up Console Access and Logging for VME and Soft IOCs]]
* [[How to Set Up NAL (Nagios Alarm Handler) to monitor an EPICS network]]

How to use GPIB ports with linux-gpib and StreamDevice

2008-01-18T15:39:11Z

StefanHeim:

== STEP 1: Create GPIB application ==
In a fresh and clean directory, do
makeBaseApp.pl -t example gpib
makeBaseApp.pl -t example -i -a linux-x86 -p gpib gpib

== STEP 2: Use asyn and StreamDevice support ==
Append to configure/RELEASE
ASYN=/opt/epics/support/asyn
STREAMS=/opt/epics/support/streamdevice

Make sure you have asyn and StreamDevice installed and supply the correct paths to your EPICS support directories.

== STEP 3: Create a protocol file ==
Create a protocol file
gpibApp/Db/yourdev.proto
like this:

=== gpibApp/Db/yourdev.proto ===
Terminator = CR LF;

getCurrentStep {
out ":CURR:STEP?";
in "%f";
}

setCurrentStep {
out ":CURR:STEP %f";
}
================================

You might want to consult the SCPI command reference for your device and
implement whatever part of the protocol you may need.

== STEP 4: Create a database ==
Create a database
gpibApp/Db/yourdev.db
matching the protocol from STEP 3 like this:

=== gpibApp/Db/yourdev.db ===
record (ai, "$(P)currentStep")
{
field (SCAN, "Passive")
field (DTYP, "stream")
field (INP, "@yourdev.proto getCurrentStep $(PORT) $(ADDR)")
}

record (ao, "$(P)setCurrentStep")
{
field (SCAN, "Passive")
field (DTYP, "stream")
field (OUT, "@yourdev.proto setCurrentStep $(PORT) $(ADDR)")
}
=============================

In order to register your database with the build system, add the line
DB += yourdev.db
in the middle of
gpibApp/Db/Makefile.

== STEP 5: Adapt application Makefile ==
Have
gpibApp/src/Makefile
read:

=== gpibApp/src/Makefile ===
TOP=../..
include $(TOP)/configure/CONFIG

# build an ioc application
PROD_IOC = gpib
PROD_LIBS += asyn
PROD_LIBS += stream

# gpib.dbd will be created and installed
DBD += gpib.dbd

# gpib.dbd will be made up from these files:
gpib_DBD += base.dbd
gpib_DBD += asyn.dbd
gpib_DBD += drvAsynIPPort.dbd
gpib_DBD += drvAsynSerialPort.dbd
gpib_DBD += drvLinuxGpib.dbd
gpib_DBD += stream.dbd

# softIOC house-keeping
gpib_SRCS += gpib_registerRecordDeviceDriver.cpp
gpib_SRCS_DEFAULT += gpibMain.cpp
gpib_LIBS += $(EPICS_BASE_IOC_LIBS)

include $(TOP)/configure/RULES
============================

== STEP 6: Create an IOC startup script ==
Have the IOC's st.cmd look like this:

=== iocBoot/iocgpib/st.cmd ===
#!../../bin/linux-x86/gpib

< envPaths
epicsEnvSet(STREAM_PROTOCOL_PATH, "../../gpibApp/Db")
cd ${TOP}

## 1 Register all support components
dbLoadDatabase("dbd/gpib.dbd")
gpib_registerRecordDeviceDriver(pdbbase)

## 2 Configure your asynPorts
# 2a GPIB: portname, autoConnect, boardId, timeout, 5th_arg
GpibBoardDriverConfig("L0", "1", "0", "3", "0")
# Note: boardId is the GPIB address *of your GPIB controller board*. The
# GPIB address of the _device_ is supplied to dbLoadRecords in step 3.
# 2b TCP/IP socket:
#drvAsynIPPortConfigure("IPPORT","192.168.0.1:6789")
# 2c Serial: "COM1", 9600 bps, 8N1, flow contr.: XON/XOFF
#drvAsynSerialPortConfigure ("SERIALPORT", "/dev/ttyS0", 0, 0, 0)
#asynSetOption ("SERIALPORT", 0, "baud", "9600")
#asynSetOption ("SERIALPORT", 0, "bits", "8")
#asynSetOption ("SERIALPORT", 0, "parity", "none")
#asynSetOption ("SERIALPORT", 0, "stop", "1")
#asynSetOption ("SERIALPORT", 0, "clocal", "Y")
#asynSetOption ("SERIALPORT", 0, "crtscts", "N")
# 2d vxi11: ...

## 3 Load record instances
# make sure you have your device's GPIB address right!
dbLoadRecords("db/yourdev.db", "P=${IOC}:,PORT=L0,ADDR=2")

cd ${TOP}/iocBoot/${IOC}
iocInit()

==============================

== STEP 7: Build and test IOC ==
Finally run
make
cd iocBoot/iocgpib
chmod +x st.cmd
./st.cmd

to get something like

Starting iocInit
############################################################################
## EPICS R3.14.9-3 $R3-14-9$ $2007/02/05 16:31:45$
## EPICS Base built Jan 17 2008
############################################################################
iocInit: All initialization complete
epics> dbl
iocgpib:currentStep
iocgpib:setCurrentStep
epics> dbpf iocgpib:currentStep.PROC 1
DBR_UCHAR: 1 0x1
epics> 2008/01/18 05:17:01.124 L0 addr 2 : device timed out.
2008/01/18 05:17:01.125 iocgpib:currentStep: Timeout after reading 17
bytes "-000.0007E-12ADC<0a>"
2008/01/18 05:17:01.125 iocgpib:currentStep: 4 bytes surplus input "ADC<0a>"
2008/01/18 05:17:01.125 iocgpib:currentStep: after 13 bytes: "-000.0007E-12"
epics>

The response here comes from my Keithley 6517A sitting at address 2 and
doesn't exactly match what we expect. In fact, not even our EOS terminator
setting is correct, that's why the device timeouts. With the exemplary
debugging information provided by StreamDevice at hand, it is a joy to
incrementally fix the "in" clauses in yourdev.proto to match what the device
_really_ sends. Here, the getCurrentStep protocol would need to be changed to

Terminator = LF;
getCurrentStep {
out ":CURR:STEP?";
in "%fADC";
}

You can reload the protocol in the iocsh via "streamReload", either for one or
for all records. Without rebooting the IOC. Without any recompilation.

Once the protocol works, do a dbpf/caput iocgpib:currentStep.SCAN ".1 second"
to have your IOC poll the device regularly. Or even better, have the device
send out readings on its own if possible and parse them in a protocol run
from an record with .SCAN="I/O Intr".

StreamDevice offers a broad range of so called format converters (the "%f" in
the in clause of the getCurrentStep protocol in yourdev.proto). There's even
a regular expression string converter that you can use to parse your favorite
stock quote from a web page into an EPICS variable.

How to use GPIB ports with linux-gpib and StreamDevice

2008-01-18T13:55:02Z

StefanHeim: Started linux-gpib HowTo

STEP 1: In a fresh and clean directory, do
makeBaseApp.pl -t example gpib
makeBaseApp.pl -t example -i -a linux-x86 -p gpib gpib

STEP 2: Append to configure/RELEASE
ASYN=/opt/epics/support/asyn
STREAMS=/opt/epics/support/streamdevice

Make sure you have asyn and StreamDevice installed and supply the correct
paths to your EPICS support directories.

STEP 3: Create a protocol file, gpibApp/Db/yourdev.proto, like this:

=== gpibApp/Db/yourdev.proto ===
Terminator = CR LF;

getCurrentStep {
out ":CURR:STEP?";
in "%f";
}

setCurrentStep {
out ":CURR:STEP %f";
}
================================

You might want to consult the SCPI command reference for your device and
implement whatever part of the protocol you may need.

STEP 4: Create a database, gpibApp/Db/yourdev.db, matching the protocol like
this:

=== gpibApp/Db/yourdev.db ===
record (ai, "$(P)currentStep")
{
field (SCAN, "Passive")
field (DTYP, "stream")
field (INP, "@yourdev.proto getCurrentStep $(PORT) $(ADDR)")
}

record (ao, "$(P)setCurrentStep")
{
field (SCAN, "Passive")
field (DTYP, "stream")
field (OUT, "@yourdev.proto setCurrentStep $(PORT) $(ADDR)")
}
=============================

STEP 5: In order to register your database with the build system, add the line
DB += yourdev.db
in the middle of gpibApp/Db/Makefile.

STEP 6: Have gpibApp/src/Makefile read:

=== gpibApp/src/Makefile ===
TOP=../..
include $(TOP)/configure/CONFIG

# build an ioc application
PROD_IOC = gpib
PROD_LIBS += asyn
PROD_LIBS += stream

# gpib.dbd will be created and installed
DBD += gpib.dbd

# gpib.dbd will be made up from these files:
gpib_DBD += base.dbd
gpib_DBD += asyn.dbd
gpib_DBD += drvAsynIPPort.dbd
gpib_DBD += drvAsynSerialPort.dbd
gpib_DBD += drvLinuxGpib.dbd
gpib_DBD += stream.dbd

# softIOC house-keeping
gpib_SRCS += gpib_registerRecordDeviceDriver.cpp
gpib_SRCS_DEFAULT += gpibMain.cpp
gpib_LIBS += $(EPICS_BASE_IOC_LIBS)

include $(TOP)/configure/RULES
============================

STEP 7: Have the IOC's st.cmd look like this:

=== iocBoot/iocgpib/st.cmd ===
#!../../bin/linux-x86/gpib

< envPaths
epicsEnvSet(STREAM_PROTOCOL_PATH, "../../gpibApp/Db")
cd ${TOP}

## 1 Register all support components
dbLoadDatabase("dbd/gpib.dbd")
gpib_registerRecordDeviceDriver(pdbbase)

## 2 Configure your asynPorts
# 2a GPIB: portname, autoConnect, boardId, timeout, 5th_arg
GpibBoardDriverConfig("L0", "1", "0", "3", "0")
# Note: boardId is the GPIB address *of your GPIB controller board*. The
# GPIB address of the _device_ is supplied to dbLoadRecords in step 3.
# 2b TCP/IP socket:
#drvAsynIPPortConfigure("IPPORT","192.168.0.1:6789")
# 2c Serial: "COM1", 9600 bps, 8N1, flow contr.: XON/XOFF
#drvAsynSerialPortConfigure ("SERIALPORT", "/dev/ttyS0", 0, 0, 0)
#asynSetOption ("SERIALPORT", 0, "baud", "9600")
#asynSetOption ("SERIALPORT", 0, "bits", "8")
#asynSetOption ("SERIALPORT", 0, "parity", "none")
#asynSetOption ("SERIALPORT", 0, "stop", "1")
#asynSetOption ("SERIALPORT", 0, "clocal", "Y")
#asynSetOption ("SERIALPORT", 0, "crtscts", "N")
# 2d vxi11: ...

## 3 Load record instances
# make sure you have your device's GPIB address right!
dbLoadRecords("db/yourdev.db", "P=${IOC}:,PORT=L0,ADDR=2")

cd ${TOP}/iocBoot/${IOC}
iocInit()

==============================

STEP 8: Finally run
make
cd iocBoot/iocgpib
chmod +x st.cmd
./st.cmd

to get something like

===
Starting iocInit
############################################################################
## EPICS R3.14.9-3 $R3-14-9$ $2007/02/05 16:31:45$
## EPICS Base built Jan 17 2008
############################################################################
iocInit: All initialization complete
epics> dbl
iocgpib:currentStep
iocgpib:setCurrentStep
epics> dbpf iocgpib:currentStep.PROC 1
DBR_UCHAR: 1 0x1
epics> 2008/01/18 05:17:01.124 L0 addr 2 : device timed out.
2008/01/18 05:17:01.125 iocgpib:currentStep: Timeout after reading 17
bytes "-000.0007E-12ADC<0a>"
2008/01/18 05:17:01.125 iocgpib:currentStep: 4 bytes surplus input "ADC<0a>"
2008/01/18 05:17:01.125 iocgpib:currentStep: after 13 bytes: "-000.0007E-12"
epics>
===

The response here comes from my Keithley 6517A sitting at address 2 and
doesn't exactly match what we expect. In fact, not even our EOS terminator
setting is correct, that's why the device timeouts. With the exemplary
debugging information provided by StreamDevice at hand, it is a joy to
incrementally fix the "in" clauses in yourdev.proto to match what the device
_really_ sends. Here, the getCurrentStep protocol would need to be changed to

Terminator = LF;
getCurrentStep {
out ":CURR:STEP?";
in "%fADC";
}

You can reload the protocol in the iocsh via "streamReload", either for one or
for all records. Without rebooting the IOC. Without any recompilation.

Once the protocol works, do a dbpf/caput iocgpib:currentStep.SCAN ".1 second"
to have your IOC poll the device regularly. Or even better, have the device
send out readings on its own if possible and parse them in a protocol run
from an record with .SCAN="I/O Intr".

StreamDevice offers a broad range of so called format converters (the "%f" in
the in clause of the getCurrentStep protocol in yourdev.proto). There's even
a regular expression string converter that you can use to parse your favorite
stock quote from a web page into an EPICS variable.