        BIM-XXX-RS232 Radio Transceiver Driver Version 1.0
	Copyright (C) Walter Fetter Lages <w.fetter@ieee.org>

0. LICENSE
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Although the driver is under the terms of the GNU General Public License, I
would like to know that you are using it and hear from modifications. Of
course, I would like to know about bugs, too. Please send bugs reports and
questions to my e-mail address.


1. INTRODUCTION

This is the first Linux release of my BIM-XXX-RS232 Radio Transceiver
driver. BIM transceivers are inexpensive low power radio modems made by
Radio Tech Limited (http://www.radio-tech.co.uk).

This driver was developed based on the Linux Driver for Baycom Modems by
Thomas M. Sailer <hb9jnx@radio.amiv.ethz.ch>. Many parts of the source code
and of this file itself were adapted from the Baycom source code and README.
It is written in C++, but with a C style of coding. Future versions will
have a better C++ style.

Two types of modems are supported: the BIM-XXX-RS232 modem and a null-modem
cable. This later one is mainly usefull for debugging and should be a
"complete handshaking" cable, i.e. a cable with DTR-DSR and RTS-CTS
cross-wired.

The above modems only support half duplex communications. However, the
driver supports the KISS (see below) fullduplex command. It then simply
starts to send as soon as there's a packet to transmit and does not care
about DCD, i.e. it starts to send even if there's someone else on the
channel.

The driver interfaces to the AX25 stack via a KISS interface. The driver can
be accessed as a character device with major 51. Major 51 reserved for the
Baycom modem, but this can be changed when loading the driver. The driver
supports multiple modems (currently four, as defined with NR_PORTS). It
therefore responds to minor numbers 0 to 3. I recommend to access the driver
via the special device files /dev/bim[0-3], which can be created with 'make
bim'.


2. COMPILING THE DRIVER

First unpack the source files into a directory. Then enter the following:
(you must be root to do it)

  make

This will create the files driver/bim.o and util/setbim. driver/bim.o is the
driver module, while util/setbim is the program to setup the driver. Since
the driver is written in C++ and many header files are not adapted to the
more strict C++ syntax checking, many warnings should arise. Just ignore
them. 

If you use Fred Kruse xwpe, you can also compile it from inside xwpe. A
project.prj file is included with this package. Actually it is just a link
to Makefile. This explains the unusual Makefile style. This way it can be
used as a xwpe project file.

To install them run

make install

driver/bim.o is copied to /lib/modules/`uname -n`/misc, util/setbim is
copied to /usr/local/bin and util/setbim.8 is copied to /usr/local/man/man8.

Then you should create the device special files if you are installing the
driver the first time. This can be done with:

  make bim

You are now ready to use the driver. You can now activate the driver
manually by entering

  insmod bim


3. CONFIGURING THE DRIVER

Every time the driver is inserted into the kernel, it has to know which
modems it should access at which ports. This can be done with the setbim
utility. You can also configure the driver from the insmod command line (or
by means of an option line in /etc/conf.modules). See the setbim(8) man page
for details.

The command line options (insmod command line) are:
 
major		major number the driver should use; default 51 

iobase#		base address of the port; common values are 0x3f8, 0x2f8,
0x3e8 and 0x2e8

irq#    	interrupt line of the port; common values are 3 and 4.

type#    	modem type; 0=none, 1=BIM RS232 modem, 2=NULL MODEM cable

baud#		default baud rate; default 19200

tx_delay# 	transmitter keyup delay in 10 ms; default 20

tx_tail#	transmitter tail time in 10 ms; default 2

slottime#	transmitter slot time in 10 ms; default 10

ppersist# 	tranmitter p persistence scaled to 0..255 range; default 63

fulldup# 	full duplex; default 0

	where # = 0, 1, 2 or 3.	


Examples:
  insmod bim type0=1 iobase0=0x3f8 irq0=4
  setbim /dev/bim0 -u modem 0x3f8 4

Both lines configure the first port to drive a BIM-XXX-RS232 modem at the
first serial port (COM1 under DOS).

  insmod bim major=60 type0=1 iobase0=0x3f8 irq0=4

This line configures the first port to drive a BIM-XXX-RS232 modem at the
first serial port (COM1 under DOS) using major 60.

  insmod bim type1=2 iobase1=0x2e8 irq1=3 baud1=38400
  setbim /dev/bim1 -u cable 0x2e8 3 38400 

Both lines configure the second port to drive a null-modem cable at the
fourth serial port (COM4 under DOS).

  insmod bim tx_delay2=0 tx_tail2=0 slottime2=1 type2=1 iobase2=0x3e8 irq2=4
  setbim /dev/bim2 -k 0 -t 0 -s 1 -u modem 0x3e8 4

Both lines configure the third port to drive a BIM-XXX-RS323 modem at the
third serial port (COM3 under DOS) and set the keyup delay, tx tail and slot
time channel access paramenters.
  
The channel access parameters can also be set through KISS parameter frames.


4. DCD DETECTION

To avoid collisions on the air, the driver must know when the channel is
busy. This is the task of the DCD circuitry/software. When using a
null-cable modem RTS/CTS are used to emulate DCD, therefore uou need a cable
with this signals wired. Also, it appears that the BIM-XXX-RS232 modem DCD
logic is inverted. Please, let me know if this is not true.


5. COMPATIBILITY WITH THE REST OF THE LINUX KERNEL

The serial driver and the bim driver compete for the same hardware
resources. Of course only one driver can access a given interface at a time.
The serial driver grabs all interfaces it can find at startup time.
Therefore the bim driver subsequently won't be able to access a serial port.
You might therefore find it necessary to release a port owned by the serial
driver with 'setserial /dev/ttyS# uart none', where # is the number of the
interface. The bim driver does not reserve any port at startup, unless one
is specified on the 'insmod' command line. Another method to solve the
problem is to compile the serial driver a module and leave it to kerneld to
load the correct driver depending on the application.

