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:
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.
If you'd like to print this tutorial you can download a PDF version.
Here are the commands I ran. You'll have to change the /home/EPICS/R3.14.5 to the path to where your EPICS 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 application as a 'soft' IOC running on the host machine, but the serial 'GPIB' driver also works on RTEMS and vxWorks.
Edit the configure/CONFIG file which makeBaseApp.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:
CROSS_COMPILER_TARGET_ARCHS =
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.
DSET_xxx
define statements can
be removed. 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).
#define DSET_AI devAB300_ai #define DSET_LI devAB300_li #define DSET_LO devAB300_lo
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 #define TIMEWINDOW 2.0
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.
{&DSET_LO, GPIBWRITE, IB_Q_HIGH, NULL, "\377\377\033", 10, 10,
NULL, 0, 0, NULL, NULL, "\033"},
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.
{&DSET_LO, GPIBWRITE, IB_Q_LOW, NULL, "\017%c", 10, 10,
NULL, 0, 0, NULL, NULL, "\030"},
%c format.
{&DSET_LI, GPIBREAD, IB_Q_LOW, "\035", NULL, 0, 10,
convertPositionReply, 0, 0, NULL, NULL, "\030"},
'\030'.
{&DSET_LI, GPIBREAD, IB_Q_LOW, "\035", NULL, 0, 10,
convertStatusReply, 0, 0, NULL, NULL, "\030"},
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.
Here are the custom conversion functions I wrote for the AB300.
/*
* 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;
}
Some points of interest:
errorMessage buffer.
Here's the initialization for the AB300 device support. As you can see, most of the skeleton file values are left unchanged:
{
{
}
}
AB300_SRCS += devAB300.c
You must also link the GPIB support libraries with your application. Add the following line
AB300_LIBS += asynbefore the
AB300_LIBS += $(EPICS_BASE_IOC_LIBS)line in the application Makefile.
"AB300Gpib" as the device type.
The driver support for serial line 'GPIB' devices must also be included in the application as shown.
include "base.dbd" # # Define the connection between the DTYP field name and the device DSET tables # device(longout, GPIB_IO, devAB300_lo, "AB300Gpib") device(longin, GPIB_IO, devAB300_li, "AB300Gpib") device(ai, GPIB_IO, devAB300_ai, "AB300Gpib") # # Pull in the driver support # include "drvGenericSerial.dbd"
I created the file AB300App/Db/AB300.db with the following contents:
record(longout, "$(user):FilterWheel:reset")
{
field(DESC, "Reset AB300 Controller")
field(SCAN, "Passive")
field(DTYP, "AB300Gpib")
field(OUT, "#L0 A0 @0")
}
record(longout, "$(user):FilterWheel")
{
field(DESC, "Set Filter Wheel Position")
field(SCAN, "Passive")
field(DTYP, "AB300Gpib")
field(OUT, "#L0 A0 @1")
field(LOPR, 1)
field(HOPR, 6)
}
record(longin, "$(user):FilterWheel:fbk")
{
field(DESC, "Filter Wheel Position")
field(SCAN, "Passive")
field(DTYP, "AB300Gpib")
field(INP, "#L0 A0 @2")
field(LOPR, 1)
field(HOPR, 6)
}
record(longin, "$(user):FilterWheel:status")
{
field(DESC, "Filter Wheel Status")
field(SCAN, "Passive")
field(DTYP, "AB300Gpib")
field(INP, "#L0 A0 @3")
}
Notes:
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.
A in
the INP and OUT fields are unused by the device support 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.
@ in
the INP and OUT fields are the
indices into the GPIB command array.
DB += AB300.db
#
and give a reasonable value to the 'user' macro:
dbLoadRecords("../../db/AB300.db","user=AB300")
drvGenericSerialConfigure("L0","164.54.9.91:4002",0,0)
drvGenericSerialConfigure("L0","/dev/ttyS0",0,0)
asynSetPortOption("L0", "baud", "9600")
asynSetPortOption("L0", "bits", "8")
asynSetPortOption("L0", "parity", "none")
asynSetPortOption("L0", "stop", "1")
asynSetPortOption("L0", "clocal", "Y")
asynSetPortOption("L0", "crtscts", "N")
ipacAddVIPC616_01("0x6000,B0000000")
tyGSOctalDrv(1)
tyGSOctalModuleInit("RS232", 0x80, 0, 0)
tyGSOctalDevCreate("/tyGS/0/0",0,0,1000,1000)
drvGenericSerialConfigure("L0","/tyGS/0/0",0,0)
asynSetPortOption("L0","baud","9600")
In all of the above examples the first argument of the
drvGenericSerialConfigure and asynSetPortOption commands is
the link identifier and must match the L value in the EPICS
database record INP and OUT fields.
asynSetTraceMask("L0",0,0xff)
asynSetTraceIOMask("L0",0,0x2)
A better way to control the amount and type of diagnostic output is through
the use of the
asynTrace
facility.
If all goes well you'll be left with an executable program in bin/linux-x86/AB300.
Check the process variable names:
Reset the filter wheel. The values sent between the IOC and the filter wheel are shown:
\033
\377\377\033
\033
Read back the filter wheel position. The dbtr command prints the record before the I/O has a chance to occur:
\030
\035
\001\020\030
Now the process variable should have that value:
Move the wheel to position 4:
\017\004
\020
\030
Read back the position:
\035
\004\020\030
And it really is 4:
/*************************************************************************\
* Copyright (c) 2002 The University of Chicago, as Operator of Argonne
* National Laboratory.
* Copyright (c) 2002 The Regents of the University of California, as
* Operator of Los Alamos National Laboratory.
* EPICS BASE Versions 3.13.7
* and higher are distributed subject to a Software License Agreement found
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/* devAB300.c,v 1.3 2004/01/30 17:26:32 norume Exp */
#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 devAB300_ai
#define DSET_LI devAB300_li
#define DSET_LO devAB300_lo
#include <devGpib.h> /* must be included after DSET defines */
#define TIMEWINDOW 2.0 /* wait 2 seconds after device timeout */
#define TIMEOUT 5.0 /* I/O must complete within 5 seconds */
/*
* 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_HIGH, 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);
}
include "devAsynTrace.dbd"to the application xxxInclude.dbd file.
DB_INSTALLS += $(ASYN)/db/asynTrace.dbto an application Makefile.
dbLoadRecords("db/asynTrace.db","ioc=ab300Test,port=L0,addr=0")
to the application startup (st.cmd) script.
The port value must match the the value in the corresponding
drvGenericSerialConfigure command. The addr value should be zero.
The ioc value is arbitrary and should be chosen so that the ioc/port/addr
combination is unique among all IOCs on your network.
To run the asynTrace screen, add 
asynTop
/medm to your
EPICS_DISPLAY_PATH environment variable and start medm with
ioc, port and addr values
matching those given in the dbLoadRecords command:
medm -x -macro "ioc=ab300Test,port=L0,addr=0" asynTrace.adl &