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">
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.
21 <section id="cardconfiguration">
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.
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
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.
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.
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:
71 options comedi comedi_num_legacy_minors=4
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.
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):
90 comedi_config /dev/comedi0 labpc-1200 0x260,3
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.
101 This tutorial goes through the process of configuring &comedi;
103 National Instruments AT-MIO-16E-10, and a
104 Data Translation DT2821-F-8DI.
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
113 comedi_config /dev/comedi0 ni_atmio
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.
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>
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:
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>
155 So, the appropriate options list might be:
157 0x200,4,0,0,1,1,1,1,0,2,2
159 and the full configuration command is:
161 comedi_config /dev/comedi1 dt2821-f-8di 0x200,4,0,0,1,1,1,1,0,2,2
163 Setting the DMA channels to 0 disables the use of DMA.
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>):
181 comedi0: ni_atmio: 0x0200 can't find board
185 When it does work, you get:
189 comedi0: ni_atmio: 0x0260 at-mio-16e-10 ( irq = 3 )
193 Note that it also correctly identified the board.
198 <section id="gettinginformation">
200 Getting information about a card
204 So now that you have &comedi; talking to the hardware, try to
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>.
215 version code: 0x00074c
216 driver name: usbduxsigma
217 board name: usbduxsigma
218 number of subdevices: 4
220 type: 1 (analog input)
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
229 all chans: [-1.325 V,1.325 V]
236 command structure filled with probe_cmd_generic_timed for 16 channels:
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
247 type: 2 (analog output)
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
255 all chans: [0 V,2.5 V]
262 command structure filled with probe_cmd_generic_timed for 4 channels:
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
273 type: 5 (digital I/O)
275 SDF_READABLE:subdevice can be read
276 SDF_WRITABLE:subdevice can be written
277 number of channels: 24
286 SDF_MODE1:can do mode 1
287 SDF_WRITABLE:subdevice can be written
288 number of channels: 8
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.
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:
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
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>).