RRM 3-14 Analog Output

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.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
OMSL	Output Mode Select	menuOmsl	Yes	0	Yes	Yes	No	No
DOL	Desired Output Location (an Input Link)	INLINK	Yes	0	Yes	Yes	No	No
OIF	Out Full or Incremental	aoOIF	Yes	0	Yes	Yes	No	No
DRVH	Drive High	DOUBLE	Yes	0	Yes	Yes	No	Yes
DRVL	Drive Low	DOUBLE	Yes	0	Yes	Yes	No	Yes
VAL	Value	DOUBLE	No	0	Yes	Yes	Yes	Yes
OROC	Maximum Output Rate of Change	DOUBLE	Yes	0	Yes	Yes	No	No
OVAL	Output Value	DOUBLE	No	0	Yes	Yes	Yes	No

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.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
OUT	Output Link	OUTLINK	Yes	0	Yes	Yes	No	No
DTYP	Device Type	DEVCHOICE	Yes	0	Yes	No	No
LINR	Type of Conversion	menuConvert	Yes	0	Yes	Yes	No	Yes
RVAL	Raw Value	LONG	No	0	Yes	Yes	Yes	Yes
ROFF	Raw Value Offset	LONG	No	0	Yes	Yes	No	Yes
EGUF	Engineering Units Full	DOUBLE	Yes	0	Yes	Yes	No	Yes
EGUL	Engineering Units Low	DOUBLE	Yes	0	Yes	Yes	No	Yes
AOFF	Adjustment Offset	DOUBLE	Yes	0	Yes	Yes	No	Yes
ASLO	Adjustment Slope	DOUBLE	Yes	1	Yes	Yes	No	Yes
ESLO	Slope for Linear Conversions	DOUBLE	Yes	1	Yes	No	No	No
EOFF	Offset for Linear Conversions	DOUBLE	Yes	0	Yes	No	No	No

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.

EGUF	The user must provide 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
ESLO	Computed 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
AOFF	These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.
ASLO
ROFF	This field may be set by device support to configure an offset to be subtracted from the adjusted value when a value is converted to RVAL. It should not be set by the user.

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.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
EGU	Engineering Units	STRING [16]	Yes	null	Yes	Yes	No	No
HOPR	High Operating Range	DOUBLE	Yes	0	Yes	Yes	No	No
LOPR	Low Operating Range	DOUBLE	Yes	0	Yes	Yes	No	No
PREC	Display Precision	SHORT	Yes	0	Yes	Yes	No	No
NAME	Record Name	STRING [29]	Yes	0	Yes	No	No	No
DESC	Description	STRING [29]	Yes	Null	Yes	Yes	No	No

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.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
HIHI	Hihi Alarm Limit	DOUBLE	Yes	0	Yes	Yes	No	Yes
HIGH	High Alarm Limit	DOUBLE	Yes	0	Yes	Yes	No	Yes
LOW	Low Alarm Limit	DOUBLE	Yes	0	Yes	Yes	No	Yes
LOLO	Lolo Alarm Limit	DOUBLE	Yes	0	Yes	Yes	No	Yes
HHSV	Hihi Alarm Severity	menuAlarmSevr	Yes	0	Yes	Yes	No	Yes
HSV	High Alarm Severity	menuAlarmSevr	Yes	0	Yes	Yes	No	Yes
LSV	Low Alarm Severity	menuAlarmSevr	Yes	0	Yes	Yes	No	Yes
LLSV	Lolo Alarm Severity	menuAlarmSevr	Yes	0	Yes	Yes	No	Yes
HYST	Alarm Deadband	DOUBLE	Yes	0	Yes	Yes	No	No
IVOA	Invalid Alarm Output Action	menuIvoa	Yes	0	Yes	Yes	No	No
IVOV	Invalid Alarm Output Value, in eng. units	DOUBLE	Yes	0	Yes	Yes	No	No

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.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
ADEL	Archive Deadband	DOUBLE	Yes	0	Yes	Yes	No	No
MDEL	Monitor, i.e. value change, Deadband	DOUBLE	Yes	0	Yes	Yes	No	No

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.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
ORAW	Old Raw Value	LONG	No	0	Yes	No	No	No
RBV	Read Back Value	LONG	No	0	Yes	No	Yes	No
ORBV	Old read back value	LONG	No	0	Yes	No	No	No
LALM	Last Alarm Monitor Trigger Value	DOUBLE	No	0	Yes	No	No	No
ALST	Last Archiver Monitor Trigger Value	DOUBLE	No	0	Yes	No	No	No
MLST	Last Value Change Monitor Trigger Value	DOUBLE	No	0	Yes	No	No	No
INIT	Initialize	SHORT	No	0	Yes	No	No	No
PBRK	Address of Breakpoint Table	NOACCESS	No	4	No	No	No
LBRK	Last Breakpoint	SHORT	No	0	Yes	No	No	No
PVAL	Previous Data Value	DOUBLE	No	0	Yes	No	No	No
OMOD	OVAL modified?	LONG	No	Null	Yes	No	No	No

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.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
SIOL	Simulation Value Location	INLINK	Yes	0	Yes	Yes	No	No
SIML	Simulation Mode Location	INLINK	Yes	0	Yes	Yes	No	No
SIMM	Simulation Mode	menuSimm	No	0	Yes	Yes	No	No
SIMS	Simulation Mode Alarm Severity	menuAlarmSevr	Yes	0	Yes	Yes	No	No

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:

Name	Summary	Description
PACT	Processing Active	See Fields Common to All Record Types for an explanation of these fields.
DPVT	Device Private
NSEV	New Alarm Severity
NSTA	New Alarm Status
OUT	Output Link	This field is used by the device support routines to locate its output.
EGUF	Engineering Units Full	These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.
EGUL	Engineering Unit Low
ESLO	Slope	These 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.
EOFF	Offset
RVAL	Raw Value	This 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.