tutorial

tutorial

Documents
15 pages
Lire
Le téléchargement nécessite un accès à la bibliothèque YouScribe
Tout savoir sur nos offres

Description

mailto:norume@aps.anl.gov../asynDriver.htmltutorial.pdf../devGpib.htmlHowtocreateEPICSdevicesupportforasimpleserialorGPIBdeviceW.EricNorumnorume.aps.anl.govAugust19,20091 IntroductionThistutorialprovidesstep by stepinstructionsonhowtocreateEPICSsupportforasimpleserialorGPIB(IEEE 488)device. The steps are presented in a way that should make it possible to apply them in cookbook fashion to createsupport for other devices. For comprehensive description of all the details of the I/O system used here, refer to theasynDriver anddevGpib documentation.This document isn’t for the absolute newcomer though. You must have EPICS installed on a system somewhere andknowhowtobuildandruntheexampleapplication. Inparticularyoumusthavethefollowinginstalled:• EPICSR3.14.6orhigher.• EPICSmodules/soft/asynversion4.0orhigher.Serial and GPIB devices can now be treated in much the same way. The EPICS ’asyn’ driver devGpib module canuse the low level drivers which communicate with serial devices connected to ports on the IOC or to Ethernet/SerialconvertersorwithGPIBdevicesconnectedtolocalI/OcardsortoEthernet/GPIBconverters.I based this tutorial on the device support I wrote for a CVI Laser Corporation AB300 filter wheel. You’re almostcertainly interested in controlling some other device so you won’t be able to use the information directly. I chosethe AB300 as the basis for this tutorial since the AB300 has a very limited command set, which keeps this documentsmall, and yet ...

Sujets

Informations

Publié par
Nombre de visites sur la page 110
Langue English
Signaler un problème

HowtocreateEPICSdevicesupportforasimpleserialorGPIB
device
W.EricNorum
norume.aps.anl.gov
August19,2009
1 Introduction
Thistutorialprovidesstep by stepinstructionsonhowtocreateEPICSsupportforasimpleserialorGPIB(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 anddevGpib documentation.
This document isn’t for the absolute newcomer though. You must have EPICS installed on a system somewhere and
knowhowtobuildandruntheexampleapplication. Inparticularyoumusthavethefollowinginstalled:
• EPICSR3.14.6orhigher.
• EPICSmodules/soft/asynversion4.0orhigher.
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
convertersorwithGPIBdevicesconnectedtolocalI/OcardsortoEthernet/GPIBconverters.
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
otherdevices. Ifyou’dliketoprintthistutorialyoucandownloadPDFversion .
2 DeterminetherequiredI/Ooperations
The first order of business is to determine the set of 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
anEPICSprocessvariable(PV)whosetypemustbeappropriatetothedatatransferredbythecommand. TheAB300
commandsandprocessvariablerecordtypesIchoosetoassociatewiththemareshownintable1.
There are lots of other ways that the AB300 could be handled. It might be useful, for example, to treat the filter
positionasmulti bitbinaryrecordsinstead.
3 Createanewdevicesupportmodule
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.plscriptsuppliedwiththeEPICSASYNpackage.
1
../asynDriver.htmlmailto:norume@aps.anl.gov../devGpib.htmltutorial.pdfTable1: AB300filterwheelcommands
CVILaserCorporationAB300filterwheel
Command EPICSrecordtype
Reset longout
Gotonewposition
Queryposition longinstatus
HerearethecommandsIran. You’llhavetochangethe tothepathwhereyour
EPICSASYNdriverisinstalled.
mkdirab300
cdab300
/home/EPICS/modules/soft/asyn/bin/linux x86/makeSupport.pl tdevGpibAB300
3.1 Makesomechangestothefilesinconfigure/
Edit the file which makeSupport.pl created and confirm that the entries describing the paths to
yourEPICSbaseandASYNsupportarecorrect. Forexamplethesemightbe:
Editthe filewhichmakeSupport.plcreatedandspecifytheIOCarchitecturesonwhichtheappli
cationistorun. IwantedtheapplicationtorunasasoftIOC,soIuncommentedthe
definitionandsetthedefinitiontobeempty:
3.2 Createthedevicesupportfile
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 . Of course, device
supportforadevicesimilartotheoneyou’reworkingwithprovidesaneveneasierstartingpoint.
The remainder this section describes the changes that I made to the skeleton file in order to support the AB300 filter
wheel. You’llhavetomodifythestepsasappropriateforyourdevice.
3.2.1 DeclaretheDSETtablesprovidedbythedevicesupport
Since the AB300 provides only longin and longout records most of the 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
providesnoanalog inrecords(asisthecasefortheAB300).
2
ASYN=/home/EPICS/modu_ARCHSDSET_LOCROSS_COMPILER_TARGET#defineconfigure/CONFIGnorume>S/baseDSET_AIEPICS_BASE=/home/EPICdevLiAB300_ARCHSnorume>=configure/RELEASECROSS_COMPILER_TARGET#defineDSET_devAiAB300AB300Sup/devAB300.cDSET_LI/home/EPICS/modules/s#defineoft/asyndevLoAB300norume>les/soft/asyn3.2.2 Selecttimeoutvalues
The default value of (2 seconds) is reasonable for the AB300, but I increased the value of to
5secondssincethefilterwheelcanbeslowinresponding.
3.2.3 Cleanupsomeunusedvalues
The skeleton file provides a number of example character string arrays. None are needed for the AB300 so I just
removedthem. Notmuchspacewouldbewastedbyjustleavingtheminplacehowever.
3.2.4 Declarethecommandarray
This is the hardest part of the job. Here’s where you have to figure how to produce the command strings required to
controlthedeviceandhowtoconvertthedeviceresponsesintoEPICSprocessvariablevalues.
EachcommandarrayentrydescribesthedetailsofasingleI/Ooperationtype. Theapplicationdatabaseusestheindex
of the entry in the command array to provide the link between the process variable and the I/O operation to read or
writethatvalue.
ThecommandarrayentriesIcreatedfortheAB300areshownbelow. Theelementsofeachentryaredescribedusing
thenamesfromtheGPIBdocumentation .
Commandarrayindex0–DeviceReset
dset Thiscommandisassociatedwithanlongoutrecord.
type AWRITEoperationistobeperformed.
pri Thisoperationwillbeplacedonthelow priorityqueueofI/Orequests.
cmd BecausethisisaGPIBWRITEoperationthiselementisunused.
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 resets itself fast enough that it can see an echo
commandimmediatelyfollowingtheresetcommand.
Note that the process variable value is not used (there’s no printf format character in the command string).
TheAB300isresetwhenevertheEPICSrecordisprocessed.
rspLen The size of the readback buffer. Although only one readback byte is expected I allow for a few extra bytes
justincase.
msgLen Thesizeofthebufferintowhichthecommandstringisplaced. Iallowedalittleextraspaceincasealonger
commandisusedsomeday.
convert Nospecialconversionfunctionisneeded.
P1,P2,P3 There’snospecialconversionfunctionsonoargumentsareneeded.
pdevGpibNames There’snonametable.
3
/*%*/mustwithin5.0after/*#defineI/ONULL,0,viceNULL,thisNULL,W"\033"},time#define10,TIMEOUT0,TIMEOUTtimeoutTIMEWINDOWde{&DSET_LO,longGPIBWRWaitITE,2.0IB_Q_LOW,TIMEWINDONULL,*/"\377\37this7\033",../devGpib.html10,completeeos Theend of stringvalueusedtomarktheendofthereadbackoperation. GPIBdevicescanusuallyleavethisentry
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 couldalso leave these entries NULL and set the end of string value with
theiocshasynOctetSetInputEoscommand.
Commandarrayindex1–Gotonewfilterposition
dset Thiscommandisassociatedwithanlongoutrecord.
type AWRITEoperationistobeperformed.
pri Thisoperationwillbeplacedonthelow priorityqueueofI/Orequests.
cmd BecausethisisaGPIBWRITEoperationthiselementisunused.
format Theformatstringtogeneratethecommandtobesenttothedevice. Thefilterposition(1 6)canbeconverted
totherequiredcommandbytewiththeprintf format.
rspLen Thesizeofthereadbackbuffer. AlthoughonlytworeadbackbytesareexpectedIallowforafewextrabytes
justincase.
msgLen Thesizeofthebufferintowhichthecommandstringisplaced. Iallowedalittleextraspaceincasealonger
commandisusedsomeday.
convert Nospecialconversionfunctionisneeded.
P1,P2,P3 There’snospecialconversionfunctionsonoargumentsareneeded.
pdevGpibNames There’snonametable.
eos Theend of stringvalueusedtomarktheendofthereadbackoperation.
Commandarrayindex2–Queryfilterposition
dset Thiscommandisassociatedwithanlonginrecord.
type AREADoperationistobeperformed.
pri Thisoperationwillbeplacedonthelow priorityqueueofI/Orequests.
cmd Thecommandstringtobesenttothedevice. TheAB300respondstothiscommandbysendingbackthreebytes:
thecurrentposition,thecontrollerstatus,andaterminating .
format Becausethisoperationhasitsownconversionfunctionthiselementisunused.
rspLen Thereisnocommandechotoberead.
msgLen The size of the buffer into which the reply string is placed. Although only three reply bytes are expected I
allowforafewextrabytesjustincase.
convert There’snosscanfformatthatcanconvertthereplyfromtheAB300soaspecialconversionfunctionmustbe
provided.
4
NULL,NULL,NULL,GPIBWR"\035",ITE,10,IB_Q_LOW,\030"},IB_Q_LOW,"\030"},AD,0,GPIBRE",{&DSET_LI,"{&DSET_LO,NULL,'\030'%c0,NULL,10,0,convertPositionReply,NULL,0,10,0,NULL,"\017%cP1,P2,P3 Thespecialconversionfunctionrequiresnoarguments.
pdevGpibNames There’snonametable.
eos Theend of stringvalueusedtomarktheendofthereadoperation.
Commandarrayindex3–Querycontrollerstatus This command array entry is almost identical to the previous
entry. Theonlychangeisthatadifferentcustomconversionfunctionisused.
3.2.5 Writethespecialconversionfunctions
Asmentionedabove,specialconversionfunctionsareneedtoconvertreplymessagesfromtheAB300intoEPICSPV
values. Theeasiestplacetoputtheseisjustbeforethe table. Theconversionfunctionsarepassed
apointertothe structureandthreevaluesfromthecommandtableentry. The structurecontains
atotheEPICSrecord. Thecustomconversionfunctionusesthispointertosettherecord’svaluefield.
HerearethecustomconversionfunctionsIwrotefortheAB300.
5
pdgpibDpvt{{&DSET_LI,**P3)GPIBRE}AD,ructgpibDpvtlongiIB_Q_LOW,-1;"\035",-1;NULL,}0,P1,10,rdconvertStatusReply,(pdpvt->msgInp0,orMessageSize,0,pdNULL,reply");NULL,pli->val"\0return30"},int/**pdpvt,*P2,Customstructconv=ersion*)(pdpvt->precord));routines!=*/pasynUser->errorMessage,staticreply");intpli->valconvertPositionReply(returnstruct"InvalidgpibDpvtreturn*pdpvt,}int=P1,pvt->msg[0];gpibCmds0;P2,staticcharconvertStatusReply(st**P3gpibDpvt)int{intstructcharlonginReco{rdlonginReco*pli*pli=((struct((structnRecordlongiifnRecordutLen*)(pdpvt->precord));3)ifepicsSnprintf(pdpvt->(pdpvt->msgInppdpvt->pasynUser->errutLen"Invalid!=return3)}{=epicsSnprintf(pdpvt->pvt->msg[1];pasynUser->errorMessage,0;pdpvt->pasynUser->errorMessageSize,intSomepointsofinterest:
1. Customconversionfunctionsindicateanerrorbyreturning 1.
2. Ifanerrorstatusisreturnedanexplanationshouldbeleftinthe buffer.
3. Iputinasanitychecktoensurethattheend of stringcharacteriswhereitshouldbe.
3.2.6 Providethedevicesupportinitialization
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
mustdeclareananalog inDSET.
Here’s the initialization for the AB300 device support. The AB300 immediately echos the command characters sent
toitsotherespond2Writesvaluemustbesetto0. AlltheothervaluesareleftascreatedbythemakeSupport.plscript:
3.3 Modifythedevicesupportdatabasedefinitionfile
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 . If you
removed any of the xxx definitions from the device support file you must remove the corresponding lines from
this file. You must define an analog in DSET even if the device provides no analog in records (as is the case for the
AB300).
3.4 Createthedevicesupportdatabasefile
ThisisthedatabasedescribingtheactualEPICSprocessvariablesassociatedwiththefilterwheel.
Imodifiedthefile tohavethefollowingcontents:
6
devSupParms.name")"Resedevice(longin,longGPIB_IO,=devLiAB300,AB300Sup/devAB300.db"AB300")="AB300device(longout,"GPIB_IO,"devAB300";devLoAB300,if(pass==0)"AB300")nit_ai(intincludeerrorMessage"asyn.dbdw"AB300device(ai,{devAiAB300,GPIB_IO,DSET_gpibCmds;AB300Sup/devAB300.dbddevSupParms.gpibCmds}=return(0);{}{0;pass)=iritesstaticdevSupParms.respond2WTIMEWINDOW;devSupParms.numparamsrecord(longout,=$(P)$(R)FilterWheel:reset")NUMPARAMS;field(DESC,devSupParms.timeoutt=Controller")TIMEOUT;devSupParms.timeWindoNotes:
1. Thenumbersfollowingthe intheINPandOUTfieldsarethenumberofthe‘link’usedtocommunicatewith
thefilterwheel. Thislinkissetupatruntimebycommandsintheapplicationstartupscript.
2. The numbers following the 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
requireamatchingvalue.
3. Thenumbersfollowingthe intheINPandOUTfieldsaretheindicesintotheGPIBcommandarray.
4. TheDTYPfieldsmustmatchthenamesspecifiedinthedevAB300.dbddatabasedefinition.
5. The device support database follows the ASYN convention that the macros $(P), $(R), $(L) and $(A) are used
tospecifytherecordnameprefixes,linknumberandGPIBaddress,respectively.
3.5 Buildthedevicesupport
Changedirectoriestothetop leveldirectoryofyourdevicesupportand:
make
(gnumakeonSolaris).
Ifallgoeswellyou’llbeleftwithadevicesupportlibraryinlib/<EPICS_HOST_ARCH>/,adevicesupportdatabase
definitionindbd/andadevicesupportdatabaseindb/.
7
A$(A)field(DESC,Status")FilterA$(A)"Set"$"Pass"Passfield(SCAN,norume>Position")field(DESC,Wheelfield(HOPR,A$(A)0")#L$(L)0")""field(OUT,@0")erA{"AB30}field(DTYP,field(LOPR,ive")"ive")field(DTYP,"Passfield(DTYP,field(SCAN,"Position")}Wheel}er"Pass"Filtfield(SCAN,field(DESC,Wheel{"Filt(P)$(R)FilterWheel:fbk")L"$(P)$(R)FilterWheel:status")record(longin,record(longin,}6)6)1)field(HOPR,@2")1)#L$(L)field(LOPR,field(INP,@1")"AB30ive")field(SCAN,field(DTYP,ive")"AB30"AB300")field(OUT,field(INP,#L$(L)"@0")#L$(L)record(longout,A$(A)$(P)$(R)FilterWheel")@3"){4 Createatestapplication
Nowthatthedevicesupporthasbeencompletedit’stimetocreateanewEPICSapplicationtoconfirmthatthedevice
supportisoperatingcorrectly. TheeasiestwaytodothisiswiththemakeBaseApp.plscriptsuppliedwithEPICS.
HerearethecommandsIran. You’llhavetochangethe tothepathtowhereyourEPICSbaseis
installed. Ifyou’renotrunningonLinuxyou’llalsohavetochangeallthe toreflectthearchitectureyou’re
using ( , , 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 as a ’soft’ IOC running on the host machine,
buttheserial/GPIBdriveralsoworksonRTEMSandvxWorks.
cdab300
/home/EPICS/base/bin/linux x86/makeBaseApp.pl tiocAB300pp.pl i tioc
linux x86
5 Usingthedevicesupportinanapplication
Severalfilesneedminormodificationstousethedevicesupportinthetest,oranyother,application.
5.1 Makesomechangestoconfigure/RELEASE
Editthe filewhichmakeBaseApp.plcreatedandconfirmthattheEPICS_BASEpathiscorrect.
AddentriesforyourASYNanddevicesupport. Forexamplethesemightbe:
5.2 Modifytheapplicationdatabasedefinitionfile
Your application database definition file must include the database definition files for your instrument and for the
ASYNdrivers. Therearetwowaysthatthiscanbedone:
1. Ifyouarebuildingyourapplicationdatabasedefinitionfromanxxx fileyouincludetheadditional
database definitions in that file. For example, to add support for the AB300 instrument and local and remote
seriallinedrivers:
8
architecturebase:/home/EPICS/baseincludeASYN=/home/EPICS/moduRTEMS-pc386configure/RELEASElinux-x86AB300=/home/EPICS/modInclude.dbdEPICS_BASE=/home/EPICsolaris-sparcuse?"devAB300youincludesolaris-sparcPPort.dbd"ules/instrument/ab300/1-2"drvAsynSles/soft/asyn/3-2vxWorks-ppc603S/baselinux-x86ailable"intonorume>wantnorume>donorume>darwin-ppcwin32-x86-cygwin"base.dbdWhatincludeThe.dbd"following"drvAsynItargetincludearchitectureserialPort.dbd"areav2. IfyouarebuildingyourapplicationdatabasedefinitionfromtheapplicationMakefileyouspecifytheadditional
databasedefinitionsthere:
.
.
xxx_DBD+=base.dbd
xxx+=devAB300.dbd
xxx_DBD+=drvAsynIPPort.dbd
xxx+=drvAsynSerialPort.dbd
.
.
Thisisthepreferredmethod.
5.3 Addthedevicesupportlibrariestotheapplication
YoumustlinkyourdevicesupportlibraryandtheASYNsupportlibrarywiththeapplication. Addthefollowinglines
xxx
xxx
beforethe
xxx
lineintheapplication .
5.4 Modifytheapplicationstartupscript
The applicationstartupscriptcreatedbythemakeBaseApp.plscriptneedsafewchangestogettheapplication
workingproperly.
1. Loadthedevicesupportdatabaserecords:
( ifusingthevxWorksshell)
2. Setupthe’port’betweentheIOCandthefilterwheel.
• If you’re using an Ethernet/RS 232 converter or a device which communicates over a telnet style socket
connectionyouneedtospecifytheInternethostandportnumberlike:
• Ifyou’reusingaseriallinedirectlyattachedtotheIOCyouneedsomethinglike:
• 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
UARTIndustry Packmodule.
9
ICS_BASE_IOC_LIBS)"crtscts",cdigure("L0","/dev/ttyS0",0,0,0)"N")asyn$(AB300)"Y")_LIBS"clocal",st.cmd-1,+=asynSetOption("L0",_LIBS"1")drvAsynIPPortConfigur"stop",devA-1,AB300.db","P=AB300:,R=,L=0,A=0")asynSetOption("L0",drvAsynSerialPortConf"none")Makefile"parity",$(EP-1,_LIBSasynSetOption("L0",+="8")cd"bits",e("L0","164.54.9.91:4002",0,0,0)-1,B300asynSetOption("L0",AB300"9600")+="baud",dbLoadRecords("db/dev-1,asynSetOption("L0",asynSetOption("L0",-1,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 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
chooseareasonabledefaultvalue. Thefourthargumentiszerotodirectthedevicesupportlayertoautomatically
connect to the serial port on startup and whenever the serial port becomes disconnected. The final argument is
zerotodirectthedevicesupportlayertousestandardend of stringprocessingoninputmessages.
3. (Optional) Add lines to control the debugging level of the serial/GPIB driver. The following enables error
messagesandadescriptionofeveryI/Ooperation.
AbetterwaytocontroltheamountandtypeofdiagnosticoutputistoaddanasynRecord
toyourapplication.
5.5 Buildtheapplication
Changedirectoriestothetop leveldirectoryofyourapplicationand:
make
(gnumakeonSolaris).
Ifallgoeswellyou’llbeleftwithanexecutableprograminbin/linux x86/AB300.
5.6 Runtheapplication
ChangedirectoriestowheremakeBaseApp.plputtheapplicationstartupscriptandruntheapplication:
cdiocBoot/iocAB300
../../bin/linux x86/AB300st.cmd
10
asynSetTraceMask("L0"RS232",2004tyGSOctalModuleInit("###tyGSOctalDrv(1)#########################################6000,B0000000")iocInit()ipacAddVIPC616_01("0xbuiltasynSetTraceMask("L0"2008/03/25,-1,0x9)iocInit:asynSetTraceIOMask("LasynSetTraceIOMask("L0",-1,0x2)#########################################../asynRecord.htmlIOC0x80,Apr0,EPICS0)21tyGSOctalDevCreate("/StartingtyGS/0/0",0,0,1000,1000)initializationdrvAsynSerialPortConf,-1,0x9)norume>0",-1,0x2)igure("L0","/tyGS/0/0",0,0,0)#####################asynSetOption("L0",-1##############norume>EPICSnorume>CORE,"baud","9600")ondbLoadDatabase("../..23/dbd/AB300.dbd",0,0)###AB300_registerRecordDR3.14.6eviceDriver(pdbbase)18:06:L#####################${AB300}##############dbLoadRecords("db/deviocInitAB300.db","P=AB300:,R=,L=0,A=0")AlldrvAsynIPPortConfigurcompletee("L0","164.54.3.137:4001",0,0,0)cd