RRM 3-14 Analog Output

From EPICSWIKI

EPICS Record Reference Manual


ao - Analog Output

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

Parameter Fields

The analog output's fields fall into the following categories:

  • scan parameters
  • desired output parameters
  • convert and write parameters
  • operator display parameters
  • alarm parameters
  • monitor parameters
  • run-time parameters.

Scan Parameters

The analog output 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.

Desired Output Parameters

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value will be clipped within limits specified in the fields DRVH and DRVL if these have been configured by the database designer:

DRVL <= VAL <= DRVH

Note: These limits are only enforced as long as DRVH > DRVL. If they are not set or DRVH <= DRVL they will not be used.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See Address Specification for information on specifying links. Scanning Specification explains the effect of database linkage on scanning.


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
OMSLOutput Mode SelectmenuOmslYes0YesYesNoNo
DOLDesired Output Location (an Input Link)INLINKYes0NoNoN/ANo
OIFOut Full or IncrementalaoOIFYes0YesYesNoNo
DRVHDrive HighDOUBLEYes0YesYesNoYes
DRVLDrive LowDOUBLEYes0YesYesNoYes
VALValueDOUBLENo0YesYesYesYes
OROCMaximum Output Rate of ChangeDOUBLEYes0YesYesNoNo
OVALOutput ValueDOUBLENo0YesYesYesNo

Convert and Write Parameters

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO fields.


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
OUTOutput LinkOUTLINKYes0NoNoN/ANo
DTYPDevice TypeDEVCHOICEYes0YesNoNo 
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


Conversion Related Fields and the Conversion Process

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR or SLOPE for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.


EGUFThe user must calculate these fields when configuring the database for records that use LINEAR conversions. They are used to calculate the values for ESLO and EOFF. 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 using EGUF and EGUL when LINR specifies LINEAR. These values must be supplied by the user when LINR specifies SLOPE. Used only when LINR specifies 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.

Conversion proceeds as follows:

1. If LINR==LINEAR or LINR==SLOPE, then X = (VAL - EOFF) / ESLO, else if LINR==NO_CONVERSION, then X = VAL, else X is obtained via breakpoint table.
2. X = (X - AOFF) / ASLO
3. RVAL = round(X) - ROFF

To see how the Raw Soft Channel device support routine uses these fields, see Device Support For Soft Records in this chapter for more information.

Output Specification

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See Address Specification for information on the format of hardware addresses. The user 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.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See Address Specification for information on the format of database and channel access addresses.

Operator Display Parameters

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output 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, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. 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.


FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
EGUEngineering UnitsSTRING [16]YesnullYesYesNoNo
HOPRHigh Operating RangeDOUBLEYes0YesYesNoNo
LOPRLow Operating RangeDOUBLEYes0YesYesNoNo
PRECDisplay PrecisionSHORTYes0YesYesNoNo
NAMERecord NameSTRING [29]Yes0YesNoNoNo
DESCDescriptionSTRING [29]YesNullYesYesNoNo


Alarm Parameters

The possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID 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, which must be floating-point 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. See Invalid Alarm Output Action for more information on the IVOA and IVOV fields. Alarm Fields lists other fields related to a alarms that are common to all record types.


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
HIHIHihi Alarm LimitDOUBLEYes0YesYesNoYes
HIGHHigh Alarm LimitDOUBLEYes0YesYesNoYes
LOWLow Alarm LimitDOUBLEYes0YesYesNoYes
LOLOLolo Alarm LimitDOUBLEYes0YesYesNoYes
HHSVHihi Alarm SeveritymenuAlarmSevrYes0YesYesNoYes
HSVHigh Alarm SeveritymenuAlarmSevrYes0YesYesNoYes
LSVLow Alarm SeveritymenuAlarmSevrYes0YesYesNoYes
LLSVLolo Alarm SeveritymenuAlarmSevrYes0YesYesNoYes
HYSTAlarm DeadbandDOUBLEYes0YesYesNoNo
IVOAInvalid Alarm Output ActionmenuIvoaYes0YesYesNoNo
IVOVInvalid Alarm Output Value, in eng. unitsDOUBLEYes0YesYesNoNo

Monitor Parameters

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband 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 output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field is the actual read back value obtained from the hardware itself or from the associated device driver. It is the responsibility of the device support routine to give this field a value.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
ORAWOld Raw ValueLONGNo0YesNoNoNo
RBVRead Back ValueLONGNo0YesNoYesNo
ORBVOld read back valueLONGNo0YesNoNoNo
LALMLast Alarm Monitor Trigger ValueDOUBLENo0YesNoNoNo
ALSTLast Archiver Monitor Trigger ValueDOUBLENo0YesNoNoNo
MLSTLast Value Change Monitor Trigger ValueDOUBLENo0YesNoNoNo
INITInitializeSHORTNo0YesNoNoNo
PBRKAddress of Breakpoint TableNOACCESSNo4NoNoNo 
LBRKLast BreakpointSHORTNo0YesNoNoNo
PVALPrevious Data ValueDOUBLENo0YesNoNoNo
OMODOVAL modified?LONGNoNullYesNoNoNo


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


FieldSummaryTypeDCTInitialAccessModify Rec Proc MonitorPP
SIOLSimulation Value LocationINLINKYes0NoNoN/ANo
SIMLSimulation Mode LocationINLINKYes0NoNoN/ANo
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 routines.

init_record

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.

This routine next checks to see that device support is available. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

The routine next checks to see if the device support write routine is defined. If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

process

See next section.

special

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed 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 struct 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. Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
    • fetch_values:
      • if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
      • if OIF is INCREMENTAL then set value = value + VAL else value = VAL
    • convert:
      • If Drive limits are defined force value to be within limits
      • Set VAL equal to value
      • Set UDF to FALSE.
      • If OVAL is undefined set it equal to value
      • If OROC is defined and not 0 make |value-OVAL| <=OROC
      • Set OVAL equal to value
      • Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
      • For break point table conversion a call is made to cvtEngToRawBpt.
      • After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
  3. Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by at least HYST before the alarm status and severity is reduced.
  4. Check severity and write the new value. See Invalid Alarm Output Action for details on how invalid alarms affect output records.
  5. If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
  6. 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 and for RBV are checked whenever other monitors are invoked.
    • NSEV and NSTA are reset to 0.
  7. Scan forward link if necessary, set PACT and INIT FALSE, and return.

Device Support

Fields Of Interest To Device Support

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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
NSEVNew Alarm Severity
NSTANew Alarm Status
OUTOutput LinkThis field is used by the device support routines to locate its output.
EGUFEngineering Units FullThese fields are used to calculate ESLO. 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 ValueThis is the value to write to OUT.

Device Support routines

Device support consists of the following routines:

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. It returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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.

write_ao

write_ao(precord)

This routine must output a new 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 write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

0: Success.
other: Error.

special_linconv

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF or EGUL 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 a common situation 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 DAC 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 output records not related to actual hardware devices. The OUT link type must be either a CONSTANT, DB_LINK, or CA_LINK.

Soft Channel

This module writes the current value of OVAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record. init_record always returns a value of 2, which means that no conversion will ever be attempted.

write_ao calls recGblPutLinkValue to write the current value of VAL. See Soft Output for details.

Raw Soft Channel

This module is like the previous except that it writes the current value of RVAL.