Empty cart
Title Page
Login
Search 
 Control Web 8
 Drivers for Control Web
 DataLab
 DataCam
 DataLight
 For schools
 Other software
 Control Web - previous versions
 Services

DataLab IF/EIB intreface driver
 

DataLab IF/EIB intreface driver

Windows 2000 or better required

Code:CW-DLEIB
Price for system integrators (excl. VAT): 0 EUR
List price (excl. VAT): 5 EUR
Manufacturer:Moravian Instruments
 
TOTAL
Dealer Price (excl. VAT):
Total Price (excl. VAT):
*) Estimated availability varies depending on product options. Estimated availability does not include time of shipping and it is not obligatory.

The driver mediates for the application of the Control Web system data of system installation bus-bar EIB (European Installation Bus) for management of buildings connected by means of the interface module DataLab IF/EIB.

Contents of section:

Installation of the driver
Installation of the system USB driver
Installation of own driver for the Control Websystem
EIB
EIB groups, EIS and driver
Group addresses
Data Types
Speed of EIB
Driver behavior
Data objects
Reading from EIB
Writing into EIB
Status of the interface DataLab IF/EIB, exception of the driver
Unrequired data
Specific erroneous driver codes
Parametric file
Section[device]
Section[interface]
Sections [read_on_start] and [read_during_run]
Section[behaviours]
Section[objects]
Section[blocks]
Section[<block_name>]

Installation of the driver

The driver DataLab IF/EIB can be used in systems Control Web 5 and Control Web 2000 always in the environment of the operating systems Windows NT v5.0 and higher which corresponds to the current operating systems Windows 2000, Windows XP and Windows 2003.

Warning:

Other operating systems, e.g. Windows ME or Windows NT 4.0, do not contain system calling necessary for running of the driver and, therefore, the driver is not able to work in them. Due to the requirements for robustness of industrial applications, the use of safe systems with the core being Windows NT v5.0 is desirable in every case and support of only Windows 2000 and Windows XP systems does not represent restriction in practice.

The driver communicates with the interface DataLab IF/EIB by means of USB, which means:

  • the driver does not need any configuration of ports, communication speed or addressing of units,

  • the driver requires for its work that the operating system “know” the interface DataLab IF/EIB. This is ensured by means of the special system USB driver which must be installed in the operating system. After installation, this system will become an internal part of the operating system (like, for example, the driver of the graphic card).

Installation of the system USB driver

The system USB driver can be installed in two manners, automatically and manually. Automatic installation is very easy because it is controlled by the operating system.

  1. connect the interface DataLab IF/EIB,

  2. the operating system informs you about the connection of the new device and in the wizard it calls on you to type the path to the installation information (the file 'dleib.inf'),

  3. the file 'dleib.inf' is located on the installation CD in the folder '\dleibdrv'; you can let the system browse the CD-ROM drive automatically,

  4. after finding the driver and completion of the wizard, the system USB driver will be installed.

Manual installation is in principle similar: on the installation CD in the CD-ROM drive you can find in the folder '\dleibdrv' the file 'dleib.inf', open by left mouse button above the file context menu (local menu) and by selection of the command Install... you will install the driver.

Hint:

Installation from the folder on the CD-ROM is not necessary. It is possible to copy both files on each medium. If, for example, the target computer does not have the CD-ROM drive, it is possible to copy the driver on the hard disk or on USB Flash Disk and install it from this copy.

Warning:

The driver'dleib.sys' is not equipped with a digital signature and the Windows system will notify it and ask whether to continue. If you want to install the driver, select Yes. The presence or non-presence of the digital signature is only a formal matter ensuring the use of only drivers checked by the firm Microsoft and does not influence the function of the driver.

Installation of own driver for the Control Websystem

The driver is installed by means of the program 'setup.exe' in the folder '\dleibdrv' of the installation CD. After running this program the wizard will guide you through the whole installation. We recommend performing full installation.

The driver also contains this documentation. In the case of common installation, this documentation is located in the folder '\Program Files\Moravian Instruments\Drivers\DataLab IF EIB\Doc'.

EIB

The system installation bus EIB (European Installation Bus) is starting to be quickly disseminated and it is not surprising — that by its using it is possible to integrate very easily all the required functions of buildings (and not only them) into self-contained and very easily maintained systems.

The beginnings of this bar date back to 1991 when in the early variant Siemens developed it by specialization of its industrial communication protocol ProfiBUS. The consortium EIBA (European Installation Bus Association) originated and hundreds of companies gradually joined it. Approximately from 2002 the EIB busbar achieved some advantage when under the roof of the consortium EIB-KNX there was standardization and joining with other control systems of buildings.

EIB is very strongly standardized, starting from the internal behavior of basic microprocessor building modules (BAU, BCU), through exact specification of data transfer (EIB communication stack) and possible data types (EIS = EIB Internetworking Standard) up to abstract logical arrangement of parameters and configurations of bus units. This standardization makes it possible for producers of part of the bus to quickly and easily produce and for users of the EIB network to easily and in a unified manner create and configure (by means of ETS, EIB Tool Software).

In terms of information technologies, it is possible to divide EIB into two parts. The first part is the distributed system of units, when each part of the system (unit, actor, device, module, ...) is fully independent and able to perform a certain activity. This part corresponds to EIB parts, like transfer medium (TP = twisted wire, PL = low-voltage distribution 230V or iETS = transfer by means of UDP), communication, configuration of the communication buffer, behavior of units in the case of breakdown of supply, etc. The second part of EIB is more interesting — it contains groups and their linkages.

Groups and their linkages are the main parts which give EIB its great simplicity and elegance.

Group is a highly abstract term which in principle is very simple. The group has a data type (even if it is a number or logical data), a value corresponding to the type (value of temperature) and an address. This is quite clear. The group can bear values, inside statuses of the bus, or it can serve as a process tool (e.g. increase in brightness), it is always located “above” the network of units. Each unit of the network can be connected to the group (by means of group address) (more exactly one or more of its communication points = SAP = Service Access Point). Each network unit receives its image of the group which is remembered and with which it operates. One abstract group so exists in all units in a concrete form. The whole EIB then resolves by means of communication the only matter — how to ensure that these concrete group images in units are identical so that their values mutually correspond to each other.

EIB groups, EIS and driver

Group addresses

EIB group is indicated by the address. The address of the group (group address) is a 15bit number which gives the possibility to define up to 32768 different groups.

Group addresses are written in two manners (it is a matter of selection of the creator of the EIB implementation) as numbers separated by slashes:

  • by means of two numbers, main group and subgroup, and the main group can be within the range 0–15 and the subgroup within the range 0–2047. The writing of the group address in this form may look, for example, as follows: 4/1225.

  • by means of three numbers, main group and middle group and subgroup, and the main group can be within the range 0–15, the middle group can be within the range 0–7 and the subgroup within the range 0–255. The group address in this form may look, for example, as follows: 2/2/173.

Of course, the driver DataLab IF/EIB works with group addresses and supports both their possible forms. In the parametric file (see of the Section Parametric file) the driver naturally uses the mentioned form with slashes, in the map file (in most cases created automatically) and in the application of the Control Web system it is not possible to use slashes for writing.

Therefore, for the map file and the application it is possible to use position writing of the group address where individual parts of the group address are written into the decimal series of the resulting number:

  • the group address in the form g/s is written as a number in the form 1gg0ssss, the address 4/1225 , therefore, will be written as 10401225,

  • the group address in the form g/m/s is written as a number in the form 0ggmmsss, the address 2/2/173 , therefore, will be written as 202173.

It is evident that the writing of a two-part group address starts with number 1 in tens of millions and that the writing of the mail group and the two-part and three-part group address correspond to each other.

The group address in the position writing (or in the application or in the map file) means directly the number of channel driver (and, therefore, it is used, for example, directly in the writing of the attribute driver_index of channels), so during the development of the application it is clear at first sight which groups correspond to the channel.

Data Types

In addition to the address, the group also relates to its data type. The data type of the group as a part of the EIB system is exactly given by the EIB standard (EIS) and, therefore, in the driver it is defined as this EIB (EIS) type. However, the Control Web uses other data types, so it is necessary to introduce between EIS types and types of the Control Web system some rules..

The Control Web system uses series of various types, so linkage with EIS types is natural. EIS types supported by the driver, corresponding data types of the Control Web system and possible meaning of values are defined in the Table .

EIS number EIS function type Control Web meaning of values
1 switch boolean  
2 dimming/control shortint +/-0–100% brightness increment
3 time longcard 0–85399 seconds in day + 0–7 × 100000 for day in week
4 date real Julian date
5 value real  
6 scaling shortcard 0–100% or 0–255
7 drive control boolean up, open =true
9 float real  
10 16bit counter cardinal  
11 32bit counter longcard  
13 ASCII character string  
14 8bit counter shortcard  
15 character string string maximum 23 characters

Mutual conversion of EIS types and data types of the Control Web system

There are several recommendations for correct use of EIS types in the application:

EIS2

EIS defines this type as “an increment or decrement of the value by the fraction 1/1, 1/2–1/64 of its value”, which corresponds to the change by 100%, 50%–1,6%. Changes cannot be fluent and the possible interval +/-0–100% (see Table) will always be converted during the writing into the group to the nearest fraction according to the TableConversion of percentage to fractions of the value for EIS2.

The sign + or – of the number states whether it concerns the increment of the value or its decrement.

EIS3

The number of seconds in a day can be achieved in the application in the simplest manner by reading of the system variable sec_in_day. Day in a week (which is part of EIS3 is rather paradoxical) is added to this value as the number of ten thousands.

If the value is written only as a simple sum of seconds (i.e. without any ten thousands), the driver will use the actual day in a week.

Example: 43200 corresponds to noon (12:00:00) of the actual day (day in a week is determined automatically), 430917 corresponds to Thursday 8:35:17.

EIS4

The Julian date which is required for this data type can be achieved (and it is possible to work with it) by means of native procedures of the system instrument date (e.g.: date.GetDateJD()).

EIS6

EIS defines this type as the range 0–100%. This data type is internally converted to the number from interval 0–255 (ETS understands it in this manner). The driver enables access to both percent range (0–100%) and native range numeric (0–255).

Control Web output EIS2 Control Web input
+/-67–100% +/-1/1 +/-100%
+/-34–66% +/-1/2 +/-50%
+/-18–33% +/-1/4 +/-25%
+/-9–17% +/-1/8 +/-13%
+/-5–8% +/-1/16 +/-6%
+/-3–4% +/-1/32 +/-3%
+/-1–2% +/-1/64 +/-2%
+/-0% +/-0 +/-0%

Conversion of percentage to fractions of the value for EIS2

Speed of EIB

The most often used (and the basic) transfer medium for EIB is twisted wire (TP) by which the interface is connected to the interface DataLab IF/EIB. This transmission medium uses the transmission speed 9600bps, which when considering the length of the shortest possible EIB TP telegram (8 byte), timeout and confirmation of the telegram (ACK) gives the communication speed of 64 EIB telegrams per second.

It would not be too much if we wanted to communicate without stated rules. For technology of buildings it is enough because speeds of monitored and controlled actions are in tens and hundreds of seconds.

The Control Web as general visualization and control tool works with its speed and due to its high performance it is very easy possible to overload EIB bus by careless (or incorrect) application. Therefore, we recommend keeping in the application the EIS standard from which there is the following quotation:

Warning:

EIBA Handbook Series, Internetworking standards, 2.3 General Requirements for Interworking, 2.3.1 Busload:

Speed of repeating — the speed of repeating should be selected very carefully because it significantly influences the operation on the bus and there is a risk of its overloading. The expected load of the bus should be part of the plan of installation of the EIB network.

The following rules are recommended:

  • for user (manual) operations the distance between sent telegrams should be at least 200 milliseconds

  • for automatic operations the distance between sent telegrams should be in seconds or minutes.

Note: In most cases of automatic operations the sufficient speed of repeating is in minutes — for example, measurement of temperature, brightness, time, etc. always measure values which change slowly.

Driver behavior

Data objects

The term data objects is met with in EIB in functional units. Each unit has a certain function, in most cases multiple (for example, two dark channels) and each function relates for the purpose of control and change in behavior to several data objects.

The data object in the unit is connected to the group (by means of the group address) and if it is connected only to one group this data object (as mentioned above) is a concrete image of the abstract group.

Nevertheless, data objects can be connected to more groups at once, one data object summarizes data from all these groups. It is clear from the principle of EIB communication that data objects belonging to more groups always have the value of the last modified group.

The keeping of concrete group images in data objects can (according to the EIB standard) be influenced by the following options:

the object is communicated

if the option is set, the data object reacts to changes in the group, if the option is not set, the object is quite passive (and non-functional for EIB). The driver DataLab IF/EIB does not offer this option — all data objects are communicated

it is possible to read the object from other units (read flag)

if the option is set, it is possible to read the value of the data object inside the EIB network

it is possible to write into the object from other units (write flag)

if the option is set, it is possible to write the value of the data object inside the EIB network — or the object monitors change in the value of the group

the object writes into the EIB network (transmit flag)

if the option is set, the already written value is written (e.g. from the application) into the data object and also into the EIB network and also into the group

it is possible to change the object by unwanted communication (update flag)

this option means that the answer with the read value of the data object from the other unit will influence the data object in this unit. This option is ON in all BCU 1 devices (and it is not possible to switch OFF), in all BCU2 devices and also in the driver DataLab IF/EIB it is possible to set this option

By a combination of the described options it is possible to achieve varying behavior of data objects.

The driver DataLab IF/EIB for Control Web fully supports the above-mentioned options, and for easier work with objects the behavior originated by various combinations of objects is named. Moreover, as described in the Section about the file with parameters, it is possible to determine own behavior (i.e. a combination of options), exactly according to the required behavior of the object. The data object in the driver needs some other setting (because Control Web also has other possibilities than defined by EIB); at present this is the only expansion option:

During reading the object will always be read from the EIB network (from the group) communicate_on_read)

The principle of EIB work is clear — the abstract group, if it is modified, ensures by means of EIB communication the expansion of its new value into all units. Therefore, each unit will always know that the group was changed. Therefore, the data object always has the correct value of the group.

If the driver (application) wants to use the value from the data object, it will read it. If the object works in the manner which is normal in EIB, the application always gets the correct value. However, for example, if the group is passive (or its values are never written into the network because the data object does not have set transmit flag), it can be necessary to read the value from such a group by explicitly reading — which is something more than simply taking the value of the local data object of the driver. Such a manner of work with the group is not too common in EIB (but it is sometimes used), however, the driver must support it.

The object will be read from the EIB during the start of the driver (initial read will be performed) (read_on_start)

All objects inside the driver are “empty” when the driver starts, they contain initialization values (usually zeros). Such initialization values do not correspond to the actual state of the EIB network, of course. Application not regarding this discrepancy would not work correctly (at last until the data inside the driver are synchronized due to EIB updates).

Control Web offers standard means for data synchronization on application startup, that means all data could be read from EIB using only standard application initialization. But EIB offers another (more comfortable) ways to initialize internal values of data objects.

If the driver wants to read data from EIB network on startup, it is necessary to define this data object option (read_on_start). If this option is not defined, the driver reads object's data either after data are changed on EIB network or on Control Web application activity.

Initial read of object data from EIB network can be also altered by parameters of section Section[interface] of parameter file t and read_on_start_repeat_count. The driver repeats the initial read according to the second parameter value (and repeats the read only for objects, for whit the previous read failed). The driver waits for a period defined in the first parameter before each read attempt..

Names used for behavior of objects are used by the driver DataLab IF/EIB (together with the respective combinations of options) as follows:

reader

update + communicate_on_read

tracker

update + write

tracker_init

update + write + read_on_start

transmitter

transmit

transmitter_with_status

update + write + transmit

transmitter_with_status_init

update + write + transmit + read_on_start

server

read

concentrator

update + write + read

source

transmit + read

Data objects which are connected into more groups are in the application accessible under more numbers of channels — one channel number corresponds to each group address. Because all group addresses belong to one communication object, for the use of the object in the application it is possible to use any of its channels (any channel number).

EIB links with the data object its importance, which has practical impact mainly during data transmission in the EIB network. The importance or class of the object (or priority ), can be the following:

ValueMeaning
normal

basic importance, most data objects have this importance. At the same time, it is the value which in data objects of the driver is preset (i.e. it is used if another importance is not set).

high

high importance

alarm

warning importance, the second importance which sometimes appears. The typical use is for messaging of crisis statuses: entrance into the object, breaking of a window or removal of the removable part of EIB elements.

system

system importance is de facto reserved for configuration communication, normal operation in the configured EIB network should not use this importance. In the driver DataLab IF/EIB it is not possible to define it.

The importance of the data object is in the driver DataLab IF/EIB related to the behavior of the object and in the parametric file it is defined in the same place (as it would concern the option of behavior of the data object), see SectionSection[behaviours].

Control Web uses directions when defining channels, which is a simple expression of the way data are transferred (output channel passes data from the application to the outer world and similarly input channel passes data from outer world to the application).

Control Web 5 (and its successors) determines channel directions directly from the driver, so it is not possible to assign wrong direction to channels during application development. Control Web 2000 does not implement this feature and proper channel directions must be defined in the Driver Map File (.'DMF').

The following assignments of channel directions in the '.DMF' file and application are recommended to achieve proper channel (data object) functionality in Control Web 2000. If the different direction is specified the Control Web 2000 can unnecessarily ban the channel usage in particular direction:

data object with only the transmit option:

output

data object without the transmit option:

input

data object with transmit option together with other options:

bidirectional

Reading from EIB

Reading of data from EIB can be performed in the driver in two manners:

reading of local value

This manner of reading of the value from the group is basic and is recommended. It presupposes that groups in the EIB network are active, they work and the respective units write data into them. During the writing into the group the data object in the driver will always automatically receive the value.

During this manner of reading the driver does not communicate , it only provides data for the application. Reading of the value of the data object does not burden the EIB network. In the case of this manner of reading the driver immediately returns data and it does not make sense for it to control communication by means of timeouts (input_timeout).

If the data object is linked with more groups, it will cause change in the value of the data object and writing into any of its groups. For example — if the object is linked with the groups 3/1/0 (light A) and3/1/255 (all switch off), the object receives the value during the writing into any of the groups.

The data object reads data from EIB in this manner, if there is no setting in its behavior communicate_on_read.

communication from EIB

This manner of reading from the group is expanding and is only recommended for use in extraordinary cases — for example, if in a certain situation it is necessary to read from a certain unit some special (e.g. erroneous or status) data object. It is possible to call it required reading.

During this manner of reading the driver communicates, it will require a new value from the EIB network and then after receipt of the group value it will provide the new value for the application. Communication causes loading of the EIB network. In this manner of reading, the driver returns data with delay (after it receives them) and it makes sense for it to control communication by means of timeouts (input_timeout).

If the data object is linked with more groups, the driver communicates data from the first group of the object (from the first address of the object), unless another group is marked for reading (see Section[objects] of parametric file).

The data object reads data from EIB in this manner, if there is setting in its behavior communicate_on_read.

If, together with the option communicate_on_read in the behavior of the object there is the option update or write, there is change in the value of the object also outside the required reading. If in such a situation the application does not wait for termination of communication (see communication of the Control Web system), the application will read the last local value of the data object.

The required reading can be affected by a set of parameters (delay to finish reading, number of read attempts and delay between individual attempts). These parameter are defined separately for initial read and for read during application runtime — viz Sections [read_on_start] and [read_during_run] of parameter file.

Channels of the application which are linked with the data object must be input or bidirectional. At the same time, it is valid (see above) that the value of the data object can be obtained in the application by reading of any channel of the data object (if the channel communicates, the communication is always performed by means of the first group address irrespective of the channel number which was used for access to data of the object).

Writing into EIB

Writing of data into EIB is performed in the driver in only one manner — the value from the application is written into the data object and if in the behavior of the object the option transmit is on, this new value is written into the EIB network into the first group of the object (into the first address of the object).

Therefore, writing of data into EIB typically communicates and, therefore, loads the EIB network.

Because there is communication during writing, it is possible to control and monitor writing and its result by means of the mechanism of the application (communication timeouts output_timeout etc.

Channels of the application which are linked with the data object must be output (output) or bidirectional (bidirectional). At the same time, it is valid (see above) that the value of the data object can be written from the application by means of any channel of the data object (the writing is always performed into the first group address irrespective of the channel number which was used for access to data of the object).

Status of the interface DataLab IF/EIB, exception of the driver

The USB interface by which the driver communicates can be connected or disconnected irrespective of the running of the application and irrespective of the status of the driver, the same is valid for the EIB network (ON/OFF). These statuses may be very important for the application, therefore, the driver provides the application in its status channel.

The number of the status channel is optional (in the file with parameters). The change in the status of the driver (or the change in the status channel) is always reported to the application of the Control Web system by means of driver exception (the parameter driver_exception of instruments), so the application does not have the possibility to react asynchronously to any discrepancies.

The status channel is a 32-bit number (longcard), in which individual bits have the following meaning:

ValueMeaning
0 (USB_connected)

this bit is set if the driver found the connected interface DataLab IF/EIB with the respective identification and successfully communicates with it

1 (EIB_connected)

this bit is set if the interface DataLab IF/EIB is connected with the EIB network and the driver is able to communicate EIB data

2 (init_read_pending)

the bit is set when the driver did not finished the initial read of data objects from EIB network yet

3 (queue_overflow)

the bit is set if the number of recorded and unprocessed changes in data outside the queue Section ) reached the limit stated by the parameter input_queue_length

2, 4–31 (reserved)

reserved for future use

Example of reaction to the change in the status of the driver (in the Control Web system it is also possible to use the event procedure OnDriverException()):

program EIBStatus;
  driver_exception = EIBDriver;

  procedure OnActivate( Time, Instrument, Driver, Data : boolean );
  begin
    if not Driver then
      return;
    end;

    if bitget( StatusChannel, 0 ) = 1 then
      (* we have device *)
    else
      (* we did not find any device yet *)
    end;

    if bitget( StatusChannel, 1 ) = 1 then
      (* we have EIB connection *)
    else
      (* EIB is not connected *)
    end;
  end_procedure;

end_program;

Unrequired data

Warning:

The communication of unrequired data cannot be used in the system Control Web 2000. Support of communication of unrequired data is available in the Control Web 5 system and higher.

By definition, the EIB network is an environment in which individual units perform executing activity quite independently. This means that each unit can modify the value of the group when it wants to according to its need. In terms of other units (and also in terms of the driver DataLab IF/EIB) such change in the group looks quite asynchronous and unexpected — the unit receives data (new value of the group) without requiring them.

The writing into the group (modification of the group value) can be considered on each unit an asynchronous event (events in programs usually mean activities originated from somewhere, not from the program itself). Expression means of the Control Web system offer for asynchronous events event procedures. Because during the communication the work is performed with channels (with data elements linked with the driver), for processing of unrequired data it is possible to use event procedures of the section in which the respective channels are defined.

Communication of unrequired data is totally automatic. As soon as the driver processes the unrequired event, it informs Control Web which will ensure communication of unrequired data outside the queue by the common communication mechanism. It means that unrequired communication is reflected in this respect inside the application in the same manner as required communication — after its completion there is calling of the event procedure On*Communicated (see the description of event procedures of data sections in the documentation) and then, if communications caused change in the value of the element, also the event procedure On*Change.

The mechanism of receipt of unrequired data respects the application — if the application (in the respective data section) does not contain any of the mentioned procedures, no data outside the queue cause any activity of the application (of course, the received value is stored in the driver; only the application does not know about it).

Because (see Section Data objects) each data element relates to possibly more group addresses, during the processing of unrequired data it would be possible to use any channel. For practical reasons it is stated that unrequired data are in the event procedures On*Communicated andOn*Change always offered in the channel which corresponds to the first group address of the object. Or, the first group address of the data object has an extraordinary position not only on the part of EIB (it is used for writing and required reading), but also on the part of the application of the Control Web system — it is the only one used during the messaging of unrequired communication.

The following simple example shows the procedure which processes all event procedures 3/2/13 (EIS2 dimming/control) and stores inside the variable Level the actual status of brightness of the dimmer (the procedure executes part of the function of the dimmer). Always when in the EIB network somebody writes into the group 3/2/13unrequired data are transferred from EIB into the Control Web system, which results in calling of the event procedure (in the example specific for one data element):

data

  var LIGHTS;
    Level : shortcard;
  end_var;

  channel {driver = eib; direction = input};
    DimmingControl = shortint {driver_index = 302013};

    procedure On_DimmingControl_Communicated( Status : longcard );
    begin
      if Status <> 0 then
        (* communication error *)
        return;
      end;
      Level = min2( 100, Level + DimmingControl );
      (* limiting Level to 0 is not neccessary, as shortcard data type cannot contain numbers lower than zero *)
    end_procedure; 

  end_channel;

end_data;

The mentioned example is elementary, it does not deal, for example, with multiple use of the procedure for more elements, etc., nevertheless, the objective of the documentation of the driver is not to repeat information which is described in detail in the documentation for the Control Web system. For more knowledge we recommend the main documentation of the system.

Unrequired data must be (to make sense) stored in the driver during the period from the origination of the event (receipt of the value in the data object) up to its processing in the event procedure. The excess in performance of the Control Web system towards EIB is great, despite this fact it could happen (on old or very burdened computers) that something can be lost without storage (it does not matter for darkening, but somewhere it depends on the number of writings (e.g. the value true), it could cause a problem. The storage of unrequired data is performed in the driver automatically and it is restricted by the parameter input_queue_length (see the section Parametric file). In the case of overflow of the queue, the driver informs the application by means of exception of the driver and setting the bit 3 (queue_overflow) of the status channel. In this case, it is possible to modify (increase) the length of the queue of unrequired data from the beginning 256 events to a higher number.

Specific erroneous driver codes

The driver uses the following specific erroneous codes (these erroneous codes appear in the Message Window and they are also in the attributes error and write_error):

ValueMeaning
1 (ecDeviceUnplugged)

the unit is disconnected — DataLab IF/EIB either does not have supply connected (the USB cable is disconnected) or the serial number of the correctly connected unit does not correspond to the parameter setting id of the parametric file

2 (ecNoEIBConnection)

EIB bus is not connected — DataLab IF/EIB there is no connection with the EIB network

4 (ecUnACKed)

the sent EIB package was not confirmed by any receiving unit.

5 (ecReadResponseTimeout)

the request to read value from EIB network expired, the device did not respond in defined time

6 (ecLineBusy)

the writing of data was unsuccessful, as the EIB network is busy

7 (ecTransceiverFault)

the writing of data was unsuccessful, as the data was not transmitted by hardware

8 (ecOutputQueueOverflow)

the writing of data was unsuccessful, as the limited length of output queue was reached (the error can occur only if the length of the output queue is limited)

Remark:

Erroneous channel codes specific for the driver are in the Control Web system distinguished from general erroneous codes by the value 65,536 (10000H). According to this shift, the Control Web system knows whether it concerns a general error valid within the whole system or a specific error valid for the respective type of driver. In the log window (Log Window) it is possible to see error codes decreased by 65,536 (in the case of DataLab IF/EIB codes 1 to 4). If the application directly reads the codes through the attribute channel:error the value of this attribute will be 65,537 to 65,540.

Parametric file

Although most configurations of the driver are performed by means of the tool of the Control Web system (see Chapter), it is necessary for the parametric file to be described in detail.

The parametric file contains settings which depend on the type of driver, so the parametric file for the driver DataLab IF/EIB cannot be used for another driver (ADAM units, etc.).

The parameter file of the driver DataLab IF/EIB is text file arranged into sections with configuration parameters written in lines in the format key = value. The section serves for main classification, whereas the keys represent own setting. The driver DataLab IF/EIB uses in its parametric file the following default sections:

ValueMeaning
device

section for configuration of the USB interface DataLab IF/EIB on the part of the computer

interface

section for configuration of the EIB communication buffer

read_on_start
read_during_run

section for parameters affecting initial read on application startup and reads during application runtime

behaviours

section for definition of behavior of data objects

objects

section for definition of individual independent data objects

blocks

section for definition of blocks of data objects which share certain settings

[<block_name>]

section for definition of data objects which share certain settings

Inside these objects other (also default) keywords are used for writing of EIS data types and for writing of default behavior (behavior of data objects is described in Chapter Data objects, for writing of behavior in the parametric file, see sectionSection[behaviours]).

There are three manners of naming data types in the driver — by number and two symbolic names:

EIS1

the type is indicated as 1 or as switch or as eis1

EIS2 control

2 or increase or eis2

EIS3

3, time, eis3

EIS4

4, date, eis4

EIS5

5, value, eis5

EIS6

6, scaling, eis6 — range 0–100%

EIS6

scaling255 — range 0–255

EIS7

7, updown, eis7

EIS9

9, float, eis9

EIS10

10, counter16, eis10

EIS11

11, counter32, eis11

EIS13

13, char, eis13

EIS14

14, counter8, eis14

EIS15

15, string, eis15

Section[device]

Section[device] contains the following keys:

ParameterMeaning
id

Each interface DataLab IF/EIB is produced with a unique identification which, as serial number, is indicated on the label on the box of the interface. The driver uses this identification for USB connection with the interface — if the identification does not match, the driver is not connected to the interface.

Example:

[device]
id = 2401406

The key is obligatory.

status_channel

Number of the status channel of the driver. Without the defining of this parameter it will not be possible to use the status channel in the application. The number must not be negative and can be arbitrarily selected with certain restrictions: the number of the status channel must be selected in such a manner that it is not identical with any of the group addresses used in the driver.

Example:

[device]
status_channel = 1

The key is not obligatory, its default value is not defined.

input_queue_length_channel

Number of the driver channel with the actual input queue length (the queue of data received out of order). Without the defining of this parameter it will not be possible to use the actual input queue length channel in the application. The number must not be negative and can be arbitrarily selected with certain restrictions: the number of the status channel must be selected in such a manner that it is not identical with any of the group addresses used in the driver.

Example:

[device]
input_queue_length_channel = 2

The key is not obligatory, its default value is not defined.

output_queue_length_channel

Number of the driver channel with the actual output queue length (the queue of data ready to send). Without the defining of this parameter it will not be possible to use the actual output queue length channel in the application. The number must not be negative and can be arbitrarily selected with certain restrictions: the number of the status channel must be selected in such a manner that it is not identical with any of the group addresses used in the driver.

Example:

[device]
output_queue_length_channel = 2

The key is not obligatory, its default value is not defined.

Section[interface]

Section[interface] contains the following keys:

ParameterMeaning
address

Physical address of the interface, the address which will be reported in the EIB network. The address is physical, the first two of its parts (area and line) should correspond to the line to which the interface DataLab IF/EIB is connected.

Example:

[interface]
address = 14.1.255
input_queue_length

Number of unrequired communications (EIB packages) which the driver keeps up to the moment of the processing of the application (by means of event procedures). Because the application in the Control Web system has a several times higher performance compared with EIB communication, it will not be necessary to modify this parameter.

Example:

[interface]
input_queue_length = 1000

The key is not obligatory, its initial value is 256.

output_queue_length

Number of packets ready to be sent, stored in memory by the driver in the case packets cannot be send fast enough. Because the Control Web application can run much faster than the EIB bus is able to respond, it can happen that the EIB bus cannot handle all communication requests so some data can be lost. The output queue stores requests up to the time the EIB network can accept them.

Obviously the application can continuously send more data than the EIB bus can accept. This means the output queue would continuously grow. The output_queue_length parameter then limits the maximum queue length. If the queue is full, the write request will fail with the error 8 (ecOutputQueueOverflow).

Example:

[interface]
output_queue_length = 10000

The key is not obligatory, its initial default is 4,294,967,295 (that means maximum).

ACK_method

Manner of behavior of the interface DataLab IF/EIB for receipt of the EIB package. Each package in EIB communication should be acknowledged (ACK = acknowledge), and in normally installed EIB networks it is done. Usually, in each group there are sources (transmitters) of values, as well as their receivers (actors, etc.), so confirmation of the package can be acknowledged.

If the package is not acknowledged, EIB usually repeats it, which increases loading of the network.

If the driver DataLab IF/EIB is used mainly for visualization, it is probable that the EIB network and its groups will always have the receiver which acknowledges packages. However, if the Control Web is used in the EIB network with higher performance, for solution to logical linkages, etc., it may happen that some of the groups will have another recipient than the driver DataLab IF/EIB. Then, it is correct that only the driver must take care of acknowledgment of such packages.

The parameter ACK_method can have two values: none and all. In the case of the first selection of the interface no packages are acknowledged, in the case of the second selection of the interface all packages are acknowledged.

Example:

[interface]
ACK_method = all

The key is not obligatory, its initial value is none.

ACK_timeout

Delay for which the driver waits for packet acknowledge (both positive and negative). If the delay expires, the driver sends another prepared packet to the EIB network.

Example:

[interface]
ACK_timeout = 750

The key is not obligatory, its default value is 500. The number represents time in milliseconds.

BUSY_delay

Delay for which the driver waits before repeating the request if the EIB network is busy in time of output request. The request is repeated no more than tree times.

Example:

[interface]
BUSY_delay = 500

The key is not obligatory, its default is 200. The number represents time in milliseconds.

read_on_start_delay

Delay for which the driver waits before repeated initial object read (the driver reads only objects, which data was not read yet). Number of initial read attempts is defined by parameter read_on_start_repeat_count.

Example:

[interface]
read_on_start_delay = 15000

The key is not obligatory, its default is 5000. The number represents time in milliseconds.

read_on_start_repeat_count

Number of initial object data read attempts (the driver reads only objects, which data was not read yet). The delay between individual attempts is defined by the parameter read_on_start_delay.

Example:

[interface]
read_on_start_repeat_count = 5

The key is not obligatory, its default is 3.

Sections [read_on_start] and [read_during_run]

Both sections contain settings defining behavior of requested reads from EIB network. The [read_on_start] section defines parameters for initial read on driver startup, [read_during_run] section defines parameters for requested reads during application runtime for objects with communicate_on_read parameter. The reading is affected by the following keys (all keys can be defined in both sections):

ParameterMeaning
timeout

Delay for which the driver waits to EIB device response (that means for the read object data). If no response arrives until this delay the read attempt fails with the error 5 (ecReadResponseTimeout).

Example:

[read_on_start]
timeout = 2500

The key is not obligatory, its default value is 1500 in [read_on_start] section and 2500 in [read_on_start] section. The number represents time in milliseconds.

repeat_count

Number of read attempts. The driver repeats requests if the read fails.

Example:

[read_on_start]
repeat_count = 3

The key is not obligatory, its default value is 1 in both [read_on_start] and [read_on_start] sections.

delay

Delay between individual read attempts.

Example:

[read_on_start]
delay = 250

The key is not obligatory, its default value is 150 in [read_on_start] section and 0 in [read_on_start] section. The number represents time in milliseconds.

Section[behaviours]

Section[behaviours] contains the following keys:

ParameterMeaning
behaviour

the key which serves for definition of own behavior of data objects; the behavior is written as the name of the option followed by combinations of options of behaviors separated by commas. The sequence of options is not obligatory.

The key in the section may repeat without restriction.

Options are derived from options of communication of data elements (see Section Data objects); so it is possible to write into the key the list selected from the following keywords:

ValueMeaning
readable

for the option of the object read

writable

for the option of the object write

transmit

for the option of the object transmit

updateable

for the option of the object update

communicate_on_read

for switching on the required reading

read_on_start

for switching on the initial reading

high

option for setting of importance high (see section Data objects)

alarm

option for setting of importance alarm (see section Data objects)

Example:

[behaviours]
behaviour = all, readable, updateable, transmit, communicate_on_read, writable
behaviour = my_transmitter, transmit, alarm

Names of behavior (in the example all and my_transmitter) can be used in the driver anywhere the writing of the behavior name is required, which is either in the keys object and objects in the Section objects and in the key behaviour in the Section [<block_name>].

In addition to such user-defined behavior, the driver distinguishes default behavior, so it is probable that in common EIB settings it will not be necessary for [behaviours] to be used. Default behavior is (for more information, including its explanation, see Section Data objects): reader, tracker, transmitter, transmitter_with_status, server, source and concentrator.

Section[objects]

Section [objects] contains the following keys:

ParameterMeaning
object

the key which serves for definition of one communication object, and the object can be connected to several groups

objects

the key which serves for definition of more communication objects at once, and each object is connected into one group

Keys object, as well as keys objects may be repeated without restrictions. Each object is written by means of these keys on individual lines.

The format of writing of keys is as follows:

object/objects = <behaviour>, <EIS type>, <address_list>

Individual parts in the line mean:

ParameterMeaning
<behaviour>

the name of behavior; the name may be written of some default behavior transmitter) or any behavior defined by means of the key behaviour in the Section behaviours.

<EIS type>

EIB data type of the object, number or keyword; possible values are written above.

<address_list>

The group address, the list of group addresses or the range of group addresses.

Everything can be illustrated from the example:

[objects]
object = transmitter_with_status, switch, 3/1/9, 3/0/9
objects = transmitter, scaling, 3/3/0..3/3/13, 3/3/24
object = transmitter, 5, 4/0/0
...
  • The first line defines one object connected into two groups (3/1/9 and3/0/9), according to the rules described in Section Driver behavior the first group address 3/1/9) has an exclusive position and it is used for writing values, the announcement of receipt of unrequired data and required reading of values, if there is no other group address selected for reading.

  • The second line defines 15 objects with addresses 3/3/0, 3/3/1, ..., 3/3/13 and3/3/24.

  • The third line defines again the independent object with the type 5 i.e. value, the object is connected into one group.

The definition of object having more group addresses (definition using object =) allows determine the single group address used for required reading (aka the reading directly from EIB network). The determination need not be set for any of defined address, in such case the first group address for the required reading will be used. Selecting of the group address used for required reading is simple only by writing the letter r or R exactly (without a space) before the group address. Slightly modified preceding sample shows this:

[objects]
object = transmitter_with_status, switch, 3/1/9, r3/0/9
...

So, the object defined in the sample will use the group address 3/1/9 for sending data and for the announcement of receipt of unrequired data, the group address 3/0/9 for required reading and both the addresses for receiving of data from EIB network.

Section[blocks]

Section[blocks] contains the following keys:

ParameterMeaning
block

Repeated key which serves for the driver only as information which all sections [<block_name>] with group definitions of objects are to be searched in the parameter file.

Keys refer to other sections which define data objects.

Example:

[blocks]
block = Lights
block = Presence
block = Temperatures

Section[<block_name>]

Section[<block_name>] in the parametric file serves for easy writing of many data objects only by writing of their group address. The name of the section can be arbitrary. For the use of these sections there is only one condition: the name of the section (or <block_name>) must be known for the driver from some key block of the Section blocks.

Section[<block_name>] contains the following keys:

ParameterMeaning
behaviour

Behavior of data objects which is to be valid for all data objects defined inside this section. The name can be written as one of the default behaviors (transmitter) or any behavior defined by means of the key behaviour in the Section behaviours.

The parameter in the Section is obligatory.

type

EIS type of data objects of this section (possible values – see above).

The parameter in the Section is obligatory.

object

The key which serves for definition of one communication object, and the object can be connected to several groups.

objects

The key which serves for definition of more communication objects at once and each object is connected into one group.

Parameters of the object and objects are written similarly as in SectionSection[objects] with the difference being that not even behavior or EIS type is mentioned in the writing. The following example shows the definition of several sections <block_name>:

[Lights]
behaviour = transmitter
type = switch
objects = 10/5/20..10/6/20, 11/1/0..11/1/15, 1/1/5
object = 1/1/6, 1/1/7

[Presence]
behaviour = tracker
type = switch
objects = 2/0/1, 2/1/1, 2/2/1, 2/3/1, 2/4/1, 2/5/1

[Temperatures]
behaviour = tracker
type = eis5
objects = 3/4/128..3/4/143
objects = 3/5/64..3/5/95