1 <!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> -->
4 <section id="acquisitionfunctions">
6 Acquisition and configuration functions
10 This Section gives an overview of all &comedi; functions with which
11 application programmers can implement their data acquisition. (With
12 <quote>acquisition</quote> we mean all possible kinds of interfacing
13 with the cards: input, output, configuration, streaming, etc.)
14 <xref linkend="comedireference"> explains the function calls in full
18 <section id="singleacquisition">
20 Functions for single acquisition
24 The simplest form of using &comedi; is to get one single sample to or
25 from an interface card. This sections explains how to do such simple
26 <link linkend="dio">digital</link> and
27 <link linkend="singleanalog">analog</link> acquisitions.
32 Single digital acquisition
36 Many boards supported by &comedi; have digital input and output
37 channels; i.e., channels that can only produce a <literal>0</literal>
38 or a <literal>1</literal>.
39 Some boards allow the <emphasis>direction</emphasis> (input or output)
40 of each channel to be specified independently in software.
44 &comedi; groups digital channels into a
45 <emphasis>subdevice</emphasis>, which is a group of digital channels
46 that have the same characteristics. For example, digital output lines
47 will be grouped into a digital
48 output subdevice, bidirectional digital lines will be grouped
49 into a digital I/O subdevice. Thus, there can be multiple
50 digital subdevices on a particular board.
54 Individual bits on a digital I/O device can be read and written using
57 int <link linkend="func-ref-comedi-dio-read">comedi_dio_read</link>(device,subdevice,channel,unsigned int *bit);
58 int <link linkend="func-ref-comedi-dio-write">comedi_dio_write</link>(device,subdevice,channel,unsigned int bit);
60 The <parameter class=function>device</parameter> parameter is a
61 <link linkend="ref-type-comedi-t">pointer</link>
62 to a successfully opened &comedi; device.
63 The <parameter class=function>subdevice</parameter> and
64 <parameter class=function>channel</parameter> parameters are positive
65 integers that indicate which subdevice and channel is used in the
66 acquisition. The integer <parameter class=function>bit</parameter>
67 contains the value of the acquired bit.
70 The direction of bidirectional lines can be configured using
73 <link linkend="func-ref-comedi-dio-config">comedi_dio_config</link>(device,subdevice,channel,unsigned int dir);
75 The parameter <parameter class=function>dir</parameter> should be
76 either <literal>COMEDI_INPUT</literal> or
77 <literal>COMEDI_OUTPUT</literal>.
78 Many digital I/O subdevices group channels into blocks for
79 configuring direction. Changing one channel in a block changes
84 Multiple channels can be read and written simultaneously using the
87 <link linkend="func-ref-comedi-dio-bitfield">comedi_dio_bitfield</link>(device,subdevice,unsigned int write_mask,unsigned int *bits);
89 Each channel is assigned to a bit in the
90 <parameter class=function>write_mask</parameter> and
91 <parameter class=function>bits</parameter>
93 <parameter class=function>write_mask</parameter> is set, the
94 corresponding bit in <parameter class=function>*bits</parameter> will
95 be written to the corresponding digital output line.
96 Each digital line is then read and placed into
97 <parameter class=function>*bits</parameter>. The value
98 of bits in <parameter class=function>*bits</parameter> corresponding
99 to digital output lines is undefined and device-specific. Channel
100 <literal>0</literal> is the least significant bit in the bitfield;
101 channel <literal>31</literal> is the most significant bit. Channels
102 higher than <literal>31</literal> cannot be accessed using this method.
106 The digital acquisition functions seem to be very simple, but, behind
107 the implementation screens of the &comedi; kernel module, they are
108 executed as special cases of the general
109 <link linkend="instructions">instruction</link> command.
116 <section id="singleanalog">
118 Single analog acquisition
121 Analog &comedi; channels can produce data values that are
122 <emphasis>samples</emphasis> from continuous analog signals.
123 These samples are integers with a significant content in
124 the range of, typically, <literal>8</literal>, <literal>10</literal>,
125 <literal>12</literal>, or <literal>16</literal> bits.
130 int <link linkend="func-ref-comedi-data-read">comedi_data_read</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel,
131 unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> * data);
133 function reads one such data value from a &comedi; channel, and puts it in
134 the user-specified <parameter>data</parameter> buffer. The
136 int <link linkend="func-ref-comedi-data-write">comedi_data_write</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel,
137 unsigned int range, unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> data);
139 works in the opposite direction. Data values returned by this function
140 are unsigned integers less than, or equal to, the maximum sample value
141 of the channel, which can be determined using the function
143 <link linkend="ref-type-lsampl-t">lsampl_t</link> <link linkend="func-ref-comedi-get-maxdata">comedi_get_maxdata</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel);
145 Conversion of data values to physical units can be performed by the
148 double <link linkend="func-ref-comedi-to-phys">comedi_to_phys</link>(<link linkend="ref-type-lsampl-t">lsampl_t</link> data, comedi_range * range, <link linkend="ref-type-lsampl-t">lsampl_t</link> maxdata);
150 There are two data structures in these commands that are not fully
156 <link linkend="ref-type-comedi-t">comedi_t</link>: this data structure
157 contains all information that a user program has to know about an
158 <emphasis>open</emphasis> &comedi; device. The programmer doesn't have
159 to fill in this data structure manually: it gets filled in by opening
166 <link linkend="ref-type-lsampl-t">lsampl_t</link>: this
167 <quote>data structure</quote> represents one single sample. On most
168 architectures, it's nothing more than a 32 bits value. Internally,
169 &comedi; does some conversion from raw sample data to
170 <quote>correct</quote> integers. This is called <quote>data
178 Each single acquisition by, for example,
180 <link linkend="func-ref-comedi-data-read">comedi_data_read()</link>
182 requires quite some overhead, because all the arguments of the
183 function call are checked. If multiple acquisitions must be done on
184 the same channel, this overhead can be avoided by using a function
185 that can read more than one sample:
187 int <link linkend="func-ref-comedi-dio-read">comedi_data_read_n</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, unsigned int subdev, unsigned int chan, unsigned int range,
188 unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> *data, unsigned int n)
190 The number of samples, <parameter class=function>n</parameter>, is
191 limited by the &comedi; implementation (to a maximum of 100 samples),
192 because the call is blocking.
195 The start of the data acquisition can also be delayed by a specified
196 number of nano-seconds:
198 int <link linkend="func-ref-comedi-data-read-delayed">comedi_data_read_delayed</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, unsigned int subdev, unsigned int chan, unsigned int range,
199 unsigned int aref, <link linkend="ref-type-lsampl-t">lsampl_t</link> *data, unsigned int nano_sec)
201 All these read and write acquisition functions are implemented on top
202 of the generic <link linkend="instructions">instruction</link>
211 <section id="instructions">
213 Instructions for multiple acquisitions
216 The <emphasis>instruction</emphasis> is one of the most generic,
217 overloaden and flexible functions in the &comedi; API. It is used to
218 execute a multiple of identical acquisitions on the same channel, but
220 <link linkend="instructionsconfiguration">configuration</link> of a
222 <anchor id="anchor.instruction.list">
223 An <emphasis>instruction list</emphasis> is a list of instructions,
224 possibly on different channels. Both instructions and instructions
225 lists are executed <emphasis>synchronously</emphasis>, i.e., while
226 <emphasis role="strong">blocking</emphasis> the calling process.
227 This is one of the limitations of instructions; the other one is that
228 they cannot code an acquisition involving timers or external events.
229 These limits are eliminated by the
230 <link linkend="commandsstreaming">command</link> acquisition
235 <section id="comediinsnstructure">
237 The instruction data structure
240 All the information needed to execute an instruction is stored in the
241 <link linkend="ref-type-comedi-insn">comedi_insn</link>
244 struct <anchor id="insn-data-structure">comedi_insn_struct{
245 <anchor id="insn-data-structure-insn">unsigned int insn; // integer encoding the type of acquisition
246 // (or configuration)
247 unsigned int n; // number of samples
248 <link linkend="ref-type-lsampl-t">lsampl_t</link> <anchor id="insn-data-structure-data">*data; // pointer to data buffer
249 unsigned int subdev; // subdevice
250 unsigned int <anchor id="insn-data-structure-chanspec"><link linkend="ref-macro-CR-PACK">chanspec</link>; // encoded channel specification
251 unsigned int unused[3];
254 Because of the large flexibility of the instruction function, many
255 types of instruction do not need to fill in all fields, or attach
256 different meanings to the same field. But the current implementation
257 of &comedi; requires the
258 <link linkend="insn-data-structure-data">data</link> field to be at
263 The <link linkend="insn-data-structure-insn">insn</link> flag of the
264 <link linkend="insn-data-structure">instruction data structure</link>
265 determines the type of acquisition executed in the corresponding
271 INSN_READ: the instruction executes a read on an analog channel.
277 INSN_WRITE: the instruction executes a write on an analog channel.
283 INSN_BITS: indicates that the instruction must
284 read or write values on multiple digital I/O channels.
290 INSN_GTOD: the instruction performs a <quote>Get Time Of Day</quote>
297 INSN_WAIT: the instruction blocks for a specified number of
308 <section id="instructionexecution">
310 Instruction execution
313 Once an instruction data structure has been filled in, the
314 corresponding instruction is executed as follows:
316 int <link linkend="func-ref-comedi-do-insn">comedi_do_insn</link>(<link linkend="ref-type-comedi-t">comedi_t</link> *it, <link linkend="ref-type-comedi-insn">comedi_insn</link> * instruction);
318 Many &comedi; instructions are shortcuts that relieve the programmer
319 from explicitly filling in the data structure and calling the
320 <link linkend="func-ref-comedi-do-insn">comedi_do_insn</link>
326 int <link linkend="func-ref-comedi-do-insnlist">comedi_do_insnlist</link><link linkend="ref-type-comedi-t">comedi_t</link> *it, <link linkend="ref-type-comedi-insnlist">comedi_insnlist</link> * list)
328 instruction allows to perform a list of instructions in one function
329 call. The number of instructions in the list is limited in the
330 implementation, because instructions are executed
331 <emphasis>synchronously</emphasis>, i.e., the call blocks until the
332 whole instruction (list) has finished.
340 <section id="instructionsconfiguration">
342 Instructions for configuration
345 <xref linkend="instructions"> explains how instructions are used to do
346 <emphasis>acquisition</emphasis> on channels. This section explains
347 how they are used to <emphasis>configure</emphasis> a device.
348 There are various sorts of configurations, and the
349 specific information for each different configuration possibility is
350 to be specified via the
351 <link linkend="insn-data-structure-data">data</link> buffer of the
352 <link linkend="insn-data-structure">instruction data structure</link>.
353 (So, the pointer to a
354 <link linkend="ref-type-lsampl-t">lsampl_t</link>
355 is misused as a pointer to an array with board-specific information.)
359 Using INSN_CONFIG as the
360 <link linkend="insn-data-structure-insn">insn</link> flag in an
361 <link linkend="insn-data-structure">instruction data structure</link>
362 indicates that the instruction will
363 <emphasis>not perform acquisition</emphasis> on a
364 channel, but will <emphasis>configure</emphasis> that channel.
365 For example, the configuration of digital I/O channels is done as
367 <link linkend="ref-macro-CR-PACK">chanspec</link> field in the
368 <link linkend="insn-data-structure-chanspec">comedi_insn</link>
369 data structure, contains the channel to be configured. And
370 <link linkend="insn-data-structure-data">data</link>[0] contains
371 either COMEDI_INPUT or COMEDI_OUTPUT, depending on the desired
372 direction of the digital I/O lines.
373 On typical devices, multiple channels are grouped together in blocks
374 for determining their direction. And configuring one channel in a
375 block configures the entire block.
379 Another example of an INSN_CONFIG instruction is the configuration of
380 the <link linkend="trigother-event">TRIG_OTHER</link> event source.
386 <section id="inttrigconfiguration">
388 Instruction for internal triggering
391 This special instruction has
392 <anchor id="insn-inttrig">INSN_INTTRIG as the
393 <link linkend="insn-data-structure-insn">insn</link> flag in its
394 <link linkend="insn-data-structure">instruction data structure</link>.
395 Its execution causes an
396 <link linkend="trig-int-start-src">internal triggering event</link>. This
397 event can, for example, cause the device driver to start a conversion,
398 or to stop an ongoing acquisition. The exact meaning of the triggering
399 depends on the card and its particular driver.
403 <link linkend="insn-data-structure-data">data</link>[0] field of the
404 INSN_INTTRIG instruction is reserved for future use, and should be set
411 <section id="commandsstreaming">
413 Commands for streaming acquisition
417 The most powerful &comedi; acquisition primitive is the
418 <emphasis>command</emphasis>. It's powerful because, with one single
419 command, the programmer launches:
424 a possibly infinite <emphasis>sequence of acquisitions</emphasis>,
430 accompanied with various <emphasis>callback</emphasis> functionalities
431 (DMA, interrupts, driver-specific callback functions),
437 for <emphasis>any number of channels</emphasis>,
443 with an <emphasis>arbitrary order</emphasis> of channels in each scan
444 (possibly even with repeated channels per scan),
450 and with various scan <emphasis>triggering sources</emphasis>,
451 external (i.e., hardware pulses) as well as internal (i.e., pulses
452 generated on the DAQ card itself, or generated by a
453 <link linkend="inttrigconfiguration">software trigger instruction</link>).
458 This command functionality exists in the &comedi; API, because various
459 data acquisition devices have the capability to perform this kind of
460 complex acquisition, driven by either on-board or
461 off-board timers and triggers.
465 A command specifies a particular data
466 <link linkend="fig-acq-seq">acquisition sequence</link>, which
467 consists of a number of <emphasis>scans</emphasis>, and each scan is
468 comprised of a number of <emphasis>conversions</emphasis>, which
469 usually corresponds to a single A/D or D/A conversion. So, for
470 example, a scan could consist of sampling channels 1, 2 and 3 of a
471 particular device, and this scan should be repeated 1000 times, at
472 intervals of 1 millisecond apart.
475 The command function is complementary to the
476 <link linkend="instructionsconfiguration">configuration instruction</link>
477 function: each channel in the command's
478 <link linkend="command-data-struct-chanlist">chanlist</link>
479 should first be configured by an appropriate instruction.
483 <section id="executingcommand">
489 A commands is executed by the following &comedi; function:
491 int <link linkend="func-ref-comedi-command">comedi_command</link>(<link linkend="ref-type-comedi-t">comedi_t</link> * device, <link linkend="ref-type-comedi-cmd">comedi_cmd</link> * command);
493 The following sections explain the meaning of the
494 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data structure.
495 Filling in this structure can be quite complicated, and
496 requires good knowledge about the exact functionalities of the DAQ
497 card. So, before launching a command, the application programmer is
498 adviced to check whether this complex command data structure can be
499 successfully parsed. So, the typical sequence for executing a command is
500 to first send the command through
501 <link linkend="func-ref-comedi-command-test">comedi_command_test()</link>
502 once or twice. The test will check that the command is valid for the
503 particular device, and often makes some adjustments to the command
504 arguments, which can then be read back by the user to see the actual
508 A &comedi; program can find out on-line what the command capabilities
509 of a specific device are, by means of the
510 <link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask()</link>
517 <section id="comedicmdstructure">
519 The command data structure
522 The command executes according to the information about the requested
523 acquisition, which is stored in the
524 <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
525 <anchor id="command-data-struct">data structure:
527 typedef struct comedi_cmd_struct comedi_cmd;
529 struct comedi_cmd_struct{
530 unsigned int subdev; // which subdevice to sample
531 unsigned int <anchor id="command-data-struct-flags">flags; // encode some configuration possibilities
532 // of the command execution; e.g.,
533 // whether a callback routine is to be
534 // called at the end of the command
536 unsigned int <anchor id="command-data-struct-start-src">start_src; // event to make the acquisition start
537 unsigned int <anchor id="command-data-struct-start-arg">start_arg; // parameters that influence this start
539 unsigned int <anchor id="command-data-struct-scan-begin-src">scan_begin_src; // event to make a particular scan start
540 unsigned int <anchor id="command-data-struct-scan-begin-arg">scan_begin_arg; // parameters that influence this start`
542 unsigned int <anchor id="command-data-struct-convert-src">convert_src; // event to make a particular conversion start
543 unsigned int <anchor id="command-data-struct-convert-arg">convert_arg; // parameters that influence this start
545 unsigned int <anchor id="command-data-struct-scan-end-src">scan_end_src; // event to make a particular scan terminate
546 unsigned int <anchor id="command-data-struct-scan-end-arg">scan_end_arg; // parameters that influence this termination
548 unsigned int <anchor id="command-data-struct-stop-src">stop_src; // what make the acquisition terminate
549 unsigned int <anchor id="command-data-struct-stop-arg">stop_arg; // parameters that influence this termination
551 unsigned int <anchor id="command-data-struct-chanlist">*chanlist; // pointer to list of channels to be sampled
552 unsigned int <anchor id="command-data-struct-chanlist-len">chanlist_len; // number of channels to be sampled
554 sampl_t *<anchor id="command-data-struct-data">data; // address of buffer
555 unsigned int <anchor id="command-data-struct-data-len">data_len; // number of samples to acquire
558 The start and end of the whole command acquisition sequence, and the
559 start and end of each scan and of each conversion, is triggered by a
560 so-called <emphasis>event</emphasis>. More on these in
561 <xref linkend="comedicmdsources">.
565 The <parameter class=function>subdev</parameter> member of the
566 <link linkend="ref-type-comedi-cmd">comedi_cmd()</link> structure is
567 the index of the subdevice the command is intended for. The
568 <link linkend="func-ref-comedi-find-subdevice-by-type">comedi_find_subdevice_by_type()</link>
569 function can be useful in discovering the index of your desired subdevice.
573 The <link linkend="command-data-struct-chanlist">chanlist</link>
575 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
576 structure should point to an array whose number of elements is
578 <link linkend="command-data-struct-chanlist-len">chanlist_len</link>
579 (this will generally be the same as the
580 <link linkend="command-data-struct-scan-end-arg">scan_end_arg</link>).
582 <link linkend="command-data-struct-chanlist">chanlist</link>
583 specifies the sequence of channels and gains (and analog references)
584 that should be stepped through for each scan. The elements of the
585 <link linkend="command-data-struct-chanlist">chanlist</link> array should be
586 initialized by <quote>packing</quote> the channel, range and reference
587 information together with the
588 <parameter class=function>
589 <link linkend="ref-macro-CR-PACK">CR_PACK()</link>
595 The <link linkend="command-data-struct-data">data</link> and
596 <link linkend="command-data-struct-data-len">data_len</link>
597 members can be safely ignored when issueing commands from a user-space
598 program. They only have meaning when a command is sent from a
599 <emphasis role="strong">kernel</emphasis> module using the
600 <function>kcomedilib</function> interface, in which case they specify
601 the buffer where the driver should write/read its data to/from.
605 The final member of the
606 <link linkend="command-data-struct">comedi_cmd</link> structure is the
607 <link linkend="command-data-struct-flags">flags</link> field,
608 i.e., bits in a word that can be bitwise-or'd together. The meaning of
609 these bits are explained in a
610 <link linkend="source.flags.anchor">later section</link>.
616 <section id="comedicmdsources">
618 The command trigger events
619 <anchor id="source.trigger.anchor">
622 A command is a very versatile acquisition instruction, in the sense
623 that it offers lots of possibilities to let different hardware and
624 software sources determine when acquisitions are started, performed,
625 and stopped. More specifically, the command
626 <link linkend="command-data-struct">data structure</link>
627 has <emphasis>five</emphasis> types of events: start the
628 <link linkend="acquisitionterminology">acquisition</link>,
629 start a <link linkend="scan">scan</link>, start a
630 <link linkend="conversion">conversion</link>, stop a scan, and stop
631 the acquisition. Each event can be given its own
632 <emphasis><link linkend="source.trigger.anchor">source</link></emphasis>
633 (the <parameter class=function>*_src</parameter> members in the
634 <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
635 structure). And each event source can have a corresponding
636 argument (the <parameter class=function>*_arg</parameter> members of
637 the <link linkend="ref-type-comedi-cmd">comedi_cmd</link> data
638 structure) whose meaning depends on the type of source trigger.
639 For example, to specify an external digital line <quote>3</quote> as a
640 source (in general, <emphasis>any</emphasis> of the five event
641 sources), you would use
642 <parameter>src</parameter>=<link linkend="trig-ext">TRIG_EXT</link> and
643 <parameter>arg</parameter>=3.
646 The following paragraphs discuss in somewhat more detail the trigger
647 event sources(<parameter class=function>*_src</parameter>), and the
648 corresponding arguments (<parameter class=function>*_arg</parameter>).
651 The start of an acquisition is controlled by the
652 <link linkend="command-data-struct-start-src">start_src</link> events.
653 The available options are:
658 <anchor id="trig-now-start-src">
660 <link linkend="command-data-struct-start-src">start_src</link>
662 <link linkend="command-data-struct-start-arg">start_arg</link>
663 nanoseconds after the
664 <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
665 is called. Currently, only
666 <link linkend="command-data-struct-start-arg">start_arg</link>=0 is
673 <anchor id="trig-follow-start-src">
674 TRIG_FOLLOW: (For an output device.) The
675 <link linkend="command-data-struct-start-src">start_src</link>
676 event occurs when data is written to the buffer.
682 <anchor id="trig-ext-start-src">
683 TRIG_EXT: the start event occurs when an external trigger signal
684 occurs; e.g., a rising edge of a digital line.
685 <link linkend="command-data-struct-start-arg">start_arg</link>
686 chooses the particular digital line.
692 <anchor id="trig-int-start-src">
693 TRIG_INT: the start event occurs on a &comedi; internal signal, which
694 is typically caused by an
695 <link linkend="insn-inttrig">INSN_INTTRIG instruction</link>.
700 The start of the beginning of each
701 <link linkend="scan">scan</link> is controlled by the
702 <link linkend="command-data-struct-scan-begin-src">scan_begin</link> events.
703 The available options are:
708 <anchor id="trig-timer-start-scan">
710 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
711 events occur periodically. The time between
712 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
714 <link linkend="command-data-struct-convert-arg">convert_arg</link>
721 <anchor id="trig-follow-start-scan">
723 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
724 event occurs immediately after a
725 <link linkend="command-data-struct-scan-end-src">scan_end</link>
732 <anchor id="trig-ext-start-scan">
734 <link linkend="command-data-struct-scan-begin-src">scan_begin</link>
735 event occurs when an external trigger signal
736 occurs; e.g., a rising edge of a digital line.
737 <link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link>
738 chooses the particular digital line.
744 <link linkend="command-data-struct-scan-begin-arg">scan_begin_arg</link>
745 used here may not be supported exactly by the device, but it
746 will be adjusted to the nearest supported value by
747 <link linkend="func-ref-comedi-command-test">comedi_command_test()</link>.
750 The timing between each sample in a
751 <link linkend="scan">scan</link> is controlled by the
752 <link linkend="command-data-struct-convert-src">convert_*</link>
758 <anchor id="convert-trig-timer">
759 <anchor id="trig-timer">
760 TRIG_TIMER: the conversion events occur periodically. The time
761 between convert events is
762 <link linkend="command-data-struct-convert-arg">convert_arg</link>
769 <anchor id="convert-trig-ext">
770 <anchor id="trig-ext">
771 TRIG_EXT: the conversion events occur when an external trigger signal
772 occurs, e.g., a rising edge of a digital line.
773 <link linkend="command-data-struct-convert-arg">convert_arg</link>
774 chooses the particular digital line.
780 <anchor id="convert-trig-now">
781 <anchor id="trig-now">
782 TRIG_NOW: All conversion events in a
783 <link linkend="scan">scan</link> occur simultaneously.
788 The <emphasis>end</emphasis> of each scan is almost always specified
790 <link linkend="trig-count">TRIG_COUNT</link>, with the argument being
791 the same as the number of channels in the
792 <link linkend="command-data-struct-chanlist">chanlist</link>. You
793 could probably find a device that allows something else, but it would
798 <link linkend="acquisitionterminology">acquisition</link> is
800 <link linkend="command-data-struct-stop-src">stop_src</link>
801 and <link linkend="command-data-struct-stop-arg">stop_arg</link>:
806 <anchor id="acquisition-end-trig-count">
807 <anchor id="trig-count">
808 TRIG_COUNT: stop the acquisition after
809 <link linkend="command-data-struct-stop-arg">stop_arg</link>
816 <anchor id="acquisition-end-trig-none">
817 <anchor id="trig-none">
818 TRIG_NONE: perform continuous acquisition, until stopped using
819 <link linkend="func-ref-comedi-cancel">comedi_cancel()</link>.
822 Its argument is reserved and should be set to 0.
823 (<quote>Reserved</quote>
824 means that unspecified things could happen if it is set to something
830 There are a couple of less usual or not yet implemented events:
835 <anchor id="trig-time">
837 cause an event to occur at a particular time.
840 (This event source is reserved for future use.)
846 <anchor id="trigother-event">
847 TRIG_OTHER: driver specific event trigger.
850 This event can be useful as any of the trigger sources. Its exact
851 meaning is driver specific, because it implements a feature that
852 otherwise does not fit into the generic &comedi; command interface.
853 Configuration of TRIG_OTHER features are done by
854 <link linkend="instructionsconfiguration">INSN_CONFIG</link>
858 The argument is reserved and should be set to 0.
863 Not all event sources are applicable to all events. Supported
864 trigger sources for specific events depend significantly on your
865 particular device, and even more on the current state of its device
867 <link linkend="func-ref-comedi-get-cmd-src-mask">comedi_get_cmd_src_mask()</link>
868 function is useful for determining what trigger sources a subdevice
875 <section id="comedicmdflags">
878 <anchor id="source.flags.anchor">
883 <link linkend="command-data-struct-flags">flags</link> field in the
884 <link linkend="ref-type-comedi-cmd">command data structure</link>
885 is used to specify some <quote>behaviour</quote> of the acquisitions in
887 The meaning of the field is as follows:
892 <anchor id="trig-rt">
893 TRIG_RT: ask the driver to use a
894 <emphasis role="strong">hard real-time</emphasis> interrupt handler.
895 This will reduce latency in handling interrupts from your data
897 hardware. It can be useful if you are sampling at high frequency, or
898 if your hardware has a small onboard data buffer. You must have a
899 real-time kernel (<ulink url="http://www.rtai.org">RTAI</ulink> or
900 <ulink url="http://fsmlabs.com/community/">RTLinux/Free</ulink>)
901 and must compile &comedi; with real-time support, or this flag will do
908 <anchor id="trig-wake-eos">
910 where <quote>EOS</quote> stands for <quote>End of Scan</quote>. Some
911 drivers will change their behaviour when this flag is set, trying to
912 transfer data at the end of every scan (instead of, for example,
913 passing data in chunks whenever the board's hardware data buffer is
914 half full). This flag may degrade a driver's performance at high
915 frequencies, because the end of a scan is, in general, a much more
916 frequent event than the filling up of the data buffer.
922 <anchor id="trig-round-nearest">
924 round to nearest supported timing period, the default.
925 This flag (as well as the following three), indicates how timing
926 arguments should be rounded if the hardware cannot achieve the exact
933 <anchor id="trig-round-down">
934 TRIG_ROUND_DOWN: round period down.
940 <anchor id="trig-round-up">
941 TRIG_ROUND_UP: round period up.
947 <anchor id="trig-round-up-next">
949 this one doesn't do anything, and I don't know what it was intended
956 <anchor id="trig-dither">
957 TRIG_DITHER: enable dithering? Dithering is a software technique to
958 smooth the influence of discretization <quote>noise</quote>.
964 <anchor id="trig-deglitch">
965 TRIG_DEGLITCH: enable deglitching? Another <quote>noise</quote>
972 <anchor id="trig-write">
974 write to bidirectional devices. Could be useful, in principle, if
975 someone wrote a driver that supported commands for a digital I/O
976 device that could do either input or output.
982 <anchor id="trig-bogus">
983 TRIG_BOGUS: do the motions?
989 <anchor id="trig-other">
990 TRIG_CONFIG: perform configuration, not triggering. This is a legacy
992 <link linkend="ref-type-comedi-cmd">comedi_trig_struct</link>
993 data structure, and has no function at present.
1007 If you wish to aquire accurate waveforms, it is vital that you use an
1008 anti-alias filter. An anti-alias filter is a low-pass filter used to
1009 remove all frequencies higher than the Nyquist frequency (half your sampling rate)
1010 from your analog input signal
1011 before you convert it to digital. If you fail to filter your input signal,
1012 any high frequency components in the original analog signal will create
1013 artifacts in your recorded digital waveform that cannot be corrected.
1016 For example, suppose you are sampling an analog input channel at a rate of
1017 1000 Hz. If you were to apply a 900 Hz sine wave to the input, you
1018 would find that your
1019 sampling rate is not high enough to faithfully record the 900 Hz input,
1020 since it is above your Nyquist frequency of 500 Hz. Instead, what you
1021 will see in your recorded digital waveform is a 100 Hz sine wave! If you
1022 don't use an anti-alias filter, it is impossible to tell whether the 100
1023 Hz sine wave you see in your digital signal was really produced by a
1024 100 Hz input signal, or a 900 Hz signal aliased to 100 Hz, or a 1100 Hz
1028 In practice, the cutoff frequency for the anti-alias filter is usually
1029 set 10% to 20% below the Nyquist frequency due to fact that real filters
1030 do not have infinitely sharp cutoffs.
1036 <section id="slowlyvarying">
1038 Slowly-varying inputs
1042 Sometimes, your input channels change slowly enough that
1043 you are able to average many successive input values to get a
1044 more accurate measurement of the actual value. In general,
1045 the more samples you average, the better your estimate
1046 gets, roughly by a factor of sqrt(number_of_samples).
1047 Obviously, there are limitations to this:
1054 you are ultimately limited by <quote>Spurious Free Dynamic
1055 Range</quote>. This SFDR is one of the popular measures to quantify how
1056 much noise a signal carries. If you take a Fourier transform of your
1057 signal, you will see several <quote>peaks</quote> in the transform: one
1058 or more of the fundamental harmonics of the measured signal, and lots
1059 of little <quote>peaks</quote> (called <quote>spurs</quote>) caused by
1060 noise. The SFDR is then the difference between the amplitude of the
1061 fundamental harmonic and of the largest spur (at frequencies below
1062 half of the Nyquist frequency of the DAQ sampler!).
1068 you need to have <emphasis>some</emphasis> noise on the input channel,
1069 otherwise you will be averaging the same number <literal>N</literal>
1070 times. (Of course, this only holds if the noise is large enough to
1071 cause at least a one-bit discretization.)
1077 the more noise you have, the greater your SFDR, but it
1078 takes many more samples to compensate for the increased
1085 if you feel the need to average samples for, for example, two seconds,
1086 your signal will need to be <emphasis>very</emphasis> slowly-varying,
1087 i.e., not varying more than your target uncertainty for the entire two
1095 As you might have guessed, the &comedi; library has functions
1096 to help you in your quest to accurately measure slowly varying
1099 int <link linkend="func-ref-comedi-sv-init">comedi_sv_init</link>(<link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> * sv, <link linkend="ref-type-comedi-t">comedi_t</link> * device, unsigned int subdevice, unsigned int channel);
1101 This function initializes the
1102 <link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> data structure, used
1103 to do the averaging acquisition:
1105 struct comedi_sv_struct{
1106 <link linkend="ref-type-comedi-t">comedi_t</link> *dev;
1107 unsigned int subdevice;
1114 /* number of measurements to average (for analog inputs) */
1120 The actual acquisition is done with:
1122 int <link linkend="func-ref-comedi-sv-measure">comedi_sv_measure</link>(<link linkend="ref-type-comedi-sv-t">comedi_sv_t</link> * sv, double * data);
1124 The number of samples over which the
1125 <function>comedi_sv_measure()</function> averages is limited by the
1126 implementation (currently the limit is 100 samples).
1130 One typical use for this function is the measurement of thermocouple
1132 And the &comedi; self-calibration utility also uses these functions.
1133 On some hardware, it is possible to tell it to measure an
1134 internal stable voltage reference, which is typically going
1135 to be very slowly varying; on the kilosecond time scale
1136 or more. So, it is reasonable to measure millions of samples,
1137 to get a very accurate measurement of the A/D converter output
1138 value that corresponds to the voltage reference. Sometimes,
1139 however, this is overkill, since there is no need to
1140 perform a part-per-million calibration to a standard that
1141 is only accurate to a part-per-thousand.
1146 <section id="experimentalfunctionality">
1148 Experimental functionality
1152 The following subsections document functionality that has not yet
1153 matured. Most of this functionality has even not been implemented yet
1154 in any single device driver. This information is included here, in
1155 order to stimulate discussion about their API, and to encourage
1156 pioneering implementations.
1159 <section id="digitalinputcombining">
1161 Digital input combining machines
1165 (<emphasis role="strong">Status: experimental (i.e., no driver implements
1166 this yet)</emphasis>)
1169 When one or several digital inputs are used to modify an output
1170 value, either an accumulator or a single digital line or bit,
1171 a bitfield structure is typically used in the &comedi; interface.
1172 The digital inputs have two properties, <quote>sensitive</quote> inputs
1173 and <quote>modifier</quote> inputs. Edge transitions on sensitive
1174 inputs cause changes in the output signal, whereas modifier inputs
1175 change the effect of edge transitions on sensitive inputs. Note that
1176 inputs can be both modifier inputs and sensitive inputs.
1180 For simplification purposes, it is assumed that multiple digital
1181 inputs do not change simultaneously.
1185 The combined state of the modifier inputs determine a modifier
1186 state. For each combination of modifier state and sensitive
1187 input, there is a set of bits that determine the effect on the
1188 output value due to positive or negative transitions of the
1189 sensitive input. For each transition direction, there are two
1190 bits defined as follows:
1194 00: transition is ignored.
1198 01: accumulator is incremented, or output is set.
1202 10: accumulator is decremented, or output is cleared.
1210 For example, a simple digital follower is specified by the bit
1211 pattern 01 10, because it sets the output on positive transitions
1212 of the input, and clears the output on negative transitions. A
1213 digital inverter is similarily 10 01. These systems have only
1214 one sensitive input.
1218 As another example, a simple up counter, which increments on
1219 positive transitions of one input, is specified by 01 00. This
1220 system has only one sensitive input.
1224 When multiple digital inputs are used, the inputs are divided
1225 into two types, inputs which cause changes in the accumulator, and
1226 those that only modify the meaning of transitions on other inputs.
1227 Modifier inputs do not require bitfields, but there needs to be
1228 a bitfield of length 4*(2^(N-1)) for each edge sensitive input,
1229 where N is the total number of inputs. Since N is usually 2 or
1230 3, with only one edge sensitive input, the scaling issues are
1237 <section id="analogconversion">
1239 Analog filtering configuration
1243 <emphasis role="strong">(Status: design (i.e., no driver implements
1244 this yet).)</emphasis>
1248 The <link linkend="insn-data-structure-insn">insn</link> field of the
1249 <link linkend="insn-data-structure">instruction data structure</link>
1250 has not been assigned yet.
1253 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1254 of the <link linkend="insn-data-structure">instruction data
1255 structure</link> is ignored.
1259 Some devices have the capability to add white noise (dithering) to
1260 analog input measurement. This additional noise can then be averaged
1261 out, to get a more accurate measurement of the input signal. It
1262 should not be assumed that channels can be separately configured.
1263 A simple design can use 1 bit to turn this feature on/off.
1267 Some devices have the capability of changing the glitch characteristics
1268 of analog output subsytems. The default (off) case should be where
1269 the average settling time is lowest. A simple design can use 1 bit
1270 to turn this feature on/off.
1274 Some devices have a configurable analog filters as part of the analog
1275 input stage. A simple design can use 1 bit to enable/disable the
1276 filter. Default is disabled, i.e., the filter being bypassed, or if
1277 the choice is between two filters, the filter with the largest
1282 <section id="waveformgeneration">
1284 Analog Output Waveform Generation
1288 <emphasis role="strong">(Status: design (i.e., no driver implements
1289 this yet).)</emphasis>
1292 The <link linkend="insn-data-structure-insn">insn</link> field of the
1293 <link linkend="insn-data-structure">instruction data structure</link>
1294 has not been assigned yet.
1297 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1298 of the <link linkend="insn-data-structure">instruction data
1299 structure</link> is ignored.
1303 Some devices have the ability to cyclicly loop through samples kept in
1304 an on-board analog output FIFO. This config should allow the user to
1305 enable/disable this mode.
1309 This config should allow the user to configure the number of samples
1310 to loop through. It may be necessary to configure the channels used.
1315 <section id="extendedtriggering">
1320 <emphasis role="strong">(Status: alpha.)</emphasis>
1324 The <link linkend="insn-data-structure-insn">insn</link> field of the
1325 <link linkend="insn-data-structure">instruction data structure</link>
1326 has not been assigned yet.
1329 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1330 of the <link linkend="insn-data-structure">instruction data
1331 structure</link> is ignored.
1335 This section covers common information for all extended
1336 triggering configuration, and doesn't describe a particular
1337 type of extended trigger.
1341 Extended triggering is used to configure triggering engines that
1342 do not fit into commands. In a typical programming sequence, the
1343 application will use
1344 <link linkend="instructionsconfiguration">configuration instructions</link>
1345 to configure an extended trigger, and a
1346 <link linkend="commandsstreaming">command</link>,
1348 <link linkend="trig-other">TRIG_OTHER</link> as one of the trigger
1353 Extended trigger configuration should be designed in such a way
1354 that the user can probe for valid parameters, similar to how
1355 command testing works. An extended trigger configuration instruction
1356 should not configure the hardware directly, rather, the configuration
1357 should be saved until the subsequent command is issued. This
1358 allows more flexibility for future interface changes.
1362 It has not been decided whether the configuration stage should return a
1363 token that is then used as the trigger argument in the command.
1364 Using tokens is one method to satisfy the problem that extended
1365 trigger configurations may have subtle compatiblity issues with
1366 other trigger sources/arguments that can only be determined at
1367 command test time. Passing all stages of a command test should
1368 only be allowed with a properly configured extended trigger.
1372 Extended triggers must use
1373 <link linkend="insn-data-structure-data">data[1]</link> as flags. The
1374 upper 16 bits are reserved and used only for flags that are common to
1375 all extended triggers. The lower 16 bits may be defined by the
1376 particular type of extended trigger.
1380 Various types of extended triggers must use
1381 <link linkend="insn-data-structure-data">data[1]</link> to know which
1382 event the extended trigger will be assigned to in the command
1383 structure. The possible values are an OR'd mask of the following:
1394 COMEDI_EV_SCAN_BEGIN
1416 <section id="analogtriggering">
1421 <emphasis role="strong">
1422 (Status: alpha. The <function>ni_mio_common.c</function> driver
1423 implements this feature.)
1428 The <link linkend="insn-data-structure-insn">insn</link> field of the
1429 <link linkend="insn-data-structure">instruction data structure</link>
1430 has not been assigned yet.
1433 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1434 of the <link linkend="insn-data-structure">instruction data
1435 structure</link> is ignored.
1439 The <link linkend="insn-data-structure-data">data</link> field
1440 of the <link linkend="insn-data-structure">instruction data
1441 structure</link> is used as follows:
1444 data[1]: trigger and combining machine configuration.
1447 data[2]: analog triggering signal chanspec.
1450 data[3]: primary analog level.
1453 data[4]: secondary analog level.
1458 Analog triggering is described by a digital combining machine that
1459 has two sensitive digital inputs. The sensitive digital inputs are
1460 generated by configurable analog comparators. The analog comparators
1461 generate a digital 1 when the analog triggering signal is greater
1462 than the comparator level. The digital inputs are not modifier
1463 inputs. Note, however, there is an effective modifier due to the
1464 restriction that the primary analog comparator level must be less
1465 than the secondary analog comparator level.
1469 If only one analog comparator signal is used, the combining machine
1470 for the secondary input should be set to ignored, and the secondary
1471 analog level should be set to 0.
1475 The interpretation of the chanspec and voltage levels is device
1476 dependent, but should correspond to similar values of the analog
1477 input subdevice, if possible.
1481 Notes: Reading range information is not addressed. This makes it
1482 difficult to convert comparator voltages to data values.
1486 Possible extensions: A parameter that specifies the necessary time
1487 that the set condition has to be true before the trigger is generated.
1488 A parameter that specifies the necessary time that the reset condition
1489 has to be true before the state machine is reset.
1494 <section id="bitfieldmatching">
1496 Bitfield Pattern Matching Extended Trigger
1499 <emphasis role="strong">
1500 (Status: design. No driver implements this feature yet.)
1505 The <link linkend="insn-data-structure-insn">insn</link> field of the
1506 <link linkend="insn-data-structure">instruction data structure</link>
1507 has not been assigned yet.
1510 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1511 of the <link linkend="insn-data-structure">instruction data
1512 structure</link> is ignored.
1516 The <link linkend="insn-data-structure-data">data</link> field
1517 of the <link linkend="insn-data-structure">instruction data
1518 structure</link> is used as follows:
1522 data[1]: trigger flags.
1533 The pattern matching trigger issues a trigger when all of a specifed
1534 set of input lines match a specified pattern. If the device allows,
1535 the input lines should correspond to the input lines of a digital input
1536 subdevice, however, this will necessarily be device dependent. Each
1537 possible digital line that can be matched is assigned a bit in the
1538 mask and pattern. A bit set in the mask indicates that the
1539 input line must match the corresponding bit in the pattern.
1540 A bit cleared in the mask indicates that the input line is ignored.
1544 Notes: This only allows 32 bits in the pattern/mask, which may be
1545 too few. Devices may support selecting different sets of lines from
1546 which to match a pattern.
1550 Discovery: The number of bits can be discovered by setting the mask
1551 to all 1's. The driver must modify this value and return -EAGAIN.
1556 <section id="countertimer">
1558 Counter configuration
1561 <emphasis role="strong">
1562 (Status: design. No driver implements this feature yet.)
1567 The <link linkend="insn-data-structure-insn">insn</link> field of the
1568 <link linkend="insn-data-structure">instruction data structure</link>
1569 has not been assigned yet.
1572 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1573 of the <link linkend="insn-data-structure">instruction data
1574 structure</link> is used to specify which counter to use. (I.e., the
1575 counter is a &comedi; channel.)
1579 The <link linkend="insn-data-structure-data">data</link> field
1580 of the <link linkend="insn-data-structure">instruction data
1581 structure</link> is used as follows:
1585 data[1]: trigger configuration.
1588 data[2]: primary input chanspec.
1591 data[3]: primary combining machine configuration.
1594 data[4]: secondary input chanspec.
1597 data[5]: secondary combining machine configuration.
1600 data[6]: latch configuration.
1605 Note that this configuration is only useful if the counting has to be
1606 done in <emphasis>software</emphasis>. Many cards offer configurable
1607 counters in hardware; e.g., general purpose timer cards can be
1608 configured to act as pulse generators, frequency counters, timers,
1612 Counters can be operated either in synchronous mode (using
1613 <link linkend="comediinsnstructure">INSN_READ</link>)
1614 or asynchronous mode (using
1615 <link linkend="commandsstreaming">commands</link>), similar to analog
1617 The input signal for both modes is the accumulator.
1618 Commands on counter subdevices are almost always specified using
1619 <link linkend="command-data-struct-scan-begin-src">scan_begin_src</link>
1620 = <link linkend="trigother-event">TRIG_OTHER</link>, with the
1621 counter configuration also serving as the extended configuration for
1622 the scan begin source.
1626 Counters are made up of an accumulator and a combining machine that
1627 determines when the accumulator should be incremented or decremented
1628 based on the values of the input signals. The combining machine
1629 optionally determines when the accumulator should be latched and
1630 put into a buffer. This feature is used in asynchronous mode.
1634 Note: How to access multiple pieces of data acquired at each event?
1639 <section id="auxcounter">
1641 One source plus auxiliary counter configuration
1644 <emphasis role="strong">
1645 (Status: design. No driver implements this feature yet.)
1650 The <link linkend="insn-data-structure-insn">insn</link> field of the
1651 <link linkend="insn-data-structure">instruction data structure</link>
1652 has not been assigned yet.
1655 The <link linkend="insn-data-structure-chanspec">chanspec</link> field
1656 of the <link linkend="insn-data-structure">instruction data
1657 structure</link> is used to …
1661 The <link linkend="insn-data-structure-data">data</link> field
1662 of the <link linkend="insn-data-structure">instruction data
1663 structure</link> is used as follows:
1669 data[1]: is flags, including the flags for the command triggering
1670 configuration. If a command is not subsequently issued on the
1671 subdevice, the command triggering portion of the flags are ignored.
1674 data[2]: determines the mode of operation. The mode of operation
1675 is actually a bitfield that encodes what to do for various
1676 transitions of the source signals.
1680 data[3], data[4]: determine the primary source for the counter,
1682 <link linkend="command-data-struct-scan-begin-src">_src</link> and the
1683 <link linkend="command-data-struct-scan-begin-arg">_arg</link> fields
1685 <link linkend="command-data-struct">command data structure</link>.
1692 Notes: How to specify which events cause a latch and push, and what