doc/install.sgml

   1 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
   2
   3
   4 <section>
   5 <title>
   6 Installation and Configuration
   7 </title>
   8
   9 <para>
  10 I assume that your hardware device is in your computer, and that
  11 you know the relevant details about it, i.e., what kind of card
  12 it is, the I/O base, the IRQ, jumper settings related to input
  13 ranges, etc.
  14 </para>
  15
  16 <para>
  17 To tell the comedi kernel module that you have a particular device, and
  18 some information about it, you will be running the comedi_config
  19 command.  Perhaps you should read the man page now.
  20 </para>
  21
  22 <para>
  23 In this tutorial, I will go through the process of configuring comedi
  24 for two devices, a National Instruments AT-MIO-16E-10
  25 and a Data Translation DT2821-F-8DI.
  26 </para>
  27
  28 <para>
  29 The NI board is plug-and-play, and the man page tells me that I need
  30 to configure the PnP part of the board with isapnptools.  The isapnptools
  31 package is a little cryptic, but the concepts are simple.  Once I
  32 learned how to use it, I settled on a /etc/isapnp.conf file that
  33 contained the lines:
  34 </para>
  35
  36
  37 <screen>
  38 # ANSI string --&gt;National Instruments, AT-MIO-16E-10&lt;--
  39 (CONFIGURE NIC2400/10725401 (LD 0
  40         (IO 0 (BASE 0x0260))
  41         (INT 0 (IRQ 3 (MODE +E)))
  42 #       (DMA 0 (CHANNEL 5))
  43 #       (DMA 1 (CHANNEL 6))
  44         (ACT Y)
  45 ))
  46 </screen>
  47
  48
  49 <para>
  50 It also contains a few lines about overall configuration and about my
  51 sound card.  I found out after a bit of trial-and-error that the NI
  52 board does not always work with interrupts other than IRQ 3.  YMMV.
  53 Currently, the driver doesn't use DMA, but it may in the future, so
  54 I commented out the DMA lines.  It is a curious fact that the device
  55 ignores the IRQ and DMA information given here, however, I keep the
  56 information here to remind myself that the numbers aren't arbitrary.
  57 </para>
  58
  59 <para>
  60 When I run comedi_config (as root, of course), I provide the same
  61 information.  Since I want to have the board configured every time
  62 I boot, I put the line
  63 </para>
  64
  65 <screen>
  66 /usr/sbin/comedi_config /dev/comedi0 ni_atmio 0x260,3
  67 </screen>
  68
  69 <para>
  70 into <filename>/etc/rc.d/rc.local</filename>.  You can, of course, run this command at
  71 a command prompt.  The man page tells me that the option list
  72 is supposed to be "(I/O base),(IRQ)", so I used the same numbers
  73 as I put in /etc/isapnp.conf, i.e., 0x260,3.
  74 </para>
  75
  76 <para>
  77 For the Data Translation board, I need to have a list of the
  78 jumper settings.  Fortunately, I wrote them all down in the
  79 manual -- I hope they are still correct.  However, I had to
  80 open the case to figure out which board in the series I had.
  81 It is a DT2821-f-8di.  The man page of comedi_config tells
  82 me that I need to know the I/O base, IRQ, DMA 1, DMA 2.  However,
  83 since I wrote the driver, I know that it also recognizes the
  84 differential/single-ended and unipolar/bipolar jumpers.  As always,
  85 the source is the final authority, and looking in module/dt282x.c
  86 tells me that the options list is interpreted as:
  87 </para>
  88
  89 <!-- XXX
  90 <itemize>
  91 <item>I/O base
  92 <item>IRQ
  93 <item>1=differential, 0=single ended
  94 <item>ai 0=unipolar, 1=bipolar
  95 <item>ao0 0=unipolar, 1=bipolar
  96 <item>ao1 0=unipolar, 1=bipolar
  97 <item>dma1
  98 <item>dma2
  99 </itemize>
 100 -->
 101
 102 <para>
 103 (ai=analog input, ao=analog output.)  From this, I decide that
 104 the appropriate options list is
 105 </para>
 106
 107 <screen>
 108 0x200,4,,1,1,1
 109 </screen>
 110
 111 <para>
 112 I left the differential/single-ended number blank, since the
 113 driver already knowns (from the board name), that it is
 114 differential.  I  also left the DMA numbers blank, since I
 115 don't want the driver to use DMA.  (Don't want it to interfere
 116 with my sound card -- life is full of difficult choices.)
 117 Keep in mind that things commented in the source, but not in
 118 the documentation are about as likely to change as the weather,
 119 so I put good comments next to the following line when I put
 120 it in rc.local.
 121 </para>
 122
 123 <screen>
 124 /usr/sbin/comedi_config /dev/comedi1 dt2821-f-8di 0x200,4,,1,1,1
 125 </screen>
 126
 127 <para>
 128 So now I think that I have my boards configured correctly.
 129 Since data acquisition boards are not typically well-engineered,
 130 Comedi sometimes can't figure out if the board is actually there.
 131 If it can't, it assumes you are right.  Both of these boards
 132 are well-made, so comedi will give me an error message if it
 133 can't find them.  The comedi kernel module, since it is a part
 134 of the kernel, prints messages to the kernel logs, which you
 135 can access through the command 'dmesg' or /var/log/messages.
 136 Here is a configuration failure (from dmesg):
 137 </para>
 138
 139 <screen>
 140 comedi0: ni_atmio: 0x0200 can't find board
 141 </screen>
 142
 143 <para>
 144 When it does work, I get:
 145 </para>
 146
 147 <screen>
 148 comedi0: ni_atmio: 0x0260 at-mio-16e-10 ( irq = 3 )
 149 </screen>
 150
 151 <para>
 152 Note that it also correctly identified my board.
 153 </para>
 154
 155
 156 <section>
 157 <title>
 158 Getting information from comedi
 159 </title>
 160
 161 <para>
 162 So now that we have comedi talking to the hardware, we want to
 163 talk to comedi.  Here's some pretty low-level information --
 164 it's sometimes useful for debugging:
 165 </para>
 166
 167 <screen>
 168 cat /proc/comedi
 169 </screen>
 170
 171 <para>
 172 Right now, on my computer, this command gives:
 173 </para>
 174
 175 <screen>
 176 comedi version 0.6.4
 177 format string
 178  0: ni_atmio             at-mio-16e-10           7
 179  1: dt282x               dt2821-f-8di            4
 180 </screen>
 181
 182 <para>
 183 This is a feature that is not well-developed yet.  Basically, it
 184 currently tells you driver name, device name, and number of
 185 subdevices.
 186 </para>
 187
 188 <para>
 189 In the <filename>demo/</filename> directory, there is a command called
 190 <command>info</command>, which provides information about each
 191 subdevice on the
 192 board.  The output of it is rather long, since I have 7
 193 subdevices  (4 or fewer is common for other boards.)
 194 Here's part of the output of the NI board (which
 195 is on <filename>/dev/comedi0</filename>.)  ('demo/info /dev/comedi0')
 196 </para>
 197
 198 <screen>
 199 overall info:
 200   version code: 0x000604
 201   driver name: ni_atmio
 202   board name: at-mio-16e-10
 203   number of subdevices: 7
 204 subdevice 0:
 205   type: 1 (unknown)
 206   number of channels: 16
 207   max data value: 4095
 208 ...
 209 </screen>
 210
 211 <para>
 212 The overall info gives information about the device -- basically
 213 the same information as /proc/comedi.
 214 </para>
 215
 216 <para>
 217 This board has 7 subdevices.  Devices are separated into
 218 subdevices that each have a distinct purpose -- e.g., analog
 219 input, analog output, digital input/output.  This board also
 220 has an EEPROM and calibration DACs that are also subdevices.
 221 </para>
 222
 223 <para>
 224 Subdevice 0 is the analog input subdevice.  You would have
 225 known this from the 'type: 1 (unknown)' line, if I've updated
 226 demo/info recently, because it would say 'type: 1 (analog input)'
 227 instead.  The other lines should be self-explanitory.  Comedi
 228 has more information about the device, but demo/info doesn't
 229 currently display this.
 230 </para>
 231
 232
 233 </section>
 234 </section>