
                               TPUART V 0.03
		
			2004 by Reinhold Buchinger
		      University of Technology, Vienna

		
                       (C) 2001 by Raffael Stocker
                University of applied sciences, Deggendorf

                          Covered by the GNU GPL
                         See COPYING for details


Changes from V 0.02 to V 0.03
=============================

With V 0.03 the driver was ported to kernel 2.6. You must use V 0.02 for kernel
version 2.2 and 2.4. The functionality of V 0.03 is the same as V 0.02. The only
extension is that you can query the state of the TPUART with an ioctl command.

The author of V 0.02 is Raffael Stocker(raffael.stocker@stud.fh-deggendorf.de). 
The author of the ported version 0.03 is Reinhold Buchinger 
(e0125124@student.tuwien.ac.at). 

This file is a modified version of the readme of V 0.02.

What is tpuart?
===============

tpuart is a Linux kernel module (version 2.6) for interfacing a 
PC to the European Installation Bus (EIB). It uses the Siemens-TPUART-
interface for the serial port. All you need to use it is a PC with Linux 
and a standard serial port (must have a FIFO), the TPUART-interface and 
your EIB system, of course.

The EIB is a home automation system defined by the EIBA (EIB Association,
<www.eiba.org>). The protocol specification should be downloadable from
their website.

Information on the TPUART-interface and -chip can be downloaded from
<http://www.georg-luber.de/chips.htm>.

What exactly does it do then?
-----------------------------

tpuart is a device driver. Neither more nor less. If you want a GUI-driven
application to program and manage your EIB-system, than you are at the
wrong place here. The driver's only purpose is to give you a low-level
interface to the hardware. If you want to really use it for something, you
will have to write your own application on top of the driver's interface.

Installing it
=============

To install it first extract the archive's contents with

        tar xvzf tpuart-<version-code>.tar.gz

This will create a subdirectory called tpuart-<version-code>. Since this
is only a source archive, you will have to compile it. 

Enter

    	make

in the subdirectory of the driver. If that doesn't work, please don't
hesitate to mail us a bug report (and, if you find out what's the cause
of your trouble, a patch would also be welcome).

After successful compilation, the driver needs to be installed in the
right place. 

        make install

as root. This will copy the driver module to /lib/modules/<current-
kernel-version>/char. You can change the path if you modify the variable INSTALL_PATH
in the Makefile. If this doesn't work on your distribution, you will have to 
install it by hand.

You can load the driver with the init script tpuart.init. The name of the variable
DEVICE must be the same as MODULE_NAME in the Makefile. If you want to specify options 
you can create a config file. The name of the config file has to be the name of the Device 
with .conf at the end and should be stored in /etc. You can change the path with the variable 
CONFIG_PATH.

The format of the config file is:
owner <ownername>
group <groupname>
mode  <modename>
options tpuart_major=<majornumber>

With owner,group,mode you can specify the attributes of the entries in /dev.
Type
	./tpuart.init start
to load the driver and
	./tpuart.init stop
to unload the driver.

If you want to load the driver automatically you can copy the init script in the directory 
your distribution uses for these scripts (most common directories uses are /etc/init.d, 
/etc/rc.d/init.d) and make a link to it from the appropiate run-level directory.

You should now be able to use the driver.

Using it
========

For interfacing to the driver, four special files are created:

        /dev/tpuart0      (using io-port 0x3f8)
        /dev/tpuart1      (using io-port 0x2f8)
        /dev/tpuart2      (using io-port 0x3e8)
        /dev/tpuart3      (using io-port 0x2e8)

After opening the files by calling open(2) in your application,
you can read(2) and write(2) messages using the following structure:

struct telegram_t {
	struct timeval timestamp;     /* time of message receiption,
                                         leave empty when sending. */
	unsigned short data_length;   /* overall message length. Must
                                         always be set appropriately when
                                         sending! */
	unsigned char data[64];       /* message data */
};

Data can only be sent and received using this structure! Since it is not
globally defined in the driver's header file, you have to define it for
yourself (this is because struct timeval is different in the kernel,
compared to the C-library).

You can set and retrieve physical and group addresses using the ioctl(2)
call. Include 'tpuart_main.h' for this.

All settable driver attributes default to 0!

Known bugs
==========

Since this is not a realtime-module, the driver can't appropriately detect
the 2 msec timeout between a message on the bus and a message from the
interface-chip. This problem arises only, however, if a faulty message
is sent on the bus (i. e. the length of a received telegram is not true).
Since we may not be able to resynchronize after receiving a faulty
message, we cannot trigger on the error messages from the chip, because
that would lead us into nirvana. So, error messages are ignored by now.

To do
=====

Eventually prepare a realtime version (using rtlinux or RTAI). This may
eliminate our message-timeout problem described above.

Develop a usable (class-)library.

Finish source documentation.

Thanks et al.
=============

This work was done as a project at our University together with Siemens
A&D, Regensburg. From there, we wish to thank Georg Luber, Marc Wucherer,
Andre Hnel and Josef Hofmeister. They supported us with information and
hardware during the development.

The Author can be reached at <raffael.stocker@stud.fh-deggendorf.de>.

There is a Webpage about the driver and other EIB-related stuff at
http://os-projects.fh-deggendorf.de/eib/

Raffael Stocker (06-Jun-2001)
