comedilib/doc/install.xml
Ian Abbott 2c810c12e3 doc/install.xml: Describe comedi_num_legacy_minors.
Add some info to the Install section about reserving devices for manual
configuration using the comedi_num_legacy_minors module parameter.
2012-08-28 11:54:39 +01:00

334 lines
12 KiB
XML

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % comedilib_entities SYSTEM "comedilib.ent">
%comedilib_entities;
]>
<section id="install">
<title>
Configuration
</title>
<para>
This section assumes that you have successfully compiled and installed
the &comedi; software, that your hardware device is in your computer,
and that you know the relevant details about it, i.e., what kind of
card it is, any jumper settings related to input ranges, the
I/O base address and IRQ for old non-plug-n-play boards, etc.
</para>
<section id="cardconfiguration">
<title>
Configuration
</title>
<para>
The good news is: on most systems PCI and USB based boards are
configured automatically. The kernel will
detect your data acquisition devices, will load the appropriate
kernel drivers and will create the
<filename>/dev/comedi</filename> entries.
<screen>
bp1@bp1-x61:~/sandbox/comedilib$ ls -l /dev/comedi0*
crw-rw---- 1 root iocard 98, 0 2012-04-26 23:41 /dev/comedi0
crw-rw---- 1 root iocard 98, 48 2012-04-26 23:41 /dev/comedi0_subd0
crw-rw---- 1 root iocard 98, 49 2012-04-26 23:41 /dev/comedi0_subd1
</screen>
Usually these devices belong to the group <systemitem class="groupname">iocard</systemitem> as shown here. The only
action you need to take is to become member of this group and
then the &comedi; device is ready to be used.
</para>
<para>
There are a few PCI drivers that for one reason or another
do not support auto-configuration, either because there is
more than one variant of a board sharing the same PCI device
ID (e.g. Advantech PCI-1710 and PCI-1710HG), or because
some configuration options are needed (e.g. Amplicon PCI224
and PCI234) or for some other reason. It is also possible
to disable auto-configuration when loading the
<systemitem>comedi</systemitem> kernel module. In these
cases devices need to be configured manually as for ISA
cards. Conversely, most &comedi; drivers supplied with the
kernel sources that support auto-configuration may no longer
support manual configuration.
</para>
<para>
By default, the <systemitem>comedi</systemitem> kernel module
does not reserve any devices for manual configuration so
manual configuration will fail. To allow devices to be
configured manually, set the
<parameter>comedi_num_legacy_minors</parameter> module
parameter to the number of devices to reserve for manual
configuration when loading the <systemitem>comedi</systemitem>
kernel module. If using <command>modprobe</command>, this
can be set automatically by editing
<filename>/etc/modprobe.conf</filename> or
<filename>/etc/modprobe.d/comedi.conf</filename> (depending
on the system) to include the line:
<screen>
options comedi comedi_num_legacy_minors=4
</screen>
The number <literal>4</literal> in the above line may be
adjusted to increase or decrease the number of devices to be
reserved for manual configuration.
</para>
<para>
Old ISA based cards need to be manually configured which is
explained here. You only need to read on here
if you have one of these old cards.
On embedded systems it might also be necessary to load the
driver and then to configure the boards manually.
In general manual configuration is done by running
the <command>comedi_config</command> command
(as <systemitem class="username">root</systemitem>).
Here is an example of how to use the command (perhaps you should read
its <command>man</command> page now):
<screen>
comedi_config /dev/comedi0 labpc-1200 0x260,3
</screen>
This command says that the <quote>file</quote>
<filename>/dev/comedi0</filename> can be used to access the &comedi;
device that uses the <parameter class="command">labpc-1200</parameter> board, and that
you give it two run-time parameters (<literal>0x260</literal> and
<literal>3</literal>). More parameters are possible, and their
meaning is driver dependant.
</para>
<para>
This tutorial goes through the process of configuring &comedi;
for two devices, a
National Instruments AT-MIO-16E-10, and a
Data Translation DT2821-F-8DI.
</para>
<para>
The NI board is plug-and-play. The current <systemitem>ni_atmio</systemitem> driver
has kernel-level ISAPNP support, which is used by default
if you do not specify a base address. So you could simply
run <command>comedi_config</command> as
<screen>
comedi_config /dev/comedi0 ni_atmio
</screen>
For the preceding <command>comedi_config</command> command to succeed, the
<systemitem>ni_atmio</systemitem> kernel module must
be loaded first. For plug-n-play boards on
modern kernels, the appropriate comedi kernel modules should get loaded
automatically when your computer is booted.
The <command>modprobe</command> command can
be used to manually load/unload kernel modules, and <command>lsmod</command>
will list all the currently loaded modules.
</para>
<para>
For the Data Translation board, you need to know
how the board's jumpers are configured in order to specify the correct
<command>comedi_config</command> parameters. These parameters for the board are given in the
<link linkend="lowleveldrivers">kernel drivers</link> section about the <systemitem>dt282x</systemitem>
driver.
The card discussed here is a DT2821-f-8di. The
entry for the <systemitem>dt282x</systemitem> driver tells you that the
<command>comedi_config</command> parameters give the driver the I/O base,
IRQ, DMA 1, DMA 2, and
in addition the states of the
differential/single-ended and unipolar/bipolar jumpers:
<itemizedlist>
<title>dt282x configuration options:</title>
<listitem><para>[0] - I/O port base address</para></listitem>
<listitem><para>[1] - IRQ</para></listitem>
<listitem><para>[2] - DMA 1</para></listitem>
<listitem><para>[3] - DMA 2</para></listitem>
<listitem><para>[4] - AI jumpered for 0=single ended, 1=differential</para></listitem>
<listitem><para>[5] - AI jumpered for 0=straight binary, 1=2's complement</para></listitem>
<listitem><para>[6] - AO 0 jumpered for 0=straight binary, 1=2's complement</para></listitem>
<listitem><para>[7] - AO 1 jumpered for 0=straight binary, 1=2's complement</para></listitem>
<listitem><para>[8] - AI jumpered for 0=[-10,10]V, 1=[0,10], 2=[-5,5], 3=[0,5]</para></listitem>
<listitem><para>[9] - AO 0 jumpered for 0=[-10,10]V, 1=[0,10], 2=[-5,5], 3=[0,5],
4=[-2.5,2.5]</para></listitem>
<listitem><para>[10]- A0 1 jumpered for 0=[-10,10]V, 1=[0,10], 2=[-5,5], 3=[0,5],
4=[-2.5,2.5]</para></listitem>
</itemizedlist>
</para>
<para>
So, the appropriate options list might be:
<screen>
0x200,4,0,0,1,1,1,1,0,2,2
</screen>
and the full configuration command is:
<screen>
comedi_config /dev/comedi1 dt2821-f-8di 0x200,4,0,0,1,1,1,1,0,2,2
</screen>
Setting the DMA channels to 0 disables the use of DMA.
</para>
<para>
So now you have your boards configured correctly.
Since data acquisition boards are not typically well-engineered,
&comedi; sometimes can't figure out if an old non-plug-n-play
board is actually in the computer and at the base address you specified.
If it can't, it assumes you are right. Both of these boards
are well-made, so &comedi; will give an error message if it
can't find them. The &comedi; kernel module, since it is a part
of the kernel, prints messages to the kernel logs, which you
can access through the command <command>dmesg</command> or the file
<filename>/var/log/messages</filename>.
Here is a configuration failure (from <command>dmesg</command>):
</para>
<screen>
comedi0: ni_atmio: 0x0200 can't find board
</screen>
<para>
When it does work, you get:
</para>
<screen>
comedi0: ni_atmio: 0x0260 at-mio-16e-10 ( irq = 3 )
</screen>
<para>
Note that it also correctly identified the board.
</para>
</section>
<section id="gettinginformation">
<title>
Getting information about a card
</title>
<para>
So now that you have &comedi; talking to the hardware, try to
talk to &comedi;.
Call the command <command>comedi_board_info</command>, which provides information
about each subdevice on the board.
Here's part of the output for the USB-DUX sigma
board (which is on <filename>/dev/comedi0</filename>), as a result of
the command <command>comedi_board_info -v</command>.
</para>
<screen>
overall info:
version code: 0x00074c
driver name: usbduxsigma
board name: usbduxsigma
number of subdevices: 4
subdevice 0:
type: 1 (analog input)
flags: 0x10119000
SDF_CMD_READ:can do asynchronous input commands
SDF_READABLE:subdevice can be read
SDF_GROUND:can do aref=ground
SDF_LSAMPL:subdevice uses 32-bit samples for commands
number of channels: 16
max data value: 16777215
ranges:
all chans: [-1.325 V,1.325 V]
command:
start: now|int
scan_begin: timer
convert: now
scan_end: count
stop: none|count
command structure filled with probe_cmd_generic_timed for 16 channels:
start: now 0
scan_begin: timer 1000000
scan_begin_src = TRIG_TIMER:
The sampling rate is defined per scan
meaning all channels are sampled at
the same time. The maximum sampling rate is f=1000 Hz
convert: now 0
scan_end: count 16
stop: count 2
subdevice 1:
type: 2 (analog output)
flags: 0x00125000
SDF_CMD_WRITE:can do asynchronous output commands
SDF_WRITABLE:subdevice can be written
SDF_GROUND:can do aref=ground
number of channels: 4
max data value: 255
ranges:
all chans: [0 V,2.5 V]
command:
start: now|int
scan_begin: timer
convert: now
scan_end: count
stop: none|count
command structure filled with probe_cmd_generic_timed for 4 channels:
start: now 0
scan_begin: timer 1000000
scan_begin_src = TRIG_TIMER:
The sampling rate is defined per scan
meaning all channels are sampled at
the same time. The maximum sampling rate is f=1000 Hz
convert: now 0
scan_end: count 4
stop: count 2
subdevice 2:
type: 5 (digital I/O)
flags: 0x00030000
SDF_READABLE:subdevice can be read
SDF_WRITABLE:subdevice can be written
number of channels: 24
max data value: 1
ranges:
all chans: [0 V,5 V]
command:
not supported
subdevice 3:
type: 12 (pwm)
flags: 0x00020100
SDF_MODE1:can do mode 1
SDF_WRITABLE:subdevice can be written
number of channels: 8
max data value: 512
ranges:
all chans: [0,1]
command:
not supported
</screen>
<para>
This board has four subdevices. Devices are separated into
subdevices that each have a distinct purpose; e.g., analog
input, analog output, digital input/output.
</para>
<para>
Here's the information from &comedi;'s <filename>/proc/comedi</filename>
file, which indicates what drivers are loaded and which
boards are configured:
</para>
<screen>
cat /proc/comedi
</screen>
<screen>
comedi version 0.7.76
format string: "%2d: %-20s %-20s %4d",i,driver_name,board_name,n_subdevices
0: usbduxsigma usbduxsigma 4
usbduxfast:
usbduxfast
usbduxsigma:
usbduxsigma
</screen>
<para>
This documentation feature currently returns the driver name, the device name, and the number of
subdevices. Following those lines are a list of the &comedi; kernel
driver modules currently loaded, each followed by a list of the board
names it recognizes (names that can be used with
<command>comedi_config</command>).
</para>
</section>
</section>