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:
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