comedi_calibrate/README

   1
   2 I always seem to forget how to convert the calibration
   3 dump information into code for doing a calibration, so
   4 I'm writing this mostly for myself.
   5
   6 Boards may have one of 4 calibrations statuses, depending
   7 on how well the calibration code is trusted.  These are:
   8 STATUS_NONE, the default for no information; STATUS_SOME,
   9 meaning that a dump has been converted to initial code,
  10 but not tested; STATUS_DONE means that the output of a
  11 STATUS_SOME dump has been checked, and is correct;
  12 STATUS_GUESS is a marker that code has been converted
  13 from a previous version of the code, but not checked.
  14
  15 The NI E series boards have several internal voltages that
  16 can be measured, and also several calibration DACs that function
  17 similar to adjustable resistors on old data acquisition boards.
  18 The information we need is which DACs affect which measurable
  19 voltages; then we can write calibration code that adjusts those
  20 DACs until the voltages are within spec.
  21
  22 Usually, there are DACs (or multiple DACs) that are added to
  23 an analog input signal: 1) before the variable gain amplifier
  24 ("pre-gain"), 2) after the variable gain amplifier ("post-gain"),
  25 3) between the board's stable voltage reference and the
  26 reference input to the ADC ("gain offset"), and 4) before a
  27 unipolar-to-bipolar adjuster ("unipolar offset"), or other
  28 equivalent circuit.
  29
  30 In addition there are DACs that adjust the output voltages and/or
  31 reference voltage inputs to a D/A converter.  These are pretty
  32 intuitive once analog input is understood, and is dependent on
  33 correct analog input calibration.
  34
  35 The measurable quantities are 0 volts and an internal voltage
  36 reference near 5 volts, and can be measured at any gain.  The
  37 interesting combinations are:
  38
  39   ai, bipolar zero offset, low gain
  40   ai, bipolar zero offset, high gain
  41   ai, bipolar voltage reference, low gain
  42   ai, unipolar zero offset, low gain
  43
  44 The unipolar zero offset may not be available on some boards.
  45
  46 In a STATUS_NONE dump, for each measurable quantity and each
  47 calibration DAC, the DAC is varied throughout its entire range
  48 and the quantity measured.  The data is linearly fit, and if
  49 the slope is statistically non-zero, a line is printed:
  50
  51   caldac[0] gain=1.26(11)e-7 V/bit S_min=235.659 dof=254
  52
  53 The information given is caldac index, slope (gain) and slope
  54 error (in parenthesis, modifying the last two digits of the
  55 slope), and two statistical parameters S_min and degrees
  56 of freedom.  S_min and dof will be roughly similar for a
  57 good fit.  If S_min is more than a factor of 4 greater than
  58 dof, this is probably not a good fit.  Typically this means
  59 that the DAC doesn't affect the measureable strictly linearly,
  60 or there is systematic noise.  The latter seems to common in
  61 E series boards, so I'm not too worried about the following
  62 dump where there are S_min/dof ratios above 4.
  63
  64 Here's an example dump, generated by a STATUS_NONE dump for
  65 a pci-mio-16xe-10, with the analog output section removed:
  66
  67   Warning: device not fully calibrated due to insufficient information
  68   Please send this output to <ds@schleef.org>
  69   Id: comedi_calibrate.c,v 1.21 2001/10/10 22:07:53 ds Exp
  70   Driver name: ni_pcimio
  71   Device name: pci-mio-16xe-10
  72   Comedi version: 0.7.61
  73   ai, bipolar zero offset, low gain
  74   offset -6.795(14)e-3, target 0
  75   caldac[0] gain=1.26(11)e-7 V/bit S_min=235.659 dof=254
  76   caldac[2] gain=3.96840(14)e-4 V/bit S_min=1390.18 dof=254
  77   caldac[3] gain=4.348(11)e-6 V/bit S_min=258.75 dof=254
  78   caldac[8] gain=5.4659(69)e-7 V/bit S_min=386.361 dof=254
  79   ai, bipolar zero offset, high gain
  80   offset -2.4224(55)e-4, target 0
  81   caldac[0] gain=3.61(45)e-9 V/bit S_min=247.26 dof=254
  82   caldac[2] gain=3.96644(48)e-6 V/bit S_min=351.927 dof=254
  83   caldac[3] gain=4.063(46)e-8 V/bit S_min=272.024 dof=254
  84   caldac[8] gain=5.46305(30)e-7 V/bit S_min=314.035 dof=254
  85   ai, bipolar voltage reference, low gain
  86   offset 4.992959(13), target 5
  87   caldac[0] gain=-4.4928(11)e-5 V/bit S_min=1111.4 dof=254
  88   caldac[1] gain=-2.792(11)e-6 V/bit S_min=248.971 dof=254
  89   caldac[2] gain=3.96488(14)e-4 V/bit S_min=1059.18 dof=254
  90   caldac[3] gain=4.318(11)e-6 V/bit S_min=437.441 dof=254
  91   caldac[8] gain=5.4810(70)e-7 V/bit S_min=404.213 dof=254
  92   ai, unipolar zero offset, low gain
  93   offset nan, target 0
  94   caldac[2] gain=3.96773(39)e-4 V/bit S_min=158.236 dof=107
  95
  96 [The explanation gets a little fuzzy here]
  97
  98 The resulting function for calibration will look something like:
  99
 100   void cal_ni_pci_mio_16xe_10(void)
 101   {
 102         postgain_cal(ni_zero_offset_low, ni_zero_offset_high, XXX);
 103         cal1(ni_zero_offset_high, XXX);
 104         cal1(ni_reference_low, XXX);
 105         cal1(ni_unip_offset_low, XXX);
 106   }
 107
 108 You get to fill in the XXX's.  The post-gain calibration DAC will
 109 be the one for which the ratio of caldac slopes for the low and
 110 high gain measurables is similar to the ratio of input ranges for
 111 low and high gain.  This ratio is typically 100 or 200, and really
 112 should be printed by the program.  Thus, for this dump, we choose
 113 caldac[2], since the ratio is very nearly 100.  We don't choose
 114 caldac[0] or caldac[3], because the gains are smaller, and the
 115 ratio isn't exactly 100 or 200.
 116
 117 Next is the pre-gain calibration.  Adding a voltage before the
 118 amplifier will affect every input range selection equally, so the
 119 pre-gain cadac slope will be nearly equal for both bipolar zero
 120 offset at low and high gain.  In this example, it would be caldac[8].
 121
 122 Next is the voltage reference calibration.  The caldac controlling
 123 the voltage reference adjustment is proportional to the offset,
 124 so the correct caldac will typically be the one that has a large
 125 slope for the bipolar voltage reference measurement, but a small
 126 slope (by a factor of 2e4, here) for the zero offset measurements.
 127 It could be any of caldac[0], caldac[1], or caldac[3], or possibly
 128 all of them.  We'll choose the caldac with the largest slope for
 129 rough calibration, then use the one with the smallest slope for
 130 fine calibration, namely caldac[0] and caldac[1].
 131
 132 This is one way that STATUS_SOME is useful, because you can calibrate
 133 the zero offset, then get a much better idea which other channels
 134 are likely to be for the voltage reference.
 135
 136 In this example, there doesn't appear to be a caldac that affects
 137 unipolar zero offset, so it will not be used in the final function:
 138
 139   void cal_ni_pci_mio_16xe_10(void)
 140   {
 141         postgain_cal(ni_zero_offset_low, ni_zero_offset_high, 2);
 142         cal1(ni_zero_offset_high, 8);
 143         cal1(ni_reference_low, 0);
 144         cal1(ni_reference_low, 1);
 145   }
 146