diff --git a/doc/comedilib.xml b/doc/comedilib.xml
index f7bfabe..082ad83 100644
--- a/doc/comedilib.xml
+++ b/doc/comedilib.xml
@@ -28,6 +28,11 @@
BruyninckxHerman.Bruyninckx@mech.kuleuven.ac.be
+
+ Bernd
+ Porr
+ Bernd.Porr@glasgow.ac.uk
+ 1998-2003David Schleef
@@ -40,6 +45,10 @@
2002-2003Herman Bruyninckx
+
+ 2012
+ Bernd Porr
+
diff --git a/doc/tutorial.xml b/doc/tutorial.xml
index a7fb4dc..b4ccfeb 100644
--- a/doc/tutorial.xml
+++ b/doc/tutorial.xml
@@ -71,19 +71,18 @@
If you selected an analog input subdevice, you probably noticed
- that the output of tut1 is an unsigned number, for
- example between 0 and 65535
- for a 16 bit analog input. &comedi; samples are
- unsigned,
- with 0 representing the lowest voltage of the ADC,
- and a hardware-dependent maximum value representing the highest voltage.
- &comedi; compensates for anything else the manual for
- your device says (for example, many boards represent bipolar
- analog input voltages as signed integers).
- However, you probably prefer to have this number
- translated to a voltage. Naturally, as a good programmer, your first
- question is: How do I do this in a device-independent
- manner?
+ that the output of tut1 is an unsigned
+ number, for example between 0
+ and 65535 for a 16 bit analog input. &comedi;
+ samples are unsigned, with 0 representing the
+ lowest voltage of the ADC, and a hardware-dependent maximum
+ value representing the highest voltage. &comedi; compensates
+ for anything else the manual for your device says (for example,
+ many boards represent bipolar analog input voltages as signed
+ integers). However, you probably prefer to have this number
+ translated to a voltage. Naturally, as a good programmer, your
+ first question is: How do I do this in a
+ device-independent manner?
@@ -111,7 +110,10 @@
- The source code file for the above program can be found in Comedilib, at demo/tut2.c.
+ The source code file for the above program can be found in
+ the comedilib source at demo/tut2.c and if installed as a package usually
+ at /usr/share/doc/libcomedi-dev/demo/ with all the other tutorial/demo
+ files.
@@ -121,9 +123,9 @@
Of special importance is the so called
- "asynchronous data acquisition" where the &comedi; is sampling
+ "asynchronous data acquisition" where &comedi; is sampling
in the background at a given sample rate. The
- the user can retrieve the data whenever it is convenient.
+ user can retrieve the data whenever it is convenient.
&comedi; stores the data in a ring-buffer so that
programs can perform other tasks in the foreground, for example
plotting data or interacting with the user.
@@ -140,15 +142,57 @@
Then &comedi; checks our request and it might
modify it. For example we might want to have a sampling rate of
16kHz but we only get 1kHz. Finally we can start
- the asynchronous acquisition. Once it is started we
+ the asynchronous acquisition. Once it has been started we
need to check periodically if data is available and
request it from &comedi; so that its internal buffer
won't overrun.
- The program below is a stripped down version
- of the program cmd.c in
- the demo directory. To compile it run:
+ In summary the asynchonous acquisition is performed in the following
+ way:
+
+
+
+ Create a command structure of type comedi_cmd
+
+
+ Call the
+ function comedi_get_cmd_generic_timed
+ to fill the command structure with your comedi device,
+ subdevice, sampling rate and number of channels.
+
+
+ Create a channel-list and store it in the command structure. This
+ tells comedi which channels should be sampled in the background.
+
+
+ Call comedi_command_test with your command structure. Comedi might modify your requested sampling rate and channels.
+
+
+ Call comedi_command_test again which now should return zero for success.
+
+
+ Call comedi_command to start the asynchronous acquisition. From now on the kernel ringbuffer will be filled at the specified sampling rate.
+
+
+ Call periodically the standard
+ function read and receive the data. The
+ result should always be non zero as long as the acquisition
+ is running.
+
+
+ Convert the received data either into lsampl_t or sampl_t depending on the subdevice flag SDF_LSAMPL.
+
+
+ Poll for data with read as long as it returns
+ a positive result or until the program terminates.
+
+
+
+
+ The program below is a stripped down version of the
+ program cmd.c in the demo directory. To
+ compile it run:
gcc tut3.c -lcomedi -lm -o tut3
@@ -157,8 +201,8 @@
It requests data from two channels at
a sampling rate of 1kHz and a total of 10000 samples.
which are then printed to stdout. You can pipe the data
- into a file and plot it with gnuplot. Central in this
- program is the loop using the standard C read command
+ into a file and plot it with gnuplot. As mentioned above, central in this
+ program is the loop using the standard C read command
which receives the buffer contents. Below is an
extract from tut3.c showing the
relevant commands:
@@ -166,6 +210,13 @@
+
+ For advanced programmers the
+ function comedi_get_buffer_contents
+ is useful to check if there is actually data in the ringbuffer
+ so that a call of read can be avoided for example
+ when the data readout is called by a timer call-back function.
+