Linux EIB Home Server

Documentation

Authors:

Vladimir Vinarski (volodimir@users.sourceforge.net)

Jens Neumann (jneumann@users.sourceforge.net)

1. Revisions

   Version	Date	Editor	Reason/Change
   0.1	13.03.02	V.Vinarskyi J. Neumann	Creation
   0.2	16.06.03	J.Neumann	Documentation for SourceForge
   0.3	01.04.04	V.Vinarski J.Neumann	Additions and corrections
   0.4	21.06.04	J.Neumann	New class names and therefore new figures. English translation.

2. Open Points & TODOs

• Examplary applications

• Support of all EIB data types

• UPnP support

• Windows Version

• Internet connectivity

• Mobile/SMS connectivity

• BCU 1 support

• ...

3. Table of contents

   1. Revisions
   2. Open Points & TODOs
   3. Table of contents
   4. Illustrations
   5. Introduction
   1. Architecture
   1. Interfaces for Clients
   2. Internal interface homeserver <-> homedriver
   2. Dynamic description
   1. Interface between Linux EIB Home server and EIB bus
   3. Files
   4. Module description: homedriver
   1. Short description
   2. Classes and associations
   3. Classes, attributes and methods
   4. Functions
   5. Module description: homeserver
   1. Short description
   2. Classes and associations
   3. Classes, attributes and methods
   6. Bibliography

4. Illustration listing

   1. Components.
   2. Class diagram of homedriver
   3. Driver class
   4. Die Connection class
   5. Inheritance of state classes
   6. Socket class
   7. Inheritance of message classes
   8. Exceptions
   9. Class diagram of homeserver
   10. Class HomeServer
   11. Class DatenBank
   12. Class Driver
   13. Class DriverMessages
   14. Class Client
   15. Class ClientMessages
   16. Class Interest
   17. Class PathData
   18. Class Instruction

5. Introduction

The Linux EIB Home server offers interfaces for controlling and monitoring an EIB installation.

The European installation bus (EIB) allows for the automatic control of functions in electric installations. The EIB separates clearly the transmission of electricity and information. The Installation Bus is laid parallel to the power supply network. The bus line connects the bus users (actuators and sensors) to all operational functions in an installation.

The connection between actuator and sensor is programmable and arbitrarily often changeable over the network. For the operation no central bus management is needed. The administration and storage of all data takes place decentralized in the individual bus devices. However all information of the EIB installation is available, if necessary, at each point of the network. So an integration of the electricity installation in a monitoring and control system, e.g. Embassi [ 1 ], is possible without additional installation costs.

1. Architecture

The Home server essentially consists of two components (see illustration 1):

• homedriver: Controlling of the EIB bus and communication interface between the Home server and the EIB bus, i.e. the electronic devices.

• homeserver: Communication interface between the homedriver and application programs, in the following called clients. The number of application programs is unlimited.

Information flow:

EIB bus -> FT 1.2 serial device -> homedriver -> homeserver -> Clients

Client -> homeserver -> homedriver -> -> FT 1.2 serial device -> EIB-Bus

Clients are differentiated in principle between normal application programs and HTTP Clients. The number of Clients is unlimited.

The two components homedriver and homeserver use different additional libraries:

• lfc: A Collection-Class library (Strings, HashMaps, Queues, Vectoren, ...), used by homedriver.

• vector: A collection-class library (String, Vector, Array, ...), used by homeserver.

• ixml: XML-DOM Parser (from Intel [2])

1. Interfaces for Clients

   1. EIB-HomeServer <-> TCP/IP-Applikation ( Port 8081 )

A Client is any program, that uses a tcp/ip connection to send some of the following instructions to the homeserver:

Possible instructions:

• „read“ to query for actual states of EIB devices, i.e. values of EIB group addresses.

• „write“ to change states of EIB devices, i.e. values of EIB group addresses.

• „subscribe“ to monitor state changes of EIB devices, i.e. value chnages of EIB group addresses.

• „unsubscribe“ to cancel a subscription (refer to „subscribe“-instruction).

Example for READ:

Goal: Determine the value of (devices with) group address 2/0/2.

Instruction:

<eib type="read" path="/eib/groups/2/0/2/curvalue"/>

Response from HomeServer:

<eib state="true" path="database.value/eib/groups/2/0/2/curvalue" data="0"/>

(if the actual value of the group address is 0.)

Response in case of an error:

<eib state="false" path="database.value/eib/groups/2/0/2" error="$error0007"/>

Response in case of erroneous instruction:

<eib state="false" error="instruction isn't correct"/>

Example for WRITE:

Goal: Change value of group address 2/0/2 to „11“, i.e. change the state of the corresponding devices.

Instruction:

<eib type="write" path="/eib/groups/2/0/2/curvalue" data="11">

Response from HomeServer:

<eib state="true" path="database.value/eib/groups/2/0/2/curvalue" data="11"/>

Error responses: Same as for READ instruction.

Example for SUBSCRIBE:

Goal: A client wants to monitor group address 2/1/0 überwachen, i.e. be informed on any state changes of corresponding devices.

Instruction:

<eib type="subscribe" path="/eib/groups/2/1/0"/>

Response from Home-Server:

<eib state="true" type="subscribe" path="/eib/groups/2/1/0"/>

Subsequently, the Client gets a messages on any state change of the group address.

Response in case of error: Same as for READ instruction.

This instruction supports substitute symbols, e.g.

<eib type="subscribe" path="*"/>

orders all messages of the EIB bus, i.e. all group addresses are supervised.

Response from Home-Server::

<eib state="true" type="subscribe" path="*"/>

Example for UNSUBSCRIBE:

Goal: Cancel subscription, i.e. previous SUBSCRIBE-instruction.

Instruction:

<eib type="unsubscribe" path="/eib/groups/2/1/0"/>

Response from Home-Server:

<eib state="true" type="unsubscribe" path="/eib/groups/2/1/0"/>

This instruction supports substitute symbols, e.g.

<eib type="unsubscribe" path="*"/>

cancels subscriptions for all group addresses.

Response from Home-Server:

<eib state="true" type="unsubscribe" path="*"/>

Remarks:

The connection to the Client exists until the Client closes the socket.

The READ instruction works at the same time as SUBSCRIBE instruction!!!

2. EIB-Home-Server <-> HTTP-application (Port 8080)

Format of instruction, if the HomeServer runs on a computer with IP address 192.168.169.33):

http://192.168.169.33:8080/eibhomeserver?instruction=<eib type="read" path="/eib/groups/2/0/2/curvalue"/>

After Instruction = either the complete READ or WRITE instruction described above (see previous chapter) must follow.
A HTTP Client cannot implement Subscribe or UNSUBSCRIBE instructions!

Response of HomeServer:

HTTP/1.0 200 OK
Server: Loewe HomeServer 1.0
MIME-version: 1.0
Content-type: text/html

<html><script>var answer='<eib state="true" path="database.value/eib/groups/2/0/2/curvalue" data="11"/>’;</script></html>

Examplary Write-Instruction:

http://192.168.169.33:8080/eibhomeserver?instruction=<eib type="write" path="/eib/groups/2/0/2/curvalue" data="11"/>

Response of HomeServer:

HTTP/1.0 200 OK
Server: Loewe HomeServer 1.0
MIME-version: 1.0
Content-type: text/html

<html><script>var answer='<eib state="true" path="database.value/eib/groups/2/0/2/curvalue" data="11"/>';</script></html>

Response in case of an error:

HTTP/1.0 200 OK
Server: Loewe HomeServer 1.0
MIME-version: 1.0
Content-type: text/html

<html><script>var answer='<eib state="false" error="instruction isn't correct"/>';</script></html>

Remark:

The Linux EIB Home Server closes the connection to HTTP clients after its response.

2. Internal interface homeserver <-> homedriver

Homedriver and homeserver exchange data telegrams of the following format (also refer to EIBA Handbook [3]):

The telegram consists of 12 or more bytes:

Byte 0(type): defines the telegram type

0: EIB-Message

1: Non EIB-Message, internal message between homedriver and homeserver.

Byte 1 (total length): Length of message from 2nd Byte to Checksum-Byte.

Byte 2 (control field): defaults to 0x9c.

Bytes 3, 4 (source address): defines the address of the source of the telegram

Bytes 5, 6 (group address): defines the address of the receiver of the telegram

Bytes 7 (routing counter / length): This byte is a combined field, that consists of a part called routing counter and a 2^nd part data length. The default value of routing counter is [110]. It defines Bits 6,5 und 4. The 7th Bit indicates group addressing (value 1) or physical addressing (value 0). The Bits 3, 2, 1 and 0 indicate the number of transfered data bytes, i.e. the length of the transfered value. As an example, length = 1 indicates so called short user data.

Byte 8 (transport control field / APCI ): Defaults to 0. Bits 7, 6, 5, 4, 3, 2 belong to the transport control field. Bits 1 and 0 are the first 2 Bits of the APCI.

Byte 9 (APCI / short user data ): 2 Bits (number 7 and 6) define the rest of the APCI and 6 Bits (number 5, 4, 3, 2, 1, 0) the field short user data. This field short user data is only used, if the transfered value fits in 6 Bits. Otherwise the user data Byte is (or Bytes are) used, i.e. byte(s) of number 10 (and 11).

Byte 10 (Bytes 10, 11, ... – user data): Defines the transfered value, if it does not fit in 6 Bits.

Last Byte (checksum): Special Checksum of the Bytes from the 2^nd bytes till Checksum-Byte. Calculated by Bit-function (not (b0  b1  b2  ...  bn) ), where „“““ means „xor“.

The homedriver transferes the messages from the homeserver to the EIB-Bus, whereby it adds additional headers of other OSI-Layers. (refer to EIBA-Handbook [3])

2. Dynamic description

   1. Interface between Linux EIB Home server and EIB bus

The homedriver communicates with the EIB bus via an FT1.2 compatible interface. The FT1.2 transmission protocol is based on the international standards IEC 870-5-1 und 870-5-2 (DIN 19244) (see EIBA Handbook [3]). The interface is connected to the PC with an RS232 cable and to the EIB bus by means of a so-called „Bus-Access-Unit“ (BAU) Type 2 (refer to EIBA Handbook, chapter 9/4/2, [3]).

The homedriver sets the data interface into the so-called bus monitor mode. In this mode all messages on the EIB bus are transfered to the PC. Thus the Linux EIB Home server can montor each change in the attached EIB installation.

The homedriver transfers every bus monitor mode message to the homeserver. Other messages are processed by the homedriver.

3. homedriver and homeserver files

   Modul / Include-File / Source-File	Beschreibung
   homeserver/include/client.h homeserver/src/client.cpp	Communication with different Clients, i.e. all programs that want to control or monitor the EIB bus. Listening for new clients.
   homeserver/include/homeserver.h homeserver/src /datenbank.cpp	Cmmunication between homeserver and internal database.
   homeserver/include/homeserver.h homeserver/src/driver.cpp	Communication with the homedriver. The homedriver realizes the connection to the EIB bus.
   homeserver/include/homeserver.h homeserver/src/homeserver.cpp	Central class of homeserver. Manages all threads within the homeserver.
   homedriver/main/loeweeibmain.cpp	Main program of homedrivers. Can be used to start the homedriver. You can also start the homedriver as a thread within another program.
   homedriver/include/oeweeibdriver.h homedriver/src/loeweeibdriver.cpp	Central class of homedriver. Starts all Threads and manages the connection to the EIB bus and homeserver.
   homedriver/include/loeweeibsocket.h homedriver/src/loeweeibsocket.cpp	Connection to the homeserver via a socket.
   homedriver/include/ loeweeibconnection .h homedriver/src/loeweeibconnection.cpp	Serial RS232-Connection to the EIB bus.
   homedriver/include/ loeweeibstate .h homedriver/src/loeweeibstate.cpp	State of FT1.2-protocol.
   homedriver/include/ loeweeibmessage .h homedriver/src/loeweeibmessage.cpp	EIB-message formats.
   homedriver/include/loeweeibexception .h homedriver/src/loeweeibexception.cpp	Errors and exceptions.
   homedriver/include/ loeweeibstd.h	Different definitions.

4. Module description: homedriver

   1. Short description

homedriver has two tasks:

1. It receives „Write“- and „Read“-Requests as well as „Response“-messages from the homeserver and transfers them to the EIB bus:

   1. Write: Changes the value of a group address in corresponding devices.

   2. Read: Reads the value of a group address.

   3. Response: Response to a Read-request from the EIB bus. Not implemented by homeserver because of missing necessity.
      
      

2. It transfers bus monitor messages to the homeserver.

You can start the homedriver as a stand-alone program or start it as a thread within another program:

1. stand-alone: Compile loeweeibmain.cpp and start the executable homedriver with the following parameters. Syntax:
   homedriver [–d device] [–p portnumber] [–f inputfile outputfile]
   device: Serial device for the RS232 connection to the EIB bus, e.g. /dev/ttyS4
   portnumber: Port of socket to homeserver.
   inputfile, outputfile: For simulation purposes only. May be used if no EIB installation is available. Better use the Java simulation. The files must already exist. Don't use option –f with –d.
   
   All parameters are optional.
   
   Without parameters the default values apply:
   device: /dev/ttyS0
   portnumber: 8083

2. Call from another program: Create an object of the homedriver by call of the static method:
   LoeweEibDriver::createInstance( int portNumber, char* inputDevice, char* outputDevice, bool simulation)
   portnumber: Port of socket to homeserver.
   inputDevice: Serial device for the RS232 connection to the EIB bus, e.g. /dev/ttyS1, or input file.
   outputDevice: Serial device for the RS232 connection to the EIB bus, e.g. /dev/ttyS1, or output file.
   simulation: True for simulation, i.e. input/outputDevice are files. False for EIB bus, i.e. input/ouputdevice indicate the same serial device.

2. Classes and their associations

The class diagram in Figure 2 shows provides an overview of the classes of the homedriver and the relations of the individual classes to each other. Besides the two classes LoeweEibReceiveMessage and LoeweEibSendMessage, which represent sent and received EIB messages, all other classes are realized as singletons. For this reason the class diagram almost corresponds to the object diagram.

The homedriver communicates with homeserver over a socket with default port 8083. The socket is realized in class LoeweEibDriverSocket, which instantites an object.

One thread writes messages into the Socket and another thread reads messages from the Socket. All messages are held in two message queues, realized by class lfcdllist of the LFC library. Messages, that the homedriver sends to the EIB bus are implemented by class LoeweEibSendMessage and received messages within class LoeweEibReceiveMessage.

The homedriver communicates with the EIB bus over the serial interface. During the initialization phase of the system it switches the FT1.2 data interface by appropriate messages into the bus monitor mode. Subsequently, the homedriver receives all messages, which are sent on the EIB bus. It acknowledges each message with an Acknowledge. The connection to the EIB bus is represented by the class LoeweEibConnection. The condition of the connection is described by a class, which derives from the abstract basis class LoeweEibState. The implementation follows the design pattern state machine.

Figure 2: Architecture of homedriver: Classes and associations.

At the moment the following states are implemented

1. LoeweEibStateReady: In this state the EIB server can receive and send messages.

2. LoeweEibStateSent: A Write (see 1.a in chapter 5.4.1) or Response instruction (see 1.c in chapter 5.4.1) was sent to the BAU. No further message can be sent. The homedriver waits for an acknowledge from the BAU. On receiption of the Acknowledge it returns to state LoeweEibStateReady. If no Acknowledge is received within 200ms, the homedriver repeats the message up to three times. After four unsuccessful attempts the entire connection is reinitialized.

3. LoeweEibStateRequest: A Read-instruction (siehe in Kapitel S) was sent to the BAU. No further message can be sent. The homedriver waits for an acknowledge. If no Acknowledge is received within a certain time, the message will be repeated up to three times. After four unsuccessful attempts the homedriver reinitializes the entire connection.

4. LoeweEibStateWait: An Acknowledge for Read-instruction was received. The homedriver waits then for a response from a device. No further message can be sent. On the receiption of the Response or after a special TimeOut (see EIBA Handbook [3]), the homedriver returns to state LoeweEibStateReady.

The homedriver removes the FT1.2-Protocol-Frame, the status byte and the TimeStamp from all received bus monitor messages and transfers the rest to the homeserver. Repetitions are deleted. Chapter TODO describes the message format.

3. Classes, attributes and methods

   1. EibDriver

Figure 3 shows the class EibDriver, its attributes and methods.

Figure 3: Class EibDriver

2. EibConnection

The Methods and attributes of class EibConnection are shown in Figure 4.

Figure 4: The Connection class

3. EibState

Figure 5 shows the abstract base class EibState and its derived state classes.

Figure 5: Inheritance of state classes.

4. EibSocket

Figure 6 shows the interface of class EibSocket.

Figure 6: Socket class of the homedriver.

5. EibMessage

Figure 7 shows the inheritance of EIB message classes.

Figure 7: Inheritance of message classes.

6. EibException

Figure 8 shows the exceptions used within homedriver.

Figure 8: Exception classes within module homedriver.

4. Functions

Except for the main() function all other methods within module homedriver are class members.

You can start the homedriver

• über via Method run() of class EibDriver

• oder or via main() in file eibmain.cpp.

Refer to section 5.4.1. Please refer also to description within the source code.

5. Module description: homeserver

   1. Short description

The homeserver has two tasks:

1. It communicates via TCP/IP or HTTP with client applications (refer to 5.1.1)

2. It communicates with the homedriver (refer to 5.4)

3. It manages a database with group-addresses and the corresponding actual values.

Der The homeserver stores actual values within an XML-file (default name: eibdb.xml). This file must be initialized once during installation of the server with data of the EIB installation. During operation the server updates the actual values of group-addresses and synchronizes occasionally the XML-file.

You can configure the synchronization interval with the start parameter

-s <value in seconds>
( Deafult: -s 300, i.e. synchronization every 5 minutes, if there are changes. No synchronization: -s 0).

Start command syntax:

homeserver -dr driver-host -db database -dp driver-port -ap applications-port -wp http-port -s synctimeout

Description of parameters:

• driverhost: IP-Address or name of the PC, that runs the homedriver (homedriver and homeserver can run on different computers.)

• driver-port: IP-Port of homedriver.

• database: Name of database file

• applications-port: Port for TCP/IP-client applications

• http-port:Port for HTTP-client applications

• synctimeout: Synchronization interval of database (see above)

Default values:

driverhost: localhost

driver-port: 8083

database: eibdb.xml

applications-port: 8081

http-port: 8080

synctimeout: 300 (in sec)

2. Classes and associations

The class diagram in Figure 9 shows the classes of homeserver und their associations.

3. Casses, attributes and methods

   1. HomeServer

Figure 10 shows attributes and methods of class HomeServer.

2. DatenBank

Figure 11 shows attributes and methods of class DatenBank (german for DataBase)..

Figure 11: Class DatenBank.

3. Driver

Figure 12 shows attributes and methods of class Driver.

Figure 12: Class Driver.

4. DriverMessages

Figure 13 shows attributes and methods of class DriverMessages.

Figure 13: Class DriverMessages.

5. Client

Figure 14 shows attributes and methods of class Client.

Figure 14: Class Client.

6. ClientMessages

Figure 15 shows attributes and methods of class ClientMessages.

Figure 15: Class ClientMessages

7. Interest

Figure 16 shows attributes and methods of class Interest.

Figure 16: Class Interest.

8. PathData

Figure 17 shows attributes and methods of class PathData.

Figure 17: Class PathData.

9. Instruction

Figure 18 shows attributes and methods of class Instruction.

Figure 18 Class Instruction.

6. Bibliography

1. BMBF Lead project Elektronische Multimediale Bedienassistenz (Embassi) www.embassi.de

2. Intel: The Universal Plug and Play (UPnP) SDK for Linux, http://sourceforge.net/projects/upnp/

3. EIB Association: www.eiba.org