Debian Codegraph @

comedi-calibrate/comedi_calibrate/README

raw
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_UNKNOWN, 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_UNKNOWN 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_UNKNOWN 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 <[email protected]>
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 Note that we haven't done anything with caldac[3]. It clearly
137 does something useful, but until we attempt a coarse calibration,
138 it's not certain what it does. It turns out to be a fine postgain
139 adjustment.
140
141 In this example, there doesn't appear to be a caldac that affects
142 unipolar zero offset, so it will not be used in the final function:
143
144 void cal_ni_pci_mio_16xe_10(void)
145 {
146 postgain_cal(ni_zero_offset_low, ni_zero_offset_high, 2);
147 cal1(ni_zero_offset_high, 8);
148 cal1(ni_reference_low, 0);
149 cal1(ni_reference_low, 1);
150 }
151
152 There are a number of functions that are useful for optimizing a
153 given caldac, each optimized for different cases. The inconsistently
154 named postgain_cal() and cal1() measure the observable(s) at a
155 number of points throughout the entire caldac range, and then do a
156 linear fit to determine the optimum value for caldac. These functions
157 are good if the caldac dependence is strictly linear. They are also
158 useful if the target value for the observable is at the endpoint of
159 the measurable range, as when measuring unipolar zero offset, since
160 the functions automatically compensate for bad input values.
161
162 The function cal_fine() is useful for fine-tuning of the results of
163 cal1(), especially if the dependence is close, but not quite linear.
164 The goodness of the linear fit is quantified by the S_min value in the
165 log -- an S_min value that is approximately the same (within a factor
166 of 2 or 3) as dof (degrees of freedom) indicates a good fit. An S_min
167 value that is about 10 times dof indicates that fine tuning is probably
168 necessary. An S_min value that is many orders of magnitude larger than
169 dof indicates that linear fitting should not be used.
170
171 The functions cal_binary() and cal_postgain_binary() are used when
172 the caldac dependence is highly non-linear. It does a binary search
173 in the range of the caldac to find a decent value.
174
175 Notes by fmhess******************************************************
176 I would use cal_binary() always, as opposed to cal1() or cal1_fine(),
177 since it is the best algorithm.
178
179 cal_relative_binary() is the same as cal_postgain_binary(). I prefer
180 the more general name because the function is useful for more than
181 just postgain offsets. It adjusts a caldac so the difference between
182 two observables is correct (although their absolute values may still
183 be offset), which works for postgain offsets, but
184 is also good for gain calibrations when the gain adjustment
185 couples with the offset.
186
187 cal_linearity_binary() was added for convenient calibration of
188 analog output linearity on NI boards. It should be fed 3
189 observables that are well separated from each other. It adjusts
190 a caldac so that the ratio (obs3 - obs2)/(obs2 - obs1) is
191 correct.