En Ocean Java Api Istochnikov Chand 1

JAVA
Application Programming Interface
for
EnOcean

Submitted by: Submitte d to : Prof. Ulrich Trick
Vladimir Istochnikov Course: Mobile Computing.
Piyush Chand

Acknowledgement

We are heartily thankful to our supervisors, Armin Lehmann and Thomas Eichelmann, whose
encouragement, guidance and support from the initial to the final level enabled us to develop
an understanding of the project.

Lastly, we offer our regards to all those who supported us in any respect during the
completion of the project.

Vladimir Istochnikov
Piyush Chand

Table of contents

1 Project Goal ..................................................................................................... 2
1.1 Report Structure ....................................................................................... 2
2 Theoretical Basis ............................................................................................. 3
2.1 EnOcean Equipments ............................................................................... 3
2.2 EnOcean Equipment Profiles ................................................................. 10
3 Used Practical Framework ............................................................................ 12
4 Developed Java API ...................................................................................... 15
5 Application Example ..................................................................................... 21
6 Future Application......................................................................................... 15
7 Conclusion ..................................................................................................... 26
8 References ..................................................................................................... 27

Mobile Computing project: Java API for EnOcean

1 Project Goal
Developing an Application Programming Interface (API) for an EnOcean BSC-BAP-
TX. The EnOcean BSC-BAP is a wireless access point for EnOcean wireless technology. This
API will give us the opportunity to control various kinds of sensors and actuators based
equipments through personal computers. This developed API, can be extended for the
implementation of home automation technology for various kinds of value added services in
the telecommunication architecture.

1.1 Report Structure
The report contains following chapters:
 Theoretical basis. Here theoretical background with respect to sensors and actuators used
for home electrical appliances and also the EnOcean BSC-BAP-TX Access point is
described. The following subchapters are included:
o A description of used EnOcean devices, where the detailed information on
concrete EnOcean devices is provided.
o EnOcean equipment operates with special messages, called telegrams. The
description of EnOcean Devices profiles with corresponding telegrams is
provided.
 Used practical framework. Here we describe the developing tools used for creating the
API. The implemented EnOcean framework is described.
 Developed Java API: here the implemented Java API for EnOcean using BSC-BAP-TX
as access point is described.
 Application example. An example of the developed API usage is given here. Here the
developed classes are implemented together to enable the EnOcean equipment
functionality.
 Future application. Here the possible implementation of developing a resource adapter
for Java APIs for Integrated Networks (JAIN) Service Logic Execution Environment
(JSLEE) is proposed. Some other examples of EnOcean devices implementation in the
real world are given.

2


2 Theoretical Basis
Home automation is the residential extension of "building automation". It is automation of
the home, housework or household activity. Home automation may include centralized control
of lighting, heating, ventilating, and air conditioning (HVAC), appliances, and other systems, to
provide improved convenience, comfort, energy efficiency and security. Home automation for
the elderly and disabled can provide increased quality of life for persons who might otherwise
require caregivers or institutional care.
EnOcean technology is based on the energetically efficient exploitation of applied slight
mechanical excitation and other potentials from the environment using the principles of energy
harvesting.
In order to transform such energy fluctuations into usable electrical energy,
electromagnetic, piezo generators, solar cells, thermocouples, and other energy converters are
used.
The EnOcean products, such as sensors and radio switches do not need a battery and are
engineered to operate maintenance-free. The signals from these sensors and switches can be
transmitted wireless over a distance of up to 300 meters. Early designs from the company used
piezo generators, later replaced with electromagnetic energy sources to reduce the operating
pressure to 7 Newtons, and increase the service life to 50,000 operations.
Packets of data are relatively small with the packet being only 14 bytes long and are
transmitted at 120 kbit/s. Three packets are sent at pseudo-random intervals reducing the
possibility of packet collisions. Switches also transmit additional data packets on release
of push-button switches, enabling other features such as light dimming to be implemented. The
transmission frequency used for the devices is 868.3 MHz [3].

2.1 EnOcean Equipments

In this part of the chapter, information about the EnOcean Equipments or in general
terms the used energy harvesting devices is discussed. Firstly, the Gateway is discussed, where
the technical functionalities and the features of the gateway are mentioned.

BSC-BAP-TX Wireless Access point for EnOcean Technology

Figure 1 is the picture of the used BSC-BAP-TX Gateway. This gateway consists of a
TCM-120 module, which is used in our practical implementation of the project.

3


Figure 1: BSC-BAP-TX

LAN - Access Point for control of “embedded intelligence” products and other EnOcean
compatible devices. Integration of up to 128 actuators and an optional number of transmitters
that is compatible with EnOcean wireless technology per BAP. [1]

 It can be integrated in an existing network infrastructure.
 Visualization with SoftwareBSC- BoSe Pro is possible.
 Connection with Power over Ethernet (PoE) is possible.
 BSC - BAP is a low consumption device with max. < 0, 5 Watt only.

a) Technical Data

 Integrated Radio Transmitter, EnOcean PTM 200
 External power supply
 Control by Power over Ethernet.
 Rj45 connector
 Removable antenna with SMA (SubMiniature version A) -connection

b) Information on Radio Sensors Transmission Range

As the radio signals are electromagnetic waves, the signal is damped on its way from the
sender to the receiver. That is to say, the electrical as well as the magnetic field strength is
removed inversely proportional to the square of the distance between sender and receiver.
Beside these natural transmission range limits, further interferences have to be considered:
Metallic parts, e.g. reinforcements in walls, metallized foils of thermal insulations or metallized
heat-absorbing glass, are reflecting electromagnetic waves. Thus, a so-called radio shadow is
built up behind these parts. It is true that radio waves can penetrate walls, but thereby the
damping attenuation is even more increased than by propagation in the free field. Penetration of
radio signals [1]:
 Wood, gypsum, glass uncoated 90...100%
 Brick, pressboard 65...95%
 Reinforced concrete 10...90%
 Metal, aluminum pasting 0...10%

4


For the praxis, this means that the building material used in a building is of paramount
importance for the evaluation of the transmitting range. For an evaluation of the environment,
some guide values are listed:

c) Radio path range/-penetration:

 Visual contacts: typ. 30m range in passages, corridors, up to 100m in halls
 Rigypsum walls/wood: typ. 30m range through max. 5 walls
 Brick wall/Gas concrete: typ. 20m range through max. 3 walls
 Reinforced concrete/-ceilings: typ. 10m range through max. 1 ceiling

Supply blocks and lift shafts should be seen as a compartmentalization In addition, the
angle with which the signal sent arrives at the wall is of great importance it depends upon the
angle, the effective wall strength and the damping attenuation of the signal changes. If possible,
the signals should run vertically through the walling. Walling recesses should be avoided. [1]

Figure 2: Radio path range/-penetration

As, you can see on the right side of the figure 2, that the iron casts a radio shadow between
the receiver and the sensor. This is a drawback while implementing the sensor and actuator
based home automation environment.
On the left side of the figure 2, you can differentiate the effective range of radio frequency
between two receivers. As one is receiving a very good range of radio frequency and the other
one is receiving it at a slightly lower level.

Wireless Actuator (FSR61NP)

In figure3, the wireless Actuator is shown. This wireless actuator is an impulse switch
with integrated relay function and features state-of-the-art hybrid technology. It combines the
wear-free receiver and evaluation electronics and a bistable relay with zero passage switching.
By using a bistable relay coil power loss and heating is avoided even in the on mode. [2]
In addition to the wireless control input via an internal antenna, this universal impulse
switching relay can also be controlled locally by a conventional 230 V AC control switch if
fitted previously. [2]
With the top rotary switch in the setting LRN up to 35 wireless push-buttons can be
assigned, of which one or more central control push-buttons.
In addition wireless window/door contacts with the function normally open (N/O)
contact or normally closed (N/C) contact while the window is open. The required function of
the impulse switch with integrated relay function can then be selected:

5


 ER = switching relay
 ESV = impulse switch. Possibly with off delay, then:
 + = ESV with push-button permanent light
 + = ESV with switch-off early warning
 + = ESV with push-button permanent light and switch-off early warning
If the permanent light function is switched on, the function can be activated by pressing
the push-button for longer than 1 second. This function switches off automatically after 2 hours
or by pressing the push-button. [2]

Figure 3: Wireless Actuator (FSR61NP)

If the switch-off early warning is switched on, the light starts to flicker approx. 30
seconds before time-out. This is repeated three times at decreasing time intervals. If both
switch-off early warning and push-button permanent light are switched on, switch-off early
warning is activated before automatic switch-off of the permanent light. The function ESV on
the bottom rotary switch sets the off delay from 2 to 120 minutes. In setting normal impulse
switch function, ES without off delay, without push-button permanent light and without switch-
off early warning. In setting ER = switching relay of the other rotary switch, this 2nd rotary
switch fulfils a safety and power saving function in the settings except. If the switch-off
command is not recognized, e.g. since the push-button is jammed or it was pressed too quickly,
the relay switches off automatically on expiry of a time adjustable between 2 and 120 seconds.
[2]
When a FTK is taught-in, this time function is turned off. If there are open flames,
waste air fans may only be switched on if the windows are open to ensure oxygen supply. In
time setting 120 the contact opens with a delay of 4 minutes if the brightness level is sufficient.
In time setting the contact opens instantly. The local and central push-button control is still
possible. [2]
Motion detection is detected with taught-in wireless motion detector FBH which can be
set in the function setting ER. The device switches on when motion is detected. If no more
motion is detected, the contact opens after the time delay setting t = 2 to 255 seconds
(Position). [2]
Outdoor brightness sensor and motion detector can be used together with function
setting ER to evaluate motion only in darkness. If the FAH detects brightness, the contact
opens immediately. When teaching-in, the switching threshold is also taught-in: between break
of twilight and complete darkness. [2]

6


The LED performs during the teach-in process according to the operation manual. It
shows wireless control commands by short flickering during operation. [2]

Wireless single-phase energy meter (FWZ12-16A)
In figure 4, the wireless single-phase energy meter is shown, this single-phase
energy meter measures active energy by means of the current between input and output and
transmits the consumption and meter reading over the Eltako wireless network. [3]
The internal power consumption of maximum 0.3 watt active power is neither
metered nor indicated. Like all meters without PTB (Physikalisch-Technische Bundesanstalt)
or MID (Measuring Instruments Directive) approval in Germany, not approved to levy
electricity charges. One phase conductor with a maximum current up to 16A can be connected.
The rush in current is 20mA. The consumption is saved to a non-volatile memory and is
immediately available again after a power failure. [3]
Wireless telegrams: When the power status changes by 10 percent, a telegram is
transmitted within 20 seconds. A change in meter reading is transmitted immediately. A full
telegram comprising meter reading and power status is transmitted every 10 minutes. When the
power supply is switched on, a teach-in telegram is sent to teach in the associated energy
consumption indicator. If the L input and the L output are interchanged when hooked up, a
normal rate (HT)/off peak (NT) switchover telegram is transmitted to indicate the hook-up
error. [3]

Figure 4: Wireless Single-Phase Energy Meter (FWZ12-16A)

This single-phase energy meter measures active energy by means of the current
between input and output, and then transmits the consumption and meter reading over the
Eltako wireless network. [3]
Evaluation on PC can be done by using the Visualization and Control Software FVS or
the energy consumption indicators FEA55LED or FEA55D. FVS-Energy and FVS-Home
support up to 100 transmitter modules, FVS-Professional up to 250 transmitter modules. [3]

7


Wireless Switch/Push-button (FT4F)
In figure5, the Wireless Switch is shown; this wireless switch/push-button is used in the
practical framework. The Wireless push-buttons with one rocker can transmit two evaluable
signals: press rocker up and press rocker down. Wireless push-buttons with double rocker can
transmit four evaluable signals: press two rockers up or down. [4]

Figure 5: Wireless Switch/Push-button (FT4F)

The mounting base can be screwed onto a flat surface or glued to the wall, on glass or on
furniture using the enclosed adhesive foil. Use the sleeves in the 55mm socket box for screw
mounting. Then the wireless switch lighting FTB can be snapped into the mounting plate from
the rear. [4]
The unprinted double rocker is snapped onto the wireless module at the factory. If the
double rocker is replaced by the large unprinted rocker, remove the rocker halves by pulling off
to the front. Do not bend towards the middle. Then snap the large rocker so that the markings 0
and I on the back line up with the same markings on the wireless module. [4]

Wireless Motion/brightness sensor (FBH55)
In figure 6, the wireless motion sensor is shown, this wireless motion/brightness sensor
FBH55 requires no installation depth behind the mounting plate. It transmits a message to the
Eltako wireless network every 100 seconds if the brightness changes by min. 10 lux. If the
sensor detects motion, it sends a signal twice immediately. The switch-off signal is sent after
the off delay which has a fixed setting of 1 minute. If there is no change, a status message is
sent every 20 minutes. [5]

8


Figure 6: Wireless Motion/brightness sensor (FBH55)

When teaching-in actuators, the switching threshold is defined for switching the light
on/off depending on the brightness. Additional variables are also taught-in on the FKR12.
When an FBH detects movement, switching takes place then and time delay only starts when
all FBHs taught-in in an actuator detect no more movement. [5]

Standardization of Radio Protocols:
In a home automation environment, it has become very important to standardize the radio
protocols, which allow developers and engineers to provide a common platform for
communication with radio frequency. Figure 7, shows the standardization of radio Protocols.

Figure 7: Standardization of Radio Protocols [7]

2.2 EnOcean Equipment Profiles
In this part of the chapter, information with respect EnOcean Equipments and the
telegram messages will be provided.
Before, discussing about equipments and telegram messages, it is useful to know about
the radio data telegram and the features of radio sensors. The transmission of the telemetric
signals, EnOcean has defined a dynamic radio data telegram that is adapted to the individual
application. [7]

It is optimized to the essential features of energy autarkic radio sensors:

• Minimal energy demand
• Minimal collision risk
• Maximum transmission reliability
• Wide transmission range
• Easy extensibility
• Suitable for uni- and bi-directional communication
• Flexibility for adaptation of different data structures and data quantities

9


• Data encryption option

EnOcean Telegram Stack
In figure 8, the telegram stack is presented, in this figure it can be seen how the
telegram stack is organized and which fields are useful for developing an EnOcean message. In
figure 9, a detailed description of the telegram message is given.

Figure 8: EnOcean Telegram Stack [6]

Figure 9: Detail Description of the EnOcean Telegram [6]

Following, a detailed description of the Telegram message is provided:

10


1. SYNC_BYTE: This field of the stack is used for synchronization of received bytes and
sent bytes. It consists of two sync bytes which are 8 bits each
Hexadecimal representation: 0xA5, 0x5A i.e. a55a
2. H_SEQ: This field of the stack is the Header Sequence; this field identifies which type
of function the telegram message will implement. The length of this field is of 3 bits.
Types of telegram functions:
1. RRT (Received Radio telegram): the function to receive radio data telegram on the
BSC-BAP-TX gateway. Hexadecimal representation: 0x00 i.e. 0
2. TRT (Transmit Radio Telegram): This function of the telegram message provides
the function to transmit radio data telegram to the BSC-BAP-TX gateway.
Hexadecimal representation: 0x03 i.e. 3
3. RMT (Receive Message telegram): This function of the telegram message provides
the function to receive telegram messages from the energy harvesting devices.
Hexadecimal representation: 0x04 i.e. 4
4. TCT (Transmit Command Telegram): This function of the telegram message provides the
function to send command telegram messages which means, the energy devices can be
controlled by using this telegram message. Hexadecimal representation: 0x05 i.e. 5
3. LENGTH: This field of the stack provides the information about the number octets
following the header octet. This field length is of 5 bits and combines with H_SEQ field
to complete 1 Byte of the telegram stack.
Hexadecimal representation: 0x0b i.e. B

In Table 1, it can be seen, how the conversion is being done, to understand which
relevant telegram message is to be sent or to understand which telegram message is being
received.
Table 1.

Telegram H_SEQ Length H_SEQ & LENGTH Hexadecimal
Functions Representation
3bits 5bits 8bits
Combining Both
RRT 000 01011 00001011 0B
TRT 011 01011 01101011 6B
RMT 100 01011 10001011 4B
TCT 101 01011 10101011 AB

4. ORG: This field defines which type of telegram is used within the telegram stack. For
TCM-120 module there are 6 types of telegram messages, which are as follows:

11


Figure 10: Description of ORG field
A more detailed information on EnOcean equipment telegrams please refer to the
official EnOcean equipment profiles description [6].

3 Used Practical Framework
In this part of the report, we will be discussing the framework, programming tools and
devices that we have used for the project.
1. Software tools used for developing the Java API.
I. Programming Language used for the developing the API: JAVA Standard Edition Core.
II. Programming Integrated Development Environment (IDE) used: Eclipse, version-1.3.5.
This is a software application that provides comprehensive facilities to computer
programmers for software development.
III. Developing Graphical User Interface: NetBeans, version 6.9.1.
This is a Java desktop applications and an Integrated Development Environment (IDE)
for developing with Java and other programming languages.
IV. Wireshark
This software is used for network troubleshooting, analysis, software and
communications protocol development.
2. Devices Used:
I. EnOcean BSC-BAP.
II. Eltako Single-Phase Energy Meter.
III. Eltako Wireless Actuator.
IV. Signal Lamp.
V. Eltako Motion Sensor.
VI. Eltako Switch.

12


For the detailed information on the listed devices please refer to subchapter 2.2. of the
current report.

Figure 11: The Practical Framework

The above mentioned figure 11, provides the information of the architecture that has
been used to develop and test the program and the user interface.
In the framework, the BSC-BAP-TX Wireless Access Point (for more information read
the subchapter 2.1) is connected with PC by using Ethernet. The IP-address is configured for
the PC and the Wireless Access Point, which makes the PC as a server and the wireless access
point as a client; this will be discussed in detail in chapter 4.
The framework consists of a wireless actuator, (for more information about the wireless
actuator read the subchapter 2.1) which is connected to the signal lamp, this actuator will
receive telegram messages from the BSC-BAP-TX Wireless Access Point, and after receiving
the telegram message the actuator will perform an action, in this case it will be glowing of the
lamp.

13


Figure 12: Created practical framework

Figure 12 is the photo of the created practical framework. The Eltako devices, mentioned
in the chapter 2 are built on the board. The built devices board complies with safety precautions
required for safe usage of the devices within the project.
The wireless motion sensor (for more information read the subchapter 2.1) sends out
telegram messages to the BSC-BAP-TX wireless access point, these messages are read on the
PC. By using this motion sensor, a scenario can be created in which, some motion on the device
is detected and an action is performed.
The wireless switch (for more information read the subchapter 2.1) sends out telegram
messages to the BSC-BAP-TX wireless access point, these messages are read on the PC and
then are used by the developed user interface on the PC (for more information read chapter 5)
The wireless energy meter sensor (for more information read the subchapter 2.1) also
sends out telegram messages to the BSC-BAP-TX gateway, the wireless energy meter only
works when a large amount of energy is disseminated through the meter, so a lamp of at least
20 watts should be connected to the energy meter to send out valuable telegram messages to the
BSC-BAP-TX wireless access point. This wireless access point is connected to the PC, which
will read out messages received from the wireless energy meter.

14


4 Developed Java API
The basic model of any network interface at the programming level completely depends
upon the concept of client/server network programming. In our implementation the BSC-BAP-
TX will act as a client and the personal computer will act as a server.
The BSC-BAP-TX gateway has a set of ports which can be used for various kinds of
functionality with respect to the EnOcean controlling devices. These ports provide us the
opportunity to program a network interface between the BSC-BAP-TX gateway and the
personal computer. The combination of the IP address and the port is called socket. Further on
we are calling personal computer as server, and the BSC-BAP-TX as gateway.
The different types of ports and their functionality are described as follows:

1. Port 2010 : Setting Server and Gateway IP-addresses
This port is used for initial configuration of the gateway IP-address and the server IP-
address. This port is used to establish a connection and configure the BSC-BAP
Gateway and Server.

SETIP#<IP-ADRESS>#<Subnetwork>#<Server-IP>

This command can be used anytime to change the IP-addresses of the gateway and the
server. In this project following IP addresses were configured:
- BSC-BAP-TX Gateway: 192.168.0123
- Server: 192.168.0.64

2. Port 2001: open connection for the Gateway

This port is used to establish the connection between the gateway and the server. It
means gateway is trying to connect to the port 2001 of the server in a cyclic way, each 10
seconds.
The EnOceanServer Java class, shown on the figure 13, provides this functionality:

Figure 13. API EnOceanServer Class

15


The server socket is created in the EnOceanServer class method called MultiServerStart,
lines 9 – 11 in the figure 13. Server port 2001 will be opened to make gateway be able to
connect. Another important line is line 17, where the connection from gateway is accepted by
server. With this command the server gets the IP-address of the gateway and the remote port
(gateway socket).
After the server has opened port 2001 and the gateway has successfully connected, the
gateway is expecting the following message from the server:

accept#<Timestamp>*<TransferPort>

This is implemented within the class SendReceive, which is shown on figure 14.

Figure 14. SendReceive Class

In this class there is the method called Connect, which receives as the parameter the
socket object, which is basically the accepted connection from the gateway (see figure 13, line
17). For this socket the output stream is opened, and the necessary message (figure 14, line 23)
was sent. It is seen there that the transfer port was chosen to be 2100. Notice that “Timestamp”
part of the message can be called with System.nanotime() command.
After the transfer port was chosen and sent to the gateway, the gateway is sending the
following message back (note that gateway is still sending it to the server port 2001):

16


<< <BAP-ID>#<Message>#<Timestamp>

The method Connect from the class SendReceive, shown in figure 14 has all parts of the
message as strings printed into console.
Note: BAP-ID is a necessary part of this message. It is printed to the console in decimal
format. It is important to know the BAP-ID in hexadecimal format for sending out the
telegrams to the devices through the gateway.

3. Ports from 2100: the transfer ports on the Server for receiving
the telegrams from the Gateway
These ports are to be chosen by user. It can be any port from 2100. We chose port 2100
for the data exchange between gateway and server. This provides the functionality to receive
the telegrams sent from the gateway. Now as we informed the gateway that the server has port
2100 for transfer (figure 14, line 23), we need to open the 2100 server socket. Figure 15
represents the continuation of the SendReceive class, where the server socket on port 2100 is
opened, and the gateway attempts to connect to this port are accepted.

Figure 15. SendReceive class open transfer port socket

On the figure 15 lines 40 – 53 are opening the server socket on port 2100 (chosen
transfer port) and client socket for gateway connection. After this socket was opened, the server
is able to receive telegrams from the gateway on port 2001.

17


Note 1: Understanding of the written code supposes having knowledge of Java socket
programming. For deeper understanding of server and client socket communication please refer
to Java programming language tutorial on socket or network programming.
Note 2: methods implemented in lines 54 and 56 are described in chapter 5 of the
current report, called “Application Example”.

4. Port 2002: send control commands to the Gateway
This port provides the functionality for server to send controlling commands for
disconnecting from gateway and to reset the gateway.
byebye
This string is used to close the connection between the gateway and the Server
reset
This string is used to reset or restart the gateway. This functionality is similar to the
hardware reset button on the upper side of the gateway.
This functionality is implemented with the universal for sending out the messages class
Link and its method SendPortMessage, which receives as parameters the port number as integer
number, on which the server socket is to be opened, and the message to be sent as string. The
Link class is shown in figure 16.

Figure 16. Universal send messages class Link

18


Note that this class has a string variable called IP. This variable has the IP-address
variable (figure 16, line 6) of the gateway in order to open the sending socket to this IP and port
number. For port 2002 the method SendPortMessage will look like this:
SendPortMessage (2002,”byebye”) – for disconnection or
SendPortMessage (2002,”reset”) – for the gateway reset/restart

Note: in this class a pure functionality to send the message to the defined port and
defined IP is implemented. No checking is provided for gateway availability or gateway actual
status. In order to provide this class should be combined with other (see port 2003 description
for providing availability of the gateway checking).

5. Port 2003: check the readiness of the Gateway
To ensure that there is no failure in the operation of the gateway, the server should verify
the readiness of the gateway in a cyclic way. The user can define the period of cyclic checks. If
the gateway is ready, the server receives the message “ready” on port 2003. Normally gateway
send “ready” message every 10 seconds. For this a server socket on port 2003 should be
opened, and the incoming should be read out. This is implemented in the class Ready, and its
method CheckReady, shown in the figure 17. CheckReady has a string return type, meaning that
it returns the string message received from the gateway (figure 17, line 17). This class opens a
client socket on server port 2003 (figure 17, line 12). After the server reads out the incoming
stream, and should receive the “ready” message from gateway.

Figure 17. Ready class with CheckReady method

6. Port 2005: send EnOcean telegrams to the Gateway

19


This port provides the functionality to send an EnOcean telegram from the server i.e.
personal computer to the gateway, and gateway according to the telegram should react
accordingly, for example send it further to the EnOcean wireless actuator.

<String>

String is an EnOcean telegram in hexadecimal format (see subchapter 2.2 for details on
EnOcean telegrams). It consists of following parts:
Sync byte 1: a5
Sync byte 2: 5a
Header byte: 0b (for received telegram), 6b (for telegram to be sent)
ORG: 05 (can be different, see EnOcean equipment profiles for details)
Data bytes 3..0: see EnOcean equipment profiles for details
ID bytes 3..0: since server is connected to the gateway, this is the ID of the gateway. It
can be read out while connection establishment on port 2001. Note: gateway is sending its ID
in the decimal format. To get the right ID and fit it into the string telegram it is necessary to
convert decimal format into hexadecimal.
Status field byte: see EnOcean equipment profiles for details
Note: EnOcean telegram has one additional byte, which is the checksum (see subchapter
2.2 of the current report, figures 8 and 9), this is the last byte. If the user wants the gateway to
send the telegram out no checksum byte should be included, since the gateway calculates it and
adds automatically.
The functionality to send messages on the port 2005 is implemented with the universal
class Link and its method SendPortMessage (see figure 15). For example, a telegram
“a55a6b50DB3..0ID3..0Status” is to be sent on port 2005, the Link class method
SendPortMessage will look like this:
SendPortMessage (2005“a55a6b50DB3..0ID3..0Status”) – please pay attention on
appropriate data bytes and ID bytes.

In addition for the ease of Java API use, an extra class called Messages was created,
where a user can define all necessary messages and call them further on in appropriate classes
and methods. This class is shown in figure 18, where the implemented example with telegrams
for switching the light on and off with EnOcean wireless actuator is shown.

20


Figure 18. Message class for gathering all messages in one class

Let’s take a look at the used messages shown in figure 18 and the process for defining
these messages. The actuator in the learning phase saved the information that the rocker FT4F
is acting as a lamp on and lamp off switch. When pressing switch buttons the EnOcean
telegram was received from FT4F. Take into consideration the figures 8 and 9 for the telegram
description. The telegram parts in the Message class are named accordingly (SYNC = sync
bytes, DB = data byte, and so on). The detailed description of telegram structure is provided in
“EnOcean Equipment Profiles (EEP) V2.0” and “TCM 120 Transceiver Module User
Manual V1.53” [6,7], there is a detailed definition provided for each separate field of the
EnOcean telegram (i.e. ORG, Status, Data bytes, ID bytes).

5 Application Example
This chapter shows the basic example of implementing the developed Java API
functionality on the existing practical framework (see chapter 3, subchapter 2.1). A simple
graphical user interface (GUI), shown in figure 19 has been created.

21


Figure 19. Application example GUI

The implemented example uses the threads for making possible parallel running of
multiple processes, for example opening a thread for the CheckReady method running in a
cyclic way, which checks if the gateway is ready each minute.
The implemented example has 4 main buttons showing the functionality of the
implemented API. They are:

- Button “Turn Light On/Turn Light OFF”: this button shows the functionality of the
class Link with SendPortMessage method for port 2005 and defined EnOcean telegrams
for turning the light on and off, defined as string messages in the class Message (see
figure 18, lines 3,4 and 23-29). The process for activating this button is started as a
thread immediately after loading the GUI. It is implemented by combination of classes
SendThread (here the process is started) and the class Link on port 2005 with the
corresponding messages. Note that this process does not make a cyclic check for the

22


gateway readiness. It shows that gateway is always listening on its port 2005 to receive
messages.

- Button “Enable the Switch”. Here the two processes are started, and the functionality
of Ready class on port 2003 is used. By pressing this button following is happening:
 The ReadyThread process is started – it opens server socket on port 2003 and waits
for the message “ready” from the Gateway. It is implemented with combination of
the ReadyThread class with Ready class.
 If the “ready” message comes, showing that gateway is ready, the
SendReceiveThread process is started, which implements a functionality of
SendReceive class on port 2001 and further the transfer port 2100. The readiness
checking process is invoked each minute, and by receiving the “ready” message the
second process is started.
 After transfer port 2100 is opened, it is possible to receive messages from EnOcean
devices, and in the given project the wireless switch FTF4 was used (see subchapter
2.1). Upon pressing the switch button the appropriate telegram is received and the
necessary telegram is sent back on gateway to send it further to the wireless actuator
to activate the lamp. It is implemented by using the class Link with port 2005 and
appropriate string telegram within the SendReceiveThread and SendReceive class.

- Button “Stop”. This is the implementation of the Link class on port 2002 and the
controlling message “byebye” (see chapter 4, port 2002 description). After pressing this
button the connection is temporarily stopped waiting for the next connection, which the
gateway does each 10 seconds.

- Button “Reset”. This is similar to the button “Stop”, but the message sent is “reset”
(see chapter 3 port 2002 description). This button implements the functionality of
making the hardware reset. After pressing this button, after circa 10 seconds the
gateway is restarted. Note: the gateway is not starting immediately; it takes circa 1
minute to restart the gateway.

- Button “Terminate”. This button is closing all existing threads, similar to closing the
GUI window. After this the program should be started again.

Note: the implemented application example is a simple software tool to test the developed
Java classes’ functionality. It has a lot of things to be further developed, for example: the
readiness checking is the essential process that has to be started at the beginning, and
performed in a cyclic way before any other process is started. Also the controlling
commands influence on threads should be taken into account, i.e. when “byebye” message
is sent, all other processes should be interrupted or put in a “sleep” mode waiting for the
next gateway connection.

6 Future Application
Resource Adapter for EnOcean
Today, as the importance of (Next Generation Networks) NGN in telecommunication has
become very significant, this provides an extensive approach of development for exclusive
value added services at the application level. When talking about application level development

23


the significance of a resource adapter can not be denied. The Application Server based on
JSLEE provides an opportunity to develop Resource Adapters (RA) to interact with the
external environment, which makes it interesting at the developer’s point of view. The RA not
only provides an opportunity to extend your services but also makes it possible to combine
other technologies with the JSLEE based Application Server.
The resource adapter for EnOcean can provide us the opportunity to extend the support for
EnOcean devices to the JSLEE( JAIN Service Logic Execution Environment), which one of the
known telecommunication developing environment.
This Stack will be used to develop the resource adapter for the JSLEE Architecture:
SYNC_BYTE
SYNC_BYTE
LENGTH
ORG
DATA_BYTE3
DATA_BYTE2
DATA_BYTE1
DATA_BYTE0
ID_BYTE3
ID_BYTE2
ID_BYTE1
ID_BYTE0
STATUS
CHECKSUM

Figure 20. The Telegram Stack

Proposal for developing an EnOcean Resource Adapter:
From the knowledge that has been acquired after implementing the JAVA API for EnOcean,
it becomes understandable, how the roadmap can be for developing the EnOcean resource
adapter.
In the EnOcean framework the most important concept is the telegram stack. So, the basic
idea for developing the EnOcean RA will be to develop the telegram stack within the resource
adapter.
The structure of the Resource Adapter:
A JSLEE Resource Adapter (RA) consists mainly of two things:
 Resource Adaptor Type
 Resource Adaptor
The RA Type specifies the Events emitted by this class of RAs, the shareable state
information between application logic Service Building Blocks (SBBs) and Resource Adapter

24


(RA), the Activity Context, and the interface utilized by JSLEE application logic SBBs to
access RA functions. Usually, RA Types are defined by an industry with same interests. [8]
The RA implements exactly one RA Type at a time. Java Native Interface (JNI)
technology is used to integrate non Java stacks. Usually, RAs are stateful and model an internal
state machine of the protocol activities, for implementing the EnOcean RA, the activities will
be according to the behaviour of the telegram stack. [8]
The RA decides on incoming signals to alter the internal state and to notify the JSLEE. To
allow Sbbs to access the state of a RA, Activities and Activity Contexts (AC) are introduced.
An Activity, for example, represents one phone call or a game session. Incoming signals are
mapped to one session-unique AC (the interface to the Activity) via the Activity Handle. The
AC is accessible both from the RA and the SBBs. [8]
The required telegram stack can be integrated with the functionalities of a JSLEE resource
adapter and then required SBB(Service Building Blocks) can be developed with respect to the
resource adapter. After this development, both the SBB and the resource adapter can be
deployed to implement value added services. [8]
Further extension of the development can be done by using the following resource adapters:
1) EnOcean Resource Adapter
2) SIP Resource Adapter.
In figure 21, a general view of the JSLEE architecture is provided with the resource
adapter. By using both these resource adapter, it can be possible to develop value added
services which will be supported by the JSLEE architecture.

Management Framework Components

JMX Trace SBB
Lifecycle
AGENT Alarm
SBB
Timer
Events
SLEE and
Management Profile Access
SBB
Interface
Event Router Registration
Deployment Format
Calling Semantics

Resource Adapter

SIP RA EnOcean RA Any other RA

Figure 21. JSLEE Architecture

25


JMX: Java Management Extension
SBB: Service Building Block
RA: Resource Adapter
Some examples for Value Added Services, with respect to EnOcean Resource Adapter
and SIP Resource Adapter can be as follows:
1. Developing a Service, where a SIP based end user can control the EnOcean devices, like
the wireless actuator.
2. Developing a Service, where a SIP based end user can monitor the energy consumption
of the electrical devices, by using the wireless energy meter.

7 Conclusion
The framework that we have used to develop and implement our scenario is on a small
scale. However, many scenarios can be implemented on a much larger scale with the same
basic knowledge and information from this project report.
The conclusion, after completing this project report is that, implementing more and more
energy harvesting devices and developing ways to control these devices can not only make our
life much more convenient but, most importantly it can make an impact to the energy
consumption which is one of the challenges that the world is facing.
One scenario for Building /Home Automation is discussed below.
Building/Home Automation
Figure 22, shows an example of a home or building automation environment. EnOcean
devices provide us the opportunity to implement many types of home automation or building
automation environments. Some types of application are mentioned in this part of the report.

Figure 22.Home automation Environment

26


The Energy Harvesting Wireless Standard for Building Automation, the sequences of
numbers mentioned below are associated to the device numbers mentioned in figure 22.
1) Energy harvesting wireless switches: Control lighting and shading.
2) Energy harvesting wireless outdoor light sensors: automatically match lighting to daylight.
3) Energy harvesting wireless occupancy sensor: Adjusts temperature and turns off lights
when a room is not in use.
4) Energy harvesting wireless room temperature sensor: For minimal energy consumption and
maximum comfort.
5) Energy harvesting wireless climatic sensors: Humidity and CO2 - monitor indoor air
quality.
6) Energy harvesting wireless position sensors: Window handle and window contact – cut out
heating.
7) Energy harvesting wireless position sensors: Air-conditioning when windows are open.
8) Central control: On a touch panel or PC/notebook.
9) Remote monitoring and control by a mobile phone or on the Internet.

8 References
[1] BSC-BAP-TX Wireless Access point: BSC-BAP Datasheet, issue date 21.08.07, available
at http://www.enoceanalliance.org/uploads/tx_f03enocean/bsc_Produktdatenblatt-BAP.pdf
[2]Wireless Actuator (FSR61NP): The Eltako Wireless System, 2011, available at
http://www.eltako.com/fileadmin/downloads/en/_catalogue/wireless_system_high_res.pdf
[3]Wireless single-phase energy Meter (FWZ12-16A): The Eltako Wireless System, 2011,
available at
[4] Wireless switch/ Push-button (FT4F): The Eltako Wireless System, 2011, available at
[5] Motion/Brightness sensor (FBH55): The Eltako Wireless System, 2011, available at
[6]EnOcean Equipment Profiles (EEP) V2.0, July 2009, available at
http://www.enoceanalliance.org/fileadmin/redaktion/enocean_alliance/pdf/EnOcean_Equipmen
t_Profiles_2.0.pdf
[7] TCM 120 Transceiver Module User Manual V1.53, August 2008, available at
http://www.enocean.com/en/enocean_modules/TCM_120_User_Manual_V1.53_02.pdf
[8] Implementing a JSLEE Resource Adaptor, A quick-starter’s guide, available at
http://www.maretzke.de/pub/howtos/mobicents_ra/HowTo_Mobicents_RA_MiMa_v1.1_2005
1007.pdf

27

En Ocean Java Api Istochnikov Chand 1

More Related Content

What's hot

Similar to En Ocean Java Api Istochnikov Chand 1

More from Piyush Chand

En Ocean Java Api Istochnikov Chand 1