1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>4. Acquisition and configuration functions</title><link rel="stylesheet" type="text/css" href="comedilib.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Comedi"><link rel="up" href="index.html" title="Comedi"><link rel="prev" href="ar01s03s05.html" title="3.5. Further examples"><link rel="next" href="instructions.html" title="4.2. Instructions for multiple acquisitions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.
Acquisition and configuration functions
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s03s05.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="instructions.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="acquisitionfunctions"></a>4.
Acquisition and configuration functions
</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="acquisitionfunctions.html#singleacquisition">4.1.
Functions for single acquisition
</a></span></dt><dt><span class="section"><a href="instructions.html">4.2.
Instructions for multiple acquisitions
</a></span></dt><dt><span class="section"><a href="instructionsconfiguration.html">4.3.
Instructions for configuration
</a></span></dt><dt><span class="section"><a href="inttrigconfiguration.html">4.4.
Instruction for internal triggering
</a></span></dt><dt><span class="section"><a href="commandsstreaming.html">4.5.
Commands for streaming acquisition
</a></span></dt><dt><span class="section"><a href="slowlyvarying.html">4.6.
Slowly-varying inputs
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html">4.7.
Experimental functionality
</a></span></dt></dl></div><p>
This Section gives an overview of all <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> functions with which
application programmers can implement their data acquisition. (With
<span class="quote">“<span class="quote">acquisition</span>”</span> we mean all possible kinds of interfacing
with the cards: input, output, configuration, streaming, etc.)
<a class="xref" href="comedireference.html" title="5. Comedi reference">Section 5</a> explains the function calls in full
detail.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="singleacquisition"></a>4.1.
Functions for single acquisition
</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="acquisitionfunctions.html#dio">4.1.1.
Single digital acquisition
</a></span></dt><dt><span class="section"><a href="acquisitionfunctions.html#singleanalog">4.1.2.
Single analog acquisition
</a></span></dt></dl></div><p>
The simplest form of using <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> is to get one single sample to or
from an interface card. This sections explains how to do such simple
<a class="link" href="acquisitionfunctions.html#dio" title="4.1.1. Single digital acquisition">digital</a> and
<a class="link" href="acquisitionfunctions.html#singleanalog" title="4.1.2. Single analog acquisition">analog</a> acquisitions.
</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="dio"></a>4.1.1.
Single digital acquisition
</h4></div></div></div><p>
Many boards supported by <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> have digital input and output
channels; i.e., channels that can only produce a <code class="literal">0</code>
or a <code class="literal">1</code>.
Some boards allow the <span class="emphasis"><em>direction</em></span> (input or output)
of each channel to be specified independently in software.
</p><p>
<a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> groups digital channels into a
<span class="emphasis"><em>subdevice</em></span>, which is a group of digital channels
that have the same characteristics. For example, digital output lines
will be grouped into a digital
output subdevice, bidirectional digital lines will be grouped
into a digital I/O subdevice. Thus, there can be multiple
digital subdevices on a particular board.
</p><p>
Individual bits on a digital I/O device can be read and written using
the functions <code class="function"><a class="link" href="func-ref-comedi-dio-read.html" title="comedi_dio_read">comedi_dio_read</a></code>
and <code class="function"><a class="link" href="func-ref-comedi-dio-write.html" title="comedi_dio_write">comedi_dio_write</a></code>:
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">comedi_dio_read</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">subdevice</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">channel</var>, </td></tr><tr><td> </td><td>unsigned int *<var class="pdparam">bit</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">comedi_dio_write</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">subdevice</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">channel</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">bit</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
The <em class="parameter"><code>device</code></em> parameter is a
<a class="link" href="datatypesstructures.html#ref-type-comedi-t" title="5.3.2. comedi_t">pointer</a>
to a successfully opened <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> device.
The <em class="parameter"><code>subdevice</code></em> and
<em class="parameter"><code>channel</code></em> parameters are positive
integers that indicate which subdevice and channel is used in the
acquisition. The integer <em class="parameter"><code>bit</code></em>
contains the value of the acquired bit.
</p><p>
The direction of bidirectional lines can be configured using the function
<code class="function"><a class="link" href="func-ref-comedi-dio-config.html" title="comedi_dio_config">comedi_dio_config</a></code>:
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">comedi_dio_config</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">subdevice</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">channel</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">dir</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
The parameter <em class="parameter"><code>dir</code></em> should be
either <code class="constant">COMEDI_INPUT</code> or
<code class="constant">COMEDI_OUTPUT</code>.
Many digital I/O subdevices group channels into blocks for
configuring direction. Changing one channel in a block changes
the entire block.
</p><p>
Multiple channels can be read and written simultaneously using the
function <code class="function"><a class="link" href="func-ref-comedi-dio-bitfield2.html" title="comedi_dio_bitfield2">comedi_dio_bitfield2</a></code>:
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">comedi_dio_bitfield2</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">subdevice</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">write_mask</var>, </td></tr><tr><td> </td><td>unsigned int *<var class="pdparam">bits</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">base_channel</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
Each channel from <em class="parameter"><code>base_channel</code></em>
to <em class="parameter"><code>base_channel</code></em> +
<code class="literal">31</code> is assigned to a bit in the
<em class="parameter"><code>write_mask</code></em> and
<em class="parameter"><code>bits</code></em>
bitfield with bit 0 assigned to channel
<em class="parameter"><code>base_channel</code></em>, bit 1 assigned to channel
<em class="parameter"><code>base_channel</code></em> +
<code class="literal">1</code>, etc. If a bit in
<em class="parameter"><code>write_mask</code></em> is set, the
corresponding bit in <em class="parameter"><code>*bits</code></em> will
be written to the digital output line corresponding to the channel given by
<em class="parameter"><code>base_channel</code></em> plus the bit number.
Each digital line is then read and placed into
<em class="parameter"><code>*bits</code></em>. The value
of bits in <em class="parameter"><code>*bits</code></em> corresponding
to digital output lines is undefined and device-specific. Channel
<em class="parameter"><code>base_channel</code></em> +
<code class="literal">0</code> is the least significant bit in the bitfield. No
more than 32 channels at once can be accessed using this method.
<span class="strong"><strong>Warning!</strong></span> Older versions of <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a>
may ignore <em class="parameter"><code>base_channel</code></em> and treat
it as <code class="literal">0</code> unless the subdevice has more than 32 channels.
</p><p>
The digital acquisition functions seem to be very simple, but, behind
the implementation screens of the <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> kernel module, they are
executed as special cases of the general
<a class="link" href="instructions.html" title="4.2. Instructions for multiple acquisitions">instruction</a> command.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="singleanalog"></a>4.1.2.
Single analog acquisition
</h4></div></div></div><p>
Analog <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> channels can produce data values that are
<span class="emphasis"><em>samples</em></span> from continuous analog signals.
These samples are integers with a significant content in
the range of, typically, 8, 10, 12, or 16 bits.
</p><p>
Single samples can be read from an analog channel using the function
<code class="function"><a class="link" href="func-ref-comedi-data-read.html" title="comedi_data_read">comedi_data_read</a></code>:
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">comedi_data_read</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">subdevice</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">channel</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">range</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">aref</var>, </td></tr><tr><td> </td><td>lsampl_t *<var class="pdparam">data</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
This reads one such data value from a <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> channel, and puts it in
the user-specified <em class="parameter"><code>data</code></em> buffer.
</p><p>
The <em class="parameter"><code>range</code></em> parameter is the zero-based
index of one of the gain ranges supported by the channel. This is a number
from 0 to N-1 where N is the number of ranges supported by the channel.
Use the function
<code class="function"><a class="link" href="func-ref-comedi-get-n-ranges.html" title="comedi_get_n_ranges">comedi_get_n_ranges</a></code>
to get the number of ranges supported by the channel, the function
<code class="function"><a class="link" href="func-ref-comedi-find-range.html" title="comedi_find_range">comedi_find_range</a></code>
to search for a suitable range, or the function
<code class="function"><a class="link" href="func-ref-comedi-get-range.html" title="comedi_get_range">comedi_get_range</a></code>
to get the details of a supported range.
</p><p>
The <em class="parameter"><code>aref</code></em> parameter specifies an
analog reference to use:
<code class="constant"><a class="link" href="constantsmacros.html#aref-ground">AREF_GROUND</a></code>,
<code class="constant"><a class="link" href="constantsmacros.html#aref-common">AREF_COMMON</a></code>,
<code class="constant"><a class="link" href="constantsmacros.html#aref-diff">AREF_DIFF</a></code>, or
<code class="constant"><a class="link" href="constantsmacros.html#aref-other">AREF_OTHER</a></code>.
Use the function
<code class="function"><a class="link" href="func-ref-comedi-get-subdevice-flags.html" title="comedi_get_subdevice_flags">comedi_get_subdevice_flags</a></code>
to see which analog references are supported by the subdevice.
</p><p>
In the opposite direction, single samples can be written to an analog output
channel using the function
<code class="function"><a class="link" href="func-ref-comedi-data-write.html" title="comedi_data_write">comedi_data_write</a></code>:
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">comedi_data_write</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">subdevice</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">channel</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">range</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">aref</var>, </td></tr><tr><td> </td><td>lsampl_t <var class="pdparam">data</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
Raw data values read or written by the above functions
are unsigned integers less than, or equal to, the maximum sample value
of the channel, which can be determined using the function
<code class="function"><a class="link" href="func-ref-comedi-get-maxdata.html" title="comedi_get_maxdata">comedi_get_maxdata</a></code>:
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">lsampl_t <b class="fsfunc">comedi_get_maxdata</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">subdevice</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">channel</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
Conversion between raw data values and uncalibrated physical units can
be performed by the functions
<code class="function"><a class="link" href="func-ref-comedi-to-phys.html" title="comedi_to_phys">comedi_to_phys</a></code>
and <code class="function"><a class="link" href="func-ref-comedi-from-phys.html" title="comedi_from_phys">comedi_from_phys</a></code>:
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">double <b class="fsfunc">comedi_to_phys</b>(</code></td><td>lsampl_t <var class="pdparam">data</var>, </td></tr><tr><td> </td><td>comedi_range *<var class="pdparam">range</var>, </td></tr><tr><td> </td><td>lsampl_t <var class="pdparam">maxdata</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">lsampl_t <b class="fsfunc">comedi_from_phys</b>(</code></td><td>double <var class="pdparam">data</var>, </td></tr><tr><td> </td><td>comedi_range *<var class="pdparam">range</var>, </td></tr><tr><td> </td><td>lsampl_t <var class="pdparam">maxdata</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
There are some data structures in these commands that are not fully
self-explanatory:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-comedi-t" title="5.3.2. comedi_t">comedi_t</a></span>: this data structure
contains all information that a user program has to know about an
<span class="emphasis"><em>open</em></span> <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> device. The programmer doesn't have
to fill in this data structure manually: it gets filled in by opening
the device.
</p></li><li class="listitem"><p>
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-lsampl-t" title="5.3.4. lsampl_t">lsampl_t</a></span>: this
<span class="quote">“<span class="quote">data structure</span>”</span> represents one single sample. On most
architectures, it's nothing more than a 32 bits value. Internally,
<a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> does some conversion from raw sample data to
<span class="quote">“<span class="quote">correct</span>”</span> integers. This is called <span class="quote">“<span class="quote">data
munging</span>”</span>.
</p></li><li class="listitem"><p>
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-comedi-range" title="5.3.9. comedi_range">comedi_range</a></span>:
this holds the minimum and maximum physical values for a gain range supported
by a channel of a subdevice, and specifies the units. This can be used in
combination with the channel's <span class="quote">“<span class="quote">maxdata</span>”</span> value to convert between
unsigned integer sample values (of type
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-lsampl-t" title="5.3.4. lsampl_t">lsampl_t</a></span> or
<span class="type"><a class="link" href="datatypesstructures.html#ref-type-sampl-t" title="5.3.3. sampl_t">sampl_t</a></span>) and physical
units in a nominal (uncalibrated) way using the
<code class="function"><a class="link" href="func-ref-comedi-to-phys.html" title="comedi_to_phys">comedi_to_phys</a></code>
and
<code class="function"><a class="link" href="func-ref-comedi-from-phys.html" title="comedi_from_phys">comedi_from_phys</a></code>
functions. Use the
<code class="function"><a class="link" href="func-ref-comedi-get-maxdata.html" title="comedi_get_maxdata">comedi_get_maxdata</a></code>
function to get the <span class="quote">“<span class="quote">maxdata</span>”</span> value for the channel.
</p><p>
Most functions specify the range to be used for a channel by a zero-based
index into the list of ranges supported by the channel. Depending on the
device and subdevice, different channels on the subdevice may or may not
share the same list of ranges, that is, ranges may or may not be
channel-specific. (The <code class="constant">SDF_RANGETYPE</code> subdevice flag
indicates whether ranges are channel-specific.)
</p></li></ul></div><p>
</p><p>
Each single acquisition by, for example,
<code class="function"><a class="link" href="func-ref-comedi-data-read.html" title="comedi_data_read">comedi_data_read</a></code>
requires quite some overhead, because all the arguments of the
function call are checked. If multiple acquisitions must be done on
the same channel, this overhead can be avoided by using a function
that can read more than one sample,
<code class="function"><a class="link" href="func-ref-comedi-data-read-n.html" title="comedi_data_read_n">comedi_data_read_n</a></code>:
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">comedi_data_read_n</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">subdevice</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">channel</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">range</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">aref</var>, </td></tr><tr><td> </td><td>lsampl_t *<var class="pdparam">data</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">n</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
The number of samples, <em class="parameter"><code>n</code></em>, is
limited by the <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> implementation (to a maximum of 100 samples),
because the call is blocking.
</p><p>
The start of the a single data acquisition can also be delayed by a specified
number of nano-seconds using the function
<code class="function"><a class="link" href="func-ref-comedi-data-read-delayed.html" title="comedi_data_read_delayed">comedi_data_read_delayed</a></code>:
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">comedi_data_read_delayed</b>(</code></td><td>comedi_t *<var class="pdparam">device</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">subdevice</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">channel</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">range</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">aref</var>, </td></tr><tr><td> </td><td>lsampl_t *<var class="pdparam">data</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">nano_sec</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
All these read and write acquisition functions are implemented on top
of the generic <a class="link" href="instructions.html" title="4.2. Instructions for multiple acquisitions">instruction</a>
command.
</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s03s05.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="instructions.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.5. Further examples </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.2.
Instructions for multiple acquisitions
</td></tr></table></div></body></html>
|
