Update the initial documentation to normal Pod syntax

This commit is contained in:
Andrew Johnson
2012-09-04 00:40:37 -05:00
committed by Ralph Lange
parent 29a9ad3f90
commit d2d40b901a
3 changed files with 281 additions and 274 deletions

View File

@@ -1,137 +1,141 @@
#=head1 Channel Filters
#
# Channel Filters can be applied to Channel Access channels by a client, using
# a JSON Field Modifier to select the filter and any parameters.
# The following filters are available in this release:
#
#=over 4
#
#=item * L<TimeStamp|/"TimeStamp Filter "ts"">
#
#=item * L<Deadband|/"Deadband Filter "dbnd"">
#
#=item * L<Array|/"Array Filter "arr"">
#
#=item * L<Synchronize|/"Synchronize Filter "sync"">
#
#=back
#
#=head2 Using Filters
#
# Channel filters can be added to any Channel Access channel name.
# There can be more than one filter applied to the same channel, in which case the
# order that they are specified will control the order in which they are applied
# to the resulting data-stream.
# The filter specification must appear after the field name, or if the default
# (VAL) field is used after a dot C<.> appended to the record name.
# With the exception of the array short-hand which is described below, all filters
# must appear inside a pair of braces C< {} > after the dot expressed as a JSON
# (L<JavaScript Object Notation|http://www.json.org/>) object, which allows filter
# parameters to be included as needed.
#
# Each filter is given as a name/value pair. The filter name (given in parentheses
# in the titles below) is a string, and must be enclosed inside double-quotes C<">
# characters as per the JSON specification.
# Parameters to that filter are provided as the value part of the name/value pair,
# and will normally appear as a child JSON object consisting of name/value pairs
# inside a nested pair of braces C< {} >.
#
#=head4 Example Filter
#
# Given a record called C<test:channel> the following would apply a filter C<f> to
# the VAL field of that record, giving the filter two numeric parameters named C<lo>
# and C<hi>:
#
# test:channel.{"f":{"lo":0,"hi":10}}
#
# Note that due to the required presence of the double-quote characters in the JSON
# strings in the name string, it will usually be necessary to enclose a filtered name
# within single-quotes C<< ' E<hellip> ' >> when typing it as an argument to a Unix
# shell command.
#
#=head2 Filter Reference
#
=head1 Channel Filters
Channel Filters can be applied to Channel Access channels by a client, using
a JSON Field Modifier to select the filter and any parameters.
The following filters are available in this release:
=over 4
=item * L<TimeStamp|/"TimeStamp Filter "ts"">
=item * L<Deadband|/"Deadband Filter "dbnd"">
=item * L<Array|/"Array Filter "arr"">
=item * L<Synchronize|/"Synchronize Filter "sync"">
=back
=head2 Using Filters
Channel filters can be added to any Channel Access channel name.
There can be more than one filter applied to the same channel, in which case the
order that they are specified will control the order in which they are applied
to the resulting data-stream.
The filter specification must appear after the field name, or if the default
(VAL) field is used after a dot C<.> appended to the record name.
With the exception of the array short-hand which is described below, all filters
must appear inside a pair of braces C< {} > after the dot expressed as a JSON
(L<JavaScript Object Notation|http://www.json.org/>) object, which allows filter
parameters to be included as needed.
Each filter is given as a name/value pair. The filter name (given in parentheses
in the titles below) is a string, and must be enclosed inside double-quotes C<">
characters as per the JSON specification.
Parameters to that filter are provided as the value part of the name/value pair,
and will normally appear as a child JSON object consisting of name/value pairs
inside a nested pair of braces C< {} >.
=head4 Example Filter
Given a record called C<test:channel> the following would apply a filter C<f> to
the VAL field of that record, giving the filter two numeric parameters named
C<lo> and C<hi>:
test:channel.{"f":{"lo":0,"hi":10}}
Note that due to the required presence of the double-quote characters in the
JSON strings in the name string, it will usually be necessary to enclose a
filtered name within single-quotes C<< ' E<hellip> ' >> when typing it as an
argument to a Unix shell command.
=head2 Filter Reference
=cut
registrar(tsInitialize)
#=head3 TimeStamp Filter C<"ts">
#
# This filter is used to set the timestamp of the (first) value fetched through the
# channel to the connection time, rather than the time the record last processed
# which could have been days or even weeks ago for some records, or set to the
# EPICS epoch if the record has never processed.
#
#=head4 Parameters
#
# None, use an empty pair of braces.
#
#=head4 Example
#
# Hal$ caget -a 'test:channel.{"ts":{}}'
# test:channel.{"ts":{}} 2012-08-28 22:10:31.192547 0 UDF INVALID
# Hal$ caget -a 'test:channel'
# test:channel <undefined> 0 UDF INVALID
#
=head3 TimeStamp Filter C<"ts">
This filter is used to set the timestamp of the (first) value fetched through
the channel to the connection time, rather than the time the record last
processed which could have been days or even weeks ago for some records, or set
to the EPICS epoch if the record has never processed.
=head4 Parameters
None, use an empty pair of braces.
=head4 Example
Hal$ caget -a 'test:channel.{"ts":{}}'
test:channel.{"ts":{}} 2012-08-28 22:10:31.192547 0 UDF INVALID
Hal$ caget -a 'test:channel'
test:channel <undefined> 0 UDF INVALID
=cut
registrar(dbndInitialize)
#=head3 Deadband Filter C<"dbnd">
#
# This filter implements a channel-specific monitor deadband, which is applied
# after any deadbands implemented by the record itself (it can only drop updates
# that the unfiltered channel generates, never add additional updates).
#
# The deadband can be specified as an absolute value change, or as a relative
# percentage.
#
#=head4 Parameters
#
#=over 4
#
#=item Deadband C<"d">
#
# The size of the deadband to use.
# Relative deadband values are given as a numeric percentage, but without any
# trailing percent character.
#
#=item Mode C<"m"> (optional)
#
# A string (enclosed in double-quotes C<">), which should contain either
# C<abs> or C<rel>.
# The default mode is absolute if no mode parameter is included.
#
#=back
#
#=head4 Example
#
# Hal$ camonitor 'test:channel'
# test:channel 2012-09-01 22:10:19.600595 1 LOLO MAJOR
# test:channel 2012-09-01 22:10:20.600661 2 LOLO MAJOR
# test:channel 2012-09-01 22:10:21.600819 3 LOW MINOR
# test:channel 2012-09-01 22:10:22.600905 4 LOW MINOR
# test:channel 2012-09-01 22:10:23.601023 5
# test:channel 2012-09-01 22:10:24.601136 6 HIGH MINOR
# ^C
# Hal$ camonitor 'test:channel.{"dbnd":{"d":1.5}}'
# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:49.613341 1 LOLO MAJOR
# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:51.613615 3 LOW MINOR
# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:53.613804 5
# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:55.614074 7 HIGH MINOR
# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:57.614305 9 HIHI MAJOR
# ^C
#
=head3 Deadband Filter C<"dbnd">
This filter implements a channel-specific monitor deadband, which is applied
after any deadbands implemented by the record itself (it can only drop updates
that the unfiltered channel generates, never add additional updates).
The deadband can be specified as an absolute value change, or as a relative
percentage.
=head4 Parameters
=over 4
=item Deadband C<"d">
The size of the deadband to use.
Relative deadband values are given as a numeric percentage, but without any
trailing percent character.
=item Mode C<"m"> (optional)
A string (enclosed in double-quotes C<">), which should contain either
C<abs> or C<rel>.
The default mode is absolute if no mode parameter is included.
=back
=head4 Example
Hal$ camonitor 'test:channel'
test:channel 2012-09-01 22:10:19.600595 1 LOLO MAJOR
test:channel 2012-09-01 22:10:20.600661 2 LOLO MAJOR
test:channel 2012-09-01 22:10:21.600819 3 LOW MINOR
test:channel 2012-09-01 22:10:22.600905 4 LOW MINOR
test:channel 2012-09-01 22:10:23.601023 5
test:channel 2012-09-01 22:10:24.601136 6 HIGH MINOR
^C
Hal$ camonitor 'test:channel.{"dbnd":{"d":1.5}}'
test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:49.613341 1 LOLO MAJOR
test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:51.613615 3 LOW MINOR
test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:53.613804 5
test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:55.614074 7 HIGH MINOR
test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:57.614305 9 HIHI MAJOR
^C
=cut
registrar(arrInitialize)
#=head3 Array Filter C<"arr">
#
# ...
#
=head3 Array Filter C<"arr">
...
=cut
registrar(syncInitialize)
#=head3 Synchronize Filter C<"sync">
#
# ...
#
=head3 Synchronize Filter C<"sync">
...
=cut

View File

@@ -7,149 +7,151 @@
# in file LICENSE that is included with this distribution.
#*************************************************************************
recordtype(ai) {
#=head1 Analog Input (ai)
#
# This record type is normally used to obtain an analog value from
# a hardware input and convert it to engineering units. The record
# supports linear and break-point conversion to engineering units,
# smoothing, alarm limits, alarm filtering, and graphics and control
# limits.
#
#=head2 Parameter Fields
#
# The record fields are described below grouped by functionality.
#
#=head3 Input Specification
#
# These fields control where (if anywhere) the record reads data from
# when it is processed:
#
#=fields INP, DTYP
#
# I<Description?>
#
#=head3 Units Conversion
#
# These fields control how the raw input value gets converted into
# engineering units:
#
#=fields RVAL, ROFF, ASLO, AOFF, LINR, ESLO, EOFF, EGUL, EGUF
#
# These fields are not used if the device support layer reads its
# value in engineering units and puts it directly into the VAL field.
#
# If the device support sets the RVAL field, the LINR field controls
# how this gets converted into engineering units and placed in the
# VAL field as follows:
#
#=over 4
#
#=item 1. RVAL is converted to a double and ROFF is added to it
#
#=item 2. If ASLO is non-zero the value is multiplied by ASLO
#
#=item 3. AOFF is added
#
#=item 4. If LINR is C<NO CONVERSION> the units conversion is finished
# after the above steps
#
#=item 5. If LINR is C<LINEAR> or C<SLOPE>, the value from step 3
# above is multiplied by ESLO and EOFF is added to complete the units
# conversion process
#
#=item 6. Any other value for LINR selects a particular breakpoint
# table to be used on the value from step 3 above
#
#=back
#
# The distinction between the C<LINEAR> and C<SLOPE> settings for the
# LINR field are in how the conversion parameters are calculated:
#
#=over 4
#
#=item *
# With C<LINEAR> conversion the user must set EGUL and EGUF to the
# lowest and highest possible engineering units values respectively
# that can be converted by the hardware. The device support knows
# the range of the raw data and calculates ESLO and EOFF from them.
#
#=item *
# C<SLOPE> conversion requires the user to calculate the appropriate
# scaling and offset factors and put them directly in ESLO and EOFF.
#
#=back
#
#=head3 Smoothing Filter
#
# This filter is usually only used if the device support sets the RVAL
# field and the Units Conversion process is used. Device support that
# directly sets the VAL field may implement the filter if desired.
#
# The filter is controlled with a single parameter field:
#
#=fields SMOO
#
# The SMOO field should be set to a number between 0 and 1. If set to
# zero the filter is not used (no smoothing), while if set to one the
# result is infinite smoothing (the VAL field will never change). The
# calculation performed is:
#
# VAL = VAL * SMOO + (1 - SMOO) * New Data
#
# where C<New Data> was the result from the Units Conversion above.
# This implements a first-order infinite impulse response (IIR)
# digital filter with z-plane pole at SMOO. The equivalent
# continuous-time filter time constant E<tau> is given by
#
#=over 4
#
# E<tau> = E<minus>T / ln(SMOO)
#
#=back
#
# where T is the time between record processing.
#
#=head3 Undefined Check
#
# If after applying the smoothing filter the VAL field contains a NaN
# (Not-a-Number) value, the UDF field is set to indicate that the
# record value is undefined, which triggers a C<UDF_ALARM> with
# severity C<INVALID_ALARM>.
#
#=fields UDF
#
#=head3 Operator Display Parameters
#
# These parameters are used to present meaningful data to the operator.
#
#=over 4
#
#=item *
# DESC is a string that is usually used to briefly describe the record.
#
#=item *
# EGU is a string of up to 16 characters giving the units that the
# analog input measures.
#
#=item *
# The HOPR and LOPR fields set the upper and lower display limits for
# the VAL, HIHI, HIGH, LOW, and LOLO fields.
#
#=item *
# The PREC field determines the floating point precision with which
# to display VAL.
#
#=back
#
#=fields DESC, EGU, HOPR, LOPR, PREC
#
#=head3 Alarm Parameters
#
# ...
#
#=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST, AFTC
#
#=cut
=head1 Analog Input (ai)
This record type is normally used to obtain an analog value from
a hardware input and convert it to engineering units. The record
supports linear and break-point conversion to engineering units,
smoothing, alarm limits, alarm filtering, and graphics and control
limits.
=head2 Parameter Fields
The record fields are described below grouped by functionality.
=head3 Input Specification
These fields control where (if anywhere) the record reads data from
when it is processed:
=fields INP, DTYP
I<Description?>
=head3 Units Conversion
These fields control how the raw input value gets converted into
engineering units:
=fields RVAL, ROFF, ASLO, AOFF, LINR, ESLO, EOFF, EGUL, EGUF
These fields are not used if the device support layer reads its
value in engineering units and puts it directly into the VAL field.
If the device support sets the RVAL field, the LINR field controls
how this gets converted into engineering units and placed in the
VAL field as follows:
=over 4
=item 1. RVAL is converted to a double and ROFF is added to it
=item 2. If ASLO is non-zero the value is multiplied by ASLO
=item 3. AOFF is added
=item 4. If LINR is C<NO CONVERSION> the units conversion is finished
after the above steps
=item 5. If LINR is C<LINEAR> or C<SLOPE>, the value from step 3
above is multiplied by ESLO and EOFF is added to complete the units
conversion process
=item 6. Any other value for LINR selects a particular breakpoint
table to be used on the value from step 3 above
=back
The distinction between the C<LINEAR> and C<SLOPE> settings for the
LINR field are in how the conversion parameters are calculated:
=over 4
=item *
With C<LINEAR> conversion the user must set EGUL and EGUF to the
lowest and highest possible engineering units values respectively
that can be converted by the hardware. The device support knows
the range of the raw data and calculates ESLO and EOFF from them.
=item *
C<SLOPE> conversion requires the user to calculate the appropriate
scaling and offset factors and put them directly in ESLO and EOFF.
=back
=head3 Smoothing Filter
This filter is usually only used if the device support sets the RVAL
field and the Units Conversion process is used. Device support that
directly sets the VAL field may implement the filter if desired.
The filter is controlled with a single parameter field:
=fields SMOO
The SMOO field should be set to a number between 0 and 1. If set to
zero the filter is not used (no smoothing), while if set to one the
result is infinite smoothing (the VAL field will never change). The
calculation performed is:
VAL = VAL * SMOO + (1 - SMOO) * New Data
where C<New Data> was the result from the Units Conversion above.
This implements a first-order infinite impulse response (IIR)
digital filter with z-plane pole at SMOO. The equivalent
continuous-time filter time constant E<tau> is given by
=over 4
E<tau> = E<minus>T / ln(SMOO)
=back
where T is the time between record processing.
=head3 Undefined Check
If after applying the smoothing filter the VAL field contains a NaN
(Not-a-Number) value, the UDF field is set to indicate that the
record value is undefined, which triggers a C<UDF_ALARM> with
severity C<INVALID_ALARM>.
=fields UDF
=head3 Operator Display Parameters
These parameters are used to present meaningful data to the operator.
=over 4
=item *
DESC is a string that is usually used to briefly describe the record.
=item *
EGU is a string of up to 16 characters giving the units that the
analog input measures.
=item *
The HOPR and LOPR fields set the upper and lower display limits for
the VAL, HIHI, HIGH, LOW, and LOLO fields.
=item *
The PREC field determines the floating point precision with which
to display VAL.
=back
=fields DESC, EGU, HOPR, LOPR, PREC
=head3 Alarm Parameters
...
=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST, AFTC
=cut
include "dbCommon.dbd"
field(VAL,DBF_DOUBLE) {
prompt("Current EGU Value")

View File

@@ -3,8 +3,7 @@
# National Laboratory.
# Copyright (c) 2002 The Regents of the University of California, as
# Operator of Los Alamos National Laboratory.
# EPICS BASE Versions 3.13.7
# and higher are distributed subject to a Software License Agreement found
# EPICS BASE is distributed subject to a Software License Agreement found
# in file LICENSE that is included with this distribution.
#*************************************************************************
menu(compressALG) {
@@ -16,11 +15,13 @@ menu(compressALG) {
choice(compressALG_N_to_1_Median,"N to 1 Median")
}
recordtype(compress) {
#=head1 Compress Record (compress)
#
#=fields VAL
#
#=cut
=head1 Compress Record (compress)
=fields VAL
=cut
include "dbCommon.dbd"
field(VAL,DBF_NOACCESS) {
prompt("Value")