256 lines
12 KiB
Text
256 lines
12 KiB
Text
Calibration
|
|
Function: comedi_apply_calibration -- set hardware calibration from file
|
|
Retval: int
|
|
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
|
|
Status: alpha
|
|
Description:
|
|
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 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
|
|
blow away a previously applied calibration for range 0. Or, applying
|
|
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
|
|
<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 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
|
|
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
|
|
<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 <parameter class="function">file_path</parameter> parameter can be used
|
|
to specify the file which contains the calibration information.
|
|
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 <command>comedi_calibrate</command> program (see its man page).
|
|
|
|
The functions
|
|
<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</link></function>
|
|
provide the same functionality at a slightly lower level.
|
|
Returns:
|
|
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
|
|
|
|
Function: comedi_apply_parsed_calibration -- set calibration from memory
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Param: unsigned int channel
|
|
Param: unsigned int range
|
|
Param: unsigned int aref
|
|
Param: const comedi_calibration_t * calibration
|
|
Status: alpha
|
|
Description:
|
|
This function is similar to
|
|
<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 <function>comedi_apply_calibration</function> since the
|
|
calibration file does not need to be reparsed with
|
|
every call. The value of parameter <parameter class="function">calibration</parameter> is
|
|
obtained by a call to
|
|
<function><link
|
|
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>.
|
|
|
|
Returns:
|
|
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
|
|
Status: alpha
|
|
Description:
|
|
This function frees the resources associated with a
|
|
<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 * device
|
|
Status: alpha
|
|
Description:
|
|
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
|
|
<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 * device
|
|
Param: unsigned subdevice
|
|
Param: unsigned channel
|
|
Param: unsigned range
|
|
Param: enum comedi_conversion_direction direction
|
|
Param: comedi_polynomial_t * converter
|
|
Status: alpha
|
|
Description:
|
|
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
|
|
<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 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 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 <function>comedi_get_softcal_converter</function>
|
|
instead. A subdevice will advertise the fact that it depends on a software calibration
|
|
with the <constant>SDF_SOFT_CALIBRATED</constant> subdevice flag.
|
|
|
|
The result of this function will only depend on the
|
|
<parameter class="function">channel</parameter>
|
|
parameter if either
|
|
<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:
|
|
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
|
|
|
|
Function: comedi_get_softcal_converter -- get converter for software-calibrated subdevice
|
|
Retval: int
|
|
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
|
|
Status: alpha
|
|
Description:
|
|
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
|
|
<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
|
|
<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 <constant>SDF_SOFT_CALIBRATED</constant> subdevice flag.
|
|
|
|
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
|
|
for each output channel.
|
|
|
|
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 <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:
|
|
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
|
|
Status: alpha
|
|
Description:
|
|
This function parses a calibration file (produced by the
|
|
<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 <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 <type>comedi_calibration_t</type>.
|
|
|
|
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
|
|
<constant>NULL</constant> on failure.
|