Difference between revisions of "RRM 3-14 Analog Input"

From EPICSWIKI
m
(Link fields are modifyable)
Line 180: Line 180:
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices#menuSimm|menuSimm]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices#menuSimm|menuSimm]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No

Revision as of 19:26, 22 March 2016

EPICS Record Reference Manual


ai - Analog Input

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules Soft Channel and Raw Soft Channel are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

Parameter Fields

The fields fall into the following groups of parameters:

  • scan parameters
  • read and convert parameters
  • operator display parameters
  • alarm parameters
  • monitor parameters
  • run-time parameters

Scanning Parameters

The analog input record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in Scan Fields. In addition, Scanning Specification explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

Read and Convert Parameters

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
VALValue FieldDOUBLENo0YesYesYesYes
INPInput LinkINLINKYes YesYesNoNo
DTYPDevice TypeDEVCHOICEYes0YesYesNoNo
LINRType of ConversionmenuConvertYes0YesYesNoYes
RVALRaw ValueLONGNo0YesYesYesYes
ROFFRaw Value OffsetLONGNo0YesYesNoYes
EGUFEngineering Units FullDOUBLEYes0YesYesNoYes
EGULEngineering Units LowDOUBLEYes0YesYesNoYes
AOFFAdjustment OffsetDOUBLEYes0YesYesNoYes
ASLOAdjustment SlopeDOUBLEYes1YesYesNoYes
ESLOSlope for Linear ConversionsDOUBLEYes1YesNoNoNo
EOFFOffset for Linear ConversionsDOUBLEYes0YesNoNoNo
SMOOSmoothing FactorDOUBLEYes0YesYesNoNo


Input Specification

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See Address Specification for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See Address Specification for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See Device Support For Soft Records in this chapter for more on how these device support modules work.

Conversion Related Fields

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.


EGUFThe user must calculate these fields when configuring the database for records that use LINEAR conversions. They are used by device support to calculate the values for EOFF and ESLO. See Conversion Specification for more information on how to calculate these fields.
EGUL
AOFFThese fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.
ASLO
ESLOComputed by device support from EGUF and EGUL if LINR specifies LINEAR; the user must set these directly if LINR specifies SLOPE. Used only when LINR is LINEAR or SLOPE.
EOFF
ROFFDeprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.
SMOOA value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See Conversion Specification for more information on what this field does. It is used for all records but Soft Channel records.


The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

1. Val= RVAL + ROFF
2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

4. if SMOO is 0 or INIT is True, VAL = val
5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

This implements a first-order infinite impulse response (IIR) digital filter with z-plane pole at SMOO. The equivalent continuous-time filter time constant τ, is
τ = -T / ln(SMOO)
where T is the time between record processing.

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see Conversion Specification. To see how Raw Soft Channel device support uses these parameters, see Device Support For Soft Records in this chapter.

Operator Display Parameters

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See Fields Common to All Record Types for more on the record name (NAME) and description (DESC) fields.


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
EGUEngineering UnitsSTRING [16]YesnullYesYesNoNo
HOPRHigh Operating RangeDOUBLEYes0YesYesNoNo
LOPRLow Operating RangeDOUBLEYes0YesYesNoNo
PRECDisplay PrecisionSHORTYes0YesYesNoNo
NAMERecord NameSTRING [29]Yes0YesNoNo 
DESCDescriptionSTRING [29]YesNullYesYesNoNo


Alarm Parameters

The possible alarm state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. See Alarm Specification for a complete explanation of alarms and these fields. Alarm Fields lists other fields related to alarms that are common to all record types.


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
HIHIHihi Alarm LimitDOUBLEYes0YesYesNoYes
LOLOLolo Alarm LimitDOUBLEYes0YesYesNoYes
HIGHHigh Alarm LimitDOUBLEYes0YesYesNoYes
LOWLow Alarm LimitDOUBLEYes0YesYesNoYes
HHSVHihi Alarm SeveritymenuAlarmSevrYes0YesYesNoYes
LLSVLolo Alarm SeveritymenuAlarmSevrYes0YesYesNoYes
HSVHigh Alarm SeveritymenuAlarmSevrYes0YesYesNoYes
LSVLow Alarm SeveritymenuAlarmSevrYes0YesYesNoYes
HYSTAlarm DeadbandDOUBLEYes0YesYesNoNo

Monitor Parameters

These parameters are used to determine when to send monitors placed on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the appropriate deadband. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. See Monitor Specification for a complete explanation of monitors.


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
ADELArchive DeadbandDOUBLEYes0YesYesNoNo
MDELMonitor, i.e. value change, DeadbandDOUBLEYes0YesYesNoNo


Run-Time Parameters and Simulation Mode Parameters

These parameters are used by the run-time code for processing the analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
ORAWOld Raw ValueLONGNo0YesNoNoNo
LALMLast Alarm Monitor Trigger ValueDOUBLENo0YesNoNoNo
ALSTLast Archiver Monitor Trigger ValueDOUBLENo0YesNoNoNo
MLSTLast Value Change Monitor Trigger ValueDOUBLENo0YesNoNoNo
INITInitializeSHORTNo0YesNoNoNo
PBRKAddress of Breakpoint TableNOACCESSNo4NoNoNo 
LBRKLast BreakpointSHORTNo0YesNoNoNo


The following fields are used to operate the analog input in the simulation mode. See Fields Common to Many Record Types for more information on these fields.


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
SIOLSimulation Value LocationINLINKYes0YesYesNoNo
SVALSimulation ValueDOUBLENo0YesYesNoNo
SIMLSimulation Mode LocationINLINKYes0YesYesNoNo
SIMMSimulation ModemenuSimmNo0YesYesNoNo
SIMSSimulation Mode Alarm SeveritymenuAlarmSevrYes0YesYesNoNo

Record Support

Record Support Routines

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

init_record

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

process

See next section.

special

The only special processing for analog input records is SPC_LINCONV, which is invoked whenever any of the fields LINR, EGUF or EGUL is changed and LINR is LINEAR.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

get_value

Fills in the values of the structure valueDes so that they refer to VAL.

get_alarm_double

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

Record Processing

Routine process implements the following algorithm:

  1. Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
  2. readValue is called. See Input Records for details.
  3. If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
  4. PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
  5. Perform conversion if necessary: After conversions (if any), UDF is set to FALSE.
  6. Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by more than HYST before the alarm status and severity is lowered.
  7. Check to see if monitors should be invoked:
    • Alarm monitors are invoked if the alarm status or severity has changed.
    • Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
    • Monitors for RVAL are checked whenever other monitors are invoked.
    • NSEV and NSTA are reset to 0.
  8. Scan forward link if necessary, set PACT and INIT to FALSE, and return.

Device Support

Fields Of Interest To Device Support

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai is called. The device support routines are primarily interested in the following fields:


NameSummaryDescription
PACTProcessing ActiveSee Fields Common to All Record Types for an explanation of these fields.
DPVTDevice Private
UDFVAL Undefined
NSEVNew Alarm Severity
NSTANew Alarm Status
VALValueThis field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.
INPInput LinkThis field is used by the device support routines to locate its input.
EGUFEngineering Units FullThese fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.
EGULEngineering Unit Low
ESLOSlopeThese fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.
EOFFOffset
RVALRaw ValueIt is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.

Device Support Routines

Device support consists of the following routines:

report

report (FILE fp, paddr)

Not currently used.

init

init()

This routine is called once during IOC initialization.

init_record

init_record (precord)

This routine is optional. If provided, it is called by the record support init_record routine.

get_ioint_info

get_ioint_info (int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

read_ai

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

0: Success. A new raw value is placed in RVAL. convert will be called.
2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.
Other: Error.

special_linconv

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly. The record support sets EOFF to EGUL before calling this routine, which is the very common case when RAWL is zero below.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

Device Support For Soft Records

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

Soft Channel

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See Soft Input for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

Raw Soft Channel

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and EOFF can be set manually and will be used when LINR is LINEAR.