Getting started with EPICS using StreamDevice

For our applications we are using the StreamDevice module, Asyn driver and the sCALC record. All these extensions are included in the synApps package. StreamDevice is a generic EPICS module, which supports sending and receiving strings via the serial port or ethernet using the Asyn driver for low-level support.

Before going any further into detail there are many helpful documentations on EPICS and the particular modules on the web:

• EPICS:http://www.aps.anl.gov/epics/docs/index.php
• synApps: http://www.aps.anl.gov/bcda/synApps/synApps_docs_all.html
• StreamDevice: http://epics.web.psi.ch/software/streamdevice/doc/

Since we are running Scientific Linux 4 and Scientific Linux 5 on our PCs with an i386 architecture, this guide is written for such a system. Some commands or routines could differ using another OS. EPICS base, all extensions and our applications are installed in the folder /usr/Epics/. If you install EPICS or the applications in a different folder, you have to reconsider the paths named in the following commands.

Building an EPICS Application

Creating all necessary Files

This section shows you how to build a new EPICS application using the StreamDevice module called " TEST ".

First of all, you have to create a new directory for your application. In this case, the directory has the same name as the application:

[user@host]# mkdir TEST

After creating the directory the following commands have to be performed:

[user@host]# cd TEST
[user@host]# ../base-3.14.10/bin/linux-x86/makeBaseApp.pl -t example TEST
[user@host]# ../base-3.14.10/bin/linux-x86/makeBaseApp.pl -i -t example TEST
[user@host]# setenv EPICS_HOST_ARCH linux-x86

If you are using a Bourne Shell you have to use export EPICS_HOST_ARCH=linux-x86 instead of the setenv command. These commands create all necessary directories and also some example files.

Using different modules you have to create the file TESTApp/src/TESTInclude.dbd which should look like this:

include "base.dbd"                            # EPICS-Base
include "stream.dbd"                          # StreamDevice
include "asyn.dbd"                            # Asyn driver
include "calcSupport.dbd"                     # CALC module
include "sCalcoutRecord.dbd"                  # sCALC module
include "streamSynApps.dbd"
registrar(drvAsynIPPortRegisterCommands)      # for configuring ethernet
registrar(drvAsynSerialPortRegisterCommands)  # for configuring serial port

Also one has to add the following lines to TESTApp/src/Makefile beneath the " # Build the IOC support library " comment:

PROD_LIBS += stream
PROD_LIBS += asyn
PROD_LIBS += calc
PROD_LIBS += streamSynApps

Beneath the comment " # TEST.dbd will be made up from these files: " add these lines:

TEST_DBD += TESTInclude.dbd
TEST_DBD += stream.dbd
TEST_DBD += asyn.dbd

Last but not least the file configure/RELEASE has to be amended by the lines

CALC=$(TOP)/../synApps/synApps_5_5/support/calc-2-8/
ASYN=$(TOP)/../synApps/synApps_5_5/support/asyn-4-13/
STREAM=$(TOP)/../synApps/synApps_5_5/support/stream-2-4-1/

Is everything done, you can build your application:

[user@host]# make
[user@host]# chmod u+x iocBoot/iocTEST/st.cmd

NOTE: If you enter afterwards the command make clean, some files will be deleted, that are necessary for your EPICS application! The file iocBoot/iocTEST/st.cmd is the startup script of the EPICS application. In the following sections there some lines, which have to be added to this file.

As already mentioned, we are using the StreamDevice module. The functions for this module are defined in a protocol file (c.f. section 3). In principle there is no rule or something like this, where to store this file, because one has to set the EPICS environment variable STREAM_PROTOCOL_PATH in iocBoot/iocTEST/envPaths to the path where the protocol file is located. We stored our protocol files in the subdirectory TESTApp/protocols/:

epicsEnvSet ("STREAM_PROTOCOL_PATH", "/usr/Epics/TEST/TESTApp/protocols")

Before you can start your application you have to write your database (section 2) and your protocol file (section 3) . Also you have to configure the port of your device (section 4).

Database

In the database the process variables (PV) or records of an EPICS application are defined. Most commonly the database is located in the subdirectory db of the application. An overview of all records and their fields can be found on this site: http://www.aps.anl.gov/epics/EpicsDocumentation/AppDevManuals/RecordRef/Recordref-1.html

All PVs must have unique names which should match the naming convention. One can use variables in the names which are indicated by a dollar sign and encircled by brackets (e.g. $(subsys) as a variable for the Subsystem). Moreover every channel or task should be readout or set by its own record.

As an example the following record reads out the configuration of the I-7565 USB/CAN Converter

record (stringin, "PANDA:$(subsys):$(sector):USBCAN$(P):readConfig") {
  field(DESC, "Read configuration")
  field(DTYP, "stream")
  field(INP,  "@USBCAN.proto ReadConfiguration USBCAN$(P)")
  field(PINI, "YES")
}

In the first line the type of the record ( stringin: a record which expect a string as input) and the PV name are defined. Here variables for the subsystem, the sector and the device id are used. The appropriate values are assigned to the variables

• when loading the database with the command dbLoadRecords("db/dbUSBCAN.db", "subsys=FEMC, sector=PROTO192, P=1")
• or using a database template. In this case the command would be dbLoadTemplate "db/thmp.substitutions"

The command can be written to the startup script, so that the database is loaded when EPICS get started.

The field DESC in the second line stands for the description of the record, here it is "Read configuration". The third line defines the device type (DTYP) which is in our case stream, so that we can use the protocol files of StreamDevice. The input field ( INP ) links to the function ReadConfiguration of the protocol file USBCAN.proto using the port USBCAN$(P). In the last line the "Process at Initialization" is set, which means the record will be executed with the start of EPICS.

• dbUSBCAN.db: Database for the I-7565 USB/CAN Converter application

Protocol File

The protocol file is used to define the protocols for StreamDevice. There are some global variables such as Terminator (Termination of send or received strings) and functions that are possible. An example for a protocol is

ReadConfiguration {
  out "S";
  in "!%s";
}

First comes the name of the protocol. Like the PV names, the protocol name must be unique and is case sensitive. The second line defines an output string, a capitel S. In the third line is an input-string defined. This string starts with a ! followed by an arbitrary string (%s), which is written to the VAL field of the record, calling this function.

Please refer to the aforesaid StreamDevice doumentation for more information on the complete features of StreamDevice.

• USBCAN.proto: Protocol file for the I-7565 USB/CAN Converter application

Configuring the Asyn Driver

The Asyn Driver should be configured inside the startup script of EPICS, so that the ports are loaded directly. Asyn is a driver for low level communication using either the serial port or ethernet. In case of the I-7565 USB/CAN Converter the configuration for the serial port look like this:

drvAsynSerialPortConfigure("USBCAN1","/dev/ttyUSB0")
asynSetOption ("USBCAN1", 0, "baud", "921600")
asynSetOption ("USBCAN1", 0, "bits", "8")
asynSetOption ("USBCAN1", 0, "parity", "none")
asynSetOption ("USBCAN1", 0, "stop", "1")
asynSetOption ("USBCAN1", 0, "clocal", "N")
asynSetOption ("USBCAN1", 0, "crtscts", "N")

Here USBCAN1 is the name of this port and /dev/ttyUSB0 the address. Unfortunately the option "baud" of Asyn doesn't work for baudrates higher then 200 kbaud, so that one has to make sure the correct baudrate is configured by the driver of the OS. A full documentation of the Asyn Driver can be found here.

• st.cmd: Startup script for the I-7565 USB/CAN Converter application

Contact Persons

For further questions and suggestions please contact

• FlorianFeldbauer
• ChristofMotzko