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
61 <funcsynopsis><funcprototype>
62 <funcdef>int <link linkend="func-ref-comedi-dio-read"><function>comedi_dio_read</function></link></funcdef>
63 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
64 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
65 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
66 <paramdef>unsigned int *<parameter>bit</parameter></paramdef>
67 </funcprototype></funcsynopsis>
69 <funcsynopsis><funcprototype>
70 <funcdef>int <link linkend="func-ref-comedi-dio-write"><function>comedi_dio_write</function></link></funcdef>
71 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
72 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
73 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
74 <paramdef>unsigned int <parameter>bit</parameter></paramdef>
75 </funcprototype></funcsynopsis>
77 The <parameter class="function">device</parameter> parameter is a
78 <link linkend="ref-type-comedi-t">pointer</link>
79 to a successfully opened &comedi; device.
80 The <parameter class="function">subdevice</parameter> and
81 <parameter class="function">channel</parameter> parameters are positive
82 integers that indicate which subdevice and channel is used in the
83 acquisition. The integer <parameter class="function">bit</parameter>
84 contains the value of the acquired bit.
87 The direction of bidirectional lines can be configured using
90 <funcsynopsis><funcprototype>
91 <funcdef>int <link linkend="func-ref-comedi-dio-config"><function>comedi_dio_config</function></link></funcdef>
92 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
93 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
94 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
95 <paramdef>unsigned int <parameter>dir</parameter></paramdef>
96 </funcprototype></funcsynopsis>
98 The parameter <parameter class="function">dir</parameter> should be
99 either <constant>COMEDI_INPUT</constant> or
100 <constant>COMEDI_OUTPUT</constant>.
101 Many digital I/O subdevices group channels into blocks for
102 configuring direction. Changing one channel in a block changes
107 Multiple channels can be read and written simultaneously using the
110 <funcsynopsis><funcprototype>
111 <funcdef>int <link linkend="func-ref-comedi-dio-bitfield2"><function>comedi_dio_bitfield2</function></link></funcdef>
112 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
113 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
114 <paramdef>unsigned int <parameter>write_mask</parameter></paramdef>
115 <paramdef>unsigned int *<parameter>bits</parameter></paramdef>
116 <paramdef>unsigned int <parameter>base_channel</parameter></paramdef>
117 </funcprototype></funcsynopsis>
119 Each channel from <parameter class="function">base_channel</parameter>
120 to <parameter class="function">base_channel</parameter> +
121 <literal>31</literal> is assigned to a bit in the
122 <parameter class="function">write_mask</parameter> and
123 <parameter class="function">bits</parameter>
124 bitfield with bit 0 assigned to channel
125 <parameter class="function">base_channel</parameter>, bit 1 assigned to channel
126 <parameter class="function">base_channel</parameter> +
127 <literal>1</literal>, etc. If a bit in
128 <parameter class="function">write_mask</parameter> is set, the
129 corresponding bit in <parameter class="function">*bits</parameter> will
130 be written to the digital output line corresponding to the channel given by
131 <parameter class="function">base_channel</parameter> plus the bit number.
132 Each digital line is then read and placed into
133 <parameter class="function">*bits</parameter>. The value
134 of bits in <parameter class="function">*bits</parameter> corresponding
135 to digital output lines is undefined and device-specific. Channel
136 <parameter class="function">base_channel</parameter> +
137 <literal>0</literal> is the least significant bit in the bitfield. No
138 more than 32 channels at once can be accessed using this method.
139 <emphasis role="strong">Warning!</emphasis> Older versions of &comedi;
140 may ignore <parameter class="function">base_channel</parameter> and treat
141 it as <literal>0</literal> unless the subdevice has more than 32 channels.
145 The digital acquisition functions seem to be very simple, but, behind
146 the implementation screens of the &comedi; kernel module, they are
147 executed as special cases of the general
148 <link linkend="instructions">instruction</link> command.
155 <section id="singleanalog">
157 Single analog acquisition
160 Analog &comedi; channels can produce data values that are
161 <emphasis>samples</emphasis> from continuous analog signals.
162 These samples are integers with a significant content in
163 the range of, typically, <literal>8</literal>, <literal>10</literal>,
164 <literal>12</literal>, or <literal>16</literal> bits.
169 <funcsynopsis><funcprototype>
170 <funcdef>int <link linkend="func-ref-comedi-data-read"><function>comedi_data_read</function></link></funcdef>
171 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
172 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
173 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
174 <paramdef>unsigned int <parameter>range</parameter></paramdef>
175 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
176 <paramdef><link linkend="ref-type-lsampl-t">lsampl_t</link> *<parameter>data</parameter></paramdef>
177 </funcprototype></funcsynopsis>
179 reads one such data value from a &comedi; channel, and puts it in
180 the user-specified <parameter>data</parameter> buffer. The function
182 <funcsynopsis><funcprototype>
183 <funcdef>int <link linkend="func-ref-comedi-data-write"><function>comedi_data_write</function></link></funcdef>
184 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
185 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
186 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
187 <paramdef>unsigned int <parameter>range</parameter></paramdef>
188 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
189 <paramdef><link linkend="ref-type-lsampl-t">lsampl_t</link> <parameter>data</parameter></paramdef>
190 </funcprototype></funcsynopsis>
192 works in the opposite direction. Data values returned by this function
193 are unsigned integers less than, or equal to, the maximum sample value
194 of the channel, which can be determined using the function
196 <funcsynopsis><funcprototype>
197 <funcdef><link linkend="ref-type-lsampl-t">lsampl_t</link> <link linkend="func-ref-comedi-get-maxdata"><function>comedi_get_maxdata</function></link></funcdef>
198 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
199 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
200 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
201 </funcprototype></funcsynopsis>
203 Conversion of data values to physical units can be performed by the
206 <funcsynopsis><funcprototype>
207 <funcdef>double <link linkend="func-ref-comedi-to-phys"><function>comedi_to_phys</function></link></funcdef>
208 <paramdef><link linkend="ref-type-lsampl-t">lsampl_t</link> <parameter>data</parameter></paramdef>
209 <paramdef><link linkend="ref-type-comedi-range">comedi_range</link> *<parameter>range</parameter></paramdef>
210 <paramdef><link linkend="ref-type-lsampl-t">lsampl_t</link> <parameter>maxdata</parameter></paramdef>
211 </funcprototype></funcsynopsis>
213 There are two data structures in these commands that are not fully
219 <link linkend="ref-type-comedi-t">comedi_t</link>: this data structure
220 contains all information that a user program has to know about an
221 <emphasis>open</emphasis> &comedi; device. The programmer doesn't have
222 to fill in this data structure manually: it gets filled in by opening
229 <link linkend="ref-type-lsampl-t">lsampl_t</link>: this
230 <quote>data structure</quote> represents one single sample. On most
231 architectures, it's nothing more than a 32 bits value. Internally,
232 &comedi; does some conversion from raw sample data to
233 <quote>correct</quote> integers. This is called <quote>data
241 Each single acquisition by, for example,
243 <link linkend="func-ref-comedi-data-read">comedi_data_read()</link>
245 requires quite some overhead, because all the arguments of the
246 function call are checked. If multiple acquisitions must be done on
247 the same channel, this overhead can be avoided by using a function
248 that can read more than one sample:
250 <funcsynopsis><funcprototype>
251 <funcdef>int <link linkend="func-ref-comedi-data-read-n"><function>comedi_data_read_n</function></link></funcdef>
252 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
253 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
254 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
255 <paramdef>unsigned int <parameter>range</parameter></paramdef>
256 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
257 <paramdef><link linkend="ref-type-lsampl-t">lsampl_t</link> *<parameter>data</parameter></paramdef>
258 <paramdef>unsigned int <parameter>n</parameter></paramdef>
259 </funcprototype></funcsynopsis>
261 The number of samples, <parameter class="function">n</parameter>, is
262 limited by the &comedi; implementation (to a maximum of 100 samples),
263 because the call is blocking.
266 The start of the data acquisition can also be delayed by a specified
267 number of nano-seconds:
269 <funcsynopsis><funcprototype>
270 <funcdef>int <link linkend="func-ref-comedi-data-read-delayed"><function>comedi_data_read_delayed</function></link></funcdef>
271 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
272 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
273 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
274 <paramdef>unsigned int <parameter>range</parameter></paramdef>
275 <paramdef>unsigned int <parameter>aref</parameter></paramdef>
276 <paramdef><link linkend="ref-type-lsampl-t">lsampl_t</link> *<parameter>data</parameter></paramdef>
277 <paramdef>unsigned int <parameter>nano_sec</parameter></paramdef>
278 </funcprototype></funcsynopsis>
280 All these read and write acquisition functions are implemented on top
281 of the generic <link linkend="instructions">instruction</link>
290 <section id="instructions">
292 Instructions for multiple acquisitions
295 The <emphasis>instruction</emphasis> is one of the most generic,
296 overloaden and flexible functions in the &comedi; API. It is used to
297 execute a multiple of identical acquisitions on the same channel, but
299 <link linkend="instructionsconfiguration">configuration</link> of a
301 <anchor id="anchor.instruction.list"/>
302 An <emphasis>instruction list</emphasis> is a list of instructions,
303 possibly on different channels. Both instructions and instructions
304 lists are executed <emphasis>synchronously</emphasis>, i.e., while
305 <emphasis role="strong">blocking</emphasis> the calling process.
306 This is one of the limitations of instructions; the other one is that
307 they cannot code an acquisition involving timers or external events.
308 These limits are eliminated by the
309 <link linkend="commandsstreaming">command</link> acquisition
314 <section id="comediinsnstructure">
316 The instruction data structure
319 All the information needed to execute an instruction is stored in the
320 <link linkend="ref-type-comedi-insn">comedi_insn</link>
323 struct <anchor id="insn-data-structure"/>comedi_insn_struct {
324 <anchor id="insn-data-structure-insn"/>unsigned int insn; // integer encoding the type of acquisition
325 // (or configuration)
326 unsigned int n; // number of elements in data array
327 <link linkend="ref-type-lsampl-t">lsampl_t</link> <anchor id="insn-data-structure-data"/>*data; // pointer to data buffer
328 unsigned int subdev; // subdevice
329 unsigned int <anchor id="insn-data-structure-chanspec"/><link linkend="ref-macro-CR-PACK">chanspec</link>; // encoded channel specification
330 unsigned int unused[3];
333 Because of the large flexibility of the instruction function, many
334 types of instruction do not need to fill in all fields, or attach
335 different meanings to the same field. But the current implementation
336 of &comedi; requires the
337 <link linkend="insn-data-structure-data">data</link> field to be at
342 The <link linkend="insn-data-structure-insn">insn</link> flag of the
343 <link linkend="insn-data-structure">instruction data structure</link>
344 determines the type of acquisition executed in the corresponding
350 <constant>INSN_READ</constant>: the instruction executes a read on an
357 <constant>INSN_WRITE</constant>: the instruction executes a write on an
364 <constant>INSN_BITS</constant>: indicates that the instruction must
365 read or write values on multiple digital I/O channels.
371 <constant>INSN_GTOD</constant>: the instruction performs a
372 <quote>Get Time Of Day</quote> acquisition.
378 <constant>INSN_WAIT</constant>: the instruction blocks for a specified
379 number of nanoseconds.
389 <section id="instructionexecution">
391 Instruction execution
394 Once an instruction data structure has been filled in, the
395 corresponding instruction is executed with the function
397 <funcsynopsis><funcprototype>
398 <funcdef>int <link linkend="func-ref-comedi-do-insn"><function>comedi_do_insn</function></link></funcdef>
399 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
400 <paramdef><link linkend="ref-type-comedi-insn">comedi_insn</link> *<parameter>instruction</parameter></paramdef>
401 </funcprototype></funcsynopsis>
403 Many &comedi; instructions are shortcuts that relieve the programmer
404 from explicitly filling in the data structure and calling the
405 <link linkend="func-ref-comedi-do-insn">comedi_do_insn</link>
411 <funcsynopsis><funcprototype>
412 <funcdef>int <link linkend="func-ref-comedi-do-insnlist"><function>comedi_do_insnlist</function></link></funcdef>
413 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
414 <paramdef><link linkend="ref-type-comedi-insnlist">comedi_insnlist</link> *<parameter>list</parameter></paramdef>
415 </funcprototype></funcsynopsis>
417 allows to perform a list of instructions in one function
418 call. The number of instructions in the list is limited in the
419 implementation, because instructions are executed
420 <emphasis>synchronously</emphasis>, i.e., the call blocks until the
421 whole instruction (list) has finished.
429 <section id="instructionsconfiguration">
431 Instructions for configuration
434 <xref linkend="instructions"/> explains how instructions are used to do
435 <emphasis>acquisition</emphasis> on channels. This section explains
436 how they are used to <emphasis>configure</emphasis> a subdevice.
437 There are various sorts of configurations, and the
438 specific information for each different configuration possibility is
439 to be specified via the
440 <link linkend="insn-data-structure-data">data</link> buffer of the
441 <link linkend="insn-data-structure">instruction data structure</link>.
442 (So, the pointer to a
443 <link linkend="ref-type-lsampl-t">lsampl_t</link>
444 is misused as a pointer to an array with board-specific information.)
448 Using <constant>INSN_CONFIG</constant> as the
449 <link linkend="insn-data-structure-insn">insn</link> flag in an
450 <link linkend="insn-data-structure">instruction data structure</link>
451 indicates that the instruction will
452 <emphasis>not perform acquisition</emphasis> on a
453 channel, but will <emphasis>configure</emphasis> that channel.
455 <link linkend="ref-macro-CR-PACK">chanspec</link> field in the
456 <link linkend="insn-data-structure-chanspec">comedi_insn</link>
457 data structure, contains the channel to be configured.
458 The zeroth element of the data array
459 is always an id that specifies
460 what type of configuration instruction is being performed. The
461 meaning of rest of the elements in the data array
462 depend on the configuration instruction id.
464 possible ids are summarised in the table below, along with the
465 meanings of the data array elements for
466 each type of configuration instruction.
470 <tgroup cols='4' align='left'>
471 <colspec colwidth='4*' />
472 <colspec colwidth='4*' />
473 <colspec colwidth='1*' />
474 <colspec colwidth='4*' />
477 <entry>data[0]</entry>
478 <entry>Description</entry>
479 <entry>n (number of elements in data array)</entry>
480 <entry>Meanings of data[1], ..., data[n-1]</entry>
485 <entry><constant>INSN_CONFIG_DIO_INPUT</constant></entry>
487 Configure a dio line as input. It is easier to use comedi_dio_config() than
488 to use this configuration instruction directly.
496 <entry><constant>INSN_CONFIG_DIO_OUTPUT</constant></entry>
498 Configure a dio line as output. It is easier to use comedi_dio_config() than
499 to use this configuration instruction directly.
507 <entry><constant>INSN_CONFIG_ALT_SOURCE</constant></entry>
509 Select an alternate input source. This instruction is
510 used by comedi_calibrate to configure analog input channels
511 which can be redirected to read internal calibration
512 references. You need to set the CR_ALT_SOURCE flag in the chanspec
513 when reading to actually read from the configured alternate input source.
514 If you are using comedi_data_read(), then the channel parameter can be
515 bitwise or'd with the CR_ALT_SOURCE flag.
519 data[1]: alternate input source.
523 <entry><constant>INSN_CONFIG_BLOCK_SIZE</constant></entry>
525 Specify block size for asynchonous command data.
526 When performing streaming input, many boards accumulate
527 samples in internal fifos and transfer them to the host
528 computer in chunks. Some drivers let you suggest a size in bytes for how big a
529 the chunks should be. This lets you tune how often the host computer is
530 interrupted with a new chunk of data.
534 data[1]: The desired block size in bytes. The actual configured block size is
535 writen back to data[1] after the instruction completes. This instruction
536 acts purely as a query if the block size is set to zero.
540 <entry><constant>INSN_CONFIG_DIO_QUERY</constant></entry>
542 Queries the configuration of a dio line to see if it is an input or output.
543 It is probably easier to use the comedilib function comedi_dio_get_config()
544 than to use this instruction directly.
548 data[1]: The instruction sets this element to either
549 <constant>COMEDI_INPUT</constant> or <constant>COMEDI_OUTPUT</constant>.
557 See the comedilib demo program demo/choose_clock.c for an example
558 of using a configuration instruction.
564 <section id="inttrigconfiguration">
566 Instruction for internal triggering
569 This special instruction has
570 <anchor id="insn-inttrig"/><constant>INSN_INTTRIG</constant> as the
571 <link linkend="insn-data-structure-insn">insn</link> flag in its
572 <link linkend="insn-data-structure">instruction data structure</link>.
573 Its execution causes an
574 <link linkend="trig-int-start-src">internal triggering event</link>. This
575 event can, for example, cause the device driver to start a conversion,
576 or to stop an ongoing acquisition. The exact meaning of the triggering
577 depends on the card and its particular driver.
581 <link linkend="insn-data-structure-data">data</link>[0] field of the
582 <constant>INSN_INTTRIG</constant> instruction is reserved for future use,
583 and should be set to <literal>0</literal>.
589 <section id="commandsstreaming">
591 Commands for streaming acquisition
595 The most powerful &comedi; acquisition primitive is the
596 <emphasis>command</emphasis>. It's powerful because, with one single
597 command, the programmer launches:
602 a possibly infinite <emphasis>sequence of acquisitions</emphasis>,
608 accompanied with various <emphasis>callback</emphasis> functionalities
609 (DMA, interrupts, driver-specific callback functions),
615 for <emphasis>any number of channels</emphasis>,
621 with an <emphasis>arbitrary order</emphasis> of channels in each scan
622 (possibly even with repeated channels per scan),
628 and with various scan <emphasis>triggering sources</emphasis>,
629 external (i.e., hardware pulses) as well as internal (i.e., pulses
630 generated on the DAQ card itself, or generated by a
631 <link linkend="inttrigconfiguration">software trigger instruction</link>).
636 This command functionality exists in the &comedi; API, because various
637 data acquisition devices have the capability to perform this kind of
638 complex acquisition, driven by either on-board or
639 off-board timers and triggers.
643 A command specifies a particular data
644 <link linkend="fig-acq-seq">acquisition sequence</link>, which
645 consists of a number of <emphasis>scans</emphasis>, and each scan is
646 comprised of a number of <emphasis>conversions</emphasis>, which
647 usually corresponds to a single A/D or D/A conversion. So, for
648 example, a scan could consist of sampling channels 1, 2 and 3 of a
649 particular device, and this scan should be repeated 1000 times, at
650 intervals of 1 millisecond apart.
653 The command function is complementary to the
654 <link linkend="instructionsconfiguration">configuration instruction</link>
655 function: each channel in the command's
656 <link linkend="command-data-struct-chanlist">chanlist</link>
657 should first be configured by an appropriate instruction.
661 <section id="executingcommand">
667 A command is executed by the following &comedi; function:
669 <funcsynopsis><funcprototype>
670 <funcdef>int <link linkend="func-ref-comedi-command"><function>comedi_command</function></link></funcdef>
671 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
672 <paramdef><link linkend="ref-type-comedi-cmd">comedi_cmd</link> *<parameter>command</parameter></paramdef>
673 </funcprototype></funcsynopsis>
675 The following sections explain the meaning of the
676 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data structure.
677 Filling in this structure can be quite complicated, and
678 requires good knowledge about the exact functionalities of the DAQ
679 card. So, before launching a command, the application programmer is
680 adviced to check whether this complex command data structure can be
681 successfully parsed. So, the typical sequence for executing a command is
682 to first send the command through
683 <link linkend="func-ref-comedi-command-test">comedi_command_test()</link>
684 once or twice. The test will check that the command is valid for the
685 particular device, and often makes some adjustments to the command
686 arguments, which can then be read back by the user to see the actual
690 A &comedi; program can find out on-line what the command capabilities
691 of a specific device are, by means of the
692 <link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask()</link>
699 <section id="comedicmdstructure">
701 The command data structure
704 The command executes according to the information about the requested
705 acquisition, which is stored in the
706 <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
707 <anchor id="command-data-struct"/>data structure:
709 typedef struct comedi_cmd_struct comedi_cmd;
711 struct comedi_cmd_struct {
712 unsigned int subdev; // which subdevice to sample
713 unsigned int <anchor id="command-data-struct-flags"/>flags; // encode some configuration possibilities
714 // of the command execution; e.g.,
715 // whether a callback routine is to be
716 // called at the end of the command
718 unsigned int <anchor id="command-data-struct-start-src"/>start_src; // event to make the acquisition start
719 unsigned int <anchor id="command-data-struct-start-arg"/>start_arg; // parameters that influence this start
721 unsigned int <anchor id="command-data-struct-scan-begin-src"/>scan_begin_src; // event to make a particular scan start
722 unsigned int <anchor id="command-data-struct-scan-begin-arg"/>scan_begin_arg; // parameters that influence this start`
724 unsigned int <anchor id="command-data-struct-convert-src"/>convert_src; // event to make a particular conversion start
725 unsigned int <anchor id="command-data-struct-convert-arg"/>convert_arg; // parameters that influence this start
727 unsigned int <anchor id="command-data-struct-scan-end-src"/>scan_end_src; // event to make a particular scan terminate
728 unsigned int <anchor id="command-data-struct-scan-end-arg"/>scan_end_arg; // parameters that influence this termination
730 unsigned int <anchor id="command-data-struct-stop-src"/>stop_src; // what make the acquisition terminate
731 unsigned int <anchor id="command-data-struct-stop-arg"/>stop_arg; // parameters that influence this termination
733 unsigned int <anchor id="command-data-struct-chanlist"/>*chanlist; // pointer to list of channels to be sampled
734 unsigned int <anchor id="command-data-struct-chanlist-len"/>chanlist_len; // number of channels to be sampled
736 sampl_t *<anchor id="command-data-struct-data"/>data; // address of buffer
737 unsigned int <anchor id="command-data-struct-data-len"/>data_len; // number of samples to acquire
740 The start and end of the whole command acquisition sequence, and the
741 start and end of each scan and of each conversion, is triggered by a
742 so-called <emphasis>event</emphasis>. More on these in
743 <xref linkend="comedicmdsources"/>.
747 The <parameter class="function">subdev</parameter> member of the
748 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> structure is
749 the index of the subdevice the command is intended for. The
750 <link linkend="func-ref-comedi-find-subdevice-by-type">comedi_find_subdevice_by_type()</link>
751 function can be useful in discovering the index of your desired subdevice.
755 The <link linkend="command-data-struct-chanlist">chanlist</link>
757 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
758 structure should point to an array whose number of elements is
760 <link linkend="command-data-struct-chanlist-len">chanlist_len</link>
761 (this will generally be the same as the
762 <link linkend="command-data-struct-scan-end-arg">scan_end_arg</link>).
764 <link linkend="command-data-struct-chanlist">chanlist</link>
765 specifies the sequence of channels and gains (and analog references)
766 that should be stepped through for each scan. The elements of the
767 <link linkend="command-data-struct-chanlist">chanlist</link> array should be
768 initialized by <quote>packing</quote> the channel, range and reference
769 information together with the
770 <parameter class="function">
771 <link linkend="ref-macro-CR-PACK">CR_PACK()</link>
777 The <link linkend="command-data-struct-data">data</link> and
778 <link linkend="command-data-struct-data-len">data_len</link>
779 members can be safely ignored when issueing commands from a user-space
780 program. They only have meaning when a command is sent from a
781 <emphasis role="strong">kernel</emphasis> module using the
782 <systemitem>kcomedilib</systemitem> interface, in which case they specify
783 the buffer where the driver should write/read its data to/from.
787 The final member of the
788 <link linkend="command-data-struct">comedi_cmd</link> structure is the
789 <link linkend="command-data-struct-flags">flags</link> field,
790 i.e., bits in a word that can be bitwise-or'd together. The meaning of
791 these bits are explained in a
792 <link linkend="source.flags.anchor">later section</link>.
798 <section id="comedicmdsources">
800 The command trigger events
801 <anchor id="source.trigger.anchor"/>
804 A command is a very versatile acquisition instruction, in the sense
805 that it offers lots of possibilities to let different hardware and
806 software sources determine when acquisitions are started, performed,
807 and stopped. More specifically, the command
808 <link linkend="command-data-struct">data structure</link>
809 has <emphasis>five</emphasis> types of events: start the
810 <link linkend="acquisitionterminology">acquisition</link>,
811 start a <link linkend="scan">scan</link>, start a
812 <link linkend="conversion">conversion</link>, stop a scan, and stop
813 the acquisition. Each event can be given its own
814 <emphasis><link linkend="source.trigger.anchor">source</link></emphasis>
815 (the <parameter class="function">*_src</parameter> members in the
816 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
817 structure). And each event source can have a corresponding
818 argument (the <parameter class="function">*_arg</parameter> members of
819 the <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
820 structure) whose meaning depends on the type of source trigger.
821 For example, to specify an external digital line <quote>3</quote> as a
822 source (in general, <emphasis>any</emphasis> of the five event
823 sources), you would use
824 <parameter>src</parameter>=<link linkend="trig-ext"><constant>TRIG_EXT</constant></link>
825 and <parameter>arg</parameter>=<literal>3</literal>.
828 The following paragraphs discuss in somewhat more detail the trigger
829 event sources(<parameter class="function">*_src</parameter>), and the
830 corresponding arguments (<parameter class="function">*_arg</parameter>).
833 The start of an acquisition is controlled by the
834 <link linkend="command-data-struct-start-src">start_src</link> events.
835 The available options are:
840 <anchor id="trig-now-start-src"/>
841 <constant>TRIG_NOW</constant>: the
842 <link linkend="command-data-struct-start-src">start_src</link>
844 <link linkend="command-data-struct-start-arg">start_arg</link>
845 nanoseconds after the
846 <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
847 is called. Currently, only
848 <link linkend="command-data-struct-start-arg">start_arg</link>=0 is
855 <anchor id="trig-follow-start-src"/>
856 <constant>TRIG_FOLLOW</constant>: (For an output device.) The
857 <link linkend="command-data-struct-start-src">start_src</link>
858 event occurs when data is written to the buffer.
864 <anchor id="trig-ext-start-src"/>
865 <constant>TRIG_EXT</constant>: the start event occurs when an
866 external trigger signal occurs; e.g., a rising edge of a digital line.
867 <link linkend="command-data-struct-start-arg">start_arg</link>
868 chooses the particular digital line.
874 <anchor id="trig-int-start-src"/>
875 <constant>TRIG_INT</constant>: the start event occurs on a &comedi;
876 internal signal, which is typically caused by an
877 <link linkend="insn-inttrig"><constant>INSN_INTTRIG</constant>
883 The start of the beginning of each
884 <link linkend="scan">scan</link> is controlled by the
885 <link linkend="command-data-struct-scan-begin-src">scan_begin</link> events.
886 The available options are:
891 <anchor id="trig-timer-start-scan"/>
892 <constant>TRIG_TIMER</constant>:
893 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
894 events occur periodically. The time between
895 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
897 <link linkend="command-data-struct-convert-arg">convert_arg</link>
904 <anchor id="trig-follow-start-scan"/>
905 <constant>TRIG_FOLLOW</constant>: The
906 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
907 event occurs immediately after a
908 <link linkend="command-data-struct-scan-end-src">scan_end</link>
915 <anchor id="trig-ext-start-scan"/>
916 <constant>TRIG_EXT</constant>: the
917 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
918 event occurs when an external trigger signal
919 occurs; e.g., a rising edge of a digital line.
920 <link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link>
921 chooses the particular digital line.
927 <link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link>
928 used here may not be supported exactly by the device, but it
929 will be adjusted to the nearest supported value by
930 <link linkend="func-ref-comedi-command-test">comedi_command_test()</link>.
933 The timing between each sample in a
934 <link linkend="scan">scan</link> is controlled by the
935 <link linkend="command-data-struct-convert-src">convert_*</link>
941 <anchor id="convert-trig-timer"/>
942 <anchor id="trig-timer"/>
943 <constant>TRIG_TIMER</constant>: the conversion events occur periodically.
944 The time between convert events is
945 <link linkend="command-data-struct-convert-arg">convert_arg</link>
952 <anchor id="convert-trig-ext"/>
953 <anchor id="trig-ext"/>
954 <constant>TRIG_EXT</constant>: the conversion events occur when an
955 external trigger signal occurs, e.g., a rising edge of a digital line.
956 <link linkend="command-data-struct-convert-arg">convert_arg</link>
957 chooses the particular digital line.
963 <anchor id="convert-trig-now"/>
964 <anchor id="trig-now"/>
965 <constant>TRIG_NOW</constant>: All conversion events in a
966 <link linkend="scan">scan</link> occur simultaneously.
971 The <emphasis>end</emphasis> of each scan is almost always specified
973 <link linkend="trig-count"><constant>TRIG_COUNT</constant></link>,
974 with the argument being the same as the number of channels in the
975 <link linkend="command-data-struct-chanlist">chanlist</link>. You
976 could probably find a device that allows something else, but it would
981 <link linkend="acquisitionterminology">acquisition</link> is
983 <link linkend="command-data-struct-stop-src">stop_src</link>
984 and <link linkend="command-data-struct-stop-arg">stop_arg</link>:
989 <anchor id="acquisition-end-trig-count"/>
990 <anchor id="trig-count"/>
991 <constant>TRIG_COUNT</constant>: stop the acquisition after
992 <link linkend="command-data-struct-stop-arg">stop_arg</link>
999 <anchor id="acquisition-end-trig-none"/>
1000 <anchor id="trig-none"/>
1001 <constant>TRIG_NONE</constant>: perform continuous acquisition,
1003 <link linkend="func-ref-comedi-cancel">comedi_cancel()</link>.
1006 Its argument is reserved and should be set to <literal>0</literal>.
1007 (<quote>Reserved</quote>
1008 means that unspecified things could happen if it is set to something
1009 else but <literal>0</literal>.)
1014 There are a couple of less usual or not yet implemented events:
1019 <anchor id="trig-time"/>
1020 <constant>TRIG_TIME</constant>:
1021 cause an event to occur at a particular time.
1024 (This event source is reserved for future use.)
1030 <anchor id="trigother-event"/>
1031 <constant>TRIG_OTHER</constant>: driver specific event trigger.
1034 This event can be useful as any of the trigger sources. Its exact
1035 meaning is driver specific, because it implements a feature that
1036 otherwise does not fit into the generic &comedi; command interface.
1037 Configuration of <constant>TRIG_OTHER</constant> features are done by
1038 <link linkend="instructionsconfiguration"><constant>INSN_CONFIG</constant></link>
1042 The argument is reserved and should be set to <literal>0</literal>.
1047 Not all event sources are applicable to all events. Supported
1048 trigger sources for specific events depend significantly on your
1049 particular device, and even more on the current state of its device
1051 <link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask()</link>
1052 function is useful for determining what trigger sources a subdevice
1059 <section id="comedicmdflags">
1062 <anchor id="source.flags.anchor"/>
1067 <link linkend="command-data-struct-flags">flags</link> field in the
1068 <link linkend="ref-type-comedi-cmd">command data structure</link>
1069 is used to specify some <quote>behaviour</quote> of the acquisitions in
1071 The meaning of the field is as follows:
1076 <anchor id="trig-rt"/>
1077 <constant>TRIG_RT</constant>: ask the driver to use a
1078 <emphasis role="strong">hard real-time</emphasis> interrupt handler.
1079 This will reduce latency in handling interrupts from your data
1081 hardware. It can be useful if you are sampling at high frequency, or
1082 if your hardware has a small onboard data buffer. You must have a
1083 real-time kernel (<ulink url="http://www.rtai.org">RTAI</ulink> or
1084 <ulink url="http://www.rtlinux-gpl.org/">RTLinux/GPL</ulink>)
1085 and must compile &comedi; with real-time support, or this flag will do
1092 <anchor id="trig-wake-eos"/>
1093 <constant>TRIG_WAKE_EOS</constant>:
1094 where <quote>EOS</quote> stands for <quote>End of Scan</quote>. Some
1095 drivers will change their behaviour when this flag is set, trying to
1096 transfer data at the end of every scan (instead of, for example,
1097 passing data in chunks whenever the board's hardware data buffer is
1098 half full). This flag may degrade a driver's performance at high
1099 frequencies, because the end of a scan is, in general, a much more
1100 frequent event than the filling up of the data buffer.
1106 <anchor id="trig-round-nearest"/>
1107 <constant>TRIG_ROUND_NEAREST</constant>:
1108 round to nearest supported timing period, the default.
1109 This flag (as well as the following three), indicates how timing
1110 arguments should be rounded if the hardware cannot achieve the exact
1117 <anchor id="trig-round-down"/>
1118 <constant>TRIG_ROUND_DOWN</constant>: round period down.
1124 <anchor id="trig-round-up"/>
1125 <constant>TRIG_ROUND_UP</constant>: round period up.
1131 <anchor id="trig-round-up-next"/>
1132 <constant>TRIG_ROUND_UP_NEXT</constant>:
1133 this one doesn't do anything, and I don't know what it was intended
1140 <anchor id="trig-dither"/>
1141 <constant>TRIG_DITHER</constant>: enable dithering? Dithering is
1142 a software technique to smooth the influence of discretization
1143 <quote>noise</quote>.
1149 <anchor id="trig-deglitch"/>
1150 <constant>TRIG_DEGLITCH</constant>: enable deglitching?
1151 Another <quote>noise</quote> smoothing technique.
1157 <anchor id="trig-write"/>
1158 <constant>TRIG_WRITE</constant>:
1159 write to bidirectional devices. Could be useful, in principle, if
1160 someone wrote a driver that supported commands for a digital I/O
1161 device that could do either input or output.
1167 <anchor id="trig-bogus"/>
1168 <constant>TRIG_BOGUS</constant>: do the motions?
1174 <anchor id="trig-other"/>
1175 <constant>TRIG_CONFIG</constant>: perform configuration, not triggering.
1176 This is a legacy of the deprecated
1177 <link linkend="ref-type-comedi-cmd">comedi_trig_struct</link>
1178 data structure, and has no function at present.
1192 If you wish to aquire accurate waveforms, it is vital that you use an
1193 anti-alias filter. An anti-alias filter is a low-pass filter used to
1194 remove all frequencies higher than the Nyquist frequency (half your sampling rate)
1195 from your analog input signal
1196 before you convert it to digital. If you fail to filter your input signal,
1197 any high frequency components in the original analog signal will create
1198 artifacts in your recorded digital waveform that cannot be corrected.
1201 For example, suppose you are sampling an analog input channel at a rate of
1202 1000 Hz. If you were to apply a 900 Hz sine wave to the input, you
1203 would find that your
1204 sampling rate is not high enough to faithfully record the 900 Hz input,
1205 since it is above your Nyquist frequency of 500 Hz. Instead, what you
1206 will see in your recorded digital waveform is a 100 Hz sine wave! If you
1207 don't use an anti-alias filter, it is impossible to tell whether the 100
1208 Hz sine wave you see in your digital signal was really produced by a
1209 100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz
1213 In practice, the cutoff frequency for the anti-alias filter is usually
1214 set 10% to 20% below the Nyquist frequency due to fact that real filters
1215 do not have infinitely sharp cutoffs.
1221 <section id="slowlyvarying">
1223 Slowly-varying inputs
1227 Sometimes, your input channels change slowly enough that
1228 you are able to average many successive input values to get a
1229 more accurate measurement of the actual value. In general,
1230 the more samples you average, the better your estimate
1231 gets, roughly by a factor of sqrt(number_of_samples).
1232 Obviously, there are limitations to this:
1239 you are ultimately limited by <quote>Spurious Free Dynamic
1240 Range</quote>. This SFDR is one of the popular measures to quantify how
1241 much noise a signal carries. If you take a Fourier transform of your
1242 signal, you will see several <quote>peaks</quote> in the transform: one
1243 or more of the fundamental harmonics of the measured signal, and lots
1244 of little <quote>peaks</quote> (called <quote>spurs</quote>) caused by
1245 noise. The SFDR is then the difference between the amplitude of the
1246 fundamental harmonic and of the largest spur (at frequencies below
1247 half of the Nyquist frequency of the DAQ sampler!).
1253 you need to have <emphasis>some</emphasis> noise on the input channel,
1254 otherwise you will be averaging the same number <literal>N</literal>
1255 times. (Of course, this only holds if the noise is large enough to
1256 cause at least a one-bit discretization.)
1262 the more noise you have, the greater your SFDR, but it
1263 takes many more samples to compensate for the increased
1270 if you feel the need to average samples for, for example, two seconds,
1271 your signal will need to be <emphasis>very</emphasis> slowly-varying,
1272 i.e., not varying more than your target uncertainty for the entire two
1280 As you might have guessed, the &comedi; library has functions
1281 to help you in your quest to accurately measure slowly varying
1284 <funcsynopsis><funcprototype>
1285 <funcdef>int <link linkend="func-ref-comedi-sv-init"><function>comedi_sv_init</function></link></funcdef>
1286 <paramdef><link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> *<parameter>sv</parameter></paramdef>
1287 <paramdef><link linkend="ref-type-comedi-t">comedi_t</link> *<parameter>device</parameter></paramdef>
1288 <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
1289 <paramdef>unsigned int <parameter>channel</parameter></paramdef>
1290 </funcprototype></funcsynopsis>
1292 This function initializes the
1293 <link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> data structure, used
1294 to do the averaging acquisition:
1296 struct comedi_sv_struct {
1297 <link linkend="ref-type-comedi-t">comedi_t</link> *dev;
1298 unsigned int subdevice;
1305 /* number of measurements to average (for analog inputs) */
1312 The actual acquisition is done with the function
1314 <funcsynopsis><funcprototype>
1315 <funcdef>int <link linkend="func-ref-comedi-sv-measure"><function>comedi_sv_measure</function></link></funcdef>
1316 <paramdef><link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> *<parameter>sv</parameter></paramdef>
1317 <paramdef>double *<parameter>data</parameter></paramdef>
1318 </funcprototype></funcsynopsis>
1320 The number of samples over which the
1321 <function>comedi_sv_measure()</function> averages is limited by the
1322 implementation (currently the limit is 100 samples).
1326 One typical use for this function is the measurement of thermocouple
1328 And the &comedi; self-calibration utility also uses these functions.
1329 On some hardware, it is possible to tell it to measure an
1330 internal stable voltage reference, which is typically going
1331 to be very slowly varying; on the kilosecond time scale
1332 or more. So, it is reasonable to measure millions of samples,
1333 to get a very accurate measurement of the A/D converter output
1334 value that corresponds to the voltage reference. Sometimes,
1335 however, this is overkill, since there is no need to
1336 perform a part-per-million calibration to a standard that
1337 is only accurate to a part-per-thousand.
1342 <section id="experimentalfunctionality">
1344 Experimental functionality
1348 The following subsections document functionality that has not yet
1349 matured. Most of this functionality has even not been implemented yet
1350 in any single device driver. This information is included here, in
1351 order to stimulate discussion about their API, and to encourage
1352 pioneering implementations.
1355 <section id="digitalinputcombining">
1357 Digital input combining machines
1361 (<emphasis role="strong">Status: experimental (i.e., no driver implements
1362 this yet)</emphasis>)
1365 When one or several digital inputs are used to modify an output
1366 value, either an accumulator or a single digital line or bit,
1367 a bitfield structure is typically used in the &comedi; interface.
1368 The digital inputs have two properties, <quote>sensitive</quote> inputs
1369 and <quote>modifier</quote> inputs. Edge transitions on sensitive
1370 inputs cause changes in the output signal, whereas modifier inputs
1371 change the effect of edge transitions on sensitive inputs. Note that
1372 inputs can be both modifier inputs and sensitive inputs.
1376 For simplification purposes, it is assumed that multiple digital
1377 inputs do not change simultaneously.
1381 The combined state of the modifier inputs determine a modifier
1382 state. For each combination of modifier state and sensitive
1383 input, there is a set of bits that determine the effect on the
1384 output value due to positive or negative transitions of the
1385 sensitive input. For each transition direction, there are two
1386 bits defined as follows:
1388 <variablelist spacing="compact">
1391 <listitem>transition is ignored.</listitem>
1395 <listitem>accumulator is incremented, or output is set.</listitem>
1399 <listitem>accumulator is decremented, or output is cleared.</listitem>
1403 <listitem>reserved.</listitem>
1407 For example, a simple digital follower is specified by the bit
1408 pattern 01 10, because it sets the output on positive transitions
1409 of the input, and clears the output on negative transitions. A
1410 digital inverter is similarily 10 01. These systems have only
1411 one sensitive input.
1415 As another example, a simple up counter, which increments on
1416 positive transitions of one input, is specified by 01 00. This
1417 system has only one sensitive input.
1421 When multiple digital inputs are used, the inputs are divided
1422 into two types, inputs which cause changes in the accumulator, and
1423 those that only modify the meaning of transitions on other inputs.
1424 Modifier inputs do not require bitfields, but there needs to be
1425 a bitfield of length 4*(2^(N-1)) for each edge sensitive input,
1426 where N is the total number of inputs. Since N is usually 2 or
1427 3, with only one edge sensitive input, the scaling issues are
1434 <section id="analogconversion">
1436 Analog filtering configuration
1440 <emphasis role="strong">(Status: design (i.e., no driver implements
1441 this yet).)</emphasis>
1445 The <link linkend="insn-data-structure-insn">insn</link> field of the
1446 <link linkend="insn-data-structure">instruction data structure</link>
1447 has not been assigned yet.
1450 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1451 of the <link linkend="insn-data-structure">instruction data
1452 structure</link> is ignored.
1456 Some devices have the capability to add white noise (dithering) to
1457 analog input measurement. This additional noise can then be averaged
1458 out, to get a more accurate measurement of the input signal. It
1459 should not be assumed that channels can be separately configured.
1460 A simple design can use 1 bit to turn this feature on/off.
1464 Some devices have the capability of changing the glitch characteristics
1465 of analog output subsytems. The default (off) case should be where
1466 the average settling time is lowest. A simple design can use 1 bit
1467 to turn this feature on/off.
1471 Some devices have a configurable analog filters as part of the analog
1472 input stage. A simple design can use 1 bit to enable/disable the
1473 filter. Default is disabled, i.e., the filter being bypassed, or if
1474 the choice is between two filters, the filter with the largest
1479 <section id="waveformgeneration">
1481 Analog Output Waveform Generation
1485 <emphasis role="strong">(Status: design (i.e., no driver implements
1486 this yet).)</emphasis>
1489 The <link linkend="insn-data-structure-insn">insn</link> field of the
1490 <link linkend="insn-data-structure">instruction data structure</link>
1491 has not been assigned yet.
1494 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1495 of the <link linkend="insn-data-structure">instruction data
1496 structure</link> is ignored.
1500 Some devices have the ability to cyclicly loop through samples kept in
1501 an on-board analog output FIFO. This config should allow the user to
1502 enable/disable this mode.
1506 This config should allow the user to configure the number of samples
1507 to loop through. It may be necessary to configure the channels used.
1512 <section id="extendedtriggering">
1517 <emphasis role="strong">(Status: alpha.)</emphasis>
1521 The <link linkend="insn-data-structure-insn">insn</link> field of the
1522 <link linkend="insn-data-structure">instruction data structure</link>
1523 has not been assigned yet.
1526 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1527 of the <link linkend="insn-data-structure">instruction data
1528 structure</link> is ignored.
1532 This section covers common information for all extended
1533 triggering configuration, and doesn't describe a particular
1534 type of extended trigger.
1538 Extended triggering is used to configure triggering engines that
1539 do not fit into commands. In a typical programming sequence, the
1540 application will use
1541 <link linkend="instructionsconfiguration">configuration instructions</link>
1542 to configure an extended trigger, and a
1543 <link linkend="commandsstreaming">command</link>,
1545 <link linkend="trig-other"><constant>TRIG_OTHER</constant></link>
1546 as one of the trigger sources.
1550 Extended trigger configuration should be designed in such a way
1551 that the user can probe for valid parameters, similar to how
1552 command testing works. An extended trigger configuration instruction
1553 should not configure the hardware directly, rather, the configuration
1554 should be saved until the subsequent command is issued. This
1555 allows more flexibility for future interface changes.
1559 It has not been decided whether the configuration stage should return a
1560 token that is then used as the trigger argument in the command.
1561 Using tokens is one method to satisfy the problem that extended
1562 trigger configurations may have subtle compatiblity issues with
1563 other trigger sources/arguments that can only be determined at
1564 command test time. Passing all stages of a command test should
1565 only be allowed with a properly configured extended trigger.
1569 Extended triggers must use
1570 <link linkend="insn-data-structure-data">data[1]</link> as flags. The
1571 upper 16 bits are reserved and used only for flags that are common to
1572 all extended triggers. The lower 16 bits may be defined by the
1573 particular type of extended trigger.
1577 Various types of extended triggers must use
1578 <link linkend="insn-data-structure-data">data[1]</link> to know which
1579 event the extended trigger will be assigned to in the command
1580 structure. The possible values are an OR'd mask of the following:
1586 <constant>COMEDI_EV_START</constant>
1591 <constant>COMEDI_EV_SCAN_BEGIN</constant>
1596 <constant>COMEDI_EV_CONVERT</constant>
1601 <constant>COMEDI_EV_SCAN_END</constant>
1606 <constant>COMEDI_EV_STOP</constant>
1613 <section id="analogtriggering">
1618 <emphasis role="strong">
1619 (Status: alpha. The <function>ni_mio_common.c</function> driver
1620 implements this feature.)
1625 The <link linkend="insn-data-structure-insn">insn</link> field of the
1626 <link linkend="insn-data-structure">instruction data structure</link>
1627 has not been assigned yet.
1630 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1631 of the <link linkend="insn-data-structure">instruction data
1632 structure</link> is ignored.
1636 The <link linkend="insn-data-structure-data">data</link> field
1637 of the <link linkend="insn-data-structure">instruction data
1638 structure</link> is used as follows:
1639 <variablelist spacing="compact">
1641 <term>data[1]</term>
1642 <listitem>trigger and combining machine configuration.</listitem>
1645 <term>data[2]</term>
1646 <listitem>analog triggering signal chanspec.</listitem>
1649 <term>data[3]</term>
1650 <listitem>primary analog level.</listitem>
1653 <term>data[4]</term>
1654 <listitem>secondary analog level.</listitem>
1659 Analog triggering is described by a digital combining machine that
1660 has two sensitive digital inputs. The sensitive digital inputs are
1661 generated by configurable analog comparators. The analog comparators
1662 generate a digital 1 when the analog triggering signal is greater
1663 than the comparator level. The digital inputs are not modifier
1664 inputs. Note, however, there is an effective modifier due to the
1665 restriction that the primary analog comparator level must be less
1666 than the secondary analog comparator level.
1670 If only one analog comparator signal is used, the combining machine
1671 for the secondary input should be set to ignored, and the secondary
1672 analog level should be set to <literal>0</literal>.
1676 The interpretation of the chanspec and voltage levels is device
1677 dependent, but should correspond to similar values of the analog
1678 input subdevice, if possible.
1682 Notes: Reading range information is not addressed. This makes it
1683 difficult to convert comparator voltages to data values.
1687 Possible extensions: A parameter that specifies the necessary time
1688 that the set condition has to be true before the trigger is generated.
1689 A parameter that specifies the necessary time that the reset condition
1690 has to be true before the state machine is reset.
1695 <section id="bitfieldmatching">
1697 Bitfield Pattern Matching Extended Trigger
1700 <emphasis role="strong">
1701 (Status: design. No driver implements this feature yet.)
1706 The <link linkend="insn-data-structure-insn">insn</link> field of the
1707 <link linkend="insn-data-structure">instruction data structure</link>
1708 has not been assigned yet.
1711 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1712 of the <link linkend="insn-data-structure">instruction data
1713 structure</link> is ignored.
1717 The <link linkend="insn-data-structure-data">data</link> field
1718 of the <link linkend="insn-data-structure">instruction data
1719 structure</link> is used as follows:
1721 <variablelist spacing="compact">
1723 <term>data[1]</term>
1724 <listitem>trigger flags.</listitem>
1727 <term>data[2]</term>
1728 <listitem>mask.</listitem>
1731 <term>data[3]</term>
1732 <listitem>pattern.</listitem>
1737 The pattern matching trigger issues a trigger when all of a specifed
1738 set of input lines match a specified pattern. If the device allows,
1739 the input lines should correspond to the input lines of a digital input
1740 subdevice, however, this will necessarily be device dependent. Each
1741 possible digital line that can be matched is assigned a bit in the
1742 mask and pattern. A bit set in the mask indicates that the
1743 input line must match the corresponding bit in the pattern.
1744 A bit cleared in the mask indicates that the input line is ignored.
1748 Notes: This only allows 32 bits in the pattern/mask, which may be
1749 too few. Devices may support selecting different sets of lines from
1750 which to match a pattern.
1754 Discovery: The number of bits can be discovered by setting the mask
1755 to all 1's. The driver must modify this value and return
1756 <constant>-EAGAIN</constant>.
1761 <section id="countertimer">
1763 Counter configuration
1766 <emphasis role="strong">
1767 (Status: design. No driver implements this feature yet.)
1772 The <link linkend="insn-data-structure-insn">insn</link> field of the
1773 <link linkend="insn-data-structure">instruction data structure</link>
1774 has not been assigned yet.
1777 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1778 of the <link linkend="insn-data-structure">instruction data
1779 structure</link> is used to specify which counter to use. (I.e., the
1780 counter is a &comedi; channel.)
1784 The <link linkend="insn-data-structure-data">data</link> field
1785 of the <link linkend="insn-data-structure">instruction data
1786 structure</link> is used as follows:
1788 <variablelist spacing="compact">
1790 <term>data[1]</term>
1791 <listitem>trigger configuration.</listitem>
1794 <term>data[2]</term>
1795 <listitem>primary input chanspec.</listitem>
1798 <term>data[3]</term>
1799 <listitem>primary combining machine configuration.</listitem>
1802 <term>data[4]</term>
1803 <listitem>secondary input chanspec.</listitem>
1806 <term>data[5]</term>
1807 <listitem>secondary combining machine configuration.</listitem>
1810 <term>data[6]</term>
1811 <listitem>latch configuration.</listitem>
1816 Note that this configuration is only useful if the counting has to be
1817 done in <emphasis>software</emphasis>. Many cards offer configurable
1818 counters in hardware; e.g., general purpose timer cards can be
1819 configured to act as pulse generators, frequency counters, timers,
1823 Counters can be operated either in synchronous mode (using
1824 <link linkend="comediinsnstructure"><constant>INSN_READ</constant></link>)
1825 or asynchronous mode (using
1826 <link linkend="commandsstreaming">commands</link>), similar to analog
1828 The input signal for both modes is the accumulator.
1829 Commands on counter subdevices are almost always specified using
1830 <link linkend="command-data-struct-scan-begin-src">scan_begin_src</link>
1831 = <link linkend="trigother-event"><constant>TRIG_OTHER</constant></link>,
1832 with the counter configuration also serving as the extended configuration for
1833 the scan begin source.
1837 Counters are made up of an accumulator and a combining machine that
1838 determines when the accumulator should be incremented or decremented
1839 based on the values of the input signals. The combining machine
1840 optionally determines when the accumulator should be latched and
1841 put into a buffer. This feature is used in asynchronous mode.
1845 Note: How to access multiple pieces of data acquired at each event?
1850 <section id="auxcounter">
1852 One source plus auxiliary counter configuration
1855 <emphasis role="strong">
1856 (Status: design. No driver implements this feature yet.)
1861 The <link linkend="insn-data-structure-insn">insn</link> field of the
1862 <link linkend="insn-data-structure">instruction data structure</link>
1863 has not been assigned yet.
1866 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1867 of the <link linkend="insn-data-structure">instruction data
1868 structure</link> is used to …
1872 The <link linkend="insn-data-structure-data">data</link> field
1873 of the <link linkend="insn-data-structure">instruction data
1874 structure</link> is used as follows:
1878 <variablelist spacing="compact">
1880 <term>data[1]</term>
1882 is flags, including the flags for the command triggering
1883 configuration. If a command is not subsequently issued on the
1884 subdevice, the command triggering portion of the flags are ignored.
1888 <term>data[2]</term>
1890 determines the mode of operation. The mode of operation
1891 is actually a bitfield that encodes what to do for various
1892 transitions of the source signals.
1896 <term>data[3]</term>
1897 <term>data[4]</term>
1899 determine the primary source for the counter, similar to the
1900 <link linkend="command-data-struct-scan-begin-src">_src</link> and the
1901 <link linkend="command-data-struct-scan-begin-arg">_arg</link> fields
1903 <link linkend="command-data-struct">command data structure</link>.
1910 Notes: How to specify which events cause a latch and push, and what
1918 National instruments RTSI trigger bus
1921 A number of NI boards support the RTSI (Real Time System Integration) bus.
1922 It's primary use is to synchronize multiple DAQ cards.
1923 On PXI boards, the RTSI lines correspond to the PXI trigger lines 0 to 7. PCI
1924 boards use cables to connect to their RTSI ports.
1925 The RTSI bus consists of 8 digital signal lines numbered 0 to 7 that are bi-directional.
1926 Each of these signal lines
1927 can be configured as an input or output, and the signal appearing on the output
1928 of each line can be configured to one of several internal board timing signals
1929 (although on older boards RTSI line 7 can only be used for the clock signal).
1930 The ni_pcimio, ni_atmio, and ni_mio_cs drivers expose the RTSI bus
1931 as a digital I/O subdevice (subdevice number 10).
1934 The functions comedi_dio_config() and comedi_dio_get_config() can be used on
1935 the RTSI subdevice to
1936 set/query the direction (input or output) of each of the RTSI lines individually.
1939 The subdevice also supports the
1940 <constant>INSN_CONFIG_SET_CLOCK_SRC</constant> and
1941 <constant>INSN_CONFIG_GET_CLOCK_SRC</constant> configuration
1942 instructions, which can be
1943 used to configure/query what source the board uses to synchronize its
1944 master clock to. The various possibilities are defined in the comedi.h
1948 <tgroup cols='2' align='left'>
1951 <entry>Clock Source</entry>
1952 <entry>Description</entry>
1957 <entry><constant>NI_MIO_INTERNAL_CLOCK</constant></entry>
1959 Use the board's internal oscillator.
1963 <entry><constant>NI_MIO_RTSI_CLOCK</constant></entry>
1965 Use the RTSI line 7 as the master clock. This source is
1966 only supported on pre-m-series boards. The newer m-series boards
1967 use NI_MIO_PLL_RTSI_CLOCK() instead.
1971 <entry><constant>NI_MIO_PLL_PXI_STAR_TRIGGER_CLOCK</constant></entry>
1973 Only available for newer m-series PXI boards. Synchronizes the board's
1974 phased-locked loop (which runs at 80MHz) to the PXI star trigger
1979 <entry><constant>NI_MIO_PLL_PXI10_CLOCK</constant></entry>
1981 Only available for newer m-series PXI boards.
1982 Synchronizes the board's
1983 phased-locked loop (which runs at 80MHz) to the 10 MHz PXI backplane
1989 <function>NI_MIO_PLL_RTSI_CLOCK<parameter>n</parameter></function>
1992 Only available for newer m-series boards.
1993 The function returns a clock source which will cause the board's
1994 phased-locked loop (which runs at 80MHz) to syncronize to the RTSI
1995 line specified in the function argument.
2003 For all clock sources except <constant>NI_MIO_INTERNAL_CLOCK</constant>
2004 and <constant>NI_MIO_PLL_PXI10_CLOCK</constant>,
2005 you should pass the period of the clock your are feeding to the board when
2006 using <constant>INSN_CONFIG_SET_CLOCK_SRC</constant>.
2009 Finally, the configuration instructions
2010 <constant>INSN_CONFIG_SET_ROUTING</constant> and
2011 <constant>INSN_CONFIG_GET_ROUTING</constant>
2012 can be used to select/query which internal signal
2013 will appear on a given RTSI output line. The header file comedi.h defines
2014 the following signal sources which can be routed to an RTSI line:
2018 <tgroup cols='2' align='left'>
2021 <entry>Signal Source</entry>
2022 <entry>Description</entry>
2027 <entry><constant>NI_RTSI_OUTPUT_ADR_START1</constant></entry>
2029 ADR_START1, an analog input start signal. See the NI's
2030 DAQ-STC Technical Reference Manual for more information.
2034 <entry><constant>NI_RTSI_OUTPUT_ADR_START2</constant></entry>
2036 ADR_START2, an analog input stop signal. See the NI's
2037 DAQ-STC Technical Reference Manual for more information.
2041 <entry><constant>NI_RTSI_OUTPUT_SCLKG</constant></entry>
2043 SCLKG, a sample clock signal. See the NI's
2044 DAQ-STC Technical Reference Manual for more information.
2048 <entry><constant>NI_RTSI_OUTPUT_DACUPDN</constant></entry>
2050 DACUPDN, a dac update signal. See the NI's
2051 DAQ-STC Technical Reference Manual for more information.
2055 <entry><constant>NI_RTSI_OUTPUT_DA_START1</constant></entry>
2057 DA_START1, an analog output start signal. See the NI's
2058 DAQ-STC Technical Reference Manual for more information.
2062 <entry><constant>NI_RTSI_OUTPUT_G_SRC0</constant></entry>
2064 G_SRC0, the source signal to general purpose counter 0. See the NI's
2065 DAQ-STC Technical Reference Manual for more information.
2069 <entry><constant>NI_RTSI_OUTPUT_G_GATE0</constant></entry>
2071 G_GATE0, the gate signal to general purpose counter 0. See the NI's
2072 DAQ-STC Technical Reference Manual for more information.
2076 <entry><constant>NI_RTSI_OUTPUT_RGOUT0</constant></entry>
2078 RGOUT0, the output signal of general purpose counter 0. See the NI's
2079 DAQ-STC Technical Reference Manual for more information.
2084 <function>NI_RTSI_OUTPUT_RTSI_BRD<parameter>n</parameter></function>
2087 RTSI_BRD0 though RTSI_BRD3 are four internal signals which can
2088 have various other signals routed to them in turn. Currently, comedi
2089 provides no way to configure the signals routed to the RTSI_BRD lines.
2090 See the NI's DAQ-STC Technical Reference Manual for more information.
2094 <entry><constant>NI_RTSI_OUTPUT_RTSI_OSC</constant></entry>
2096 The RTSI clock signal. On pre-m-series boards, this signal is always
2097 routed to RTSI line 7, and cannot be routed to lines 0 through 6. On
2098 m-series boards, any RTSI line can be configured to output the clock
2107 The RTSI bus pins may be used as trigger inputs for many of the
2108 &comedi; trigger functions. To use the RTSI bus pins, set the source to be
2109 <constant>TRIG_EXT</constant> and the source argument using the return values
2110 from the <function>NI_EXT_RTSI()</function> function (or similarly the
2111 <function>NI_EXT_PFI()</function> function if you want
2112 to trigger from a PFI line). The <constant>CR_EDGE</constant> and
2113 <constant>CR_INVERT</constant> flags may
2114 also be set on the trigger source argument to specify edge and
2115 falling edge/low level triggering.
2119 An example to set up a device as a master is given below.
2122 <programlisting><![CDATA[
2123 void comediEnableMaster(comedi_t *dev){
2124 comedi_insn configCmd;
2125 lsampl_t configData[2];
2128 static const unsigned rtsi_subdev = 10;
2129 static const unsigned rtsi_clock_line = 7;
2131 /* Route RTSI clock to line 7 (not needed on pre-m-series boards since their
2132 clock is always on line 7). */
2133 memset(&configCmd, 0, sizeof(configCmd));
2134 memset(&configData, 0, sizeof(configData));
2135 configCmd.insn = INSN_CONFIG;
2136 configCmd.subdev = rtsi_subdev;
2137 configCmd.chanspec = rtsi_clock_line;
2139 configCmd.data = configData;
2140 configCmd.data[0] = INSN_CONFIG_SET_ROUTING;
2141 configCmd.data[1] = NI_RTSI_OUTPUT_RTSI_OSC;
2142 ret = comedi_do_insn(dev, &configCmd);
2144 comedi_perror("comedi_do_insn: INSN_CONFIG");
2147 // Set clock RTSI line as output
2148 ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_OUTPUT);
2150 comedi_perror("comedi_dio_config");
2154 /* Set routing of the 3 main AI RTSI signals and their direction to output.
2155 We're reusing the already initialized configCmd instruction here since
2156 it's mostly the same. */
2157 configCmd.chanspec = 0;
2158 configCmd.data[1] = NI_RTSI_OUTPUT_ADR_START1;
2159 ret = comedi_do_insn(dev, &configCmd);
2161 comedi_perror("comedi_do_insn: INSN_CONFIG");
2164 ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_OUTPUT);
2166 comedi_perror("comedi_dio_config");
2170 configCmd.chanspec = 1;
2171 configCmd.data[1] = NI_RTSI_OUTPUT_ADR_START2;
2172 ret = comedi_do_insn(dev, &configCmd);
2174 comedi_perror("comedi_do_insn: INSN_CONFIG");
2177 ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_OUTPUT);
2179 comedi_perror("comedi_dio_config");
2183 configCmd.chanspec = 2;
2184 configCmd.data[1] = NI_RTSI_OUTPUT_SCLKG;
2185 ret = comedi_do_insn(dev, &configCmd);
2187 comedi_perror("comedi_do_insn: INSN_CONFIG");
2190 ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_OUTPUT);
2192 comedi_perror("comedi_dio_config");
2196 ]]></programlisting>
2199 An example to slave a m-series device from this master follows. A pre-m-series
2200 device would need to use <constant>NI_MIO_RTSI_CLOCK</constant> for
2201 the clock source instead. In
2202 your code, you may also wish to configure the master device to use the
2203 external clock source instead of using its internal clock directly (for
2204 best syncronization).
2206 <programlisting><![CDATA[
2207 void comediEnableSlave(comedi_t *dev){
2208 comedi_insn configCmd;
2209 lsampl_t configData[3];
2211 unsigned int d = 0;;
2212 static const unsigned rtsi_subdev = 10;
2213 static const unsigned rtsi_clock_line = 7;
2215 memset(&configCmd, 0, sizeof(configCmd));
2216 memset(&configData, 0, sizeof(configData));
2217 configCmd.insn = INSN_CONFIG;
2218 configCmd.subdev = rtsi_subdev;
2219 configCmd.chanspec = 0;
2221 configCmd.data = configData;
2222 configCmd.data[0] = INSN_CONFIG_SET_CLOCK_SRC;
2223 configCmd.data[1] = NI_MIO_PLL_RTSI_CLOCK(rtsi_clock_line);
2224 configCmd.data[2] = 100; /* need to give it correct external clock period */
2225 ret = comedi_do_insn(dev, &configCmd);
2227 comedi_perror("comedi_do_insn: INSN_CONFIG");
2230 /* configure RTSI clock line as input */
2231 ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_INPUT);
2233 comedi_perror("comedi_dio_config");
2236 /* Configure RTSI lines we are using for AI signals as inputs. */
2237 ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_INPUT);
2239 comedi_perror("comedi_dio_config");
2242 ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_INPUT);
2244 comedi_perror("comedi_dio_config");
2247 ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_INPUT);
2249 comedi_perror("comedi_dio_config");
2254 int comediSlaveStart(comedi_t *dev){
2256 unsigned int nChannels = 8;
2257 double sampleRate = 50000;
2258 unsigned int chanList[8];
2262 for(i = 0; i < nChannels; i++){
2263 chanList[i] = CR_PACK(i, 0, AREF_GROUND);
2266 memset(&cmd, 0, sizeof(cmd));
2267 ret = comedi_get_cmd_generic_timed(dev, subdevice, &cmd,
2268 (int)(1e9/(nChannels * sampleRate)));
2270 printf("comedi_get_cmd_generic_timed failed\n");
2273 cmd.chanlist = chanList;
2274 cmd.chanlist_len = nChannels;
2275 cmd.scan_end_arg = nChannels;
2276 cmd.start_src = TRIG_EXT;
2277 cmd.start_arg = CR_EDGE | NI_EXT_RTSI(0);
2278 cmd.convert_src = TRIG_EXT;
2279 cmd.convert_arg = CR_INVERT | CR_EDGE | NI_EXT_RTSI(2);
2280 cmd.stop_src = TRIG_NONE;
2282 ret = comedi_command(dev0, &cmd0);
2284 printf("comedi_command failed\n");
2289 ]]></programlisting>