doc/install.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="install">
   9         <title>
  10                 Configuration
  11         </title>
  12
  13         <para>
  14                 This section assumes that you have successfully compiled and installed
  15                 the &comedi; software, that your hardware device is in your computer,
  16                 and that you know the relevant details about it, i.e., what kind of
  17                 card it is, any jumper settings related to input ranges, the
  18                 I/O base address and IRQ for old non-plug-n-play boards, etc.
  19         </para>
  20
  21         <section id="cardconfiguration">
  22                 <title>
  23                         Configuration
  24                 </title>
  25                 <para>
  26                   The good news is: on most systems PCI and USB based boards are
  27                   configured automatically. The kernel will
  28                   detect your data acquisition devices, will load the appropriate
  29                   kernel drivers and will create the /dev/comedi entries.
  30 <screen>
  31 bp1@bp1-x61:~/sandbox/comedilib$ ls -l /dev/comedi0*
  32 crw-rw---- 1 root iocard 98,  0 2012-04-26 23:41 /dev/comedi0
  33 crw-rw---- 1 root iocard 98, 48 2012-04-26 23:41 /dev/comedi0_subd0
  34 crw-rw---- 1 root iocard 98, 49 2012-04-26 23:41 /dev/comedi0_subd1
  35 </screen>
  36                   Usually these devices belong to the group "iocard" as shown here. The only
  37                   action you need to take is to become member of this group and
  38                   then the &comedi; device is ready to be used.
  39                 </para>
  40
  41                 <para>
  42                   Old ISA based cards need to be manually configured which is
  43                   explained here. You only need to read on here
  44                   if you have one of these old cards.
  45                   On embedded systems it might also be necessary to load the
  46                   driver and then to configure the boards manually.
  47                   In general manual configuration is done by running
  48                   the <command>comedi_config</command> command (as root).
  49                   Here is an example of how to use the command (perhaps you should read
  50                   its <command>man</command> page now):
  51                   <screen>
  52                     comedi_config /dev/comedi0 labpc-1200 0x260,3
  53                   </screen>
  54                   This command says that the <quote>file</quote>
  55                   <filename>/dev/comedi0</filename> can be used to access the &comedi;
  56                   device that uses the <parameter>labpc-1200</parameter> board, and that
  57                   you give it two run-time parameters (<literal>0x260</literal> and
  58                   <literal>3</literal>). More parameters are possible, and their
  59                   meaning is driver dependant.
  60                 </para>
  61
  62                 <para>
  63                   This tutorial goes through the process of configuring &comedi;
  64                   for two devices, a
  65                   <literal>National Instruments AT-MIO-16E-10</literal>, and a
  66                   <literal>Data Translation DT2821-F-8DI</literal>.
  67                 </para>
  68
  69                 <para>
  70                   The NI board is plug-and-play.  The current ni_atmio driver
  71                   has kernel-level ISAPNP support, which is used by default
  72                   if you do not specify a base address.  So you could simply
  73                   run comedi_config as
  74                   <screen>
  75                     comedi_config /dev/comedi0 ni_atmio
  76                   </screen>
  77                   For the preceding comedi_config command to succeed, the
  78                   ni_atmio kernel module must
  79                   be loaded first.    For plug-n-play boards on
  80                   modern kernels, the appropriate comedi kernel modules should get loaded
  81                   automatically when your computer is booted.
  82                   The <command>modprobe</command> command can
  83                   be used to manually load/unload kernel modules, and <command>lsmod</command>
  84                   will list all the currently loaded modules.
  85                 </para>
  86                 <para>
  87                   For the <literal>Data Translation</literal> board, you need to know
  88                   how the board's jumpers are configured in order to specify the correct
  89                   comedi_config parameters.  These parameters for the board are given in the
  90                   <link endterm="lowleveldrivers">kernel drivers</link> section about the dt282x
  91                   driver.
  92                   The card discussed here is a <literal>DT2821-f-8di</literal>.  The
  93                   entry for the dt282x driver tells you that the
  94                   comedi_config parameters give the driver the I/O base,
  95                   IRQ, DMA 1, DMA 2, and
  96                   in addition the states of the
  97                   differential/single-ended and unipolar/bipolar jumpers:
  98                   <itemizedlist>
  99                     <title>dt282x configuration options:</title>
 100                     <listitem><para>[0] - I/O port base address</para></listitem>
 101                     <listitem><para>[1] - IRQ</para></listitem>
 102                     <listitem><para>[2] - DMA 1</para></listitem>
 103                     <listitem><para>[3] - DMA 2</para></listitem>
 104                     <listitem><para>[4] - AI jumpered for 0=single ended, 1=differential</para></listitem>
 105                     <listitem><para>[5] - AI jumpered for 0=straight binary, 1=2's complement</para></listitem>
 106                     <listitem><para>[6] - AO 0 jumpered for 0=straight binary, 1=2's complement</para></listitem>
 107                     <listitem><para>[7] - AO 1 jumpered for 0=straight binary, 1=2's complement</para></listitem>
 108                     <listitem><para>[8] - AI jumpered for 0=[-10,10]V, 1=[0,10], 2=[-5,5], 3=[0,5]</para></listitem>
 109                     <listitem><para>[9] - AO 0 jumpered for 0=[-10,10]V, 1=[0,10], 2=[-5,5], 3=[0,5],
 110                         4=[-2.5,2.5]</para></listitem>
 111                     <listitem><para>[10]- A0 1 jumpered for 0=[-10,10]V, 1=[0,10], 2=[-5,5], 3=[0,5],
 112                         4=[-2.5,2.5]</para></listitem>
 113                   </itemizedlist>
 114                 </para>
 115
 116                 <para>
 117                   So, the appropriate options list might be:
 118                   <screen>
 119                     0x200,4,0,0,1,1,1,1,0,2,2
 120                   </screen>
 121                   and the full configuration command is:
 122                   <screen>
 123                     comedi_config /dev/comedi1 dt2821-f-8di 0x200,4,0,0,1,1,1,1,0,2,2
 124                   </screen>
 125                   Setting the DMA channels to 0 disables the use of DMA.
 126                 </para>
 127
 128                 <para>
 129                         So now you have your boards configured correctly.
 130                         Since data acquisition boards are not typically well-engineered,
 131                         &comedi; sometimes can't figure out if an old non-plug-n-play
 132                         board is actually in the computer and at the base address you specified.
 133                         If it can't, it assumes you are right.  Both of these boards
 134                         are well-made, so &comedi; will give an error message if it
 135                         can't find them.  The &comedi; kernel module, since it is a part
 136                         of the kernel, prints messages to the kernel logs, which you
 137                         can access through the command <command>dmesg</command> or the file
 138                         <filename>/var/log/messages</filename>.
 139                         Here is a configuration failure (from <command>dmesg</command>):
 140                 </para>
 141
 142 <screen>
 143 comedi0: ni_atmio: 0x0200 can't find board
 144 </screen>
 145
 146                 <para>
 147                         When it does work, you get:
 148                 </para>
 149
 150 <screen>
 151 comedi0: ni_atmio: 0x0260 at-mio-16e-10 ( irq = 3 )
 152 </screen>
 153
 154                 <para>
 155                   Note that it also correctly identified the board.
 156                 </para>
 157
 158         </section>
 159
 160         <section id="gettinginformation">
 161                 <title>
 162                         Getting information about a card
 163                 </title>
 164
 165                 <para>
 166                   So now that you have &comedi; talking to the hardware, try to
 167                   talk to &comedi;.
 168                   Call the command <command>comedi_board_info</command>, which provides information
 169                   about each subdevice on the board.
 170                   Here's part of the output of the <literal>USB-DUX sigma</literal>
 171                   board (which is on <filename>/dev/comedi0</filename>), as a result of
 172                   the command <command>comedi_board_info -v</command>.
 173                 </para>
 174
 175 <screen>
 176 overall info:
 177   version code: 0x00074c
 178   driver name: usbduxsigma
 179   board name: usbduxsigma
 180   number of subdevices: 4
 181 subdevice 0:
 182   type: 1 (analog input)
 183   flags: 0x10119000
 184           SDF_CMD_READ:can do asynchronous input commands
 185           SDF_READABLE:subdevice can be read
 186           SDF_GROUND:can do aref=ground
 187           SDF_LSAMPL:subdevice uses 32-bit samples for commands
 188   number of channels: 16
 189   max data value: 16777215
 190   ranges:
 191     all chans: [-1.325 V,1.325 V]
 192   command:
 193     start: now|int
 194     scan_begin: timer
 195     convert: now
 196     scan_end: count
 197     stop: none|count
 198   command structure filled with probe_cmd_generic_timed for 16 channels:
 199     start: now 0
 200     scan_begin: timer 1000000
 201       scan_begin_src = TRIG_TIMER:
 202       The sampling rate is defined per scan
 203       meaning all channels are sampled at
 204       the same time. The maximum sampling rate is f=1000 Hz
 205     convert: now 0
 206     scan_end: count 16
 207     stop: count 2
 208 subdevice 1:
 209   type: 2 (analog output)
 210   flags: 0x00125000
 211           SDF_CMD_WRITE:can do asynchronous output commands
 212           SDF_WRITABLE:subdevice can be written
 213           SDF_GROUND:can do aref=ground
 214   number of channels: 4
 215   max data value: 255
 216   ranges:
 217     all chans: [0 V,2.5 V]
 218   command:
 219     start: now|int
 220     scan_begin: timer
 221     convert: now
 222     scan_end: count
 223     stop: none|count
 224   command structure filled with probe_cmd_generic_timed for 4 channels:
 225     start: now 0
 226     scan_begin: timer 1000000
 227       scan_begin_src = TRIG_TIMER:
 228       The sampling rate is defined per scan
 229       meaning all channels are sampled at
 230       the same time. The maximum sampling rate is f=1000 Hz
 231     convert: now 0
 232     scan_end: count 4
 233     stop: count 2
 234 subdevice 2:
 235   type: 5 (digital I/O)
 236   flags: 0x00030000
 237           SDF_READABLE:subdevice can be read
 238           SDF_WRITABLE:subdevice can be written
 239   number of channels: 24
 240   max data value: 1
 241   ranges:
 242     all chans: [0 V,5 V]
 243   command:
 244     not supported
 245 subdevice 3:
 246   type: 12 (pwm)
 247   flags: 0x00020100
 248           SDF_MODE1:can do mode 1
 249           SDF_WRITABLE:subdevice can be written
 250   number of channels: 8
 251   max data value: 512
 252   ranges:
 253     all chans: [0,1]
 254   command:
 255     not supported
 256 </screen>
 257
 258 <para>
 259   This board has four subdevices.  Devices are separated into
 260   subdevices that each have a distinct purpose; e.g., analog
 261   input, analog output, digital input/output.
 262 </para>
 263
 264
 265 <para>
 266   Here's the information from comedi's proc
 267   file, which indicates what drivers are loaded and which
 268   boards are configured:
 269 </para>
 270
 271 <screen>
 272 cat /proc/comedi
 273 </screen>
 274
 275 <screen>
 276 comedi version 0.7.76
 277 format string: "%2d: %-20s %-20s %4d",i,driver_name,board_name,n_subdevices
 278  0: usbduxsigma          usbduxsigma             4
 279 usbduxfast:
 280  usbduxfast
 281 usbduxsigma:
 282  usbduxsigma
 283 </screen>
 284
 285 <para>
 286   This documentation feature currently returns the driver name, the device name, and the number of
 287   subdevices. Following those lines are a list of the comedi kernel
 288   driver modules currently loaded, each followed by a list of the board
 289   names it recognizes (names that can be used with comedi_config).
 290 </para>
 291
 292
 293 </section>
 294
 295 </section>