StreamDevice
From LNLEpicsWiki
StreamDevice is a device support for EPICS I/O records. It makes the data transfer simple between an I/O EPICS record and a connected device, which listens to string commands.
It is the StreamDevice's responsibility to envelope the value (VAL) of an output EPICS record into a string, which is a command for the connected device and to send the command to the device using the ASYN device support described in the previous section.
On the other hand, it is also the responsibility of StreamDevice to put queries to the device, to unfold the strings as answers of the device and to write the contained value (VAL) into an input EPICS record.
The format of queries and answers in the device communication are device specific and have to be implemented in protocol files.
Lets see how to install the StreamDevice for an EPICS database to communicate with a Genesys power supply.
You are a user of a CentOS linux PC with pre-installed EPICS Base and ASYN device support. First of all you need an EPICS IOC as an EPICS application in your home directory:
go to the user's home directory: $ cd /home/user/ make a directory for your IOC $ mkdir top_powerSupply go into this directory $ cd top_powerSupply create the application directories for PSupply $ makeBaseApp.pl -t ioc PSupply create the boot directories for your IOC $ makeBaseApp.pl -i -t ioc PSupplyIOC Application name? PSupply (That is the application that the IOC boots at startup.)
You may start with the settings specific and needed for the power supply communication. First make ASYN available for our application:
edit into the file /home/user/top_powerSupply/configure/RELEASE $ vi /home/user/top_powerSupply/configure/RELEASE add the following line to the file: ASYN=/opt/epics/deviceSupport/asyn-4.10/
Install StreamDevice:
download the file StreamDevice-2-4.tgz from the homepage http://epics.web.psi.ch/software/streamdevice/ into the application's home directory: $ cd /home/user/top_powerSupply $ wget http://epics.web.psi.ch/software/streamdevice/StreamDevice-2-4.tgz uncompress the archive file $ tar -zxvf StreamDevice-2-4.tgz make StreamDevice $ cd StreamDevice-2-4 $ make
(What happened? A database definition file called stream.dbd has appeared in the directory /home/user/top_powerSupply/dbd/. This file contains definitions for the stream device, so that "stream" is now a possible option for the field DTYP in any conventional I/O record types, if the stream.dbd has been included into your application dbd file.)
Before starting to realize your application database you are supposed to have a database definition file (.dbd) in the /home/user/top_powerSupply/dbd/ directory which contains definitions for all records, devices and functions the database is built of. This dbd file is normally created at make time, i.e. when you give the make command in the application home directory (/home/user/top_powerSupply/), but its content is subject to some settings in the directory /home/user/top_powerSupply/PSupplyApp/src/. At least one dbd file must be present at make time in /home/user/top_powerSupply/PSupplyApp/src/, for instance psupp.dbd, and, accordingly, the following line has to be inserted into the Makefile in the same directory:
$ vi /home/user/top_powerSupply/PSupplyApp/src/Makefile ... PSupply_DBD += psupp.dbd ...
And insert the following lines into the same Makefile:
$ vi /home/user/top_powerSupply/PSupplyApp/src/Makefile #Following the instructions on page http://epics.web.psi.ch/software/streamdevice/doc/ PROD_LIBS += stream PROD_LIBS += asyn
To use StreamDevice in your database, the psupp.dbd has to contain at least the following lines:
$ vi /home/user/top_powerSupply/PSupplyApp/src/psupp.dbd ... include "base.dbd" #This line includes definitions on all conventional EPICS Base records like ai, ao, calc, ... include "stream.dbd" #This line includes the device definitions for StreamDevice and adds the "stream" option to the DTYP fields in any I/O records include "asyn.dbd" #This line and the two followings loads the definitions for ASYN which is used by StreamDevice registrar(drvAsynIPPortRegisterCommands) registrar(drvAsynSerialPortRegisterCommands) ...
Lets go now to the application home directory and make the application:
$ cd /home/user/top_powerSupply/ $ make
That's it. The PSupp.dbd file has been created in /home/user/top_powerSupply/dbd/ and you now have an installed framework for developing an EPICS database using StreamDevice.
We now show on an example how to use StreamDevice. We make a communication between an EPICS database and a Genesys power supply (GEN10-330). This power supply has an embedded driver and listens to string commands through an RS232 serial port. The available commands are written in its User Manual. Suppose, you would like to set the maximum voltage on the power supply from your database, i.e. you have an ao (analog output) record in your database and whenever you change its VAL field value (by e.g. caput) the maximum voltage setting on the device should be changed accordingly. First of all you need a protocol file, which initializes the serial communication and envelopes the analog (float) value of the ao record into a string command the device understands. In our case a protocol file might look like that:
$ cd /home/user/top_powerSupply/iocBoot/iocPSupplyIOC/
$ mkdir protocols
$ cd protocols
$ vi psupp.proto
Terminator = CR; #This line defines the end of message character which is the Carriage Return (ASCII 13) in our case according to the User Manual
setVoltage {
out "PV %f"; #This command envelopes the %f float value originating in the ao record to a string command for setting the voltage on the device
in "%*s"; #This line captures but disregards the acknowledgment (OK) of the device for setting the voltage
@init { #The commands in @init are applied once at database startup
out "ADR 6"; #This line makes the power supply listen for any following commands, i.e. it opens the communication
in "%*s";
out "RST"; #This command sets the power supply in remote control (see the User Manual for details)
in "%*s";
}
}
To make your protocol file available for the database you have to insert the following line into the IOC startup script:
$ vi /home/user/top_powerSupply/iocBoot/iocPSupplyIOC/st.cmd
epicsEnvSet("STREAM_PROTOCOL_PATH","./protocols")
The next task is to design your database:
$ cd /home/user/top_powerSupply/db
$ vi psupp.db
record(ao, set_maximum_Voltage) {
field(DTYP,"stream")
field(OUT,"@psupp.proto setVoltage PS1")
}
Finally, you have to load your database at IOC startup and build up the serial communication for ASYN. Both tasks can be carried out by editing the IOC startup script.
$ cd /home/user/top_powerSupply/iocBoot/iocPSupplyIOC/
$ vi st.cmd
dbLoadRecords("db/psupp.db","user=userHost") #This command loads the database psupp.db
#commands for serial port communication:
drvAsynSerialPortConfigure("PS1","/dev/ttyS0") #This command initializes the serial port communication between power supply and serial port COM1
#the following serial communication settings are according to the User Manual
asynSetOption("PS1",0,"baud","19200") #baud rate setting (bits per second)
asynSetOption("PS1",0,"bits","8") #number of data bits
asynSetOption("PS1",0,"parity","none") #no parity bit
asynSetOption("PS1",0,"stop","1") #number of STOP bits
asynSetOption("PS1",0,"clocal","Y") #do not use local clock
asynSetOption("PS1",0,"crtscts","N") #?
Start the IOC:
$ cd /home/user/top_powerSupply/iocBoot/iocPSupplyIOC/ $ ../../bin/linux-x86/PSupply st.cmd
The Genesys GEN10-330 power supply is current controlled. If you do not apply any load on its outputs, so just leave them free as you got it out of the box, the maximum voltage you set for the device will be the actual voltage between its output poles and this value appears on the front screen of the power supply, as well. So if you open a terminal you can change the voltage by caput to whatever value in the allowed range 0-10 Volts:
$ caput set_maximum_Voltage "5.0"
If everything works fine, you should see the voltage value 5.0 on the device screen.
