install.sgml

usb develop guide

If you are trying to use a USB mouse (or USB mice) in addition
to another pointer type device with XFree86 3.3,
then you need to use the <SystemItem>
XInput</SystemItem> extensions. Keep the existing <SystemItem>
Pointer</SystemItem> (or modify it as required for the other device if you
are doing an initial installation), and add the following entry (anywhere
 sensible, ideally in the <SystemItem>Input devices</SystemItem>
 area):
<screen>
Section "Xinput"
   SubSection "Mouse"
        DeviceName   "USB Mice"
        Protocol     "IMPS/2"
        Port         "/dev/input/mice"
        AlwaysCore
   EndSubSection
EndSection
</screen>
</>
</ListItem>

<ListItem>
<Para>
Restart the X server. If you don't have any mouse support at
this point, remember that Ctrl-Alt-F1 will get you a virtual terminal
that you can use to kill the xserver and start debugging from the error
messages.
</>
</ListItem>

</ItemizedList>
</>

<Para>
If you want to use the mouse under gpm, run (or kill and restart if it
is already running) gpm with the following options.
<UserInput>gpm -m /dev/input/mice -t imps2</UserInput>
(as superuser remember). You can make this the default if you edit the
initialisation files. These are typically named something like 
<FileName>rc.d</FileName> and are in <FileName>/etc/rc.d/</FileName> on
RedHat distributions.
</>

<Para>
If you have both a USB mouse (or USB mice) and some other kind of pointer
device, you may wish to use gpm in repeater mode. If you have a PS/2 mouse
on <filename>/dev/psaux</filename> and a USB mouse (or USB mice) on
<filename>/dev/input/mice</filename>, then the following gpm command
would probably be appropriate:
<UserInput>gpm -m /dev/input/mice -t imps2 -M -m /dev/psaux -t ps2 -R imps2</userinput>.
Note that this will make the output appear on <filename>/dev/gpmdata</filename>,
which is a FIFO and does not need to be created in advance. You can use this as
the mouse "device" to non-X programs, and both mice will work together.
</para>
</Sect2>

<Sect2><Title>Keyboard Configuration</>

<para>
You may not need any operating system support at all to use a USB keyboard
if you have a PC architecture.
There are several BIOS available where the BIOS can provide USB support
from a keyboard plugged into the root hub on the motherboard. This may or
may not work through other hubs and does not normally work with
add-in boards, so you might want to add in support anyway. You definately want
to add keyboard support if you add any operating system support, as the Linux
USB support will disable the BIOS support. You also need to use Linux USB
keyboard support if you want to use any of the "multimedia" types keys that
are provided with some USB keybords.
</>

<Para>
In the kernel configuration stage, you need to turn on
<UserInput>USB Human Interface Device (HID) support</UserInput> in
<UserInput>USB support</UserInput> and <UserInput>Keyboard
support</UserInput> in <UserInput>Input core support</UserInput>. Do
<emphasis>not</emphasis> turn on <UserInput>USB HIDBP Keyboard
support</UserInput>. Perform the normal kernel rebuild and
installation steps. If you are installing as modules, you need to load
the <FileName>hid.o</FileName>, <FileName>input.o</FileName> and
<FileName>keybdev.o</FileName> modules.
</para>


<Para>
Check the kernel logs to ensure that your keyboard is being correctly sensed
by the kernel.
</>


<Para>
At this point, you should be able to use your USB keyboard as
a normal keyboard. Be aware that LILO is not USB aware, and that
unless your BIOS supports a USB keyboard, you may not be able to
select a non-default boot image using the USB keyboard. I have
personally used only a USB keyboard (and USB mouse) and have
experienced no problems.
</>
</Sect2>

<Sect2><Title>USB Joystick and Gamepad support</>
<para>
In the kernel configuration stage, you need to turn on
<UserInput>USB Human Interface Device (HID) support</UserInput> in
<UserInput>USB support</UserInput> and
<UserInput>Joystick support</UserInput> in <UserInput>Input core
support</UserInput>. 
Perform the normal kernel rebuild and installation steps.
If you are installing as modules, you need to load
the <FileName>hid.o</FileName>, <FileName>input.o</FileName> and
<FileName>joydev.o</FileName> modules.
</para>


<Para>
You need to set up a device node entry for the joystick. It is
customary to create the entries for USB device in the
<FileName>/dev/input/</FileName> directory. You can use the following
commands to create four device nodes, although there is no reason why
you can not use more:
<screen>
mknod /dev/input/js0 c 13 0
mknod /dev/input/js1 c 13 1
mknod /dev/input/js2 c 13 2
mknod /dev/input/js3 c 13 3
</screen>
</>

<Para>
If you plug in a gamepad or joystick and
<UserInput>cat /dev/input/js0</UserInput> you should see
some bizarre looking characters as you move the stick or click any
of the buttons.
</para>

<para>
You should now be able to use the USB joystick or gamepad with any
of the normal games or other joystick compatible applications.
</>
</Sect2>
</Sect1>

<Sect1><Title>USB Scanner Support</>

<para>
USB scanners do not have a common class specification, hence it is
not possible to make a device driver that works for all scanners.
Not withstanding this, Linux USB does have a generic scanner driver
that provides the communication link between the device and user space.
</para>

<para>
In addition to the generic scanner interface, there is also a specific
driver for the Microtek X6 USB, and similar scanners such as the
Phantom 336CX, Phantom C6 and ScanMaker V6USL. Only the X6 is well
supported. 
</para>

<Sect2><Title>Generic Scanner Driver</Title>
<para>
The USB Scanner driver is capable of supporting just about any
scanner. However meaningful output depends on the availability of a
suitable user space tool, such as SANE, see
<ulink url="http://www.mostang.com/sane">http://www.mostang.com/sane</ulink>.
</>

<para>
If your scanner is not automatically associated with the scanner
driver, you have two options. The first option is to edit the source
code for the scanner driver - I assume that if you can do this, you
won't need any instructions. The second option is to use modules, and
to load the module with the vendor and product IDs specified as module
options:
<UserInput>insmod scanner.o vendor=0xXXXX product=0xYYYY</UserInput>,
where XXXX is the hexadecimal vendor ID code, and YYYY is the
hexadecimal product ID code, which you can extract from the
contents of <filename>/proc/bus/usb/devices</filename> when
you have the scanner plugged in.
</para>

<para>
You need to create an appropriate device file entry, using commands
(as root) like the following:
<screen>
mknod /dev/usb/scanner0 c 180 48
chmod a+rw /dev/usb/scanner0
</screen>
</>

<para>
To use the scanner device, you will need a suitable tool. SANE is
strongly recommended. If you don't already have it installed or your
installation is old, you will need to retrieve the package from the
closest of the sites referenced at <ulink
url="http://www.mostang.com/sane/source.html">
http://www.mostang.com/sane/source.html</ulink>.
</>

<para>
For instructions on building and installing SANE, refer to the various
README files within the SANE distribution, and more detailed instructions
for specific scanners that are provided later in this document.
</>
</Sect2>

<Sect2><title>Microtek X6USB Scanner Driver</title>
<para>
The Microtek scanner driver presents the scanner as a generic SCSI
device, which is probably <FileName>/dev/sg0</filename> unless you 
have some other device that uses the SCSI generic device interface. 
</para>

<para>
In addition to selecting the <UserInput>Microtek X6USB scanner
support</UserInput> entry in <UserInput>USB support</UserInput>, you
also need to select <UserInput>SCSI generic support</UserInput> under
<UserInput>SCSI support</UserInput>.
</para>

<para>
You need a very recent SANE release (1.0.3) or later to use this
driver. If you don't already have it installed or your
installation is old, you will need to retrieve the package from the
closest of the sites referenced at <ulink
url="http://www.mostang.com/sane/source.html">
http://www.mostang.com/sane/source.html</ulink>.
</>

<para>
For instructions on building and installing SANE, refer to the various
README files within the SANE distribution, and more detailed instructions
for specific scanners that are provided later in this document.
</para>

</Sect2>

</Sect1>

<Sect1><Title>USB Audio Support</>
<para>
USB audio systems such as speakers normally comply with
<ulink url="http://www.usb.org/developers/data/devclass/audio10.pdf">
the USB audio class specification</ulink>. If your audio device does not
comply with the specification, it will not work with Linux at this time.
</>

<para>
You need to turn on the <UserInput>Sound card support</UserInput> kernel
option, which is in the <UserInput>Sound</UserInput> section. You will
then be able to turn on the <UserInput>USB Audio support</UserInput> option
in the normal USB section.
</>

<para>
If you elected to use modules, you need to load the module called
<FileName>audio.o</FileName>.
</para>

<para>
You can test your installation by dumping some random data out to the
audio interface, using a command like
<UserInput>cat /bin/bash > /dev/dsp</UserInput>. USB audio is integrated into
the normal Linux sound architecture, and most tools should work fine with USB
speakers. See the <ulink url="http://www.linuxdoc.org/HOWTO/Sound-Playing-HOWTO.html">
Sound HOWTO</ulink> for more details and suggestions.
</para>
</Sect1>

<Sect1><Title>USB Modem Support</>

<para>
USB modems (for plain old telephone service, ISDN or cable)
are supposed to conform to the
<ulink url="http://www.usb.org/developers/data/devclass/usbcdc11.pdf">
Communication Device Class (CDC) specification</ulink>, and usually
to the Abstract Control Model (ACM) sub-class. If your modem doesn't
comply with the specification, it will not work with this driver.
</>

<para>
You need to select the
<UserInput>USB Modem (CDC ACM) support</UserInput> kernel option.
If you build as modules, you need to install the <FileName>acm.o</FileName>
option.
</>

<para>
You need to set up the device node entries for the various
modems.  You can use up to 32 modems with this driver.
Use the following commands to set up the first four:
<screen>
mknod /dev/usb/ttyACM0 c 166 0
mknod /dev/usb/ttyACM1 c 166 1
mknod /dev/usb/ttyACM2 c 166 2
mknod /dev/usb/ttyACM3 c 166 3
</screen>
</>

<para>
You should now be able to use a terminal emulator program to attach to
this device and connect to your modem or other terminal
device. Apparently this driver is working quite well, but I have not
personally tested it.
</>

</Sect1>

<Sect1><Title>Printer Support</>

<para>
You need to set up a device node entry for the printer. Use the
following command:
<screen>
mknod /dev/usb/lp0 c 180 0
</screen>
</>

<para>
Different printer tools are installed with various different rights,
and this may affect the access priviledges that you need with
the device entry. It is normally correct to make <FileName>/dev/usb/lp0</FileName>
rights the same as <FileName>/dev/lp0</FileName>, using the
<SystemItem>chmod</SystemItem>, <SystemItem>chown</systemitem> and
<systemitem>chgrp</systemitem> commands.
</para>

<para>
You should now be able to use this device in a normal
<FileName>/etc/printcap</FileName> entry. I recommend use of automated
tools to generate such files, such as RedHat's control panel