1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4 <!ENTITY % comedilib_entities SYSTEM "comedilib.ent">
8 <section id="acquisitionfunctions">
10 Acquisition and configuration functions
14 This Section gives an overview of all &comedi; functions with which
15 application programmers can implement their data acquisition. (With
16 <quote>acquisition</quote> we mean all possible kinds of interfacing
17 with the cards: input, output, configuration, streaming, etc.)
18 <xref linkend="comedireference"/> explains the function calls in full
22 <section id="singleacquisition">
24 Functions for single acquisition
28 The simplest form of using &comedi; is to get one single sample to or
29 from an interface card. This sections explains how to do such simple
30 <link linkend="dio">digital</link> and
31 <link linkend="singleanalog">analog</link> acquisitions.
36 Single digital acquisition
40 Many boards supported by &comedi; have digital input and output
41 channels; i.e., channels that can only produce a <literal>0</literal>
42 or a <literal>1</literal>.
43 Some boards allow the <emphasis>direction</emphasis> (input or output)
44 of each channel to be specified independently in software.
48 &comedi; groups digital channels into a
49 <emphasis>subdevice</emphasis>, which is a group of digital channels
50 that have the same characteristics. For example, digital output lines
51 will be grouped into a digital
52 output subdevice, bidirectional digital lines will be grouped
53 into a digital I/O subdevice. Thus, there can be multiple
54 digital subdevices on a particular board.
58 Individual bits on a digital I/O device can be read and written using
59 the functions <function><link linkend="func-ref-comedi-dio-read">comedi_dio_read</link></function>
60 and <function><link linkend="func-ref-comedi-dio-write">comedi_dio_write</link></function>:
62 <funcsynopsis><funcprototype>
63 <funcdef>int <function>comedi_dio_read</function></funcdef>
64 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
65 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
66 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
67 <paramdef>unsigned int *<parameter>bit</parameter></paramdef>
68 </funcprototype></funcsynopsis>
70 <funcsynopsis><funcprototype>
71 <funcdef>int <function>comedi_dio_write</function></funcdef>
72 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
73 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
74 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
75 <paramdef>unsigned int <parameter>bit</parameter></paramdef>
76 </funcprototype></funcsynopsis>
78 The <parameter class="function">device</parameter> parameter is a
79 <link linkend="ref-type-comedi-t">pointer</link>
80 to a successfully opened &comedi; device.
81 The <parameter class="function">subdevice</parameter> and
82 <parameter class="function">channel</parameter> parameters are positive
83 integers that indicate which subdevice and channel is used in the
84 acquisition. The integer <parameter class="function">bit</parameter>
85 contains the value of the acquired bit.
88 The direction of bidirectional lines can be configured using the function
89 <function><link linkend="func-ref-comedi-dio-config">comedi_dio_config</link></function>:
91 <funcsynopsis><funcprototype>
92 <funcdef>int <function>comedi_dio_config</function></funcdef>
93 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
94 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
95 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
96 <paramdef>unsigned int <parameter>dir</parameter></paramdef>
97 </funcprototype></funcsynopsis>
99 The parameter <parameter class="function">dir</parameter> should be
100 either <constant>COMEDI_INPUT</constant> or
101 <constant>COMEDI_OUTPUT</constant>.
102 Many digital I/O subdevices group channels into blocks for
103 configuring direction. Changing one channel in a block changes
108 Multiple channels can be read and written simultaneously using the
109 function <function><link linkend="func-ref-comedi-dio-bitfield2">comedi_dio_bitfield2</link></function>:
111 <funcsynopsis><funcprototype>
112 <funcdef>int <function>comedi_dio_bitfield2</function></funcdef>
113 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
114 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
115 <paramdef>unsigned int <parameter>write_mask</parameter></paramdef>
116 <paramdef>unsigned int *<parameter>bits</parameter></paramdef>
117 <paramdef>unsigned int <parameter>base_channel</parameter></paramdef>
118 </funcprototype></funcsynopsis>
120 Each channel from <parameter class="function">base_channel</parameter>
121 to <parameter class="function">base_channel</parameter> +
122 <literal>31</literal> is assigned to a bit in the
123 <parameter class="function">write_mask</parameter> and
124 <parameter class="function">bits</parameter>
125 bitfield with bit 0 assigned to channel
126 <parameter class="function">base_channel</parameter>, bit 1 assigned to channel
127 <parameter class="function">base_channel</parameter> +
128 <literal>1</literal>, etc. If a bit in
129 <parameter class="function">write_mask</parameter> is set, the
130 corresponding bit in <parameter class="function">*bits</parameter> will
131 be written to the digital output line corresponding to the channel given by
132 <parameter class="function">base_channel</parameter> plus the bit number.
133 Each digital line is then read and placed into
134 <parameter class="function">*bits</parameter>. The value
135 of bits in <parameter class="function">*bits</parameter> corresponding
136 to digital output lines is undefined and device-specific. Channel
137 <parameter class="function">base_channel</parameter> +
138 <literal>0</literal> is the least significant bit in the bitfield. No
139 more than 32 channels at once can be accessed using this method.
140 <emphasis role="strong">Warning!</emphasis> Older versions of &comedi;
141 may ignore <parameter class="function">base_channel</parameter> and treat
142 it as <literal>0</literal> unless the subdevice has more than 32 channels.
146 The digital acquisition functions seem to be very simple, but, behind
147 the implementation screens of the &comedi; kernel module, they are
148 executed as special cases of the general
149 <link linkend="instructions">instruction</link> command.
156 <section id="singleanalog">
158 Single analog acquisition
161 Analog &comedi; channels can produce data values that are
162 <emphasis>samples</emphasis> from continuous analog signals.
163 These samples are integers with a significant content in
164 the range of, typically, 8, 10, 12, or 16 bits.
167 Single samples can be read from an analog channel using the function
168 <function><link linkend="func-ref-comedi-data-read">comedi_data_read</link></function>:
170 <funcsynopsis><funcprototype>
171 <funcdef>int <function>comedi_data_read</function></funcdef>
172 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
173 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
174 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
175 <paramdef>unsigned int <parameter>range</parameter></paramdef>
176 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
177 <paramdef>lsampl_t *<parameter>data</parameter></paramdef>
178 </funcprototype></funcsynopsis>
180 This reads one such data value from a &comedi; channel, and puts it in
181 the user-specified <parameter>data</parameter> buffer.
185 In the opposite direction, single samples can be written to an analog output
186 channel using the function
187 <function><link linkend="func-ref-comedi-data-write">comedi_data_write</link></function>:
189 <funcsynopsis><funcprototype>
190 <funcdef>int <function>comedi_data_write</function></funcdef>
191 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
192 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
193 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
194 <paramdef>unsigned int <parameter>range</parameter></paramdef>
195 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
196 <paramdef>lsampl_t <parameter>data</parameter></paramdef>
197 </funcprototype></funcsynopsis>
201 Raw data values read or written by the above functions
202 are unsigned integers less than, or equal to, the maximum sample value
203 of the channel, which can be determined using the function
204 <function><link linkend="func-ref-comedi-get-maxdata">comedi_get_maxdata</link></function>:
206 <funcsynopsis><funcprototype>
207 <funcdef>lsampl_t <function>comedi_get_maxdata</function></funcdef>
208 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
209 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
210 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
211 </funcprototype></funcsynopsis>
213 Conversion between raw data values and uncalibrated physical units can
214 be performed by the functions
215 <function><link linkend="func-ref-comedi-to-phys">comedi_to_phys</link></function>
216 and <function><link linkend="func-ref-comedi-from-phys">comedi_from_phys</link></function>:
218 <funcsynopsis><funcprototype>
219 <funcdef>double <function>comedi_to_phys</function></funcdef>
220 <paramdef>lsampl_t <parameter>data</parameter></paramdef>
221 <paramdef>comedi_range *<parameter>range</parameter></paramdef>
222 <paramdef>lsampl_t <parameter>maxdata</parameter></paramdef>
223 </funcprototype></funcsynopsis>
225 <funcsynopsis><funcprototype>
226 <funcdef>lsampl_t <function>comedi_from_phys</function></funcdef>
227 <paramdef>double <parameter>data</parameter></paramdef>
228 <paramdef>comedi_range *<parameter>range</parameter></paramdef>
229 <paramdef>lsampl_t <parameter>maxdata</parameter></paramdef>
230 </funcprototype></funcsynopsis>
234 There are two data structures in these commands that are not fully
240 <type><link linkend="ref-type-comedi-t">comedi_t</link></type>: this data structure
241 contains all information that a user program has to know about an
242 <emphasis>open</emphasis> &comedi; device. The programmer doesn't have
243 to fill in this data structure manually: it gets filled in by opening
250 <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>: this
251 <quote>data structure</quote> represents one single sample. On most
252 architectures, it's nothing more than a 32 bits value. Internally,
253 &comedi; does some conversion from raw sample data to
254 <quote>correct</quote> integers. This is called <quote>data
262 Each single acquisition by, for example,
263 <function><link linkend="func-ref-comedi-data-read">comedi_data_read</link></function>
264 requires quite some overhead, because all the arguments of the
265 function call are checked. If multiple acquisitions must be done on
266 the same channel, this overhead can be avoided by using a function
267 that can read more than one sample,
268 <function><link linkend="func-ref-comedi-data-read-n">comedi_data_read_n</link></function>:
270 <funcsynopsis><funcprototype>
271 <funcdef>int <function>comedi_data_read_n</function></funcdef>
272 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
273 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
274 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
275 <paramdef>unsigned int <parameter>range</parameter></paramdef>
276 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
277 <paramdef>lsampl_t *<parameter>data</parameter></paramdef>
278 <paramdef>unsigned int <parameter>n</parameter></paramdef>
279 </funcprototype></funcsynopsis>
281 The number of samples, <parameter class="function">n</parameter>, is
282 limited by the &comedi; implementation (to a maximum of 100 samples),
283 because the call is blocking.
286 The start of the a single data acquisition can also be delayed by a specified
287 number of nano-seconds using the function
288 <function><link linkend="func-ref-comedi-data-read-delayed">comedi_data_read_delayed</link></function>:
290 <funcsynopsis><funcprototype>
291 <funcdef>int <function>comedi_data_read_delayed</function></funcdef>
292 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
293 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
294 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
295 <paramdef>unsigned int <parameter>range</parameter></paramdef>
296 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
297 <paramdef>lsampl_t *<parameter>data</parameter></paramdef>
298 <paramdef>unsigned int <parameter>nano_sec</parameter></paramdef>
299 </funcprototype></funcsynopsis>
303 All these read and write acquisition functions are implemented on top
304 of the generic <link linkend="instructions">instruction</link>
313 <section id="instructions">
315 Instructions for multiple acquisitions
318 The <emphasis>instruction</emphasis> is one of the most generic,
319 overloaden and flexible functions in the &comedi; API. It is used to
320 execute a multiple of identical acquisitions on the same channel, but
322 <link linkend="instructionsconfiguration">configuration</link> of a
324 <anchor id="anchor.instruction.list"/>
325 An <emphasis>instruction list</emphasis> is a list of instructions,
326 possibly on different channels. Both instructions and instructions
327 lists are executed <emphasis>synchronously</emphasis>, i.e., while
328 <emphasis role="strong">blocking</emphasis> the calling process.
329 This is one of the limitations of instructions; the other one is that
330 they cannot code an acquisition involving timers or external events.
331 These limits are eliminated by the
332 <link linkend="commandsstreaming">command</link> acquisition
337 <section id="comediinsnstructure">
339 The instruction data structure
342 All the information needed to execute an instruction is stored in the
343 <type><link linkend="ref-type-comedi-insn">comedi_insn</link></type>
346 typedef struct <anchor id="insn-data-structure"/>comedi_insn_struct {
347 <anchor id="insn-data-structure-insn"/>unsigned int insn; // integer encoding the type of acquisition
348 // (or configuration)
349 unsigned int n; // number of elements in data array
350 <link linkend="ref-type-lsampl-t">lsampl_t</link> <anchor id="insn-data-structure-data"/>*data; // pointer to data buffer
351 unsigned int subdev; // subdevice
352 unsigned int <anchor id="insn-data-structure-chanspec"/><link linkend="ref-macro-CR-PACK">chanspec</link>; // encoded channel specification
353 unsigned int unused[3];
356 Because of the large flexibility of the instruction function, many
357 types of instruction do not need to fill in all fields, or attach
358 different meanings to the same field. But the current implementation
359 of &comedi; requires the
360 <structfield><link linkend="insn-data-structure-data">data</link></structfield>
361 field to be at least one byte long.
365 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> member of the
366 <link linkend="insn-data-structure">instruction data structure</link>
367 determines the type of acquisition executed in the corresponding
373 <constant>INSN_READ</constant>: the instruction executes a read on an
380 <constant>INSN_WRITE</constant>: the instruction executes a write on an
387 <constant>INSN_BITS</constant>: indicates that the instruction must
388 read or write values on multiple digital I/O channels.
394 <constant>INSN_GTOD</constant>: the instruction performs a
395 <quote>Get Time Of Day</quote> acquisition.
401 <constant>INSN_WAIT</constant>: the instruction blocks for a specified
402 number of nanoseconds.
412 <section id="instructionexecution">
414 Instruction execution
417 Once an instruction data structure has been filled in, the
418 corresponding instruction is executed with the function
419 <function><link linkend="func-ref-comedi-do-insn">comedi_do_insn</link></function>:
421 <funcsynopsis><funcprototype>
422 <funcdef>int <function>comedi_do_insn</function></funcdef>
423 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
424 <paramdef>comedi_insn *<parameter>instruction</parameter></paramdef>
425 </funcprototype></funcsynopsis>
427 Many &comedi; instructions are shortcuts that relieve the programmer
428 from explicitly filling in the data structure and calling the
429 <function><link linkend="func-ref-comedi-do-insn">comedi_do_insn</link></function>
433 A list of instructions can be executed in one function call using the function
434 <function><link linkend="func-ref-comedi-do-insnlist">comedi_do_insnlist</link></function>:
436 <funcsynopsis><funcprototype>
437 <funcdef>int <function>comedi_do_insnlist</function></funcdef>
438 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
439 <paramdef>comedi_insnlist *<parameter>list</parameter></paramdef>
440 </funcprototype></funcsynopsis>
442 The parameter <parameter class="function">list</parameter> is a pointer to a
443 <type><link linkend="insnlist-data-structure">comedi_insnlist</link></type>
444 data structure holding a pointer to an array of <type>comedi_insn</type>
445 and the number of instructions in the list:
447 typedef struct <anchor id="insnlist-data-structure"/>comedi_insnlist_struct {
448 unsigned int n_insns;
454 The number of instructions in the list is limited in the
455 implementation, because instructions are executed
456 <emphasis>synchronously</emphasis>, i.e., the call blocks until the
457 whole instruction (list) has finished.
465 <section id="instructionsconfiguration">
467 Instructions for configuration
470 <xref linkend="instructions"/> explains how instructions are used to do
471 <emphasis>acquisition</emphasis> on channels. This section explains
472 how they are used to <emphasis>configure</emphasis> a subdevice.
473 There are various sorts of configurations, and the
474 specific information for each different configuration possibility is
475 to be specified via the
476 <structfield><link linkend="insn-data-structure-data">data</link></structfield>
478 <link linkend="insn-data-structure">instruction data structure</link>.
479 (So, the pointer to a
480 <type><link linkend="ref-type-lsampl-t">lsampl_t</link></type>
481 is misused as a pointer to an array with board-specific information.)
485 Using <constant>INSN_CONFIG</constant> as the
486 <structfield><link linkend="insn-data-structure-insn">insn</link></structfield>
488 <link linkend="insn-data-structure">instruction data structure</link>
489 indicates that the instruction will
490 <emphasis>not perform acquisition</emphasis> on a
491 channel, but will <emphasis>configure</emphasis> that channel.
493 <structfield><link linkend="ref-macro-CR-PACK">chanspec</link></structfield>
495 <type><link linkend="insn-data-structure-chanspec">comedi_insn</link></type>
496 data structure, contains the channel to be configured.
497 The zeroth element of the data array
498 is always an id that specifies
499 what type of configuration instruction is being performed. The
500 meaning of rest of the elements in the data array
501 depend on the configuration instruction id.
503 possible ids are summarised in the table below, along with the
504 meanings of the data array elements for
505 each type of configuration instruction.
509 <tgroup cols='4' align='left'>
510 <colspec colwidth='4*' />
511 <colspec colwidth='4*' />
512 <colspec colwidth='1*' />
513 <colspec colwidth='4*' />
516 <entry>data[0]</entry>
517 <entry>Description</entry>
518 <entry>n (number of elements in data array)</entry>
519 <entry>Meanings of data[1], ..., data[n-1]</entry>
524 <entry><constant>INSN_CONFIG_DIO_INPUT</constant></entry>
526 Configure a DIO line as input. It is easier to use
527 <function><link linkend="func-ref-comedi-dio-config">comedi_dio_config</link></function>
528 than to use this configuration instruction directly.
536 <entry><constant>INSN_CONFIG_DIO_OUTPUT</constant></entry>
538 Configure a DIO line as output. It is easier to use
539 <function><link linkend="func-ref-comedi-dio-config">comedi_dio_config</link></function>
540 than to use this configuration instruction directly.
548 <entry><constant>INSN_CONFIG_ALT_SOURCE</constant></entry>
550 Select an alternate input source. This instruction is used by calibration
551 programs to configure analog input channels
552 which can be redirected to read internal calibration
553 references. You need to set the <constant>CR_ALT_SOURCE</constant> flag in the chanspec
554 when reading to actually read from the configured alternate input source.
555 If you are using <function>comedi_data_read</function>, then the channel parameter can be
556 bitwise or'd with the <constant>CR_ALT_SOURCE</constant> flag.
560 data[1]: alternate input source.
564 <entry><constant>INSN_CONFIG_BLOCK_SIZE</constant></entry>
566 Specify block size for asynchonous command data.
567 When performing streaming input, many boards accumulate
568 samples in internal fifos and transfer them to the host
569 computer in chunks. Some drivers let you suggest a size in bytes for how big a
570 the chunks should be. This lets you tune how often the host computer is
571 interrupted with a new chunk of data.
575 data[1]: The desired block size in bytes. The actual configured block size is
576 writen back to data[1] after the instruction completes. This instruction
577 acts purely as a query if the block size is set to zero.
581 <entry><constant>INSN_CONFIG_DIO_QUERY</constant></entry>
583 Queries the configuration of a DIO line to see if it is an input or output.
584 It is probably easier to use the comedilib function
585 <function><link linkend="func-ref-comedi-dio-get-config">comedi_dio_get_config</link></function>
586 than to use this instruction directly.
590 data[1]: The instruction sets this element to either
591 <constant>COMEDI_INPUT</constant> or <constant>COMEDI_OUTPUT</constant>.
599 See the comedilib demo program <filename>demo/choose_clock.c</filename> for an example
600 of using a configuration instruction.
606 <section id="inttrigconfiguration">
608 Instruction for internal triggering
611 This special instruction has
612 <anchor id="insn-inttrig"/><constant>INSN_INTTRIG</constant> as the
613 <structfield><link linkend="insn-data-structure-insn">insn</link></structfield>
615 <link linkend="insn-data-structure">instruction data structure</link>.
616 Its execution causes an
617 <link linkend="trig-int-start-src">internal triggering event</link>. This
618 event can, for example, cause the device driver to start a conversion,
619 or to stop an ongoing acquisition. The exact meaning of the triggering
620 depends on the card and its particular driver.
624 <structfield><link linkend="insn-data-structure-data">data</link></structfield>[0] element of the
625 <constant>INSN_INTTRIG</constant> instruction is reserved for future use,
626 and should be set to <literal>0</literal>.
632 <section id="commandsstreaming">
634 Commands for streaming acquisition
638 The most powerful &comedi; acquisition primitive is the
639 <emphasis>command</emphasis>. It's powerful because, with one single
640 command, the programmer launches:
645 a possibly infinite <emphasis>sequence of acquisitions</emphasis>,
651 accompanied with various <emphasis>callback</emphasis> functionalities
652 (DMA, interrupts, driver-specific callback functions),
658 for <emphasis>any number of channels</emphasis>,
664 with an <emphasis>arbitrary order</emphasis> of channels in each scan
665 (possibly even with repeated channels per scan),
671 and with various scan <emphasis>triggering sources</emphasis>,
672 external (i.e., hardware pulses) as well as internal (i.e., pulses
673 generated on the DAQ card itself, or generated by a
674 <link linkend="inttrigconfiguration">software trigger instruction</link>).
679 This command functionality exists in the &comedi; API, because various
680 data acquisition devices have the capability to perform this kind of
681 complex acquisition, driven by either on-board or
682 off-board timers and triggers.
686 A command specifies a particular data
687 <link linkend="fig-acq-seq">acquisition sequence</link>, which
688 consists of a number of <emphasis>scans</emphasis>, and each scan is
689 comprised of a number of <emphasis>conversions</emphasis>, which
690 usually corresponds to a single A/D or D/A conversion. So, for
691 example, a scan could consist of sampling channels 1, 2 and 3 of a
692 particular device, and this scan should be repeated 1000 times, at
693 intervals of 1 millisecond apart.
696 The command function is complementary to the
697 <link linkend="instructionsconfiguration">configuration instruction</link>
698 function: each channel in the command's
699 <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield>
700 should first be configured by an appropriate instruction.
704 <section id="executingcommand">
710 A command is executed by the function
711 <function><link linkend="func-ref-comedi-command">comedi_command</link></function>:
713 <funcsynopsis><funcprototype>
714 <funcdef>int <function>comedi_command</function></funcdef>
715 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
716 <paramdef>comedi_cmd *<parameter>command</parameter></paramdef>
717 </funcprototype></funcsynopsis>
719 The following sections explain the meaning of the
720 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data structure.
721 Filling in this structure can be quite complicated, and
722 requires good knowledge about the exact functionalities of the DAQ
723 card. So, before launching a command, the application programmer is
724 adviced to check whether this complex command data structure can be
725 successfully parsed. So, the typical sequence for executing a command is
726 to first send the command through
727 <function><link linkend="func-ref-comedi-command-test">comedi_command_test</link></function>
728 once or twice. The test will check that the command is valid for the
729 particular device, and often makes some adjustments to the command
730 arguments, which can then be read back by the user to see the actual
734 A &comedi; program can find out on-line what the command capabilities
735 of a specific device are, by means of the
736 <function><link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask</link></function>
743 <section id="comedicmdstructure">
745 The command data structure
748 The command executes according to the information about the requested
749 acquisition, which is stored in the
750 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type>
751 <anchor id="command-data-struct"/>data structure:
753 typedef struct comedi_cmd_struct comedi_cmd;
755 struct comedi_cmd_struct {
756 unsigned int subdev; // which subdevice to sample
757 unsigned int <anchor id="command-data-struct-flags"/>flags; // encode some configuration possibilities
758 // of the command execution; e.g.,
759 // whether a callback routine is to be
760 // called at the end of the command
762 unsigned int <anchor id="command-data-struct-start-src"/>start_src; // event to make the acquisition start
763 unsigned int <anchor id="command-data-struct-start-arg"/>start_arg; // parameters that influence this start
765 unsigned int <anchor id="command-data-struct-scan-begin-src"/>scan_begin_src; // event to make a particular scan start
766 unsigned int <anchor id="command-data-struct-scan-begin-arg"/>scan_begin_arg; // parameters that influence this start`
768 unsigned int <anchor id="command-data-struct-convert-src"/>convert_src; // event to make a particular conversion start
769 unsigned int <anchor id="command-data-struct-convert-arg"/>convert_arg; // parameters that influence this start
771 unsigned int <anchor id="command-data-struct-scan-end-src"/>scan_end_src; // event to make a particular scan terminate
772 unsigned int <anchor id="command-data-struct-scan-end-arg"/>scan_end_arg; // parameters that influence this termination
774 unsigned int <anchor id="command-data-struct-stop-src"/>stop_src; // what make the acquisition terminate
775 unsigned int <anchor id="command-data-struct-stop-arg"/>stop_arg; // parameters that influence this termination
777 unsigned int <anchor id="command-data-struct-chanlist"/>*chanlist; // pointer to list of channels to be sampled
778 unsigned int <anchor id="command-data-struct-chanlist-len"/>chanlist_len; // number of channels to be sampled
780 sampl_t *<anchor id="command-data-struct-data"/>data; // address of buffer
781 unsigned int <anchor id="command-data-struct-data-len"/>data_len; // number of samples to acquire
784 The start and end of the whole command acquisition sequence, and the
785 start and end of each scan and of each conversion, is triggered by a
786 so-called <emphasis>event</emphasis>. More on these in
787 <xref linkend="comedicmdsources"/>.
791 The <parameter class="function">subdev</parameter> member of the
792 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> structure is
793 the index of the subdevice the command is intended for. The
794 <function><link linkend="func-ref-comedi-find-subdevice-by-type">comedi_find_subdevice_by_type</link></function>
795 function can be useful in discovering the index of your desired subdevice.
799 The <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield>
801 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data
802 structure should point to an array whose number of elements is
804 <structfield><link linkend="command-data-struct-chanlist-len">chanlist_len</link></structfield>
805 (this will generally be the same as the
806 <structfield><link linkend="command-data-struct-scan-end-arg">scan_end_arg</link></structfield>).
808 <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield>
809 specifies the sequence of channels and gains (and analog references)
810 that should be stepped through for each scan. The elements of the
811 <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield> array should be
812 initialized by <quote>packing</quote> the channel, range and reference
813 information together with the
814 <function><link linkend="ref-macro-CR-PACK">CR_PACK</link></function>
819 The <structfield><link linkend="command-data-struct-data">data</link></structfield> and
820 <structfield><link linkend="command-data-struct-data-len">data_len</link></structfield>
821 members can be safely ignored when issueing commands from a user-space
822 program. They only have meaning when a command is sent from a
823 <emphasis role="strong">kernel</emphasis> module using the
824 <systemitem>kcomedilib</systemitem> interface, in which case they specify
825 the buffer where the driver should write/read its data to/from.
829 The final member of the
830 <type><link linkend="command-data-struct">comedi_cmd</link></type> structure is the
831 <structfield><link linkend="command-data-struct-flags">flags</link></structfield> field,
832 i.e., bits in a word that can be bitwise-or'd together. The meaning of
833 these bits are explained in
834 <xref linkend="comedicmdflags"/>.
840 <section id="comedicmdsources">
842 The command trigger events
843 <anchor id="source.trigger.anchor"/>
846 A command is a very versatile acquisition instruction, in the sense
847 that it offers lots of possibilities to let different hardware and
848 software sources determine when acquisitions are started, performed,
849 and stopped. More specifically, the command
850 <link linkend="command-data-struct">data structure</link>
851 has <emphasis>five</emphasis> types of events: start the
852 <link linkend="acquisitionterminology">acquisition</link>,
853 start a <link linkend="scan">scan</link>, start a
854 <link linkend="conversion">conversion</link>, stop a scan, and stop
855 the acquisition. Each event can be given its own
856 <emphasis><link linkend="source.trigger.anchor">source</link></emphasis>
857 (the <parameter class="function">…_src</parameter> members in the
858 <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data
859 structure). And each event source can have a corresponding
860 argument (the <parameter class="function">…_arg</parameter> members of
861 the <type><link linkend="ref-type-comedi-cmd">comedi_cmd</link></type> data
862 structure) whose meaning depends on the type of source trigger.
863 For example, to specify an external digital line <quote>3</quote> as a
864 source (in general, <emphasis>any</emphasis> of the five event
865 sources), you would use
866 <parameter>src</parameter>=<constant><link linkend="trig-ext">TRIG_EXT</link></constant>
867 and <parameter>arg</parameter>=<literal>3</literal>.
870 The following paragraphs discuss in somewhat more detail the trigger
871 event sources(<parameter class="function">…_src</parameter>), and the
872 corresponding arguments (<parameter class="function">…_arg</parameter>).
875 The start of an acquisition is controlled by the
876 <structfield><link linkend="command-data-struct-start-src">start_src</link></structfield> events.
877 The available options are:
882 <anchor id="trig-now-start-src"/>
883 <constant>TRIG_NOW</constant>: the <quote>start</quote> event occurs
884 <structfield><link linkend="command-data-struct-start-arg">start_arg</link></structfield>
885 nanoseconds after the command is set up. Currently, only
886 <structfield><link linkend="command-data-struct-start-arg">start_arg</link></structfield>=<literal>0</literal> is
893 <anchor id="trig-follow-start-src"/>
894 <constant>TRIG_FOLLOW</constant>: (For an output device.) The <quote>start</quote>
895 event occurs when data is written to the buffer.
901 <anchor id="trig-ext-start-src"/>
902 <constant>TRIG_EXT</constant>: the <quote>start</quote> event occurs when an
903 external trigger signal occurs; e.g., a rising edge of a digital line.
904 <structfield><link linkend="command-data-struct-start-arg">start_arg</link></structfield>
905 chooses the particular digital line.
911 <anchor id="trig-int-start-src"/>
912 <constant>TRIG_INT</constant>: the <quote>start</quote> event occurs on a &comedi;
913 internal signal, which is typically caused by an
914 <constant><link linkend="insn-inttrig">INSN_INTTRIG</link></constant>
920 The start of the beginning of each
921 <link linkend="scan">scan</link> is controlled by the
922 <structfield><link linkend="command-data-struct-scan-begin-src">scan_begin_src</link></structfield> events.
923 The available options are:
928 <anchor id="trig-timer-start-scan"/>
929 <constant>TRIG_TIMER</constant>: <quote>scan begin</quote>
930 events occur periodically. The time between <quote>scan begin</quote>
932 <structfield><link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link></structfield>
939 <anchor id="trig-follow-start-scan"/>
940 <constant>TRIG_FOLLOW</constant>: The <quote>scan begin</quote>
941 event occurs immediately after a <quote>scan end</quote>
948 <anchor id="trig-ext-start-scan"/>
949 <constant>TRIG_EXT</constant>: the <quote>scan begin</quote>
950 event occurs when an external trigger signal
951 occurs; e.g., a rising edge of a digital line.
952 <structfield><link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link></structfield>
953 chooses the particular digital line.
959 <structfield><link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link></structfield>
960 used here may not be supported exactly by the device, but it
961 will be adjusted to the nearest supported value by
962 <function><link linkend="func-ref-comedi-command-test">comedi_command_test</link></function>.
965 The timing between each sample in a
966 <link linkend="scan">scan</link> is controlled by the
967 <structfield><link linkend="command-data-struct-convert-src">convert_src</link></structfield>
969 The available options are:
974 <anchor id="convert-trig-timer"/>
975 <anchor id="trig-timer"/>
976 <constant>TRIG_TIMER</constant>: the conversion events occur periodically.
977 The time between <quote>convert</quote> events is
978 <structfield><link linkend="command-data-struct-convert-arg">convert_arg</link></structfield>
985 <anchor id="convert-trig-ext"/>
986 <anchor id="trig-ext"/>
987 <constant>TRIG_EXT</constant>: the conversion events occur when an
988 external trigger signal occurs, e.g., a rising edge of a digital line.
989 <structfield><link linkend="command-data-struct-convert-arg">convert_arg</link></structfield>
990 chooses the particular digital line.
996 <anchor id="convert-trig-now"/>
997 <anchor id="trig-now"/>
998 <constant>TRIG_NOW</constant>: All conversion events in a
999 <link linkend="scan">scan</link> occur simultaneously.
1004 The <emphasis>end</emphasis> of each scan is almost always specified
1006 <structfield><link linkend="command-data-struct-scan-end-src">scan_end_src</link></structfield>
1008 <constant><link linkend="trig-count">TRIG_COUNT</link></constant>,
1009 with the argument being the same as the number of channels in the
1010 <structfield><link linkend="command-data-struct-chanlist">chanlist</link></structfield>. You
1011 could probably find a device that allows something else, but it would
1016 <link linkend="acquisitionterminology">acquisition</link> is
1018 <structfield><link linkend="command-data-struct-stop-src">stop_src</link></structfield> event.
1019 The available options are:
1024 <anchor id="acquisition-end-trig-count"/>
1025 <anchor id="trig-count"/>
1026 <constant>TRIG_COUNT</constant>: stop the acquisition after
1027 <structfield><link linkend="command-data-struct-stop-arg">stop_arg</link></structfield>
1034 <anchor id="acquisition-end-trig-none"/>
1035 <anchor id="trig-none"/>
1036 <constant>TRIG_NONE</constant>: perform continuous acquisition,
1038 <function><link linkend="func-ref-comedi-cancel">comedi_cancel</link></function>.
1041 Its <structfield>stop_arg</structfield> argument is reserved and should be set to <literal>0</literal>.
1042 (<quote>Reserved</quote>
1043 means that unspecified things could happen if it is set to something
1044 else but <literal>0</literal>.)
1049 There are a couple of less usual or not yet implemented events:
1054 <anchor id="trig-time"/>
1055 <constant>TRIG_TIME</constant>:
1056 cause an event to occur at a particular time.
1059 (This event source is reserved for future use.)
1065 <anchor id="trigother-event"/>
1066 <constant>TRIG_OTHER</constant>: driver specific event trigger.
1069 This event can be useful as any of the trigger sources. Its exact
1070 meaning is driver specific, because it implements a feature that
1071 otherwise does not fit into the generic &comedi; command interface.
1072 Configuration of <constant>TRIG_OTHER</constant> features are done by
1073 <constant><link linkend="instructionsconfiguration">INSN_CONFIG</link></constant>
1077 The argument is reserved and should be set to <literal>0</literal>.
1082 Not all event sources are applicable to all events. Supported
1083 trigger sources for specific events depend significantly on your
1084 particular device, and even more on the current state of its device
1086 <function><link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask</link></function>
1087 function is useful for determining what trigger sources a subdevice
1094 <section id="comedicmdflags">
1097 <anchor id="source.flags.anchor"/>
1102 <structfield><link linkend="command-data-struct-flags">flags</link></structfield>
1104 <link linkend="ref-type-comedi-cmd">command data structure</link>
1105 is used to specify some <quote>behaviour</quote> of the acquisitions in
1107 The meaning of the field is as follows:
1112 <anchor id="trig-rt"/>
1113 <constant>TRIG_RT</constant>: ask the driver to use a
1114 <emphasis role="strong">hard real-time</emphasis> interrupt handler.
1115 This will reduce latency in handling interrupts from your data
1117 hardware. It can be useful if you are sampling at high frequency, or
1118 if your hardware has a small onboard data buffer. You must have a
1119 real-time kernel (<ulink url="http://www.rtai.org">RTAI</ulink> or
1120 <ulink url="http://www.rtlinux-gpl.org/">RTLinux/GPL</ulink>)
1121 and must compile &comedi; with real-time support, or this flag will do
1128 <anchor id="trig-wake-eos"/>
1129 <constant>TRIG_WAKE_EOS</constant>:
1130 where <quote>EOS</quote> stands for <quote>End of Scan</quote>. Some
1131 drivers will change their behaviour when this flag is set, trying to
1132 transfer data at the end of every scan (instead of, for example,
1133 passing data in chunks whenever the board's hardware data buffer is
1134 half full). This flag may degrade a driver's performance at high
1135 frequencies, because the end of a scan is, in general, a much more
1136 frequent event than the filling up of the data buffer.
1142 <anchor id="trig-round-nearest"/>
1143 <constant>TRIG_ROUND_NEAREST</constant>:
1144 round to nearest supported timing period, the default.
1145 This flag (as well as the following three), indicates how timing
1146 arguments should be rounded if the hardware cannot achieve the exact
1153 <anchor id="trig-round-down"/>
1154 <constant>TRIG_ROUND_DOWN</constant>: round period down.
1160 <anchor id="trig-round-up"/>
1161 <constant>TRIG_ROUND_UP</constant>: round period up.
1167 <anchor id="trig-round-up-next"/>
1168 <constant>TRIG_ROUND_UP_NEXT</constant>:
1169 this one doesn't do anything, and I don't know what it was intended
1176 <anchor id="trig-dither"/>
1177 <constant>TRIG_DITHER</constant>: enable dithering? Dithering is
1178 a software technique to smooth the influence of discretization
1179 <quote>noise</quote>.
1185 <anchor id="trig-deglitch"/>
1186 <constant>TRIG_DEGLITCH</constant>: enable deglitching?
1187 Another <quote>noise</quote> smoothing technique.
1193 <anchor id="trig-write"/>
1194 <constant>TRIG_WRITE</constant>:
1195 write to bidirectional devices. Could be useful, in principle, if
1196 someone wrote a driver that supported commands for a digital I/O
1197 device that could do either input or output.
1203 <anchor id="trig-bogus"/>
1204 <constant>TRIG_BOGUS</constant>: do the motions?
1210 <anchor id="trig-other"/>
1211 <constant>TRIG_CONFIG</constant>: perform configuration, not triggering.
1212 This is a legacy of the deprecated
1213 <type><link linkend="ref-type-comedi-trig">comedi_trig_struct</link></type>
1214 data structure, and has no function at present.
1228 If you wish to aquire accurate waveforms, it is vital that you use an
1229 anti-alias filter. An anti-alias filter is a low-pass filter used to
1230 remove all frequencies higher than the Nyquist frequency (half your sampling rate)
1231 from your analog input signal
1232 before you convert it to digital. If you fail to filter your input signal,
1233 any high frequency components in the original analog signal will create
1234 artifacts in your recorded digital waveform that cannot be corrected.
1237 For example, suppose you are sampling an analog input channel at a rate of
1238 1000 Hz. If you were to apply a 900 Hz sine wave to the input, you
1239 would find that your
1240 sampling rate is not high enough to faithfully record the 900 Hz input,
1241 since it is above your Nyquist frequency of 500 Hz. Instead, what you
1242 will see in your recorded digital waveform is a 100 Hz sine wave! If you
1243 don't use an anti-alias filter, it is impossible to tell whether the 100
1244 Hz sine wave you see in your digital signal was really produced by a
1245 100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz
1249 In practice, the cutoff frequency for the anti-alias filter is usually
1250 set 10% to 20% below the Nyquist frequency due to fact that real filters
1251 do not have infinitely sharp cutoffs.
1257 <section id="slowlyvarying">
1259 Slowly-varying inputs
1263 <emphasis role="strong">Note: The functions described here use an old
1264 feature that is no longer implemented by the &comedi;
1265 kernel layer. THEY WILL NOT WORK!</emphasis>
1269 Sometimes, your input channels change slowly enough that
1270 you are able to average many successive input values to get a
1271 more accurate measurement of the actual value. In general,
1272 the more samples you average, the better your estimate
1273 gets, roughly by a factor of
1274 <function>sqrt<parameter>number_of_samples</parameter></function>.
1275 Obviously, there are limitations to this:
1282 you are ultimately limited by <quote>Spurious Free Dynamic
1283 Range</quote>. This SFDR is one of the popular measures to quantify how
1284 much noise a signal carries. If you take a Fourier transform of your
1285 signal, you will see several <quote>peaks</quote> in the transform: one
1286 or more of the fundamental harmonics of the measured signal, and lots
1287 of little <quote>peaks</quote> (called <quote>spurs</quote>) caused by
1288 noise. The SFDR is then the difference between the amplitude of the
1289 fundamental harmonic and of the largest spur (at frequencies below
1290 half of the Nyquist frequency of the DAQ sampler!).
1296 you need to have <emphasis>some</emphasis> noise on the input channel,
1297 otherwise you will be averaging the same number <literal>N</literal>
1298 times. (Of course, this only holds if the noise is large enough to
1299 cause at least a one-bit discretization.)
1305 the more noise you have, the greater your SFDR, but it
1306 takes many more samples to compensate for the increased
1313 if you feel the need to average samples for, for example, two seconds,
1314 your signal will need to be <emphasis>very</emphasis> slowly-varying,
1315 i.e., not varying more than your target uncertainty for the entire two
1323 As you might have guessed, the &comedi; library has functions
1324 to help you in your quest to accurately measure slowly varying
1327 <funcsynopsis><funcprototype>
1328 <funcdef>int <function>comedi_sv_init</function></funcdef>
1329 <paramdef>comedi_sv_t *<parameter>sv</parameter></paramdef>
1330 <paramdef>comedi_t *<parameter>device</parameter></paramdef>
1331 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
1332 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
1333 </funcprototype></funcsynopsis>
1335 The above function <function><link linkend="func-ref-comedi-sv-init">comedi_sv_init</link></function> initializes the
1336 <type><link linkend="ref-type-comedi-sv-t">comedi_sv_t</link></type> data structure, used
1337 to do the averaging acquisition:
1339 typedef struct comedi_sv_struct {
1340 <link linkend="ref-type-comedi-t">comedi_t</link> *dev;
1341 unsigned int subdevice;
1348 /* number of measurements to average (for analog inputs) */
1355 The actual acquisition is done with the function
1356 <function><link linkend="func-ref-comedi-sv-measure">comedi_sv_measure</link></function>:
1358 <funcsynopsis><funcprototype>
1359 <funcdef>int <function>comedi_sv_measure</function></funcdef>
1360 <paramdef>comedi_sv_t *<parameter>sv</parameter></paramdef>
1361 <paramdef>double *<parameter>data</parameter></paramdef>
1362 </funcprototype></funcsynopsis>
1364 The number of samples over which the function
1365 <function>comedi_sv_measure</function> averages is limited by the
1366 implementation (currently the limit is 100 samples).
1370 One typical use for this function is the measurement of thermocouple
1372 And the &comedi; self-calibration utility also uses these functions.
1373 On some hardware, it is possible to tell it to measure an
1374 internal stable voltage reference, which is typically going
1375 to be very slowly varying; on the kilosecond time scale
1376 or more. So, it is reasonable to measure millions of samples,
1377 to get a very accurate measurement of the A/D converter output
1378 value that corresponds to the voltage reference. Sometimes,
1379 however, this is overkill, since there is no need to
1380 perform a part-per-million calibration to a standard that
1381 is only accurate to a part-per-thousand.
1386 <section id="experimentalfunctionality">
1388 Experimental functionality
1392 The following subsections document functionality that has not yet
1393 matured. Most of this functionality has even not been implemented yet
1394 in any single device driver. This information is included here, in
1395 order to stimulate discussion about their API, and to encourage
1396 pioneering implementations.
1399 <section id="digitalinputcombining">
1401 Digital input combining machines
1405 (<emphasis role="strong">Status: experimental (i.e., no driver implements
1406 this yet)</emphasis>)
1409 When one or several digital inputs are used to modify an output
1410 value, either an accumulator or a single digital line or bit,
1411 a bitfield structure is typically used in the &comedi; interface.
1412 The digital inputs have two properties, <quote>sensitive</quote> inputs
1413 and <quote>modifier</quote> inputs. Edge transitions on sensitive
1414 inputs cause changes in the output signal, whereas modifier inputs
1415 change the effect of edge transitions on sensitive inputs. Note that
1416 inputs can be both modifier inputs and sensitive inputs.
1420 For simplification purposes, it is assumed that multiple digital
1421 inputs do not change simultaneously.
1425 The combined state of the modifier inputs determine a modifier
1426 state. For each combination of modifier state and sensitive
1427 input, there is a set of bits that determine the effect on the
1428 output value due to positive or negative transitions of the
1429 sensitive input. For each transition direction, there are two
1430 bits defined as follows:
1432 <variablelist spacing="compact">
1435 <listitem>transition is ignored.</listitem>
1439 <listitem>accumulator is incremented, or output is set.</listitem>
1443 <listitem>accumulator is decremented, or output is cleared.</listitem>
1447 <listitem>reserved.</listitem>
1451 For example, a simple digital follower is specified by the bit
1452 pattern 01 10, because it sets the output on positive transitions
1453 of the input, and clears the output on negative transitions. A
1454 digital inverter is similarily 10 01. These systems have only
1455 one sensitive input.
1459 As another example, a simple up counter, which increments on
1460 positive transitions of one input, is specified by 01 00. This
1461 system has only one sensitive input.
1465 When multiple digital inputs are used, the inputs are divided
1466 into two types, inputs which cause changes in the accumulator, and
1467 those that only modify the meaning of transitions on other inputs.
1468 Modifier inputs do not require bitfields, but there needs to be
1469 a bitfield of length 4*(2^(N-1)) for each edge sensitive input,
1470 where N is the total number of inputs. Since N is usually 2 or
1471 3, with only one edge sensitive input, the scaling issues are
1478 <section id="analogconversion">
1480 Analog filtering configuration
1484 <emphasis role="strong">(Status: design (i.e., no driver implements
1485 this yet).)</emphasis>
1489 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield>
1491 <link linkend="insn-data-structure">instruction data structure</link>
1492 has not been assigned yet.
1495 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1496 of the <link linkend="insn-data-structure">instruction data
1497 structure</link> is ignored.
1501 Some devices have the capability to add white noise (dithering) to
1502 analog input measurement. This additional noise can then be averaged
1503 out, to get a more accurate measurement of the input signal. It
1504 should not be assumed that channels can be separately configured.
1505 A simple design can use 1 bit to turn this feature on/off.
1509 Some devices have the capability of changing the glitch characteristics
1510 of analog output subsytems. The default (off) case should be where
1511 the average settling time is lowest. A simple design can use 1 bit
1512 to turn this feature on/off.
1516 Some devices have a configurable analog filters as part of the analog
1517 input stage. A simple design can use 1 bit to enable/disable the
1518 filter. Default is disabled, i.e., the filter being bypassed, or if
1519 the choice is between two filters, the filter with the largest
1524 <section id="waveformgeneration">
1526 Analog Output Waveform Generation
1530 <emphasis role="strong">(Status: design (i.e., no driver implements
1531 this yet).)</emphasis>
1534 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1535 <link linkend="insn-data-structure">instruction data structure</link>
1536 has not been assigned yet.
1539 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1540 of the <link linkend="insn-data-structure">instruction data
1541 structure</link> is ignored.
1545 Some devices have the ability to cyclicly loop through samples kept in
1546 an on-board analog output FIFO. This config should allow the user to
1547 enable/disable this mode.
1551 This config should allow the user to configure the number of samples
1552 to loop through. It may be necessary to configure the channels used.
1557 <section id="extendedtriggering">
1562 <emphasis role="strong">(Status: alpha.)</emphasis>
1566 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1567 <link linkend="insn-data-structure">instruction data structure</link>
1568 has not been assigned yet.
1571 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1572 of the <link linkend="insn-data-structure">instruction data
1573 structure</link> is ignored.
1577 This section covers common information for all extended
1578 triggering configuration, and doesn't describe a particular
1579 type of extended trigger.
1583 Extended triggering is used to configure triggering engines that
1584 do not fit into commands. In a typical programming sequence, the
1585 application will use
1586 <link linkend="instructionsconfiguration">configuration instructions</link>
1587 to configure an extended trigger, and a
1588 <link linkend="commandsstreaming">command</link>,
1590 <constant><link linkend="trig-other">TRIG_OTHER</link></constant>
1591 as one of the trigger sources.
1595 Extended trigger configuration should be designed in such a way
1596 that the user can probe for valid parameters, similar to how
1597 command testing works. An extended trigger configuration instruction
1598 should not configure the hardware directly, rather, the configuration
1599 should be saved until the subsequent command is issued. This
1600 allows more flexibility for future interface changes.
1604 It has not been decided whether the configuration stage should return a
1605 token that is then used as the trigger argument in the command.
1606 Using tokens is one method to satisfy the problem that extended
1607 trigger configurations may have subtle compatiblity issues with
1608 other trigger sources/arguments that can only be determined at
1609 command test time. Passing all stages of a command test should
1610 only be allowed with a properly configured extended trigger.
1614 Extended triggers must use
1615 <structfield><link linkend="insn-data-structure-data">data</link></structfield>[1] as flags. The
1616 upper 16 bits are reserved and used only for flags that are common to
1617 all extended triggers. The lower 16 bits may be defined by the
1618 particular type of extended trigger.
1622 Various types of extended triggers must use
1623 <structfield><link linkend="insn-data-structure-data">data</link></structfield>[1] to know which
1624 event the extended trigger will be assigned to in the command
1625 structure. The possible values are an OR'd mask of the following:
1631 <constant>COMEDI_EV_START</constant>
1636 <constant>COMEDI_EV_SCAN_BEGIN</constant>
1641 <constant>COMEDI_EV_CONVERT</constant>
1646 <constant>COMEDI_EV_SCAN_END</constant>
1651 <constant>COMEDI_EV_STOP</constant>
1658 <section id="analogtriggering">
1663 <emphasis role="strong">
1664 (Status: alpha. The <filename>ni_mio_common.c</filename> driver
1665 implements this feature.)
1670 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1671 <link linkend="insn-data-structure">instruction data structure</link>
1672 has not been assigned yet.
1675 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1676 of the <link linkend="insn-data-structure">instruction data
1677 structure</link> is ignored.
1681 The <structfield><link linkend="insn-data-structure-data">data</link></structfield> field
1682 of the <link linkend="insn-data-structure">instruction data
1683 structure</link> is used as follows:
1684 <variablelist spacing="compact">
1686 <term>data[1]</term>
1687 <listitem>trigger and combining machine configuration.</listitem>
1690 <term>data[2]</term>
1691 <listitem>analog triggering signal chanspec.</listitem>
1694 <term>data[3]</term>
1695 <listitem>primary analog level.</listitem>
1698 <term>data[4]</term>
1699 <listitem>secondary analog level.</listitem>
1704 Analog triggering is described by a digital combining machine that
1705 has two sensitive digital inputs. The sensitive digital inputs are
1706 generated by configurable analog comparators. The analog comparators
1707 generate a digital 1 when the analog triggering signal is greater
1708 than the comparator level. The digital inputs are not modifier
1709 inputs. Note, however, there is an effective modifier due to the
1710 restriction that the primary analog comparator level must be less
1711 than the secondary analog comparator level.
1715 If only one analog comparator signal is used, the combining machine
1716 for the secondary input should be set to ignored, and the secondary
1717 analog level should be set to <literal>0</literal>.
1721 The interpretation of the chanspec and voltage levels is device
1722 dependent, but should correspond to similar values of the analog
1723 input subdevice, if possible.
1727 Notes: Reading range information is not addressed. This makes it
1728 difficult to convert comparator voltages to data values.
1732 Possible extensions: A parameter that specifies the necessary time
1733 that the set condition has to be true before the trigger is generated.
1734 A parameter that specifies the necessary time that the reset condition
1735 has to be true before the state machine is reset.
1740 <section id="bitfieldmatching">
1742 Bitfield Pattern Matching Extended Trigger
1745 <emphasis role="strong">
1746 (Status: design. No driver implements this feature yet.)
1751 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1752 <link linkend="insn-data-structure">instruction data structure</link>
1753 has not been assigned yet.
1756 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1757 of the <link linkend="insn-data-structure">instruction data
1758 structure</link> is ignored.
1762 The <structfield><link linkend="insn-data-structure-data">data</link></structfield> field
1763 of the <link linkend="insn-data-structure">instruction data
1764 structure</link> is used as follows:
1766 <variablelist spacing="compact">
1768 <term>data[1]</term>
1769 <listitem>trigger flags.</listitem>
1772 <term>data[2]</term>
1773 <listitem>mask.</listitem>
1776 <term>data[3]</term>
1777 <listitem>pattern.</listitem>
1782 The pattern matching trigger issues a trigger when all of a specifed
1783 set of input lines match a specified pattern. If the device allows,
1784 the input lines should correspond to the input lines of a digital input
1785 subdevice, however, this will necessarily be device dependent. Each
1786 possible digital line that can be matched is assigned a bit in the
1787 mask and pattern. A bit set in the mask indicates that the
1788 input line must match the corresponding bit in the pattern.
1789 A bit cleared in the mask indicates that the input line is ignored.
1793 Notes: This only allows 32 bits in the pattern/mask, which may be
1794 too few. Devices may support selecting different sets of lines from
1795 which to match a pattern.
1799 Discovery: The number of bits can be discovered by setting the mask
1800 to all 1's. The driver must modify this value and return
1801 <constant>-EAGAIN</constant>.
1806 <section id="countertimer">
1808 Counter configuration
1811 <emphasis role="strong">
1812 (Status: design. No driver implements this feature yet.)
1817 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1818 <link linkend="insn-data-structure">instruction data structure</link>
1819 has not been assigned yet.
1822 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1823 of the <link linkend="insn-data-structure">instruction data
1824 structure</link> is used to specify which counter to use. (I.e., the
1825 counter is a &comedi; channel.)
1829 The <structfield><link linkend="insn-data-structure-data">data</link></structfield> field
1830 of the <link linkend="insn-data-structure">instruction data
1831 structure</link> is used as follows:
1833 <variablelist spacing="compact">
1835 <term>data[1]</term>
1836 <listitem>trigger configuration.</listitem>
1839 <term>data[2]</term>
1840 <listitem>primary input chanspec.</listitem>
1843 <term>data[3]</term>
1844 <listitem>primary combining machine configuration.</listitem>
1847 <term>data[4]</term>
1848 <listitem>secondary input chanspec.</listitem>
1851 <term>data[5]</term>
1852 <listitem>secondary combining machine configuration.</listitem>
1855 <term>data[6]</term>
1856 <listitem>latch configuration.</listitem>
1861 Note that this configuration is only useful if the counting has to be
1862 done in <emphasis>software</emphasis>. Many cards offer configurable
1863 counters in hardware; e.g., general purpose timer cards can be
1864 configured to act as pulse generators, frequency counters, timers,
1868 Counters can be operated either in synchronous mode (using
1869 <constant><link linkend="insn-read">INSN_READ</link></constant>)
1870 or asynchronous mode (using
1871 <link linkend="commandsstreaming">commands</link>), similar to analog
1873 The input signal for both modes is the accumulator.
1874 Commands on counter subdevices are almost always specified using
1875 <structfield><link linkend="command-data-struct-scan-begin-src">scan_begin_src</link></structfield>
1876 = <constant><link linkend="trigother-event">TRIG_OTHER</link></constant>,
1877 with the counter configuration also serving as the extended configuration for
1878 the <quote>scan begin</quote> source.
1882 Counters are made up of an accumulator and a combining machine that
1883 determines when the accumulator should be incremented or decremented
1884 based on the values of the input signals. The combining machine
1885 optionally determines when the accumulator should be latched and
1886 put into a buffer. This feature is used in asynchronous mode.
1890 Note: How to access multiple pieces of data acquired at each event?
1895 <section id="auxcounter">
1897 One source plus auxiliary counter configuration
1900 <emphasis role="strong">
1901 (Status: design. No driver implements this feature yet.)
1906 The <structfield><link linkend="insn-data-structure-insn">insn</link></structfield> field of the
1907 <link linkend="insn-data-structure">instruction data structure</link>
1908 has not been assigned yet.
1911 The <structfield><link linkend="insn-data-structure-chanspec">chanspec</link></structfield> field
1912 of the <link linkend="insn-data-structure">instruction data
1913 structure</link> is used to …
1917 The <structfield><link linkend="insn-data-structure-data">data</link></structfield> field
1918 of the <link linkend="insn-data-structure">instruction data
1919 structure</link> is used as follows:
1923 <variablelist spacing="compact">
1925 <term>data[1]</term>
1927 is flags, including the flags for the command triggering
1928 configuration. If a command is not subsequently issued on the
1929 subdevice, the command triggering portion of the flags are ignored.
1933 <term>data[2]</term>
1935 determines the mode of operation. The mode of operation
1936 is actually a bitfield that encodes what to do for various
1937 transitions of the source signals.
1941 <term>data[3]</term>
1942 <term>data[4]</term>
1944 determine the primary source for the counter, similar to the
1945 <structfield><link linkend="command-data-struct-scan-begin-src">…_src</link></structfield> and the
1946 <structfield><link linkend="command-data-struct-scan-begin-arg">…_arg</link></structfield> fields
1948 <link linkend="command-data-struct">command data structure</link>.
1955 Notes: How to specify which events cause a latch and push, and what
1963 National instruments RTSI trigger bus
1966 A number of NI boards support the RTSI (Real Time System Integration) bus.
1967 It's primary use is to synchronize multiple DAQ cards.
1968 On PXI boards, the RTSI lines correspond to the PXI trigger lines 0 to 7. PCI
1969 boards use cables to connect to their RTSI ports.
1970 The RTSI bus consists of 8 digital signal lines numbered 0 to 7 that are bi-directional.
1971 Each of these signal lines
1972 can be configured as an input or output, and the signal appearing on the output
1973 of each line can be configured to one of several internal board timing signals
1974 (although on older boards RTSI line 7 can only be used for the clock signal).
1975 The <systemitem>ni_pcimio</systemitem>, <systemitem>ni_atmio</systemitem>, and
1976 <systemitem>ni_mio_cs</systemitem> drivers expose the RTSI bus
1977 as a digital I/O subdevice (subdevice number 10).
1980 The functions <function>comedi_dio_config</function> and
1981 <function>comedi_dio_get_config</function> can be used on
1982 the RTSI subdevice to
1983 set/query the direction (input or output) of each of the RTSI lines individually.
1986 The subdevice also supports the
1987 <constant>INSN_CONFIG_SET_CLOCK_SRC</constant> and
1988 <constant>INSN_CONFIG_GET_CLOCK_SRC</constant> configuration
1989 instructions, which can be
1990 used to configure/query what source the board uses to synchronize its
1991 master clock to. The various possibilities are defined in the <filename>comedi.h</filename>
1995 <tgroup cols='2' align='left'>
1998 <entry>Clock Source</entry>
1999 <entry>Description</entry>
2004 <entry><constant>NI_MIO_INTERNAL_CLOCK</constant></entry>
2006 Use the board's internal oscillator.
2010 <entry><constant>NI_MIO_RTSI_CLOCK</constant></entry>
2012 Use the RTSI line 7 as the master clock. This source is
2013 only supported on pre-m-series boards. The newer m-series boards
2014 use <function>NI_MIO_PLL_RTSI_CLOCK</function> instead.
2018 <entry><constant>NI_MIO_PLL_PXI_STAR_TRIGGER_CLOCK</constant></entry>
2020 Only available for newer m-series PXI boards. Synchronizes the board's
2021 phased-locked loop (which runs at 80MHz) to the PXI star trigger
2026 <entry><constant>NI_MIO_PLL_PXI10_CLOCK</constant></entry>
2028 Only available for newer m-series PXI boards.
2029 Synchronizes the board's
2030 phased-locked loop (which runs at 80MHz) to the 10 MHz PXI backplane
2036 <function>NI_MIO_PLL_RTSI_CLOCK<parameter>n</parameter></function>
2039 Only available for newer m-series boards.
2040 The function returns a clock source which will cause the board's
2041 phased-locked loop (which runs at 80MHz) to syncronize to the RTSI
2042 line specified in the function argument.
2050 For all clock sources except <constant>NI_MIO_INTERNAL_CLOCK</constant>
2051 and <constant>NI_MIO_PLL_PXI10_CLOCK</constant>,
2052 you should pass the period of the clock your are feeding to the board when
2053 using <constant>INSN_CONFIG_SET_CLOCK_SRC</constant>.
2056 Finally, the configuration instructions
2057 <constant>INSN_CONFIG_SET_ROUTING</constant> and
2058 <constant>INSN_CONFIG_GET_ROUTING</constant>
2059 can be used to select/query which internal signal
2060 will appear on a given RTSI output line. The header file <filename>comedi.h</filename> defines
2061 the following signal sources which can be routed to an RTSI line:
2065 <tgroup cols='2' align='left'>
2068 <entry>Signal Source</entry>
2069 <entry>Description</entry>
2074 <entry><constant>NI_RTSI_OUTPUT_ADR_START1</constant></entry>
2076 ADR_START1, an analog input start signal. See the NI's
2077 DAQ-STC Technical Reference Manual for more information.
2081 <entry><constant>NI_RTSI_OUTPUT_ADR_START2</constant></entry>
2083 ADR_START2, an analog input stop signal. See the NI's
2084 DAQ-STC Technical Reference Manual for more information.
2088 <entry><constant>NI_RTSI_OUTPUT_SCLKG</constant></entry>
2090 SCLKG, a sample clock signal. See the NI's
2091 DAQ-STC Technical Reference Manual for more information.
2095 <entry><constant>NI_RTSI_OUTPUT_DACUPDN</constant></entry>
2097 DACUPDN, a dac update signal. See the NI's
2098 DAQ-STC Technical Reference Manual for more information.
2102 <entry><constant>NI_RTSI_OUTPUT_DA_START1</constant></entry>
2104 DA_START1, an analog output start signal. See the NI's
2105 DAQ-STC Technical Reference Manual for more information.
2109 <entry><constant>NI_RTSI_OUTPUT_G_SRC0</constant></entry>
2111 G_SRC0, the source signal to general purpose counter 0. See the NI's
2112 DAQ-STC Technical Reference Manual for more information.
2116 <entry><constant>NI_RTSI_OUTPUT_G_GATE0</constant></entry>
2118 G_GATE0, the gate signal to general purpose counter 0. See the NI's
2119 DAQ-STC Technical Reference Manual for more information.
2123 <entry><constant>NI_RTSI_OUTPUT_RGOUT0</constant></entry>
2125 RGOUT0, the output signal of general purpose counter 0. See the NI's
2126 DAQ-STC Technical Reference Manual for more information.
2131 <function>NI_RTSI_OUTPUT_RTSI_BRD<parameter>n</parameter></function>
2134 RTSI_BRD0 though RTSI_BRD3 are four internal signals which can
2135 have various other signals routed to them in turn. Currently, comedi
2136 provides no way to configure the signals routed to the RTSI_BRD lines.
2137 See the NI's DAQ-STC Technical Reference Manual for more information.
2141 <entry><constant>NI_RTSI_OUTPUT_RTSI_OSC</constant></entry>
2143 The RTSI clock signal. On pre-m-series boards, this signal is always
2144 routed to RTSI line 7, and cannot be routed to lines 0 through 6. On
2145 m-series boards, any RTSI line can be configured to output the clock
2154 The RTSI bus pins may be used as trigger inputs for many of the
2155 &comedi; trigger functions. To use the RTSI bus pins, set the source to be
2156 <constant>TRIG_EXT</constant> and the source argument using the return values
2157 from the <function>NI_EXT_RTSI<parameter>n</parameter></function> function (or similarly the
2158 <function>NI_EXT_PFI<parameter>n</parameter></function> function if you want
2159 to trigger from a PFI line). The <constant>CR_EDGE</constant> and
2160 <constant>CR_INVERT</constant> flags may
2161 also be set on the trigger source argument to specify edge and
2162 falling edge/low level triggering.
2166 An example to set up a device as a master is given below.
2169 <programlisting><![CDATA[
2170 void comediEnableMaster(comedi_t *dev){
2171 comedi_insn configCmd;
2172 lsampl_t configData[2];
2175 static const unsigned rtsi_subdev = 10;
2176 static const unsigned rtsi_clock_line = 7;
2178 /* Route RTSI clock to line 7 (not needed on pre-m-series boards since their
2179 clock is always on line 7). */
2180 memset(&configCmd, 0, sizeof(configCmd));
2181 memset(&configData, 0, sizeof(configData));
2182 configCmd.insn = INSN_CONFIG;
2183 configCmd.subdev = rtsi_subdev;
2184 configCmd.chanspec = rtsi_clock_line;
2186 configCmd.data = configData;
2187 configCmd.data[0] = INSN_CONFIG_SET_ROUTING;
2188 configCmd.data[1] = NI_RTSI_OUTPUT_RTSI_OSC;
2189 ret = comedi_do_insn(dev, &configCmd);
2191 comedi_perror("comedi_do_insn: INSN_CONFIG");
2194 // Set clock RTSI line as output
2195 ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_OUTPUT);
2197 comedi_perror("comedi_dio_config");
2201 /* Set routing of the 3 main AI RTSI signals and their direction to output.
2202 We're reusing the already initialized configCmd instruction here since
2203 it's mostly the same. */
2204 configCmd.chanspec = 0;
2205 configCmd.data[1] = NI_RTSI_OUTPUT_ADR_START1;
2206 ret = comedi_do_insn(dev, &configCmd);
2208 comedi_perror("comedi_do_insn: INSN_CONFIG");
2211 ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_OUTPUT);
2213 comedi_perror("comedi_dio_config");
2217 configCmd.chanspec = 1;
2218 configCmd.data[1] = NI_RTSI_OUTPUT_ADR_START2;
2219 ret = comedi_do_insn(dev, &configCmd);
2221 comedi_perror("comedi_do_insn: INSN_CONFIG");
2224 ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_OUTPUT);
2226 comedi_perror("comedi_dio_config");
2230 configCmd.chanspec = 2;
2231 configCmd.data[1] = NI_RTSI_OUTPUT_SCLKG;
2232 ret = comedi_do_insn(dev, &configCmd);
2234 comedi_perror("comedi_do_insn: INSN_CONFIG");
2237 ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_OUTPUT);
2239 comedi_perror("comedi_dio_config");
2243 ]]></programlisting>
2246 An example to slave a m-series device from this master follows. A pre-m-series
2247 device would need to use <constant>NI_MIO_RTSI_CLOCK</constant> for
2248 the clock source instead. In
2249 your code, you may also wish to configure the master device to use the
2250 external clock source instead of using its internal clock directly (for
2251 best syncronization).
2253 <programlisting><![CDATA[
2254 void comediEnableSlave(comedi_t *dev){
2255 comedi_insn configCmd;
2256 lsampl_t configData[3];
2258 unsigned int d = 0;;
2259 static const unsigned rtsi_subdev = 10;
2260 static const unsigned rtsi_clock_line = 7;
2262 memset(&configCmd, 0, sizeof(configCmd));
2263 memset(&configData, 0, sizeof(configData));
2264 configCmd.insn = INSN_CONFIG;
2265 configCmd.subdev = rtsi_subdev;
2266 configCmd.chanspec = 0;
2268 configCmd.data = configData;
2269 configCmd.data[0] = INSN_CONFIG_SET_CLOCK_SRC;
2270 configCmd.data[1] = NI_MIO_PLL_RTSI_CLOCK(rtsi_clock_line);
2271 configCmd.data[2] = 100; /* need to give it correct external clock period */
2272 ret = comedi_do_insn(dev, &configCmd);
2274 comedi_perror("comedi_do_insn: INSN_CONFIG");
2277 /* configure RTSI clock line as input */
2278 ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_INPUT);
2280 comedi_perror("comedi_dio_config");
2283 /* Configure RTSI lines we are using for AI signals as inputs. */
2284 ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_INPUT);
2286 comedi_perror("comedi_dio_config");
2289 ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_INPUT);
2291 comedi_perror("comedi_dio_config");
2294 ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_INPUT);
2296 comedi_perror("comedi_dio_config");
2301 int comediSlaveStart(comedi_t *dev){
2303 unsigned int nChannels = 8;
2304 double sampleRate = 50000;
2305 unsigned int chanList[8];
2309 for(i = 0; i < nChannels; i++){
2310 chanList[i] = CR_PACK(i, 0, AREF_GROUND);
2313 memset(&cmd, 0, sizeof(cmd));
2314 ret = comedi_get_cmd_generic_timed(dev, subdevice, &cmd,
2315 (int)(1e9/(nChannels * sampleRate)));
2317 printf("comedi_get_cmd_generic_timed failed\n");
2320 cmd.chanlist = chanList;
2321 cmd.chanlist_len = nChannels;
2322 cmd.scan_end_arg = nChannels;
2323 cmd.start_src = TRIG_EXT;
2324 cmd.start_arg = CR_EDGE | NI_EXT_RTSI(0);
2325 cmd.convert_src = TRIG_EXT;
2326 cmd.convert_arg = CR_INVERT | CR_EDGE | NI_EXT_RTSI(2);
2327 cmd.stop_src = TRIG_NONE;
2329 ret = comedi_command(dev0, &cmd0);
2331 printf("comedi_command failed\n");
2336 ]]></programlisting>