doc/install.sgml

   1 <!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> -->
   2
   3 <section id="install">
   4 <title>
   5 Configuration
   6 </title>
   7
   8 <para>
   9 This section assumes that you have successfully compiled and installed
  10 the &comedi; software, that your hardware device is in your computer,
  11 and that you know the relevant details about it, i.e., what kind of
  12 card it is, the I/O base, the IRQ, jumper settings related to input
  13 ranges, etc.
  14 </para>
  15
  16
  17 <section id="cardconfiguration">
  18 <title>
  19 Configuration
  20 </title>
  21 <para>
  22 Before being able to get information from a DAQ card, you first have
  23 to tell the &comedi; core kernel module which device you have, which
  24 driver you want to attach to the card, and which run-time options
  25 you want to give to the driver. This configuration is done by running
  26 the <command>comedi_config</command> command. (As root of course.)
  27 Here is an example of how to use the command (perhaps you should read
  28 its <command>man</command> page now):
  29 <screen>
  30 PATH=/sbin:/usr/sbin:/usr/local/sbin:$PATH
  31 comedi_config /dev/comedi0 labpc-1200 0x260,3
  32 </screen>
  33 This command says that the <quote>file</quote>
  34 <filename>/dev/comedi0</filename> can be used to access the &comedi;
  35 device that uses the <parameter>labpc-1200</parameter> board, and that
  36 you give it two run-time parameters (<literal>0x260</literal> and
  37 <literal>3</literal>). More parameters are possible, for example to
  38 discriminate between two or more identical cards in your system.
  39 </para>
  40 <para>
  41 If you want to have the board configured in this way every time you
  42 boot, put the lines above into a start-up script file of your Linux
  43 system (for example, the
  44 <filename>/etc/rc.d/rc.local</filename> file), or for PCMCIA
  45 boards the appropriate place is the /etc/pcmcia/comedi script.
  46 For non-PCMCIA boards, you can also arrange to have your driver
  47 loaded and comedi_config run with by adding a few lines
  48 to /etc/modules.conf (see the INSTALL file for the comedi
  49 kernel modules). You can, of course, also run comedi_config
  50 at a command prompt.
  51 </para>
  52
  53 <para>
  54 This tutorial goes through the process of configuring &comedi;
  55 for two devices, a
  56 <literal>National Instruments AT-MIO-16E-10</literal>, and a
  57 <literal>Data Translation DT2821-F-8DI</literal>.
  58 </para>
  59
  60 <para>
  61 The NI board is plug-and-play.  The current ni_atmio driver
  62 has kernel-level ISAPNP support, which is used by default
  63 if you do not specify a base address.  So you could simply
  64 run comedi_config as
  65 <screen>
  66 comedi_config /dev/comedi0 ni_atmio
  67 </screen>
  68 </para>
  69 <para>
  70
  71 For the <literal>Data Translation</literal> board, you need to have a
  72 list of the jumper settings; these are given in the &comedi; manual
  73 section about this card. (Check first to see whether they are still
  74 correct!)
  75 The card discussed her is a <literal>DT2821-f-8di</literal>.  The
  76 <command>man</command> page of <command>comedi_config</command> tells
  77 you that you need to know the I/O base, IRQ, DMA 1, DMA 2.  However,
  78 the &comedi; driver also recognizes the
  79 differential/single-ended and unipolar/bipolar jumpers.  As always,
  80 the source is the final authority, and looking in
  81 <filename>module/dt282x.c</filename>
  82 tells us that the options list is interpreted as:
  83 </para>
  84 <para>
  85 (... TO BE FILLED IN ...)
  86 </para>
  87
  88 <!-- XXX
  89 <itemize>
  90 <item>I/O base
  91 <item>IRQ
  92 <item>1=differential, 0=single ended
  93 <item>ai 0=unipolar, 1=bipolar
  94 <item>ao0 0=unipolar, 1=bipolar
  95 <item>ao1 0=unipolar, 1=bipolar
  96 <item>dma1
  97 <item>dma2
  98 </itemize>
  99 (ai=analog input, ao=analog output.)
 100 -->
 101
 102 <para>
 103 So, the appropriate options list is:
 104 <screen>
 105 0x200,4,,1,1,1
 106 </screen>
 107 and the full configuration command is:
 108 <screen>
 109 comedi_config /dev/comedi1 dt2821-f-8di 0x200,4,,1,1,1
 110 </screen>
 111 The differential/single-ended number is left blank, since the
 112 driver already knowns (from the board name), that it is
 113 differential. Also the DMA numbers are left blank, since we
 114 don't want the driver to use DMA.  (Which could interfere
 115 with the sound card...)
 116 Keep in mind that things commented in the source, but not in
 117 the documentation are about as likely to change as the weather,
 118 so put good comments next to the following line when you put
 119 it in a start-up file.
 120 </para>
 121
 122 <para>
 123 So now you have your boards configured correctly.
 124 Since data acquisition boards are not typically well-engineered,
 125 &comedi; sometimes can't figure out if the board is actually there.
 126 If it can't, it assumes you are right.  Both of these boards
 127 are well-made, so &comedi; will give an error message if it
 128 can't find them.  The &comedi; kernel module, since it is a part
 129 of the kernel, prints messages to the kernel logs, which you
 130 can access through the command <command>dmesg</command> or the file
 131 <filename>/var/log/messages</filename>.
 132 Here is a configuration failure (from <command>dmesg</command>):
 133 </para>
 134
 135 <screen>
 136 comedi0: ni_atmio: 0x0200 can't find board
 137 </screen>
 138
 139 <para>
 140 When it does work, you get:
 141 </para>
 142
 143 <screen>
 144 comedi0: ni_atmio: 0x0260 at-mio-16e-10 ( irq = 3 )
 145 </screen>
 146
 147 <para>
 148 Note that it also correctly identified the board.
 149 </para>
 150
 151 </section>
 152
 153 <section id="gettinginformation">
 154 <title>
 155 Getting information about a card
 156 </title>
 157
 158 <para>
 159 So now that you have &comedi; talking to the hardware, try to
 160 talk to &comedi;.  Here's some pretty low-level information, which can
 161 sometimes be useful for debugging:
 162 </para>
 163
 164 <screen>
 165 cat /proc/comedi
 166 </screen>
 167
 168 <para>
 169 On the particular system this demonstration was carried out, this
 170 command gives:
 171 </para>
 172
 173 <screen>
 174 comedi version 0.6.4
 175 format string
 176  0: ni_atmio             at-mio-16e-10           7
 177  1: dt282x               dt2821-f-8di            4
 178 </screen>
 179
 180 <para>
 181 This documentation feature is not well-developed yet.  Basically, it
 182 currently returns the driver name, the device name, and the number of
 183 subdevices.
 184 </para>
 185
 186 <para>
 187 In the <filename role=directory>demo/</filename> directory, there is a
 188 command called <command>info</command>, which provides information
 189 about each subdevice on the board.  Its output can be rather long,
 190 if the board has several subdevices.
 191 Here's part of the output of the <literal>National Instruments</literal>
 192 board (which is on <filename>/dev/comedi0</filename>), as a result of
 193 the command <command>demo/info /dev/comedi0</command>:
 194 </para>
 195
 196 <screen>
 197 overall info:
 198   version code: 0x000604
 199   driver name: ni_atmio
 200   board name: at-mio-16e-10
 201   number of subdevices: 7
 202 subdevice 0:
 203   type: 1 (analog input)
 204   number of channels: 16
 205   max data value: 4095
 206 ...
 207 </screen>
 208
 209 <para>
 210 The overall info gives information about the device; basically
 211 the same information as <filename>/proc/comedi</filename>.
 212 </para>
 213
 214 <para>
 215 This board has seven subdevices.  Devices are separated into
 216 subdevices that each have a distinct purpose; e.g., analog
 217 input, analog output, digital input/output.  This board also
 218 has an EEPROM and calibration DACs that are also subdevices.
 219 </para>
 220
 221 <para>
 222 &comedi; has more information about the device than what is displayed
 223 above, but <command>demo/info</command> doesn't currently display
 224 this.
 225 </para>
 226
 227 </section>
 228
 229 </section>