| 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.
connect the interface DataLab IF/EIB, 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'), 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, 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: 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: | Value | Meaning |
|---|
| 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: | Value | Meaning |
|---|
| 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): | Value | Meaning |
|---|
| 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) |
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: | Value | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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): | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Value | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| <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: | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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
|
