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

W. Eric Norum
norume@aps.anl.gov

1  Introduction

• EPICS R3.14.6 or higher.
• EPICS modules/soft/asyn version 3.2 or higher.

2  Determine the required I/O operations

---

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

---

3  Create a new device support module

3.1  Make some changes to the files in configure/

3.2  Create the device support file

3.2.1  Declare the DSET tables provided by the device support

3.2.2  Select timeout values

3.2.3  Clean up some unused values

3.2.4  Declare the command array

Command array index 0 -- Device Reset

dset

This command is associated with an longout record.

type

A WRITE operation is to be performed.

pri

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.

Command array index 1 -- Go to new filter position

dset

This command is associated with an longout record.

type

A WRITE operation is to be performed.

pri

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 filter position (1-6) can be converted to the required command byte with the printf %c format.

rspLen

The size of the readback buffer. Although only two readback bytes are 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.

Command array index 2 -- Query filter position

dset

This command is associated with an longin record.

type

A READ operation is to be performed.

pri

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

cmd

The command string to be sent to the device. The AB300 responds to this command by sending back three bytes: the current position, the controller status, and a terminating '\030'.

format

Because this operation has its own conversion function this element is unused.

rspLen

There is no command echo to be read.

msgLen

The size of the buffer into which the reply string is placed. Although only three reply bytes are expected I allow for a few extra bytes just in case.

convert

There's no sscanf format that can convert the reply from the AB300 so a special conversion function must be provided.

P1,P2,P3

The special conversion function requires no arguments.

pdevGpibNames

There's no name table.

eos

The end-of-string value used to mark the end of the read operation.

Command array index 3 -- Query controller status

3.2.5  Write the special conversion functions

1. Custom conversion functions indicate an error by returning -1.
2. If an error status is returned an explanation should be left in the errorMessage buffer.
3. 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

3.3  Modify the device support database definition file

device(ai,        GPIB_IO, devAiAB300,    "AB300")
device(longin,    GPIB_IO, devLiAB300,    "AB300")
device(longout,   GPIB_IO, devLoAB300,    "AB300")

include "asyn.dbd"

3.4  Create the device support database file

record(longout, "$(P)$(R)FilterWheel:reset")
{
    field(DESC, "Reset AB300 Controller")
    field(SCAN, "Passive")
    field(DTYP, "AB300")
    field(OUT,  "#L$(L) A$(A) @0")
}
record(longout, "$(P)$(R)FilterWheel")
{
    field(DESC, "Set Filter Wheel Position")
    field(SCAN, "Passive")
    field(DTYP, "AB300")
    field(OUT,  "#L$(L) A$(A) @1")
    field(LOPR, 1)
    field(HOPR, 6)
}
record(longin, "$(P)$(R)FilterWheel:fbk")
{
    field(DESC, "Filter Wheel Position")
    field(SCAN, "Passive")
    field(DTYP, "AB300")
    field(INP,  "#L$(L) A$(A) @2")
    field(LOPR, 1)
    field(HOPR, 6)
}
record(longin, "$(P)$(R)FilterWheel:status")
{
    field(DESC, "Filter Wheel Status")
    field(SCAN, "Passive")
    field(DTYP, "AB300")
    field(INP,  "#L$(L) A$(A) @3")
}

1. 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.
2. 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.
3. The numbers following the @ in the INP and OUT fields are the indices into the GPIB command array.
4. The DTYP fields must match the names specified in the devAB300.dbd database definition.
5. 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.

3.5  Build the device support

4  Create a test application

5  Using the device support in an application

5.1  Make some changes to configure/RELEASE

5.2  Modify the application database definition file

1. 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"
   

2. If you are building your application database definition from the application Makefile you specify the additional database definitions there:
   .
   .
   xxx_DBD += base.dbd
   xxx_DBD += devAB300.dbd
   xxx_DBD += drvAsynIPPort.dbd
   xxx_DBD += drvAsynSerialPort.dbd
   .
   .

5.3  Add the device support libraries to the application

5.4  Modify the application startup script

1. Load the device support database records:

   cd $(AB300)          (cd AB300 if using the vxWorks shell)
   
   dbLoadRecords("db/devAB300.db","P=AB300:,R=,L=0,A=0")

2. Set up the 'port' between the IOC and the filter wheel.
   • If you're using an Ethernet/RS-232 converter or a device which communicates over a telnet-style socket connection you need to specify the Internet host and port number like:

     drvAsynIPPortConfigure("L0","164.54.9.91:4002",0,0,0)

   • If you're using a serial line directly attached to the IOC you need something like:

     drvAsynSerialPortConfigure("L0","/dev/ttyS0",0,0,0) 
     asynSetOption("L0", -1, "baud", "9600") 
     asynSetOption("L0", -1, "bits", "8") 
     asynSetOption("L0", -1, "parity", "none") 
     asynSetOption("L0", -1, "stop", "1") 
     asynSetOption("L0", -1, "clocal", "Y") 
     asynSetOption("L0", -1, "crtscts", "N")

   • 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.

     ipacAddVIPC616_01("0x6000,B0000000") 
     tyGSOctalDrv(1) 
     tyGSOctalModuleInit("RS232", 0x80, 0, 0) 
     tyGSOctalDevCreate("/tyGS/0/0",0,0,1000,1000) 
     drvAsynSerialPortConfigure("L0","/tyGS/0/0",0,0,0) 
     asynSetOption("L0",-1,"baud","9600")

   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.
   
   
3. (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.

5.5  Build the application

5.6  Run the application

6  Device Support File

/*
 * AB300 device support
 */

#include <epicsStdio.h>
#include <devCommonGpib.h>

/******************************************************************************
 *
 * The following define statements are used to declare the names to be used
 * for the dset tables.   
 *
 * A DSET_AI entry must be declared here and referenced in an application
 * database description file even if the device provides no AI records.
 *
 ******************************************************************************/
#define DSET_AI     devAiAB300
#define DSET_LI     devLiAB300
#define DSET_LO     devLoAB300

#include <devGpib.h> /* must be included after DSET defines */

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

/*
 * Custom conversion routines
 */
static int
convertPositionReply(struct gpibDpvt *pdpvt, int P1, int P2, char **P3)
{
    struct longinRecord *pli = ((struct longinRecord *)(pdpvt->precord));

    if (pdpvt->msgInputLen != 3) {
        epicsSnprintf(pdpvt->pasynUser->errorMessage,
                      pdpvt->pasynUser->errorMessageSize,
                      "Invalid reply");
        return -1;
    }
    pli->val = pdpvt->msg[0];
    return 0;
}
static int
convertStatusReply(struct gpibDpvt *pdpvt, int P1, int P2, char **P3)
{
    struct longinRecord *pli = ((struct longinRecord *)(pdpvt->precord));

    if (pdpvt->msgInputLen != 3) {
        epicsSnprintf(pdpvt->pasynUser->errorMessage,
                      pdpvt->pasynUser->errorMessageSize,
                      "Invalid reply");
        return -1;
    }
    pli->val = pdpvt->msg[1];
    return 0;
}

/******************************************************************************
 *
 * Array of structures that define all GPIB messages
 * supported for this type of instrument.
 *
 ******************************************************************************/

static struct gpibCmd gpibCmds[] = {
    /* Param 0 -- Device Reset */
    {&DSET_LO, GPIBWRITE, IB_Q_LOW, NULL, "\377\377\033", 10, 10,
        NULL, 0, 0, NULL, NULL, "\033"},

    /* Param 1 -- Go to new filter position */
    {&DSET_LO, GPIBWRITE, IB_Q_LOW, NULL, "\017%c", 10, 10,
        NULL, 0, 0, NULL, NULL, "\030"},

    /* Param 2 -- Query filter position */
    {&DSET_LI, GPIBREAD, IB_Q_LOW, "\035", NULL, 0, 10,
        convertPositionReply, 0, 0, NULL, NULL, "\030"},

    /* Param 3 -- Query controller status */
    {&DSET_LI, GPIBREAD, IB_Q_LOW, "\035", NULL, 0, 10,
        convertStatusReply, 0, 0, NULL, NULL, "\030"}
};

/* The following is the number of elements in the command array above.  */
#define NUMPARAMS sizeof(gpibCmds)/sizeof(struct gpibCmd)

/******************************************************************************
 *
 * Initialize device support parameters
 *
 *****************************************************************************/
static long init_ai(int parm)
{
    if(parm==0) {
        devSupParms.name = "devAB300";
        devSupParms.gpibCmds = gpibCmds;
        devSupParms.numparams = NUMPARAMS;
        devSupParms.timeout = TIMEOUT;
        devSupParms.timeWindow = TIMEWINDOW;
        devSupParms.respond2Writes = 0;
    }
    return(0);
}

7  asynRecord support

1. Add the line
   
   DB_INSTALLS += $(ASYN)/db/asynRecord.db
   
   to an application Makefile.
2. 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.

This document was translated from L^AT_EX by H^EV^EA.