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