gpib - Generic GPIB Record

Mark Rivers

Contents

Overview

The GPIB record is designed to perform generic GPIB I/O. It is intended to allow EPICS to communicate with a new GPIB instrument without even rebooting the IOC, i.e. without writing any C code or changing the database. The GPIB record is thus very useful for allowing Channel Access clients to communicate with GPIB devices for which no EPICS device support exists. It is also useful for GPIB diagnostics. The GPIB bus address is a field in the record which can be modified, so the record can be used to communicate with multiple devices.

The GPIB record communicates with the GPIB controller hardware through the standard EPICS GPIB driver. This means that any supported GPIB controller can be used. These presently include the National Instruments VME board, and the Greenspring Industry Pack module. The latter is supported under Hideos and MPF.

There are two output fields, AOUT (ASCII Output) and BOUT (Binary Output). The OFMT (Output Format) field is used to select one of these fields or the other as the output source to the GPIB device. Similarly, there are two input fields, AINP (ASCII Input) and BINP (Binary Input). The IFMT (Input Format) field is used to select one or the other as the destination of data sent from the GPIB device. The ASCII fields are type DBF_STRING, and are very convenient for typical communication with many GPIB devices. They permit, for example, medm screens where the user can type a string and observe the response from the instrument. The ASCII fields, however are limited to 40 characters in length, and cannot be used to read or write binary data. The binary input and output fields are DBF_CHAR arrays, and can be used to transfer many kilobytes of arbitrary data, either ASCII or binary.

A read operation on input continues until 1 of the following 4 conditions is met:

  1. The device asserts EOI
  2. The input delimiter (EOS) is found. See note under Restrictions below.
  3. The desired number of input characters (NRRD) are received
  4. The timeout (TMOT) expires

The GPIB record calls the GPIB driver directly, and does not go through a separate device support layer.


Record Field Descriptions

Name Access PromptData type Description
VAL R/W "Value field (unused)" DBF_STRING This field is unused. The functions normally assigned to the VAL field in many records are performed by the AOUT, BOUT, AINP, and BINP fields in the GPIB record.
TMOD R/W "Transaction mode" DBF_RECCHOICE The type of GPIB transaction which is desired. The choices are:
"Write/Read" (default) The output source (AOUT or BOUT as selected by OFMT) is sent to the GPIB device. A response is then read back into AINP or BINP (as selected by IFMT). The response must be received within the time specified by TMOT.
"Write" The output source (AOUT or BOUT as selected by OFMT) is sent to the GPIB device. No response is read back.
"Read" Data is read from the GPIB device into the input field (AINP or BINP as selected by IFMT). The response must be received within the time specified by TMOT. No output is sent to the device prior to the read operation.
AOUT R/W* "Output (command) string" DBF_STRING The output string which is sent to the device if OFMT="ASCII". The number of bytes sent to the device will be strlen(AOUT).
BOUT R/W* "Output binary data" DBF_CHAR (array) The output data which is sent to the device if OFMT="Binary". The maximum length of this field is controlled by OMAX. The actual number of bytes to be sent to the device is controlled by NOWT.
OMAX R "Max. size of output array" DBF_LONG The allocated length of the BOUT array. This value cannot be changed after IOC initialization. Default=512.
NOWT R/W "Number of bytes to write" DBF_LONG The actual number of bytes to send from the BOUT array to the GPIB device if OFMT="Binary". This value must be less than or equal to OMAX. Default=512.
OFMT R/W "Output format" DBF_RECCHOICE The output format. The choices are:
"ASCII" The data sent to the device will be taken from the AOUT field.
"Binary" The data sent to the device will be taken from the BOUT field.
AINP R "Input (response) string" DBF_STRING The input string which is read from the device if IFMT="ASCII". The string will be NULL terminated. Note that due to the maximum size of a string in EPICS, the response must be less than 40 characters. If longer responses are required then set IFMT="Binary" and read into the BINP field.
BINP R "Input binary data" DBF_CHAR (array) The input data which is read from the device if IFMT="Binary". The maximum length of this field is controlled by IMAX. The actual number of bytes read from the device is given by NORD.
IMAX R "Max. size of input array" DBF_LONG The allocated length of the BINP array. This value cannot be changed after IOC initialization. Default=512.
EOS R/W "Input delimiter" DBF_LONG A character which indicates the end of a message on input. Set this field to -1 (the default) if no character should be used as an input delimiter. Commonly used values are 10 (Line Feed) or 13 (Carriage Return). The input delimiter will be removed from the input buffer on both ASCII and binary reads. See note under Restrictions below.
NRRD R/W "Number of bytes to read" DBF_LONG The requested number of bytes to read. This field is valid for both "ASCII" and "Binary" input formats. If this field is zero, then the requested number of bytes to read will be the EPICS defined MAX_STRING_SIZE=40 (if IFMT="ASCII") or IMAX (if IFMT="Binary"). Default=0.
NORD R "Number of bytes read" DBF_LONG The actual number of bytes read in the last GPIB read operation. This field is valid for both "ASCII" and "Binary" input formats.
IFMT R/W "Input format" DBF_RECCHOICE The input format. The choices are:
"ASCII" (default) The data read from the device will be placed in the AINP field.
"Binary" The data read from the device will be placed in the BINP field.
INP R "Input Specification" DBF_INLINK The input link specification. This field is used to select the GPIB device type (National Instruments, HiDEOS, Bitbus), link number, and GPIB address. The initial GPIB address can be specified either in the INP field or the ADDR field, with the ADDR field taking precedence if both are non-zero.
SPR R "Serial Poll Response" DBF_UCHAR The device status byte, which is read during a Serial Poll operation.
ADDR R/W "GPIB address" DBF_LONG The GPIB address of the device. This field is can be initialized to a value when creating the database. If the initial value is zero and the GPIB address specified in the INP (Input Link) field is non-zero, then the input link value will be copied to ADDR. This field can be changed at any time.
TMOT R/W "Timeout (msec)" DBF_LONG The timeout value for GPIB read operations in milliseconds. If a response is not received from the device within this time then the record sets a major alarm.
UCMD R/W* "Universal command" DBF_RECCHOICE A GPIB Universal Command to be executed. GPIB Universal Commands are commands which are directed to all devices on the GPIB bus, not just addressed devices. The choices are:
"None"
"Device Clear (DCL)"
"Local Lockout (LL0)"
"Serial Poll Disable (SPD)"
"Serial Poll Enable (SPE)"
"Unlisten (UNL)"
"Untalk (UNT)"
If the UCMD field is set to any value except "None" then the following occurs: the record processes, the appropriate Universal Command is executed, and UCMD is set back to "None". The record processing only performs the Universal Command, i.e. it does not also perform the GPIB operation indicated by TMOD.
ACMD R/W* "Addressed command" DBF_RECCHOICE A GPIB Addressed Command to be executed. GPIB Addressed Commands are commands which are directed to only the addressed devices on the GPIB bus. The choices are:
"None"
"Group Execute Trig. (GET)"
"Go To Local (GTL)"
"Selected Dev. Clear (SDC)"
"Take Control (TCT)"
"Serial Poll"
If the ACMD field is set to any value except "None" then the following occurs: the record processes, the appropriate Addressed Command is executed, and ACMD is set back to "None". The record processing only performs the Addressed Command, i.e. it does not also perform the GPIB operation indicated by TMOD.
Private Fields
IPTR N "Input buffer pointer" DBF_NOACCESS The pointer to the buffer for the BINP field.
OPTR N "Output buffer pointer" DBF_NOACCESS The pointer to the buffer for the BOUT field.
OINP R "Previous input string" DBF_STRING The previous input string. Used for posting events when IFMT="ASCII".
Note: In the Access column above:
R Read only
R/W Read and write are allowed
R/W* Read and write are allowed; write triggers record processing if the record's SCAN field is set to "Passive".
N No access allowed

Files

The following table briefly describes all of the files required to implement the GPIB record. The reader is assumed to be familiar with the EPICS IOC Software Configuration Management document which describes how to build an EPICS application tree into which these files are to be placed, and how to run "gnumake" to build the record support. These files can all be obtained in a compressed tar file. This file should be untarred in a <top>/xxxApp/ directory.

Files to be placed in <top>/xxxApp/src/
gpibRecord.c The source file for the record
gpibRecord.dbd The database definition file for the record
Makefile.Vx This file is not included in the distribution. However, the user must edit this file and add the following lines:
SRCS.c += ../gpibRecord.c
LIBOBJS += gpibRecord.o
Makefile.Host This file is not included in the distribution. However, the user must edit this file and the following line:
RECTYPES += gpibRecord.h
xxxAppInclude.dbd This file is not included in the distribution. However, the user must edit this file and add the following lines:
include "gpibRecord.dbd"

device(gpib,GPIB_IO,devGPIB,"GPIB (NI or HIDEOS)")
device(gpib,BBGPIB_IO,devGPIB,"GPIB (BitBusS)")
Files to be placed in <top>/xxxApp/op/adl/
GPIB_IO.adl This file builds an medm screen to access the GPIB record. The medm screen is most useful for communicating with GPIB devices in ASCII. To use it from the command line, type the following:
> medm -x -macro REC=my_gpib_record GPIB_IO.adl

where my_gpib_record is the name of a GPIB record in an IOC.

This file can also be used as a related display from other medm screens by passing the argument REC=my_gpib_record.

Files to be placed in <top>/xxxApp/Db/
gpib.db This file loads an instance of a GPIB record. It is very simple, and it will need to be edited if you are not using Hideos or MPF.
Files to be placed in <top>/iocBoot/<iocName>/
st.cmd This file is not included in the distribution. However, this file must be edited to enable support for the particular GPIB driver being used. A line like the following must be added to load a generic GPIB record:
dbLoadRecords "gpib.db", "P=13IDD:"


Restrictions

The GPIB record presently has no support for SRQs, which are Service Requests, the GPIB equivalent of an interrupt. Support for SRQs may be added in the future.

The EOS (input delimiter) character is presently implmented only for HiDEOS or MPF links. It is not yet implemented for National Instruments or Bitbus links. EOS may be supported for these links in a future release of the EPICS GPIB driver.


Example

The following is an IDL program which demonstrates the use of the GPIB record to communicate with a Tektronix 2432A Digital Oscilloscope. It transfers data in both ASCII and binary formats.
; This IDL program demonstrates the use of the GPIB record to
; communicate with a Tektronix 2432A Digital Oscilloscope.

; The name of the GPIB record which is communicating 
; with the GPIB bus to which the scope is connected
rec = 'test_gpib1'
aout = rec+'.AOUT'   ; Shorthand for the ASCII output field
ainp = rec+'.AINP'   ; Shorthand for the ASCII input field

; Make sure the record is set up for ASCII input and output 
; and Write/Read mode
t = caput(rec+'.OFMT', 'ASCII')
t = caput(rec+'.IFMT', 'ASCII')
t = caput(rec+'.TMOD', 'Write/Read')

; Set Channel 1 to 100 mV per division
t = caput(aout, 'CH1 VOLTS:0.1')

; Confirm that this worked
t = caput(aout, 'CH1? VOLTS')
t = caget(ainp, response)
    print, 'Channel 1 volts=', float(response)

; Set the horizontal time scale to 2 msec/div
t = caput(aout, 'HOR ASECDIV:2E-3')

; Set the waveform readout format to positive binary
t = caput(aout, 'DATA ENC:RPB')

; Switch the record to binary input mode
t = caput(rec+'.IFMT', 'Binary')

; Tell the scope to send the waveform data
t = caput(aout, 'CURVE?')

; The scope always sends 1028 bytes of data.
; Make sure the NORD field is 1028.
t = caget(rec+'.NORD', nord)
    if (nord eq 1028) then $
        print, 'Got good data from scope' $
    else $
        print, 'Error reading data from scope'

; Read from binary input field, reading only valid data
t = caget(rec+'.BINP', data, max=nord) 

; The first 3 points and last point are header and checksum.
data = data(3:1026)

; The data are in offset binary, subtract 127
data = data - 127

; Plot the data. 
plot, data

; Put the record back in ASCII input mode
t = caput(rec+'.IFMT', 'ASCII')

; Ask the scope to report the minimum and maximum values of 
; the current waveform
t = caput(aout, 'MINIMUM?; MAXIMUM?')
t = caget(ainp, response)
print, 'Range of values in waveform:', response

end

Suggestions and comments to: Mark Rivers : (rivers@cars.uchicago.edu)
Last modified: March 15, 2000