<!-- 

v0.1 wh 2001/03/26

-->

<REFMETA>
<REFENTRYTITLE>irattach</REFENTRYTITLE>
<MANVOLNUM>8</MANVOLNUM>
</REFMETA>

<REFNAMEDIV>
<REFNAME>irattach</REFNAME> 
 <REFPURPOSE>
binds the Linux-IrDA stack to a IrDA port
 </REFPURPOSE>
</REFNAMEDIV>

<REFSYNOPSISDIV>
<CMDSYNOPSIS>
 <COMMAND>irattach</COMMAND>
 <ARG>&lt;dev&gt;</ARG>
 <ARG><REPLACEABLE>-s</REPLACEABLE></ARG>
 <ARG><REPLACEABLE>-d dongle</REPLACEABLE></ARG>
 <ARG><REPLACEABLE>-v</REPLACEABLE></ARG>
 <ARG><REPLACEABLE>-h</REPLACEABLE></ARG>
</CMDSYNOPSIS>
</REFSYNOPSISDIV>

<REFSECT1>

<TITLE>DESCRIPTION</TITLE>

<PARA>
<COMMAND>irattach</COMMAND> binds the Linux-IrDA stack to an IrDA
port. It configures the low level of the Linux-IrDA stack in the
kernel. This step is usually necessary before you (or applications)
can use the higher layer of the IrDA stack.
</PARA>

<PARA>
The <COMMAND>irattach</COMMAND> command loads the necessary Linux-IrDA
driver, which configures the IrDA hardware, and configures the IrDA
stack to operate on the new IrDA port. Multiple IrDA ports can be
activated through multiple <COMMAND>irattach</COMMAND> commands.
</PARA>

<PARA>
<COMMAND>irattach</COMMAND> by default uses the
<OPTION>irtty</OPTION> driver which connects to the Linux TTY
subsystem and use the standard Linux serial driver. This works well
for most machines and configurations, but limits the baud rate to
115200bps (IrDA SIR mode). The mode of operation will work with most
FIR hardware (as found in laptops - they provide serial emulation) and
most serial dongles (provided the proper dongle type is specified),
making it a safe choice. However, USB dongles and a few FIR hardware
don't support serial emulation and can't be used with the
<OPTION>irtty</OPTION> driver.
</PARA>

<PARA>
<COMMAND>irattach</COMMAND> can also use one of the Linux FIR drivers
(including USB dongle drivers) instead of the <OPTION>irtty</OPTION>
driver. Most FIR drivers require proper configuration of module
parameters (this is documented below). FIR drivers allow you to use
higher baud rates (generally up to 4Mbps). In general, Linux FIR
support is not as stable and mature, due to lack of time and
documentation.
</PARA>

<PARA>
<COMMAND>irattach</COMMAND> must be run as root or installed setuid
root, as it requires root privileges. If you have compiled the IrDA
stack as modules (recommended), then you will need to edit the
<FILENAME>/etc/modules.conf</FILENAME> file.  See the &ir-howto; for
details.
</PARA>

</REFSECT1>

<REFSECT1>

<TITLE>OPTIONS</TITLE>

<PARA>
<OPTION>&lt;dev&gt;</OPTION> : this is the name of a TTY, an IrDA
interface or IrDA driver. <COMMAND>irattach</COMMAND> decides to use
the <OPTION>irtty</OPTION> driver or one of the FIR drivers based on
this argument.

<ITEMIZEDLIST>

<LISTITEM>
<PARA>
<COMMAND>TTY name</COMMAND> : this is the serial port to be configured
using the <OPTION>irtty</OPTION> driver, such as
<OPTION>/dev/ttyS0</OPTION>. <COMMAND>irattach</COMMAND> will use the
<OPTION>irtty</OPTION> driver, so only SIR will be available. You need
to check your serial configuration or BIOS to know which serial port
is the IrDA port that need to be passed to <COMMAND>irattach</COMMAND>.
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>interface name</COMMAND> : this is the device name of an IrDA
interface, such as <OPTION>irda0</OPTION>. <COMMAND>irattach</COMMAND>
will use one of the FIR drivers (including USB dongle drivers). The
selected FIR driver must be loaded prior to the call to
<COMMAND>irattach</COMMAND>, or the proper alias for the device name
must be set in <FILENAME>/etc/modules.conf</FILENAME>.
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>module name</COMMAND> : this is the name of an FIR driver
module, such as <OPTION>nsc-ircc</OPTION> (see list below). All new
IrDA interfaces created after loading the module will be configured,
so this won't work if the module is already loaded. This feature is
still experimental.
</PARA>
</LISTITEM>

</ITEMIZEDLIST>
</PARA>

<PARA>
<OPTION>-s</OPTION> : starts discovery of remote IrDA devices (note that
the form "-s 1" is no longer supported)
</PARA>

<PARA>
<OPTION>-v</OPTION> : shows version information (this happens, when no option 
is given, too)
</PARA>

<PARA>
<OPTION>-h</OPTION> : shows help information.
</PARA>

<PARA>
<OPTION>-d dongle</OPTION> : attaches an additional dongle driver to the
IrDA port.
</PARA>

<PARA>
You need a dongle driver if you have an infrared device that connects
to your computer's serial port (normal 9-pin serial port
connector). These devices are called dongles, and can currently be
used by any SIR driver (IrTTY or irport).  This option is not
compatible with FIR drivers, and only works with the irtty and irport
drivers.
</PARA>

<PARA>
The currently known (serial) dongles are:

<ITEMIZEDLIST>

<LISTITEM>
<PARA>
<COMMAND>esi</COMMAND>        Extended Systems JetEye PC ESI-9680
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>tekram</COMMAND>     Tekram IrMate IR-210B dongle
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>actisys</COMMAND>    ACTiSYS IR-220L dongle
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>actisys+</COMMAND>   ACTiSYS IR-220L+ dongle
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>girbil</COMMAND>     Greenwich GIrBIL dongle
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>litelink </COMMAND>  Parallax LiteLink dongle & Extended
Systems JetEye PC ESI-9680B
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>airport</COMMAND>    N.N.
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>old_belkin</COMMAND> Belkin (old) SmartBeam dongle or any
dongle only capable of 9600 bauds
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>ep7211</COMMAND>     IR port driver for the Cirrus Logic EP7211
processor (ARM based)
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>mcp2120</COMMAND>    Dongles based on the MCP2120 (Microchip)
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>act200l</COMMAND>    ACTiSYS Ir-200L dongles
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>ma600</COMMAND>      Mobile Action ma600 dongles
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>toim3232</COMMAND>   Vishay/Temic TOIM3232 and TOIM4232 based dongles
</PARA>
</LISTITEM>

</ITEMIZEDLIST>
</PARA>

</REFSECT1>

<REFSECT1>

<TITLE>FIR DRIVER MODULES</TITLE>

<PARA>
If you are one of the lucky people which have a FIR chipset or USB
dongle that is supported by one of the Linux-IrDA drivers, you can use
<COMMAND>irattach</COMMAND> with the interface name of the IrDA port
to configure. You will need to configure
<FILENAME>/etc/conf.modules</FILENAME> appropriately, with at least an
alias of <OPTION>irda0</OPTION> to the driver name, or load the driver
manually beforehand.
</PARA>

<PARA>
You don't strictly need to use <COMMAND>irattach</COMMAND> with FIR
drivers, you can use <COMMAND>modprobe</COMMAND> to load the driver,
<COMMAND>ifconfig</COMMAND> to bring up the interface and set the
various sysctl by hand, but <COMMAND>irattach</COMMAND> offer a
convenient way to do it.
</PARA>

<PARA>
Of course, you need to know which FIR driver applies to your hardware.
You may use <COMMAND>findchip</COMMAND> to get information about the
FIR chip. If this doesn't help, the &ir-howto; shows other means to
retrieve these data.
</PARA>

<PARA>
Also, you often need to configure the <OPTION>Linux-serial
driver</OPTION> to ignore the IrDA port, otherwise both drivers will
conflict. This can usually be done with
<COMMAND>setserial /dev/ttySx uart none</COMMAND>.
</PARA>

<PARA>
The currently known FIR drivers are:

<ITEMIZEDLIST>

<LISTITEM>
<PARA>
<COMMAND>ali-ircc</COMMAND>
ALi FIR Controller Driver for ALi M5123
(options: io, irq, dma).
This driver supports SIR, MIR and FIR (4Mbps) speeds.
This chipset is used by e.g.:
</PARA>

<PARA>
The ALi M5123 FIR Controller
is embedded in ALi M1543C, M1535, M1535D, M1535+, M1535D South Bridge.
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>irda-usb</COMMAND> IrDA-USB device driver, for USB
devices/dongles that comply with the official IrDA-USB class
specification. Note: USB 2.0 is not yet tested.
(options: qos_mtt_bits int, description "Minimum Turn Time").
This is used, for e.g.:
</PARA>

<PARA>
ACTiSYS ACT-IR2000U
</PARA>
<PARA>
KC Technology KC-180
</PARA>
<PARA>
Extended Systems XTNDAccess ESI-9685
</PARA>

<PARA>
Note that there is another USB driver for those devices called
<COMMAND>ir-usb</COMMAND> which is NOT compatible with the IrDA stack
and conflict with <COMMAND>irda-usb</COMMAND>. Because it
always loads first, you have to remove <COMMAND>ir-usb</COMMAND> completely.
</PARA>
<PARA>
Devices based on the SigmaTel chip are not not compliant with the
IrDA-USB class specification and therfore not supported by this
driver.
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>nsc-ircc</COMMAND>
NSC IrDA device driver 
(options: io, irq, dma, dongle_id, qos_mtt_bits).
This chipset is used by e.g.:
</PARA>

<PARA>
IBM ThinkPad		dongle_id=0x09
</PARA>
<PARA>
HP OmniBook 6000	dongle_id=0x08
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>sa1100_ir</COMMAND>
Infrared driver for devices based on the StrongARM SA1100 embedded
microprocessor 
(options: power_level, tx_lpm). 
This driver may support FIR on devices that can do it. 
This chipset is used by e.g.:
</PARA>

<PARA>
Samsung YOPY, COMPAQ iPAQ, SHARP Zaurus SL5000/5500
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>smc-ircc</COMMAND>
SMC IrCC controller driver 
(options: ircc_dma, ircc_irq).
This chipset is used by e.g.:
</PARA>

<PARA>
Fujitsu-Siemens Lifebook 635t
Sony PCG-505TX
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>w83977af_ir</COMMAND>
Winbond W83977AF IrDA device driver
(options: io, irq, qos_mtt_bits).
This chipset is used by e.g.:
</PARA>

<PARA>
Corel NetWinder
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>toshoboe</COMMAND>
Toshiba OBOE IrDA device driver, supports Toshiba Type-O IR chipset.
(options: max_baud).
This chipset is used by e.g.:
</PARA>

<PARA>
Toshiba Libretto 100CT., and many more old Toshiba laptops.
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>donauboe</COMMAND>
is a new version of <COMMAND>toshoboe</COMMAND> and has better FIR support
and compability with the Donauoboe chip http://libxg.free.fr/lib-irda.html
(options: ..).
This chipset is used by e.g.:
</PARA>

<PARA>
Toshiba Libretto 100CT., Tecra 8100, Portege 7020 and many more
Toshiba laptops.
</PARA>
</LISTITEM>

<LISTITEM>
<PARA>
<COMMAND>vlsi_ir</COMMAND>
VLSI 82C147 SIR/MIR/FIR device driver
This chipset is used by e.g.:
</PARA>

<PARA>
HP Omnibook 800
</PARA>

<PARA>
(options: ..).

        <ITEMIZEDLIST>
        <LISTITEM>
        <PARA>
        clksrc int, description "clock input source selection"
        </PARA>
        </LISTITEM>
        <LISTITEM>
        <PARA>
        ringsize int array (min = 1, max = 2), description "tx, rx ring
descriptor size"
        </PARA>
        </LISTITEM>
        <LISTITEM>
        <PARA>
        sirpulse int, description "sir pulse width tuning"
        </PARA>
        </LISTITEM>
        <LISTITEM>
        <PARA>
        mtt_bits int, description "IrLAP bitfield representing min-turn-time"
        </PARA>
        </LISTITEM>
        </ITEMIZEDLIST>
</PARA>

</LISTITEM>

</ITEMIZEDLIST>
</PARA>

</REFSECT1>

<REFSECT1>

<TITLE>EXAMPLES</TITLE>

<PARA>
Attach the IrDA stack to the second serial port (integrated IrDA port
using serial emulation) and start discovery:
<ITEMIZEDLIST>
<LISTITEM>
<PARA>
<COMMAND>irattach /dev/ttyS1 -s</COMMAND>
</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</PARA>

<PARA>
Attach the IrDA stack to the first serial port where you have an
external ACTiSYS serial dongle and start discovery:
<ITEMIZEDLIST>
<LISTITEM>
<PARA>
<COMMAND>irattach /dev/ttyS0 -d actisys+ -s</COMMAND>
</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</PARA>

<PARA>
Attach the IrDA stack to the first IrDA-USB dongle and start discovery:
<ITEMIZEDLIST>
<LISTITEM>
<PARA>
<COMMAND>modprobe irda-usb ; irattach irda0 -s</COMMAND>
</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</PARA>

<PARA>
Attach the IrDA stack to the NSC FIR (4Mbps) device driver on a Thinkpad
laptop:
<ITEMIZEDLIST>
<LISTITEM>
<PARA>
<COMMAND>modprobe nsc-ircc dongle_id=0x9 ; irattach irda0 -s</COMMAND>. 
</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</PARA>

<PARA>
Attach the IrDA stack to the NSC FIR (4Mbps) device driver on a Thinkpad
laptop:
<ITEMIZEDLIST>
<LISTITEM>
<PARA>
<COMMAND>irattach irda0 -s</COMMAND>. 
</PARA>
<PARA>
This assume that you have added the following entries to 
<FILENAME>/etc/conf.modules</FILENAME>:
</PARA>
<PARA>
options nsc-ircc dongle_id=0x09
</PARA>
<PARA>
alias irda0 nsc-ircc
</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</PARA>

</REFSECT1>

<REFSECT1>

<TITLE>CAVEATS</TITLE>

<PARA>
The following hints are a very short introduction into the
configuration of Linux/IrDA. If this doesn't help
read the &ir-tutorial; and/or the &ir-howto; .
Before configuring Linux/IrDA make sure whether you want to configure
SIR or FIR. It's recommended to try SIR first, unless your device is
not compatible with SIR (for example USB dongles).
</PARA>

<PARA>
To get the SIR "serial" device
have a look into the BIOS. Then run <COMMAND>dmesg | grep tty</COMMAND>
to get a survey of tty devices supported by your machine. Now try to 
choose the one, which is probably the IrDA device and use
<COMMAND>irattach /dev/ttySx -s</COMMAND>.
</PARA>

<PARA>
If you don't succeed with SIR (which seems a rare case) you may
try FIR. First look up the BIOS. Then run <COMMAND>findchip</COMMAND>
to get information about the IrDA controller chip. Use 
<COMMAND>setserial /dev/ttySx uart none </COMMAND> to avoid conflicts with the serial driver.
Note: don't use <COMMAND>setserial</COMMAND> if you configure SIR.
Now you may use <COMMAND>irattach</COMMAND>.
</PARA>

<PARA>
Finally <COMMAND>irdadump</COMMAND> should show at least your computer
itself. If it doesn't start at the beginning.
</PARA>

<PARA>
This man page deal only with the low level of the IrDA stack (IrDA
ports and IrDA drivers). After this step is done, you usually need to
setup your favorite application to access the high level IrDA stack
(via IrCOMM, IrLPT, IrNET, IrLAN or IrSOCK), which is documented
elsewhere.
</PARA>

<PARA>
This man page doesn't document the usage of the irport driver. The
irport driver support the same hardware as the irtty driver, but is
configured like a FIR driver.
</PARA>

</REFSECT1>

<REFSECT1>

<TITLE>DIAGNOSTICS</TITLE>

<PARA>
This section currently contains the raw error messages from source
code only.
</PARA>

<PARA>
"ioctl(TIOCGETD): %m"
</PARA>

<PARA>
"irattach: tty: set_disc(%d): %s"
</PARA>

<PARA>
"tcsetattr: %m"
</PARA>

<PARA>
"Failed to open %s: %m"
</PARA>

<PARA>
"Couldn't get device fd flags: %m"
</PARA>

<PARA>
"Couldn't set device to non-blocking mode: %m"
</PARA>

</REFSECT1>

<REFSECT1>

<TITLE>BUGS</TITLE>

<PARA>
N.N.
</PARA>

</REFSECT1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

