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 @@ Bruyninckx Herman.Bruyninckx@mech.kuleuven.ac.be + + Bernd + Porr + Bernd.Porr@glasgow.ac.uk + 1998-2003 David Schleef @@ -40,6 +45,10 @@ 2002-2003 Herman 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. +