This package provides EPICS device support for the Greenspring IP-UD (formerly called the IP-Unidig) series of digital I/O Industry Pack modules. It also supports the Systran DIO316I and the SBS IP-OPTOIO-8. The IP-UD family includes more than 20 separate models. This software provides support for most of these models. Most models provide 24 bits, with each bit individually programmable as an input or an output. The last section of this document describes any special features or restrictions on particular models.
The software is written in C++, and consists of a class that inherits from asynPortDriver.
NOTE: The rest of this documentation is obsolete and will be updated soon!!!
For output device support sends Int32Messages with the following info:
address - "mask", a bit pattern of bits to be set or cleared
value - DAC value when cmd=cmdSetDAC. Otherwise not used
cmd - cmdSetBits, cmdClearBits, or cmdSetDAC
cmdSetBits: All bits which are 1 in the mask will be set to 1 in the output register. Bits which are 0 in the mask will be unaffected in the output register.
cmdClearBits: All bits which are 1 in the mask will be set to 0 in the output register. Bits which are 0 in the mask will be unaffected in the output register.
cmdSetDAC: This command is used to set the digital-to-analog converter (DAC) in the IP-Unidig-HV series of modules. This DAC is used to set the input threshold on a comparator. The value is 12 bits, in 15 mV units, for a range of 0-61 volts.
The output server returns an Int32Message with status=(0,-1) for (success, failure).
For input device support sends Int32Messages with the following info:
address - not used
value - not used
cmd - cmdStartMonitor or cmdStopMonitor
The input server polls the input register at a user-specified rate (default=10Hz). The IP-Unidig-I models can also be set to generate interrupts when any user-specified bits changed state, which also causes the input register to be read. Whenever it detects that any input bit has changed it sends a reply message to the last client which sent it a cmdStartMonitor command. This reply message is an Int32Message that contains the current value of all input bits. If the server receives a cmdStopMonitor command it stops sending reply messages until it receives another cmdStartMonitor command.
The reply messages sent by the server to the client on change of any input bit are Int32Messages containing the following information:
address - not used
value - The current value of the input register
initIpUnidig("moduleName", "carrier", "site", queueSize, msecPoll, intVec, risingMask, fallingMask, biMask, maxClients)
where
moduleName - The "base" server name (see note below)
carrier - The ip carrier name
site - carrier IP site (e.g. "Ip_a"
queueSize - message queue size. Make this the maximum number of records attached to this device.
msecPoll - the number of millisecond between polls of the input register. Default=100 msec if this parameter is 0. This is the worst-case response time detecting a change of state for bits or modules that are not using interrupts. If interrupts are used then much faster responses can be obtained.
intVec - the interrupt vector for modules that support interrupts. Zero if interrupts are not to be used.
risingMask - bit mask of bits that should generate interrupts on the rising edge (low to high)
fallingMask - bit mask of bits that should generate interrupts on the falling edge (high to low)
biMask - bit mask of bits that should generate callbacks to the binary input record (bi) support when they interrupt.
maxClients - maximum number of clients that will request callbacks from the IpUnidig interrupt routine. This is not the number of EPICS clients, but rather the number of device support classes that want to be called from IpUnidig. 5 is the default if this parameter is 0, and should be plenty.
initIpUnidig starts two separate server tasks, one for output and one for input. The names of these servers are "moduleName"Out and "moduleName"In respectively. The reason for having separate input and output servers is that the input server polls the read register (at 10Hz by default), with a semGet(delay) between polls. If the same server were used for output it would introduce a 0.1 second latency in responding to output commands, which is not desireable.
Beginning with release R1-2 interrupts on the IP-Unidig-I models are fully supported. For each input bit the hardware can be programmed to generate interrupts on rising or falling transitions, or neither. The interrupt service routine software is written to allow alternating which transition generates interrupts, so that it is also possible to generate interrupts on both rising and falling transitions.
The risingMask and fallingMask parameters to initIpUnidig are used to specify which bits should generate interrupts on each edge. It is possible to have some bits set in neither mask, some in one mask and not the other, and some specified in both masks. For example if risingMask=5 (binary 101) and fallingMask=6 (binary 110), then the first input will generate interrupts on the rising edge, the second input will generate interrupts on the falling edge, the third input will generate interrupts on both rising and falling edges, and all other inputs will not generate interrupts at all.
The biMask parameter is used to specify which bits should generate callbacks to the binary input device support when an interrupts occurs on that line. If it is specified as the bitwise "or" of risingMask and fallingMask (or alternatively 0xffff), then all interrupts will result in callbacks to the binary input device support. If some bits are set in risingMask or fallingMask, but are not set in biMask, then transitions on those bits will generate interrupts, but will not result in a callback to the bi device support. This can be useful because it is possible for other device support modules to request callbacks at interrupt level from the IpUnidig class on receipt of an interrupt on one or more inputs. If these interrupts are occurring very quickly, and the other device support is very efficient, it may be desirable for such interrupts to only result in callbacks to the other device support, and not to the binary input device support. The binary input device support is relatively "expensive" because it results in an MPF message and channel access monitors being posted every time an interrupt occurs.
The call to initIpUnidig creates the input and output server tasks described above. It also creates an instance of the IpUnidig class, which is the class that actually communicates with the hardware. This class provides the following methods:
static IpUnidig * init(
const char *moduleName, const char *carrierName, const char *siteName,
int intVec, int risingMask, int fallingMask, int maxClients);
IpUnidig(IndustryPackModule* pIPM, unsigned char manufacturer,
unsigned char model,
int intVec, int risingMask,
int fallingMask, int maxClients);
int setBits(UINT32 mask);
int clearBits(UINT32 mask);
int readBits(UINT32 *value);
int setDAC(UINT16 value);
int registerCallback(IpUnidigCallback callback, void *pvt, int mask);
The init() and constructor methods are called from initIpUnidig() described above. setBits and clearBits are called from the output server, and readBits is called from the input server. registerCallback is called from the input server if interrupts are being used. Note, however that other device support can call setBits, clearBits, readBits and setDAC.
Most importantly other device support can call registerCallback. This will cause the the specified callback routine to be called when an interrupt occurs, passing a user-specified pointer (pvt) and the current value of the inputs. The mask parameter to registerCallback specifies which bits should result in callbacks being generated. Note that those bits must have had their interrupts enabled in the risingMask and fallingMask parameters to initIpUnidig. The callback routine is called at interrupt level, so it should be very fast and must obey the rules for interrupt routines. It can do floating point arithmetic because the floating point registers are saved and restored in the IpUnidig interrupt service routine.
EPICS device support is currently provided for 3 records, binary output (bo), long input (longin) and binary input (bi).
The bo record format is:
field(DTYP,"Greenspring IP-Unidig")
field(INP,"#C{card} S{signal} @{serverName})
card = The location of the server
signal = The output bit, starting with 0. Most models have 24 bits, so signal is typically in the range 0-23.
serverName = Must be "moduleName"Out, where "moduleName" was specified with initIpUnidig
For input the device support is done as follows:
The longin record should be configured as follows:
field(DTYP,"Greenspring IP-Unidig")
field(INP,"#C{card} S{signal} @{serverName})
card = The location of the server
signal = Not used
serverName = Must be "moduleName"In, where "moduleName" was specified with initIpUnidig
field(SCAN,"Passive")
The bi records should be configured as follows:
field(DTYP,"Greenspring IP-Unidig")
field(INP,"#C{card} S{signal} @{recordName})
card = Not used
signal = The input bit, starting with 0. Most models have 24 bits, so signal is in the range 0-23.
recordname = The name of the longin record described above Note that there is currently no device support for the cmdSetDAC command with the IP-Unidig-HV modules. It is easy to add ao record support for this.
field(SCAN,"I/O Intr")
The IP-Unidig family consists of more than 20 different models. These models differ in the following ways:
The following provides information on specific models. Note that only the IP-Unidig-I and Systran DIO316I have actually been tested. The support for other models is based on reading the manuals. Users who have problems are encouraged to contact the author so that fixes can be incorporated.