TPUART V 0.02 (C) 2001 by Raffael Stocker University of applied sciences, Deggendorf Covered by the GNU GPL See COPYING for details What is tpuart? =============== tpuart is a Linux kernel module (version 2.2 and 2.4) 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, ). The protocol specification should be downloadable from their website. Information on the TPUART-interface and -chip can be downloaded from . 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 ============= The newest version can always be found on our Website at www.hto.fh-deggendorf.de/komm/linux.html. To install it, first you need the linux-kernel compiled yourself to have all the necessary include files!!!! Next please extract the archive's contents with tar xvzf tpuart-.tar.gz This will create a subdirectory called tpuart-. Since this is only a source archive, you will have to compile it. Make sure the directory '/usr/src/linux/include' points to the include directories for the kernel you want to compile for. If this is not the case, edit the Makefile to change the CFLAGS setting to match your installation. To finally 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. Then call make install as root. This will copy the driver module to /lib/modules//misc (or /lib/modules//kernel/drivers/char/ for kernel version 2.4.x). The module directory must be set in the Makefile (MPATH) and defaults to the 2.4.x version. If this doesn't work on your distribution, you will have to install it by hand. ******************************************************************************* To load the driver call /etc/init.d/tpuart_start, which is automatically copied to this directory. Or you start it by hand. !!!You always have to do this after you reboot your system!!! ****************************************************************************** You can optimise this by writig an initscript (not included)! This script will load the kernel module and update the links /dev/tpuart0..3. 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) Check the tpuart by using the busmontest: Usage: busmontest device example: busmontest /dev/tpuart0 Then you are monitoring the EIB telegrams. 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 Hänel and Josef Hofmeister. They supported us with information and hardware during the development. There is a Webpage about the driver and other EIB-related stuff at http://www.hto.fh-deggendorf.de/komm/ R. Zizlsperger (13-Mar-2003)