doc/tutorial.xml

   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">
   5 %comedilib_entities;
   6 ]>
   7
   8 <section id="writingprograms" xmlns:xi="http://www.w3.org/2001/XInclude">
   9   <title>
  10     Writing &comedi; programs
  11   </title>
  12   <para>
  13     This section describes how &comedi;
  14     can be used in an application, to communicate data with a set
  15     of &comedi; devices.
  16     <xref linkend="acquisitionfunctions"/> gives more details about
  17     the various acquisition functions with which the application
  18     programmer can perform data acquisition in &comedi;.
  19   </para>
  20   <para>
  21     Also don't forget to take a good look at the
  22     <filename class="directory">demo</filename>
  23     directory of the Comedilib source code. It contains lots of examples
  24     for the basic functionalities of &comedi;.
  25   </para>
  26
  27   <section id="firstprogram">
  28     <title>
  29       Your first &comedi; program
  30     </title>
  31
  32     <para>
  33       This example requires a card that has analog or digital input. This
  34       progam opens the device, gets the data, and prints it out:
  35       <programlisting>
  36         <xi:include href="../demo/tut1.c" parse="text"/>
  37       </programlisting>
  38     </para>
  39     <para>
  40       The source code file for the above program can be found in Comedilib,
  41       at <filename>demo/tut1.c</filename>.  You can compile the program using
  42     </para>
  43
  44     <screen>
  45       cc tut1.c -lcomedi -o tut1
  46     </screen>
  47     <para>
  48       The
  49       <function>
  50         <link linkend="func-ref-comedi-open">comedi_open</link>
  51       </function> call can only be successful if the
  52       <filename>comedi0</filename> device file is configured with a
  53       valid &comedi; driver. <xref linkend="cardconfiguration"/> explains
  54       how this driver is linked to the <quote>device file</quote>.
  55     </para>
  56     <para>
  57       The <parameter class="function">range</parameter> variable tells
  58       &comedi; which gain to use when measuring an analog voltage.  Since we
  59       don't know (yet) which numbers are valid, or what each means, we'll
  60       use <literal>0</literal>, because it won't cause errors.  Likewise
  61       with <parameter class="function">aref</parameter>, which determines the
  62       analog reference used.
  63     </para>
  64   </section>
  65
  66
  67   <section id="convertingsamples">
  68     <title>
  69       Converting between integer data and physical units
  70     </title>
  71
  72     <para>
  73       If you selected an analog input subdevice, you probably noticed
  74       that the output of <command>tut1</command> is an unsigned
  75       number, for example between <literal>0</literal>
  76       and <literal>65535</literal> for a 16 bit analog input. &comedi;
  77       samples are unsigned, with <literal>0</literal> representing the
  78       lowest voltage of the ADC, and a hardware-dependent maximum
  79       value representing the highest voltage.  &comedi; compensates
  80       for anything else the manual for your device says (for example,
  81       many boards represent bipolar analog input voltages as signed
  82       integers).  However, you probably prefer to have this number
  83       translated to a voltage.  Naturally, as a good programmer, your
  84       first question is: <quote>How do I do this in a
  85       device-independent manner?</quote>
  86     </para>
  87
  88     <para>
  89       The functions
  90       <link linkend="func-ref-comedi-to-physical"><function>comedi_to_physical</function></link>, <link linkend="func-ref-comedi-to-phys"><function>comedi_to_phys</function></link>,
  91       <link linkend="func-ref-comedi-from-physical"><function>comedi_from_physical</function></link> and <link linkend="func-ref-comedi-from-phys"><function>comedi_from_phys</function></link>
  92       are used to convert between &comedi;'s integer data and floating point numbers corresponding
  93       to physical values (voltages, etc.).
  94     </para>
  95
  96   </section>
  97
  98   <section id="secondprogram">
  99     <title>
 100       Your second &comedi; program
 101     </title>
 102
 103
 104     <para>
 105       Actually, this is the first &comedi; program again, except
 106       we've added code to convert the integer data value to physical units.
 107     </para>
 108
 109     <programlisting>
 110       <xi:include href="../demo/tut2.c" parse="text"/>
 111     </programlisting>
 112     <para>
 113       The source code file for the above program can be found in
 114       the comedilib source at demo/tut2.c and if installed as a package usually
 115       at /usr/share/doc/libcomedi-dev/demo/ with all the other tutorial/demo
 116       files.
 117     </para>
 118   </section>
 119
 120   <section id="asyncprogram">
 121     <title>
 122       Asynchronous acquisition
 123     </title>
 124     <para>
 125       Of special importance is the so called
 126       "asynchronous data acquisition" where &comedi; is sampling
 127       in the background at a given sample rate. The
 128       user can retrieve the data whenever it is convenient.
 129       &comedi; stores the data in a ring-buffer so that
 130       programs can perform other tasks in the foreground, for example
 131       plotting data or interacting with the user.
 132       This technique is used in programs such
 133       as <command>ktimetrace</command> or <command>comedirecord</command>.
 134     </para>
 135     <para>
 136       There are two different ways how a sequence of channels is
 137       measured during asynchronous acquisition (see also the Figure in
 138       the introduction):
 139     <itemizedlist>
 140       <listitem>
 141         The channels are measured with the help
 142         of a multiplexer which switches to the next channel after each measurement.
 143         This means that the sampling rate is divided by the number
 144         of channels.
 145       </listitem>
 146       <listitem>
 147         The channels are all measured at the same time, for example
 148         when every channel has its own converter. In this case the
 149         sampling rate need not to be divided by the number of channels.
 150       </listitem>
 151     </itemizedlist>
 152     How your &comedi; device handles the asynchronous acquisition can be found out
 153     with the command <command>comedi_board_info -v</command>.
 154     </para>
 155     <para>
 156       The program <command>tut3.c</command> demonstrates the
 157       asynchronous acquisition. The general strategy is always
 158       the same: first, we tell &comedi; all sampling parameters such as
 159       the sampling rate,
 160       the number of channels and anything it needs to know
 161       so that it can run independently in the background.
 162       Then &comedi; checks our request and it might
 163       modify it. For example we might want to have a sampling rate of
 164       16kHz but we only get 1kHz. Finally we can start
 165       the asynchronous acquisition. Once it has been started we
 166       need to check periodically if data is available and
 167       request it from &comedi; so that its internal buffer
 168       won't overrun.
 169     </para>
 170     <para>
 171       In summary the asynchonous acquisition is performed in the following
 172       way:
 173     </para>
 174     <itemizedlist>
 175       <listitem>
 176         Create a command structure of type <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
 177       </listitem>
 178       <listitem>
 179         Call the
 180         function <link linkend="func-ref-comedi-get-cmd-generic-timed"><function>comedi_get_cmd_generic_timed</function></link>
 181         to fill the command structure with your comedi device,
 182         subdevice, sampling rate and number of channels.
 183       </listitem>
 184       <listitem>
 185         Create a channel-list and store it in the command structure. This
 186         tells comedi which channels should be sampled in the background.
 187       </listitem>
 188       <listitem>
 189         Call <link linkend="func-ref-comedi-command-test"><function>comedi_command_test</function></link> with your command structure. Comedi might modify your requested sampling rate and channels.
 190       </listitem>
 191       <listitem>
 192         Call <link linkend="func-ref-comedi-command-test"><function>comedi_command_test</function></link> again which now should return zero for success.
 193       </listitem>
 194       <listitem>
 195         Call <link linkend="func-ref-comedi-command"><function>comedi_command</function></link> to start the asynchronous acquisition. From now on the kernel ringbuffer will be filled at the specified sampling rate.
 196       </listitem>
 197       <listitem>
 198         Call periodically the standard
 199         function <function>read</function> and receive the data. The
 200         result should always be non zero as long as the acquisition
 201         is running.
 202       </listitem>
 203       <listitem>
 204         Convert the received data either into <link linkend="ref-type-lsampl-t">lsampl_t</link> or <link linkend="ref-type-sampl-t">sampl_t</link> depending on the subdevice flag SDF_LSAMPL.
 205       </listitem>
 206       <listitem>
 207         Poll for data with <function>read</function> as long as it returns
 208         a positive result or until the program terminates.
 209       </listitem>
 210     </itemizedlist>
 211
 212     <para>
 213       The program below is a stripped down version of the
 214       program <command>cmd.c</command> in the demo directory. To
 215       compile it run:
 216     </para>
 217     <screen>
 218       gcc tut3.c -lcomedi -lm -o tut3
 219     </screen>
 220     <para>
 221       It requests data from two channels at
 222       a sampling rate of 1kHz and a total of 10000 samples.
 223       which are then printed to stdout. You can pipe the data
 224       into a file and plot it with gnuplot. As mentioned above, central in this
 225       program is the loop using the standard C <function>read</function> command
 226       which receives the buffer contents. Below is an
 227       extract from <filename>tut3.c</filename> showing the
 228       relevant commands:
 229     </para>
 230     <programlisting>
 231       <xi:include href="../demo/tut3_part.c" parse="text"/>
 232     </programlisting>
 233     <para>
 234       For advanced programmers the
 235       function <link linkend="func-ref-comedi-get-buffer-contents"><function>comedi_get_buffer_contents</function></link>
 236       is useful to check if there is actually data in the ringbuffer
 237       so that a call of <function>read</function> can be avoided for example
 238       when the data readout is called by a timer call-back function.
 239     </para>
 240   </section>
 241
 242   <section>
 243     <title>Further examples</title>
 244     <para>
 245       See the demo subdirectory of Comedilib for more example programs.
 246       The directory contains
 247       a README file with descriptions of the various demo programs.
 248     </para>
 249   </section>
 250
 251 </section>