A handy tool for device support with EPICS is asynDriver, which dramatically reduces the amount of code needed to write device support for EPICS records. To learn more about how asyn works and specifically about asyn port drivers, we include some suggested reading and lectures.
Asyn's git repository, has an example port driver in the TestAsynPortDriver directory.
Example port driver which we will go through the process of writing lower down.
While writing a port driver there are a few things that are important to keep in mind:
To help you out with that we walk through implementing a much simpler port driver that essentially counts and puts the value back into an Epics record.
Step 1. Modify some files so we can use Asyn and create a port driver
to include in configure/RELEASE
ASYN_MODULE_VERSION = R4.39-1.0.1 #Replace with whatever the current up-to-date version is ASYN = $(EPICS_MODULES)/asyn/$(ASYN_MODULE_VERSION) EPICS_BASE = $(BASE_SITE_TOP)/$(BASE_MODULE_VERSION)
to include in $(YourAppName)App/src/Makefile
$(YourAppName)_DBD += asyn.dbd $(YourAppName_LIBS += asyn
Step 2. Create the EPICS Records we will modify and read with our port driver
## counter.db
record(ai, "$(USER):one")
{
field(DTYP, "asynFloat64")
field(INP, "@asyn($(PORT),$(ADDR),$(TIMEOUT))COUNTER")
field(SCAN, "I/O Intr")
}
record(ao, "$(USER):two")
{
field(DTYP, "asynInt32")
field(OUT, "@asyn($(PORT),$(ADDR),$(TIMEOUT))STEP")
field(PINI, "1")
field(VAL, "23")
}
In $(YourAppName)App/Db/Makefile add the following line
DB += counter.db
We use "I/O Intr" within the SCAN field of our EPICS records, this is an interrupt driven scan so whenever we update a value within the record, it'll process.
Step 3. Defining your port driver
Within $(NAME).h
#include <iostream>
#include <cstdint>
#include <memory>
#include <functional>
#include <map>
#include <iocsh.h>
#include <epicsExport.h>
#include <epicsThread.h>
#include <epicsEvent.h>
#include <epicsTimer.h>
#include <epicsTypes.h>
#include <asynPortDriver.h>
using namespace std;
#define CounterString "COUNTER"
#define StepString "STEP"
class CounterDriver : public asynPortDriver {
public:
CounterDriver(const char *portName);
void counterTask(void);
protected:
int CounterIndex;
int StepIndex;
};
There's some important things we defined in this file, so let's break them down a little.
These strings are used to define the records which our port driver will connect and modify, they correspond to the INP or OUT field of your EPICS record.
#define CounterString "COUNTER" #define StepString "STEP"
This is where we state the capabilities of our port driver, any methods of the port driver we want to override or any unique functions. We include some protected integers here to store the indexes of the parameters with the port driver's parameter list.
class CounterDriver : public asynPortDriver {
public:
CounterDriver(const char *portName);
void counterTask(void);
protected:
int CounterIndex;
int StepIndex;
};
#include "counter.h"
#include <unistd.h>
void counterTask(void *driverPointer); //Necessary otherwise we get an error about functions being declared
CounterDriver::CounterDriver(const char *portName) : asynPortDriver (
portName,
1,
asynFloat64Mask | asynInt32Mask | asynDrvUserMask,
asynFloat64Mask | asynInt32Mask,
ASYN_MULTIDEVICE,
1,
0,
0
)
{
createParam(CounterString, asynParamFloat64, &CounterIndex);
createParam(StepString, asynParamInt32, &StepIndex);
asynStatus status;
status = (asynStatus)(epicsThreadCreate("CounterTask", epicsThreadPriorityMedium, epicsThreadGetStackSize(epicsThreadStackMedium), (EPICSTHREADFUNC)::counterTask, this) == NULL);
if (status)
{
printf("Thread didn't launch please do something else");
return;
}
}
void counterTask(void* driverPointer)
{
CounterDriver *pPvt = (CounterDriver *) driverPointer;
pPvt->counterTask();
}
void CounterDriver::counterTask(void)
{
int step;
double count;
while(1)
{
sleep(1); //Necessary because the thread will go faster than I/O Scan will accept and write inputs
getDoubleParam(CounterIndex, &count);
getIntegerParam(StepIndex, &step);
setDoubleParam(CounterIndex, count + step);
setIntegerParam(StepIndex, step + 1);
callParamCallbacks();
}
}
extern "C"
{
int CounterDriverConfigure(const char* portName)
{
new CounterDriver(portName);
return asynSuccess;
}
static const iocshArg initArg0 = {"portName", iocshArgString};
static const iocshArg * const initArgs[] = {&initArg0};
static const iocshFuncDef initFuncDef = {"CounterDriverConfigure", 1, initArgs};
static void initCallFunc(const iocshArgBuf *args)
{
CounterDriverConfigure(args[0].sval);
}
void CounterDriverRegister(void)
{
iocshRegister(&initFuncDef, initCallFunc);
}
epicsExportRegistrar(CounterDriverRegister);
}
asynDrvUserMask is necessary whenever working with multiple parameters, your port driver will not give you the behavior you expect when working with multiple records if this flag is not here
Here's the meat of our port driver, where we initialize our port driver and create parameters, that our port driver can access and modify; for more information about the options that are inherited from the base asynport driver, refer to here.
CounterDriver::CounterDriver(const char *portName) : asynPortDriver (
portName,
1,
asynFloat64Mask | asynInt32Mask | asynDrvUserMask,
asynFloat64Mask | asynInt32Mask,
ASYN_MULTIDEVICE,
1,
0,
0
)
{
createParam(CounterString, asynParamFloat64, &CounterIndex);
createParam(StepString, asynParamInt32, &StepIndex);
asynStatus status;
status = (asynStatus)(epicsThreadCreate("CounterTask", epicsThreadPriorityMedium, epicsThreadGetStackSize(epicsThreadStackMedium), (EPICSTHREADFUNC)::counterTask, this) == NULL);
if (status)
{
printf("Thread didn't launch please do something else");
return;
}
}
counterTask is a class specific method, in the constructor we launch a thread where the port driver completes this task, the code is fairly straightforward, feel free to do whatever you want.
void counterTask(void* driverPointer)
{
CounterDriver *pPvt = (CounterDriver *) driverPointer;
pPvt->counterTask();
}
void CounterDriver::counterTask(void)
{
int step;
double count;
while(1)
{
sleep(1); //Necessary because the thread will go faster than I/O Scan will accept and write inputs
getDoubleParam(CounterIndex, &count);
getIntegerParam(StepIndex, &step);
setDoubleParam(CounterIndex, count + step);
setIntegerParam(StepIndex, step + 1);
callParamCallbacks();
}
}
This extern "C" block allows us to create our port driver through the iocsh, essentially it's a block of code that wraps the code to launch our port driver and lets us call it from iocsh.
extern "C" {
int CounterDriverConfigure(const char* portName) {
new CounterDriver(portName);
return asynSuccess;
}
static const iocshArg initArg0 = {"portName", iocshArgString};
static const iocshArg * const initArgs[] = {&initArg0};
static const iocshFuncDef initFuncDef = {"CounterDriverConfigure", 1, initArgs};
static void initCallFunc(const iocshArgBuf *args)
{
CounterDriverConfigure(args[0].sval);
}
void CounterDriverRegister(void) {
iocshRegister(&initFuncDef, initCallFunc);
}
epicsExportRegistrar(CounterDriverRegister);
}
The values you expect to be present in your epics records may not match up with the local copy of the parameter in your port driver's parameter list
Step 4: Create a .dbd file (This file should be in $(YourAppName)App/src/
registrar(CounterDriverRegister)
CountingTest_DBD += <name>.dbd CountingTest_SRCS += counter.cpp USR_CPPFLAGS += -std=c++11
Step 5: Modifying your st.cmd
Replace the things surrounded like <THIS> with your items.
CounterDriverConfigure("<PORTNAME>")
dbLoadRecords("db/counter.db", "USER=<USERNAME>,PORT=<PORTNAME>,ADDR=0,TIMEOUT=0") #For more detailed reading see the links at the top
Step 6: Use Make to build your application and then run ./st.cmd, you should be able to observe your pv's through camonitor and edit them with caput. Try doing things with other records.
Congratulations on making a port driver.