doc/calibration_funcref.txt

   1 Function: comedi_apply_calibration -- set hardware calibration from file
   2 Retval: int
   3 Param: comedi_t *device
   4 Param: unsigned int subdevice
   5 Param: unsigned int channel
   6 Param: unsigned int range
   7 Param: unsigned int aref
   8 Param: const char *file_path
   9 Status: alpha
  10 Description:
  11  This function sets the calibration of the specified subdevice
  12  so that it is in proper calibration when using the specified
  13  channel, range and aref.  It does so by performing writes
  14  to the appropriate channels of the board's calibration
  15  subdevice(s).  Depending on the hardware, the
  16  calibration settings used may or may not depend on the channel,
  17  range, or aref.  Furthermore, the calibrations appropriate
  18  for different channel, range, and aref parameters
  19  may not be able to be applied simultaneously.
  20  For example, some boards cannot have their analog inputs calibrated
  21  for more than one input range simultaneously.  Applying a calibration for range 1 may
  22  blow away a previously applied calibration for range 0.  Or, applying
  23  a calibration for analog input channel 0 may cause the same
  24  calibration to be applied to all the
  25  other analog input channels as well.
  26  Your only guarantee is that calls to comedi_apply_calibration()
  27  on different subdevices will not interfere with each other.
  28
  29  In practice, their are some rules of thumb on how
  30  calibrations behave.  No calibrations depend on the aref.
  31  A multiplexed analog input will have calibration settings that
  32  do not depend on the channel, and applying a setting for one
  33  channel will affect
  34  all channels equally.  Analog outputs, and analog inputs
  35  with independent a/d converters for each input channel, will have
  36  calibrations settings which do depend on the channel, and the
  37  settings for each channel will be independent of the other
  38  channels.
  39
  40  If you wish to investigate exactly what comedi_apply_calibration()
  41  is doing, you can perform reads on your board's calibration
  42  subdevice to see which calibration channels it is changing.
  43  You can also try to decipher the calibration file directly (it's a
  44  text file).
  45
  46  The file_path parameter can be used
  47  to specify the file which contains the calibration information.
  48  If <parameter>file_path</parameter> is NULL, then comedilib
  49  will use a default
  50  file location.  The calibration information used by this function
  51  is generated by the comedi_calibrate program (see its man page).
  52
  53  The functions comedi_parse_calibration_file(),
  54  comedi_apply_parsed_calibration(), and comedi_cleanup_calibration()
  55  provide the same functionality at a slightly lower level.
  56 Returns:
  57  Zero on success, a negative number on failure.
  58
  59 Function: comedi_apply_parsed_calibration -- set calibration from memory
  60 Retval: int
  61 Param: comedi_t * device
  62 Param: unsigned int subdevice
  63 Param: unsigned int channel
  64 Param: unsigned int range
  65 Param: unsigned int aref
  66 Param: const comedi_calibration_t *calibration
  67 Status: alpha
  68 Description:
  69  This function is similar to comedi_apply_calibration()
  70  except the calibration information is read from memory
  71  instead of a file.  This function can be more
  72  efficient than comedi_apply_calibration() since the
  73  calibration file does not need to be reparsed with
  74  every call.  The <parameter>calibration</parameter> is
  75  obtained by a call to comedi_parse_calibration_file().
  76
  77 Returns:
  78  Zero on success, a negative number on failure.
  79
  80 Function: comedi_cleanup_calibration -- free calibration resources
  81 Retval: void
  82 Param: comedi_calibration_t *calibration
  83 Status: alpha
  84 Description:
  85  This function frees the resources associated with a
  86  comedi_calibration_t obtained from
  87  comedi_parse_calibration_file().  <parameter>calibration</parameter>
  88  can not be used again after calling this function.
  89
  90 Function: comedi_get_default_calibration_path -- get default calibration file path
  91 Retval: char*
  92 Param: comedi_t *dev
  93 Status: alpha
  94 Description:
  95  This function returns a string containing a default calibration file
  96  path appropriate for <parameter>dev</parameter>.  Memory for the
  97  string is allocated by the function, and should be freed when
  98  the string is no longer needed.
  99 Returns:
 100  A string which contains a file path useable by
 101  comedi_parse_calibration_file().  On error, NULL is returned.
 102
 103 Function: comedi_get_hardcal_converter -- get converter for hardware-calibrated subdevice
 104 Retval: int
 105 Param: comedi_t *dev
 106 Param: unsigned subdevice
 107 Param: unsigned channel
 108 Param: unsigned range
 109 Param: enum comedi_conversion_direction direction
 110 Param: comedi_polynomial_t *converter
 111 Status: alpha
 112 Description:
 113  comedi_get_hardcal_converter() initializes <parameter>converter</parameter> so it can be
 114  passed to either comedi_to_physical() or comedi_from_physical().  The result can be used to
 115  convert data from the specified <parameter>subdevice</parameter>,
 116  <parameter>channel</parameter>, and <parameter>range</parameter>.  The <parameter>direction</parameter>
 117  parameter specifies whether <parameter>converter</parameter> will be passed to comedi_to_physical()
 118  or comedi_from_physical().
 119
 120  This function initializes <parameter>converter</parameter> as a simple linear function with no
 121  calibration information, appropriate
 122  for boards which do their gain/offset/nonlinearity corrections in hardware.  If your board
 123  needs calibration to be performed in software by the host computer, use comedi_get_softcal_converter()
 124  instead.  A subdevice will advertise the fact that it depends on a software calibration
 125  with the SDF_SOFT_CALIBRATED subdevice flag.
 126
 127  The result of this function will only depend on the <parameter>channel</parameter>
 128  parameter if either comedi_range_is_chan_specific() or comedi_maxdata_is_chan_specific()
 129  is true for the specified <parameter>subdevice</parameter>.
 130 Returns:
 131  Zero on success or -1 on failure.
 132
 133 Function: comedi_get_softcal_converter -- get converter for software-calibrated subdevice
 134 Retval: int
 135 Param: unsigned subdevice
 136 Param: unsigned channel
 137 Param: unsigned range
 138 Param: enum comedi_conversion_direction direction
 139 Param: const comedi_calibration_t *parsed_calibration
 140 Param: comedi_polynomial_t *converter
 141 Status: alpha
 142 Description:
 143  comedi_get_softcal_converter() initializes <parameter>converter</parameter> so it can be
 144  passed to either comedi_to_physical() or comedi_from_physical().  The <parameter>converter</parameter>
 145  parameter can then be used to
 146  convert data from the specified <parameter>subdevice</parameter>,
 147  <parameter>channel</parameter>, and <parameter>range</parameter>.  The <parameter>direction</parameter>
 148  parameter specifies whether <parameter>converter</parameter> will be passed to comedi_to_physical()
 149  or comedi_from_physical().  The <parameter>parsed_calibration</parameter> parameter contains the
 150  software calibration values for your device, and may be obtained by calling comedi_parse_calibration_file()
 151  on a calibration file generated by the comedi_soft_calibrate program.
 152
 153  This function is only useful for boards that perform their calibrations in software on the host
 154  computer.  A subdevice will advertise the fact that it depends on a software calibration
 155  with the SDF_SOFT_CALIBRATED subdevice flag.
 156
 157  Whether or not the result of this function actually depends on the <parameter>channel</parameter>
 158  parameter is
 159  hardware dependent.  For example, a multiplexed analog input will typically use the same
 160  calibration for all input channels.  Analog outputs will typically use different calibrations
 161  for each output channel.
 162
 163  Software calibrations are implemented as polynomials (up to third order).  Since the inverse
 164  of polynomials of order higher than one can't be represented exactly as another polynomial, you
 165  may not be able to get converters for the "reverse" direction.  For example, you may be
 166  able to get a converter for an analog input in the COMEDI_TO_PHYSICAL direction, but not
 167  in the COMEDI_FROM_PHYSICAL direction.
 168 Returns:
 169  Zero on success or -1 on failure.
 170
 171 Function: comedi_parse_calibration_file -- load contents of calibration file
 172 Retval: comedi_calibration_t*
 173 Param: const char *file_path
 174 Status: alpha
 175 Description:
 176  This function parses a calibration file (produced by the
 177  comedi_calibrate or comedi_soft_calibrate programs) and returns a pointer
 178  to a comedi_calibration_t which can be passed to the
 179  comedi_apply_parsed_calibration() or comedi_get_softcal_converter()
 180  functions.  When you are
 181  finished using the comedi_calibration_t, you should
 182  call comedi_cleanup_calibration() to free the resources
 183  associated with the comedi_calibration_t.
 184
 185  The comedi_get_default_calibration_path() function may
 186  be useful in conjunction with this function.
 187 Returns:
 188  A pointer to parsed calibration information on success,  or NULL on failure.