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.