Getting started with EPICS using StreamDevice

For our applications we are using the StreamDevice module, Asyn driver and the sequencer. 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 base
• asynDriver: Asynchronous Driver Support
• StreamDevice
• State Notation Language and Sequencer

Since we are running Scientific Linux 6 on our PCs with an x86_64 architecture, this guide is written for such a system. Some commands or routines could differ using another OS.

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: After creating the directory the following commands have to be performed:

$ setenv EPICS_HOST_ARCH `<PATH_TO_EPICSBASE>/startup/EpicsHostArch.pl`
$ mkdir TEST
$ cd TEST
$ <PATH_TO_EPICSBASE>/bin/$EPICS_HOST_ARCH/makeBaseApp.pl -t ioc TEST
$ <PATH_TO_EPICSBASE>/bin/$EPICS_HOST_ARCH/makeBaseApp.pl -i -t ioc TEST

If you are using a Bourne Shell you have to use export EPICS_HOST_ARCH=`/path/to/EpicsBase/startup/EpicsHostArch.pl` instead of the setenv command. These commands create all necessary directories and files. If you use -t example instead of -t ioc in the last command you will also have some example files for the sequencer and EPICS database setup.

Adding modules to your IOC

Using different modules you have to modify TESTApp/src/Makefile

Depending on what modules you are using, add these lines after the comment " # TEST.dbd will be made up from these files: "

TEST_DBD += base.dbd
TEST_DBD += stream.dbd
TEST_DBD += asyn.dbd
TEST_DBD += drvAsynSerialPort.dbd

Add the following lines beneath the " # Build the IOC support library " comment:

TEST_LIBS += stream
TEST_LIBS += asyn

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

SNCSEQ=<PATH_TO_SEQUENCER>
ASYN=<PATH_TO_ASYN>
STREAM=<PATH_TO_STREAMDEVICE>

Is everything done, you can build your application:

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

The file iocBoot/iocTEST/st.cmd is the startup script of the EPICS application. In the following sections there are 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.

epicsEnvSet ("STREAM_PROTOCOL_PATH", "<PATH_TO_YOUR_PROTOCOL_FILES>")

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 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 the Record Reference Manual

All records must have unique names within the whole LAN which should match the naming convention. One can use macros 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(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 name are defined. Here macros 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 second 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 than 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