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       The program <command>tut3.c</command> demonstrates the
 137       asynchronous acquisition. The general strategy is always
 138       the same: first, we tell &comedi; all sampling parameters such as
 139       the sampling rate,
 140       the number of channels and anything it needs to know
 141       so that it can run independently in the background.
 142       Then &comedi; checks our request and it might
 143       modify it. For example we might want to have a sampling rate of
 144       16kHz but we only get 1kHz. Finally we can start
 145       the asynchronous acquisition. Once it has been started we
 146       need to check periodically if data is available and
 147       request it from &comedi; so that its internal buffer
 148       won't overrun.
 149     </para>
 150     <para>
 151       In summary the asynchonous acquisition is performed in the following
 152       way:
 153     </para>
 154     <itemizedlist>
 155       <listitem>
 156         Create a command structure of type <link linkend="ref-type-comedi-cmd">comedi_cmd</link>
 157       </listitem>
 158       <listitem>
 159         Call the
 160         function <link linkend="func-ref-comedi-get-cmd-generic-timed"><function>comedi_get_cmd_generic_timed</function></link>
 161         to fill the command structure with your comedi device,
 162         subdevice, sampling rate and number of channels.
 163       </listitem>
 164       <listitem>
 165         Create a channel-list and store it in the command structure. This
 166         tells comedi which channels should be sampled in the background.
 167       </listitem>
 168       <listitem>
 169         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.
 170       </listitem>
 171       <listitem>
 172         Call <link linkend="func-ref-comedi-command-test"><function>comedi_command_test</function></link> again which now should return zero for success.
 173       </listitem>
 174       <listitem>
 175         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.
 176       </listitem>
 177       <listitem>
 178         Call periodically the standard
 179         function <function>read</function> and receive the data. The
 180         result should always be non zero as long as the acquisition
 181         is running.
 182       </listitem>
 183       <listitem>
 184         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.
 185       </listitem>
 186       <listitem>
 187         Poll for data with <function>read</function> as long as it returns
 188         a positive result or until the program terminates.
 189       </listitem>
 190     </itemizedlist>
 191
 192     <para>
 193       The program below is a stripped down version of the
 194       program <command>cmd.c</command> in the demo directory. To
 195       compile it run:
 196     </para>
 197     <screen>
 198       gcc tut3.c -lcomedi -lm -o tut3
 199     </screen>
 200     <para>
 201       It requests data from two channels at
 202       a sampling rate of 1kHz and a total of 10000 samples.
 203       which are then printed to stdout. You can pipe the data
 204       into a file and plot it with gnuplot. As mentioned above, central in this
 205       program is the loop using the standard C <function>read</function> command
 206       which receives the buffer contents. Below is an
 207       extract from <filename>tut3.c</filename> showing the
 208       relevant commands:
 209     </para>
 210     <programlisting>
 211       <xi:include href="../demo/tut3_part.c" parse="text"/>
 212     </programlisting>
 213     <para>
 214       For advanced programmers the
 215       function <link linkend="func-ref-comedi-comedi-get-buffer-contents"><function>comedi_get_buffer_contents</function></link>
 216       is useful to check if there is actually data in the ringbuffer
 217       so that a call of <function>read</function> can be avoided for example
 218       when the data readout is called by a timer call-back function.
 219     </para>
 220   </section>
 221
 222   <section>
 223     <title>Further examples</title>
 224     <para>
 225       See the demo subdirectory of Comedilib for more example programs.
 226       The directory contains
 227       a README file with descriptions of the various demo programs.
 228     </para>
 229   </section>
 230
 231 </section>