doc/calibration_funcref.txt: Some DocBook mark-up changes.
This commit is contained in:
Ian Abbott
parent
09106917de
commit
c1cd802546
1 changed files with 132 additions and 82 deletions
|
|
@ -1,22 +1,28 @@
|
|||
Calibration
|
||||
Function: comedi_apply_calibration -- set hardware calibration from file
|
||||
Retval: int
|
||||
Param: comedi_t *device
|
||||
Param: comedi_t * device
|
||||
Param: unsigned int subdevice
|
||||
Param: unsigned int channel
|
||||
Param: unsigned int range
|
||||
Param: unsigned int aref
|
||||
Param: const char *file_path
|
||||
Param: const char * file_path
|
||||
Status: alpha
|
||||
Description:
|
||||
This function sets the hardware calibration for the specified subdevice
|
||||
so that it is in proper calibration when using the specified
|
||||
channel, range and aref. It does so by performing writes
|
||||
The function <function>comedi_apply_calibration</function> sets the
|
||||
hardware calibration for the subdevice specified by
|
||||
<parameter class="function">device</parameter> and
|
||||
<parameter class="function">subdevice</parameter>
|
||||
so that it is in proper calibration when using the channel specified by
|
||||
<parameter class="function">channel</parameter>,
|
||||
range index specified by <parameter class="function">range</parameter> and
|
||||
analog reference specified by <parameter class="function">aref</parameter>.
|
||||
It does so by performing writes
|
||||
to the appropriate channels of the board's calibration
|
||||
subdevice(s). Depending on the hardware, the
|
||||
calibration settings used may or may not depend on the channel,
|
||||
range, or aref. Furthermore, the calibrations appropriate
|
||||
for different channel, range, and aref parameters
|
||||
range, or analog reference. Furthermore, the calibrations appropriate
|
||||
for different channel, range, and analog reference parameters
|
||||
may not be able to be applied simultaneously.
|
||||
For example, some boards cannot have their analog inputs calibrated
|
||||
for more than one input range simultaneously. Applying a calibration for range 1 may
|
||||
|
|
@ -24,40 +30,46 @@ Description:
|
|||
a calibration for analog input channel 0 may cause the same
|
||||
calibration to be applied to all the
|
||||
other analog input channels as well.
|
||||
Your only guarantee is that calls to comedi_apply_calibration()
|
||||
Your only guarantee is that calls to
|
||||
<function>comedi_apply_calibration</function>
|
||||
on different subdevices will not interfere with each other.
|
||||
|
||||
In practice, their are some rules of thumb on how
|
||||
calibrations behave. No calibrations depend on the aref.
|
||||
calibrations behave. No calibrations depend on the analog reference.
|
||||
A multiplexed analog input will have calibration settings that
|
||||
do not depend on the channel, and applying a setting for one
|
||||
channel will affect
|
||||
all channels equally. Analog outputs, and analog inputs
|
||||
with independent a/d converters for each input channel, will have
|
||||
calibrations settings which do depend on the channel, and the
|
||||
calibration settings which do depend on the channel, and the
|
||||
settings for each channel will be independent of the other
|
||||
channels.
|
||||
|
||||
If you wish to investigate exactly what comedi_apply_calibration()
|
||||
If you wish to investigate exactly what
|
||||
<function>comedi_apply_calibration</function>
|
||||
is doing, you can perform reads on your board's calibration
|
||||
subdevice to see which calibration channels it is changing.
|
||||
You can also try to decipher the calibration file directly (it's a
|
||||
text file).
|
||||
|
||||
The file_path parameter can be used
|
||||
The <parameter class="function">file_path</parameter> parameter can be used
|
||||
to specify the file which contains the calibration information.
|
||||
If <parameter>file_path</parameter> is NULL, then comedilib
|
||||
If <parameter class="function">file_path</parameter> is
|
||||
<constant>NULL</constant>, then Comedilib
|
||||
will use a default
|
||||
file location. The calibration information used by this function
|
||||
is generated by the comedi_calibrate program (see its man page).
|
||||
is generated by the <command>comedi_calibrate</command> program (see its man page).
|
||||
|
||||
The functions
|
||||
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>,
|
||||
<link linkend="func-ref-comedi-apply-parsed-calibration"><function>comedi_apply_parsed_calibration</function></link>,
|
||||
and <link linkend="func-ref-comedi-cleanup-calibration"><function>comedi_cleanup_calibration_file</function></link>
|
||||
<function><link
|
||||
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>,
|
||||
<function><link
|
||||
linkend="func-ref-comedi-apply-parsed-calibration">comedi_apply_parsed_calibration</link></function>,
|
||||
and <function><link
|
||||
linkend="func-ref-comedi-cleanup-calibration">comedi_cleanup_calibration_file</link></function>
|
||||
provide the same functionality at a slightly lower level.
|
||||
Returns:
|
||||
Zero on success, a negative number on failure.
|
||||
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
|
||||
|
||||
Function: comedi_apply_parsed_calibration -- set calibration from memory
|
||||
Retval: int
|
||||
|
|
@ -66,81 +78,99 @@ Param: unsigned int subdevice
|
|||
Param: unsigned int channel
|
||||
Param: unsigned int range
|
||||
Param: unsigned int aref
|
||||
Param: const comedi_calibration_t *calibration
|
||||
Param: const comedi_calibration_t * calibration
|
||||
Status: alpha
|
||||
Description:
|
||||
This function is similar to
|
||||
<link linkend="func-ref-comedi-apply-calibration"><function>comedi_apply_calibration</function></link>,
|
||||
<function><link
|
||||
linkend="func-ref-comedi-apply-calibration">comedi_apply_calibration</link></function>,
|
||||
except the calibration information is read from memory
|
||||
instead of a file. This function can be more
|
||||
efficient than comedi_apply_calibration() since the
|
||||
efficient than <function>comedi_apply_calibration</function> since the
|
||||
calibration file does not need to be reparsed with
|
||||
every call. The <parameter>calibration</parameter> is
|
||||
every call. The value of parameter <parameter class="function">calibration</parameter> is
|
||||
obtained by a call to
|
||||
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>.
|
||||
<function><link
|
||||
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>.
|
||||
|
||||
Returns:
|
||||
Zero on success, a negative number on failure.
|
||||
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
|
||||
|
||||
Function: comedi_cleanup_calibration -- free calibration resources
|
||||
Retval: void
|
||||
Param: comedi_calibration_t *calibration
|
||||
Param: comedi_calibration_t * calibration
|
||||
Status: alpha
|
||||
Description:
|
||||
This function frees the resources associated with a
|
||||
comedi_calibration_t obtained from
|
||||
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>.
|
||||
*<parameter>calibration</parameter>
|
||||
<type>comedi_calibration_t</type> obtained from
|
||||
<function><link
|
||||
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>.
|
||||
The <type>comedi_calibration_t</type> pointed to by
|
||||
<parameter class="function">calibration</parameter>
|
||||
can not be used again after calling this function.
|
||||
|
||||
Function: comedi_get_default_calibration_path -- get default calibration file path
|
||||
Retval: char*
|
||||
Param: comedi_t *dev
|
||||
Retval: char *
|
||||
Param: comedi_t * device
|
||||
Status: alpha
|
||||
Description:
|
||||
This function returns a string containing a default calibration file
|
||||
path appropriate for <parameter>dev</parameter>. Memory for the
|
||||
string is allocated by the function, and should be freed when
|
||||
This function returns a pointer to a string containing a default calibration file
|
||||
path appropriate for the Comedi device specified by
|
||||
<parameter class="function">device</parameter>. Memory for the
|
||||
string is allocated by the function, and should be freed with the C library
|
||||
function <function>free</function> when
|
||||
the string is no longer needed.
|
||||
Returns:
|
||||
A string which contains a file path useable by
|
||||
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>.
|
||||
On error, NULL is returned.
|
||||
<function><link
|
||||
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>.
|
||||
On error, <constant>NULL</constant> is returned.
|
||||
|
||||
Function: comedi_get_hardcal_converter -- get converter for hardware-calibrated subdevice
|
||||
Retval: int
|
||||
Param: comedi_t *dev
|
||||
Param: comedi_t * device
|
||||
Param: unsigned subdevice
|
||||
Param: unsigned channel
|
||||
Param: unsigned range
|
||||
Param: enum comedi_conversion_direction direction
|
||||
Param: comedi_polynomial_t *converter
|
||||
Param: comedi_polynomial_t * converter
|
||||
Status: alpha
|
||||
Description:
|
||||
comedi_get_hardcal_converter() initializes *<parameter>converter</parameter> so it can be
|
||||
The function <function>comedi_get_hardcal_converter</function> initializes
|
||||
the <type>comedi_polynomial_t</type> pointed to by
|
||||
<parameter class="function">converter</parameter> so it can be
|
||||
passed to either
|
||||
<link linkend="func-ref-comedi-to-physical"><function>comedi_to_physical</function></link>,
|
||||
or <link linkend="func-ref-comedi-from-physical"><function>comedi_from_physical</function></link>.
|
||||
<function><link
|
||||
linkend="func-ref-comedi-to-physical">comedi_to_physical</link></function>,
|
||||
or <function><link
|
||||
linkend="func-ref-comedi-from-physical">comedi_from_physical</link></function>.
|
||||
The result can be used to
|
||||
convert data from the specified <parameter>subdevice</parameter>,
|
||||
<parameter>channel</parameter>, and <parameter>range</parameter>. The <parameter>direction</parameter>
|
||||
parameter specifies whether <parameter>converter</parameter> will be passed to comedi_to_physical()
|
||||
or comedi_from_physical().
|
||||
convert data from the specified <parameter class="function">subdevice</parameter>,
|
||||
<parameter class="function">channel</parameter>, and <parameter
|
||||
class="function">range</parameter>. The <parameter class="function">direction</parameter>
|
||||
parameter specifies whether <parameter class="function">converter</parameter>
|
||||
will be passed to <function>comedi_to_physical</function>
|
||||
or <function>comedi_from_physical</function>.
|
||||
|
||||
This function initializes *<parameter>converter</parameter> as a simple linear function with no
|
||||
This function initializes the <type>comedi_polynomial_t</type> pointed to by
|
||||
<parameter class="function">converter</parameter> as a simple linear function with no
|
||||
calibration information, appropriate
|
||||
for boards which do their gain/offset/nonlinearity corrections in hardware. If your board
|
||||
needs calibration to be performed in software by the host computer, use comedi_get_softcal_converter()
|
||||
needs calibration to be performed in software by the host computer,
|
||||
use <function>comedi_get_softcal_converter</function>
|
||||
instead. A subdevice will advertise the fact that it depends on a software calibration
|
||||
with the SDF_SOFT_CALIBRATED subdevice flag.
|
||||
with the <constant>SDF_SOFT_CALIBRATED</constant> subdevice flag.
|
||||
|
||||
The result of this function will only depend on the <parameter>channel</parameter>
|
||||
The result of this function will only depend on the
|
||||
<parameter class="function">channel</parameter>
|
||||
parameter if either
|
||||
<link linkend="func-ref-comedi-range-is-chan-specific"><function>comedi_range_is_chan_specific</function></link>
|
||||
or <link linkend="func-ref-comedi-maxdata-is-chan-specific"><function>comedi_maxdata_is_chan_specific</function></link>
|
||||
returns true for the specified <parameter>subdevice</parameter>.
|
||||
<function><link
|
||||
linkend="func-ref-comedi-range-is-chan-specific">comedi_range_is_chan_specific</link></function>
|
||||
or <function><link
|
||||
linkend="func-ref-comedi-maxdata-is-chan-specific">comedi_maxdata_is_chan_specific</link></function>
|
||||
returns true for the specified <parameter class="function">subdevice</parameter>.
|
||||
Returns:
|
||||
Zero on success or -1 on failure.
|
||||
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
|
||||
|
||||
Function: comedi_get_softcal_converter -- get converter for software-calibrated subdevice
|
||||
Retval: int
|
||||
|
|
@ -148,29 +178,42 @@ Param: unsigned subdevice
|
|||
Param: unsigned channel
|
||||
Param: unsigned range
|
||||
Param: enum comedi_conversion_direction direction
|
||||
Param: const comedi_calibration_t *parsed_calibration
|
||||
Param: comedi_polynomial_t *converter
|
||||
Param: const comedi_calibration_t * parsed_calibration
|
||||
Param: comedi_polynomial_t * converter
|
||||
Status: alpha
|
||||
Description:
|
||||
comedi_get_softcal_converter() initializes *<parameter>converter</parameter> so it can be
|
||||
The function <function>comedi_get_softcal_converter</function> initializes
|
||||
the <type>comedi_polynomial_t</type> pointed to by
|
||||
<parameter class="function">converter</parameter> so it can be
|
||||
passed to either
|
||||
<link linkend="func-ref-comedi-to-physical"><function>comedi_to_physical</function></link>
|
||||
or <link linkend="func-ref-comedi-from-physical"><function>comedi_from_physical</function></link>.
|
||||
The *<parameter>converter</parameter>
|
||||
struct can then be used to
|
||||
convert data from the specified <parameter>subdevice</parameter>,
|
||||
<parameter>channel</parameter>, and <parameter>range</parameter>. The <parameter>direction</parameter>
|
||||
parameter specifies whether *<parameter>converter</parameter> will be passed to comedi_to_physical()
|
||||
or comedi_from_physical(). The <parameter>parsed_calibration</parameter> parameter contains the
|
||||
<function><link
|
||||
linkend="func-ref-comedi-to-physical">comedi_to_physical</link></function>
|
||||
or <function><link
|
||||
linkend="func-ref-comedi-from-physical">comedi_from_physical</link></function>.
|
||||
The <type>comedi_polynomial_t</type> pointed to by
|
||||
<parameter class="function">converter</parameter>
|
||||
can then be used to
|
||||
convert data for the specified <parameter class="function">subdevice</parameter>,
|
||||
<parameter class="function">channel</parameter>, and
|
||||
<parameter class="function">range</parameter>.
|
||||
The <parameter class="function">direction</parameter>
|
||||
parameter specifies whether <parameter class="function">converter</parameter>
|
||||
will be passed to <function>comedi_to_physical</function>
|
||||
or <function>comedi_from_physical</function>.
|
||||
The <parameter class="function">parsed_calibration</parameter> parameter
|
||||
points to the
|
||||
software calibration values for your device, and may be obtained by calling
|
||||
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>
|
||||
on a calibration file generated by the comedi_soft_calibrate program.
|
||||
<function><link
|
||||
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>
|
||||
on a calibration file generated by the
|
||||
<command>comedi_soft_calibrate</command> program.
|
||||
|
||||
This function is only useful for boards that perform their calibrations in software on the host
|
||||
computer. A subdevice will advertise the fact that it depends on a software calibration
|
||||
with the SDF_SOFT_CALIBRATED subdevice flag.
|
||||
with the <constant>SDF_SOFT_CALIBRATED</constant> subdevice flag.
|
||||
|
||||
Whether or not the result of this function actually depends on the <parameter>channel</parameter>
|
||||
Whether or not the result of this function actually depends on the
|
||||
<parameter class="function">channel</parameter>
|
||||
parameter is
|
||||
hardware dependent. For example, the calibration of a multiplexed analog input will typically
|
||||
not depend on the channel, only the range. Analog outputs will typically use different calibrations
|
||||
|
|
@ -178,29 +221,36 @@ Description:
|
|||
|
||||
Software calibrations are implemented as polynomials (up to third order). Since the inverse
|
||||
of a polynomial of order higher than one can't be represented exactly as another polynomial, you
|
||||
may not be able to get converters for the "reverse" direction. For example, you may be
|
||||
able to get a converter for an analog input in the COMEDI_TO_PHYSICAL direction, but not
|
||||
in the COMEDI_FROM_PHYSICAL direction.
|
||||
may not be able to get converters for the <quote>reverse</quote> direction. For example, you may be
|
||||
able to get a converter for an analog input in the
|
||||
<constant>COMEDI_TO_PHYSICAL</constant> direction, but not
|
||||
in the <constant>COMEDI_FROM_PHYSICAL</constant> direction.
|
||||
Returns:
|
||||
Zero on success or -1 on failure.
|
||||
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
|
||||
|
||||
Function: comedi_parse_calibration_file -- load contents of calibration file
|
||||
Retval: comedi_calibration_t*
|
||||
Param: const char *file_path
|
||||
Retval: comedi_calibration_t *
|
||||
Param: const char * file_path
|
||||
Status: alpha
|
||||
Description:
|
||||
This function parses a calibration file (produced by the
|
||||
comedi_calibrate or comedi_soft_calibrate programs) and returns a pointer
|
||||
to a comedi_calibration_t which can be passed to the
|
||||
<link linkend="func-ref-comedi-apply-parsed-calibration"><function>comedi_apply_parsed_calibration</function></link>
|
||||
or <link linkend="func-ref-comedi-get-softcal-converter"><function>comedi_get_softcal_converter</function></link>
|
||||
<command>comedi_calibrate</command> or
|
||||
<command>comedi_soft_calibrate</command> programs) and returns a pointer
|
||||
to a <type>comedi_calibration_t</type> which can be passed to the
|
||||
<function><link
|
||||
linkend="func-ref-comedi-apply-parsed-calibration">comedi_apply_parsed_calibration</link></function>
|
||||
or <function><link
|
||||
linkend="func-ref-comedi-get-softcal-converter">comedi_get_softcal_converter</link></function>
|
||||
functions. When you are
|
||||
finished using the comedi_calibration_t, you should
|
||||
call <link linkend="func-ref-comedi-cleanup-calibration"><function>comedi_cleanup_calibration</function></link>
|
||||
finished using the <type>comedi_calibration_t</type>, you should
|
||||
call <function><link
|
||||
linkend="func-ref-comedi-cleanup-calibration">comedi_cleanup_calibration</link></function>
|
||||
to free the resources
|
||||
associated with the comedi_calibration_t.
|
||||
associated with the <type>comedi_calibration_t</type>.
|
||||
|
||||
The <link linkend="func-ref-comedi-get-default-calibration-path"><function>comedi_get_default_calibration_path</function></link>
|
||||
The <function><link
|
||||
linkend="func-ref-comedi-get-default-calibration-path">comedi_get_default_calibration_path</link></function>
|
||||
function may be useful in conjunction with this function.
|
||||
Returns:
|
||||
A pointer to parsed calibration information on success, or NULL on failure.
|
||||
A pointer to parsed calibration information on success, or
|
||||
<constant>NULL</constant> on failure.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue