How to create EPICS device support for a simple serial or GPIB device

This tutorial provides step-by-step instructions on how to create
EPICS support for a simple serial or GPIB (IEEE-488) device. The steps
are presented in a way that should make it possible to apply them
in cookbook fashion to create support for other devices. For comprehensive
description of all the details of the I/O system used here, refer
to the asynDriver and devGpib
documentation.

This document isn't for the absolute newcomer though. You must have
EPICS installed on a system somewhere and know how to build and run
the example application. In particular you must have the following
installed:

EPICS R3.14.6 or higher.

EPICS modules/soft/asyn version 4.0 or higher.

Serial and GPIB devices can now be treated in much the same way. The
EPICS 'asyn' driver devGpib module can use the low-level drivers which
communicate with serial devices connected to ports on the IOC or to
Ethernet/Serial converters or with GPIB devices connected to local
I/O cards or to Ethernet/GPIB converters.

I based this tutorial on the device support I wrote for a CVI Laser
Corporation AB300 filter wheel. You're almost certainly interested
in controlling some other device so you won't be able to use the information
directly. I chose the AB300 as the basis for this tutorial since the
AB300 has a very limited command set, which keeps this document small,
and yet has commands which raise many of the issues that you'll have
to consider when writing support for other devices.

The first order of business is to determine the set of operations
the device will have to perform. A look at the AB300 documentation
reveals that there are four commands that must be supported. Each
command will be associated with an EPICS process variable (PV) whose
type must be appropriate to the data transferred by the command. The
AB300 commands and process variable record types I choose to associate
with them are shown in table 12Determine the required I/O operationstable.1.

Table 1: AB300 filter wheel commands

CVI Laser Corporation AB300 filter wheel

Command

EPICS record type

Reset

longout

Go to new position

longout

Query position

longin

Query status

longin

There are lots of other ways that the AB300 could be handled. It might
be useful, for example, to treat the filter position as multi-bit
binary records instead.

Now that the device operations and EPICS process variable types have
been chosen it's time to create a new EPICS application to provide
a place to perform subsequent software development. The easiest way
to do this is with the makeSupport.pl script supplied with the EPICS
ASYN package.

Here are the commands I ran. You'll have to change the /home/EPICS/modules/soft/asyn
to the path where your EPICS ASYN driver is installed.

Edit the configure/RELEASE file which makeSupport.pl created
and confirm that the entries describing the paths to your EPICS base
and ASYN support are correct. For example these might be:

ASYN=/home/EPICS/modules/soft/asyn

EPICS_BASE=/home/EPICS/base

Edit the configure/CONFIG file which makeSupport.pl created
and specify the IOC architectures on which the application is to run.
I wanted the application to run as a soft IOC, so I uncommented the
CROSS_COMPILER_TARGET_ARCHS definition and set the definition
to be empty:

The contents of the device support file provide all the details of
the communication between the device and EPICS. The makeSupport.pl
command created a skeleton device support file in AB300Sup/devAB300.c.
Of course, device support for a device similar to the one you're working
with provides an even easier starting point.

The remainder this section describes the changes that I made to the
skeleton file in order to support the AB300 filter wheel. You'll have
to modify the steps as appropriate for your device.

3.2.1 Declare the DSET tables provided by the device support

Since the AB300 provides only longin and longout records most of the
DSET_xxx define statements can be removed although
leaving them in place will not hurt anything. Because of the way that
the device initialization is performed you must define an analog-in
DSET even if the device provides no analog-in records (as is the case
for the AB300).

3.2.2 Select timeout values

The default value of TIMEWINDOW (2 seconds) is reasonable
for the AB300, but I increased the value of TIMEOUT to 5 seconds
since the filter wheel can be slow in responding.

#define TIMEOUT 5.0 /* I/O must complete within this time */
#define TIMEWINDOW 2.0 /* Wait this long after device timeout */

3.2.3 Clean up some unused values

The skeleton file provides a number of example character string arrays.
None are needed for the AB300 so I just removed them. Not much space
would be wasted by just leaving them in place however.

3.2.4 Declare the command array

This is the hardest part of the job. Here's where you have to figure
how to produce the command strings required to control the device
and how to convert the device responses into EPICS process variable
values.

Each command array entry describes the details of a single I/O operation
type. The application database uses the index of the entry in the
command array to provide the link between the process variable and
the I/O operation to read or write that value.

The command array entries I created for the AB300 are shown below.
The elements of each entry are described using the names from the
GPIB documentation.

Command array index 0 – Device Reset

This operation will be placed on the low-priority queue of
I/O requests.

cmd

Because this is a GPIBWRITE operation this element is unused.

format

The format string to generate the command to be sent to
the device. The first two bytes are the RESET command, the third byte
is the ECHO command. The AB300 sends no response to a reset command
so I send the 'ECHO' to verify that the device is responding. The
AB300 resets itself fast enough that it can see an echo command immediately
following the reset command.

Note that the process variable value is not used (there's no printf
% format character in the command string). The AB300 is
reset whenever the EPICS record is processed.

rspLen

The size of the readback buffer. Although only one readback
byte is expected I allow for a few extra bytes just in case.

msgLen

The size of the buffer into which the command string is
placed. I allowed a little extra space in case a longer command is
used some day.

convert

No special conversion function is needed.

P1,P2,P3

There's no special conversion function so no arguments
are needed.

pdevGpibNames

There's no name table.

eos

The end-of-string value used to mark the end of the readback
operation. GPIB devices can usually leave this entry NULL since they
use the End-Or-Identify (EOI) line to delimit messages.Serial devices
which have the same end-of-string value for all commands could also
leave these entries NULL and set the end-of-string value with theiocsh
asynOctetSetInputEos command.

3.2.5 Write the special conversion functions

As mentioned above, special conversion functions are need to convert
reply messages from the AB300 into EPICS PV values. The easiest place
to put these functions is just before the gpibCmds table.
The conversion functions are passed a pointer to the gpibDpvt
structure and three values from the command table entry. The gpibDpvt
structure contains a pointer to the EPICS record. The custom conversion
function uses this pointer to set the record's value field.

If an error status is returned an explanation should be left in the
errorMessage buffer.

I put in a sanity check to ensure that the end-of-string character
is where it should be.

3.2.6 Provide the device support initialization

Because of way code is stored in object libraries on different systems
the device support parameter table must be initialized at run-time.
The analog-in initializer is used to perform this operation. This
is why all device support files must declare an analog-in DSET.

Here's the initialization for the AB300 device support. The AB300
immediately echos the command characters sent to it so the respond2Writes
value must be set to 0. All the other values are left as created by
the makeSupport.pl script:

This file specifies the link between the DSET names defined in the
device support file and the DTYP fields in the application database.
The makeSupport.pl command created an example file in AB300Sup/devAB300.dbd.
If you removed any of the DSET_xxx definitions
from the device support file you must remove the corresponding lines
from this file.

The numbers following the L in the INP and OUT fields are
the number of the `link' used to communicate with the filter wheel.
This link is set up at run time by commands in the application startup
script.

The numbers following the A in the INP and OUT fields are
unused by serial devices but must be a valid GPIB address (0-30) since
the GPIB address conversion routines check the value and the diagnostic
display routines require a matching value.

The numbers following the @ in the INP and OUT fields are
the indices into the GPIB command array.

The DTYP fields must match the names specified in the devAB300.dbd
database definition.

The device support database follows the ASYN convention that the macros
$(P), $(R), $(L) and $(A) are used to specify the record name
prefixes, link number and GPIB address, respectively.

Now that the device support has been completed it's time to create
a new EPICS application to confirm that the device support is operating
correctly. The easiest way to do this is with the makeBaseApp.pl script
supplied with EPICS.

Here are the commands I ran. You'll have to change the /home/EPICS/base
to the path to where your EPICS base is installed. If you're not running
on Linux you'll also have to change all the linux-x86 to
reflect the architecture you're using (solaris-sparc, darwin-ppc,
etc.). I built the test application in the same <top> as the device
support, but the application could be built anywhere. As well, I built
the application as a 'soft' IOC running on the host machine, but the
serial/GPIB driver also works on RTEMS and vxWorks.

Your application database definition file must include the database
definition files for your instrument and for the ASYN drivers. There
are two ways that this can be done:

If you are building your application database definition from an xxxInclude.dbd
file you include the additional database definitions in that file.
For example, to add support for the AB300 instrument and local and
remote serial line drivers:

include "base.dbd"
include "devAB300.dbd"
include "drvAsynIPPort.dbd"
include "drvAsynSerialPort.dbd"

If you're using a serial line directly attached to a vxWorks IOC you
must first configure the serial port interface hardware. The following
example shows the commands to configure a port on a GreenSprings UART
Industry-Pack module.

In all of the above examples the first argument of the configure and
set port option commands is the link identifier and must match the
L value in the EPICS database record INP and OUT fields.
The second argument of the configure command identifies the port to
which the connection is to be made. The third argument sets the priority
of the worker thread which performs the I/O operations. A value of
zero directs the command to choose a reasonable default value. The
fourth argument is zero to direct the device support layer to automatically
connect to the serial port on startup and whenever the serial port
becomes disconnected. The final argument is zero to direct the device
support layer to use standard end-of-string processing on input messages.

(Optional) Add lines to control the debugging level of the serial/GPIB
driver. The following enables error messages and a description of
every I/O operation.

asynSetTraceMask("L0",-1,0x9)
asynSetTraceIOMask("L0",-1,0x2)

A better way to control the amount and type of diagnostic output is
to add an asynRecord to your application.

The asynRecord provides a convenient mechanism for controlling the
diagnostic messages produced by asyn drivers. To use an asynRecord
in your application:

Add the line

DB_INSTALLS += $(ASYN)/db/asynRecord.db

to an application Makefile.

Create the diagnostic record by adding a line like

cd $(ASYN) (cd ASYN if using the vxWorks shell) dbLoadRecords("db/asynRecord.db","P=AB300,R=Test,PORT=L0,ADDR=0,IMAX=0,OMAX=0")

to the application startup (st.cmd) script. The PORT
value must match the the value in the corresponding drvAsynIPPortConfigure
or drvAsynSerialPortConfigure command. The addr
value should be that of the instrument whose I/O you wish to monitor.
The P and R values are arbitrary and are concatenated
together to form the record name. Choose values which are unique
among all IOCs on your network.

To run the asynRecord screen, add <asynTop>/medm
to your EPICS_DISPLAY_PATH environment variable and start
medm with P, R, PORT and ADDR
values matching those given in the dbLoadRecords command:

Devices which use the same character, or characters, to mark the end
of each command or response message need not specify these characters
in the GPIB command table entries. They can, instead, specify the
terminator sequences as part of the driver port configuration commands.
This makes it possible for a single command table to provide support
for devices which provide a serial or Ethernet interface (and require
command/response terminators) and also provide a GPIB interface (which
does not require command/response terminators).

For example, the configuration commands for a TDS3000 digital oscilloscope
connected through an Ethernet serial port adapter might look like: