Prev		Next

139 Device Service Specification for EnOcean™ Technology

Version 1.0

139.1 Introduction

EnOcean is a standard wireless communication protocol designed for low-cost and low-power devices by EnOcean Alliance.

EnOcean is widely supported by various types of devices such as smart meters, lights and many kinds of sensors in the residential area. OSGi applications need to communicate with those EnOcean devices. This specification defines how OSGi bundles can be developed to discover and control EnOcean devices on the one hand, and act as EnOcean devices and interoperate with EnOcean clients on the other hand. In particular, a Java mapping is provided for the standard representation of EnOcean devices called EnOcean Equipment Profile (EEPs). See [2] EnOcean Equipment Profiles v2.6.2.

The specification also describes the external API of an EnOcean Base Driver according to Device Access specification.

139.2 Essentials

Scope - This specification is limited to general device discovery and control aspects of the standard EnOcean specifications. Aspects concerning the representation of specific or proprietary EnOcean profiles is not addressed.
Transparency - EnOcean devices discovered on the network and devices locally implemented on the platform are represented in the OSGi service registry with the same API.
Lightweight implementation option - The full description of EnOcean device services on the OSGi platform is optional. Some base driver implementations may implement all the classes including EnOcean device description classes while Implementations targeting constrained devices are able to implement only the part that is necessary for EnOcean device discovery and control.
Network Selection - It must be possible to restrict the use of the EnOcean protocols to a selection of the connected devices.
Event handling - Bundles are able to listen to EnOcean events.
Discover and control EnOcean devices as OSGi services - Available learned (via an EnOcean teach-in procedure) EnOcean external endpoints are dynamically reified as OSGi services on the service registry upon discovery.
OSGi services as exported EnOcean devices - OSGi services implementing the API defined here and explicitly set to be exported should be made available to networks with EnOcean-enabled endpoints in a transparent way.

139.3 Entities

EnOcean Base Driver - The bundle that implements the bridge between OSGi and EnOcean networks, see Figure 139.1 on page . It is responsible for accessing the various EnOcean gateway chips on the execution machine, and ensures the reception and translation of EnOcean messages into proper objects. It is also used to send messages on the EnOcean network, using whatever chip it deems most appropriate.
EnOcean Host - The EnOceanHost object is a link between the software and the EnOcean network. It represents the chip configuration (gateway capabilities) described in [5] EnOcean System Specification - Security of EnOcean Radio Networks v1.9. It is registered as an OSGi service.
EnOcean Device - An EnOcean device. This entity is represented by a EnOceanDevice interface and registered as a service within the framework. It carries the unique chip ID of the device, and may represent either an imported or exported device, which may be a pure transmitter or a transceiver.
EnOcean Message - Every EnOcean reporting equipment is supposed to follow a “profile”, which is essentially the way the emitted data is encoded. In order to reflect this standard as it is defined in [2] EnOcean Equipment Profiles v2.6.2, manufacturers are able to register the description of “Messages”, the essence of a profile, along with their associated payload (as Channels). See “EnOcean Channels” below for more information.
EnOcean Channel - EnOcean channels are available as an array inside EnOceanMessage objects. They are a useful way to define any kind of payload that would be put inside of an EnOcean Message.

EnOcean Messages and their associated Channels can be described with EnOceanMessageDescription and EnOceanChannelDescription interfaces. Description providers aggregate these descriptions in sets that they register with EnOceanMessageDescriptionSet and EnOceanChannelDescriptionSet interfaces within the framework.
EnOcean RPC - An interface that enables the invocation of vendor-specific Remote Procedure Calls and Remote Management Commands. These are particular types of Messages and are not linked to any EnOcean Profile, so that their descriptions are defined and registered in another way. The RPCs are documented via the EnOceanRPCDescription objects gathered into registered EnOceanRPCDescriptionSet services.
EnOcean Handler - Enables clients to asynchronously get answers to their RPCs.
EnOcean Client - An application that is intended to control EnOcean device services.
EnOcean Exception - Delivers errors during EnOceanMessage serialization/deserialization or during execution outside transmission.

Figure 139.1 EnOcean Service Specification class diagram.

139.4 Operation Summary

To make an EnOcean device service available to EnOcean clients on the OSGi platform, it must be registered under the EnOceanDevice interface within the OSGi framework.

The EnOcean Base Driver is responsible for mapping external devices into EnOceanDevice objects, through the use of an EnOcean gateway. See [1] Pervasive Service Composition in the Home Network. The latter is represented on OSGi framework as an object implementing EnOceanHost interface. EnOcean “teach-in” messages will trigger this behavior, this is called a device import situation, see Figure 139.2 on page .

Figure 139.2 EnOcean device import.

Client bundles may also expose framework-internal (local) EnOceanDevice instances, registered within the framework, see Figure 139.3 on page . The Base Driver then should emulate those objects as EnOcean devices on the EnOcean network. This is a device export situation, made possible by the use of the 127 virtual base IDs available on an EnOcean gateway. For more information about this process, see Export Situation.

Figure 139.3 EnOcean device export.

EnOcean clients send RPCs (Remote Procedure Calls) to EnOcean devices and receives RPC responses and messages from them. Messages coming from EnOcean devices are accessible through Event Admin.

RPCs and messages content are specified by EnOcean Alliance or vendor-specific descriptions. Those descriptions may be provided on the OSGi platform by any bundle through the registration of EnOceanRPCDescriptionSet, EnOceanMessageDescriptionSet and EnOceanChannelDescriptionSet services. Every service is a set of description that enables applications to retrieve information about supported RPCs, messages or channels that compose messages.

Figure 139.4 Using a set of message descriptions.

139.5 EnOcean Base Driver

Most of the functionality described in the operation summary is implemented in an EnOcean base driver. This bundle implements the EnOcean protocol and handles the interaction with bundles that use the EnOcean devices. An EnOcean base driver is able to discover EnOcean devices on the network and map each discovered device into an OSGi registered EnOceanDevice service. It is also the receptor, through EventAdmin service and OSGi service registry, of all the events related to local devices and clients. It enables bidirectional communication for RPC and Channel updates.

Several base drivers may be deployed on a residential OSGi device, one for every supported network technology. An OSGi device abstraction layer may then be implemented as a layer of refinement drivers above a layer of base drivers. The refinement driver is responsible for adapting technology-specific device services registered by the base driver into device services of another model, see AbstractDevice interface in Figure 139.5 on page . In the case of a generic device abstraction layer, the model is agnostic to technologies.

The EnOcean Alliance defines their own abstract model with EnOcean Equipment Profiles and refinement drivers may provide the implementation of all EEPs with EnOcean specific Java interfaces. The AbstractDevice interface of Figure 139.5 on page is then replaced by an EEP specific Java interface in that case. The need and the choice of the abstraction depends on the targeted application domain.

Figure 139.5 EnOcean Base Driver and a refinement driver representing devices in an abstract model.

139.6 EnOcean Host

The EnOcean host represents an EnOcean gateway chip. Any EnOcean device service implementation should rely on at least one Gateway Chip in order to send and receive messages on the external EnOcean network. This interface enables standard control over an EnOcean compatible chip. Every EnOceanHost object should at least be identified by its unique chip ID.

The EnOceanHost interface enables OSGi applications to:

Get or set gateway metadata (version, name, etc);
Reset the gateway chip device;
Retrieve a chip ID (derived from EnOcean's BASE_ID) for the given Service PID of a device.

139.7 EnOcean Device

139.7.1 Generics

A physical EnOcean device is reified as an EnOceanDevice object within the framework.

An EnOcean device holds most of the natural properties for an EnOcean object: its unique ID, the profile, a friendly name, its security information, and its available RPCs – along with the associated getters (and setters when applicable). All those properties MUST be persistent across restart so that teach-in procedures are made only once.

It also holds methods that reflect the natural actions a user application may physically trigger on such a device: send a message to the device, send a teach-in message to the device, or switch the device to learning mode.

Every EnOcean Device keeps a service PID property that is assigned either by the base driver or by any service-exporting bundle. The property value format is free and the value must be unique on the framework.

The properties on which EnOceanDevice services can be filtered on are: the device's service PID and chip ID, and its profile identifiers (RORG / FUNC / TYPE integers).

The EnOceanDevice also keeps security features as defined in the EnOcean Security Draft, [5] EnOcean System Specification - Security of EnOcean Radio Networks v1.9, which allow for a security level format (integer mask), an encryption key and/or a rolling authentication code.

The EnOceanDevice service MUST also be registered with the DEVICE_CATEGORY service property, see Device Service Registration, that describes a array of categories to which the device belongs. One value MUST be EnOcean which is specified in DEVICE_CATEGORY.

Values for the additional service properties, DEVICE_DESCRIPTION, DEVICE_SERIAL as defined in Device Service Registration, are not specified here as no description nor application-level serial number are provided in the EnOcean standard protocol.

139.7.2 Import Situation

In import situations, the device's chip ID is uniquely set by the Base Driver, according to the one present in the teach-in message that originated the Device's creation. The service PID, see [7] Persistent Identifier (PID), should also be generated and deterministically derived from the chip ID to allow reconstruction of a device without a new teach-in process after a framework restart.

139.7.3 Export Situation

In export situations:

The registering Client bundle sets the service PID of the EnOceanDevice object by itself, in a unique manner, and registers that object.
The chip ID (this device's EnOcean source ID when it issues messages) will be allocated by the Base Driver. The latter keeps a dictionary of the currently allocated chip IDs. The Client bundle must also set an ENOCEAN_EXPORT property in the registered device's Property Map.

The standard way to programmatically retrieve an exported chip ID from a given service PID is by using EnOceanHost's dedicated interface for this use.

The Base Driver MUST ensure the persistence of the CHIP_ID:SERVICE_PID mapping.

As an application developer, please refer to the documentation of your Base Driver to know its policies concerning exported chip ID updating, deletion and exhaustion.

139.7.4 Interface

The EnOceanDevice interface enables client bundles to:

Get or set the security features of the device in a protected way;
Retrieve the currently paired devices in the case of a receiver, as a collection of device IDs;
Get the ID-based list of currently available RPCs for the device, as a Map of {manufacturerID:[functionId1, functionId2,...]};
Invoke RPCs onto the device, through the invoke(EnOceanRPC,EnOceanHandler) call.

139.8 EnOcean Messages

EnOcean Messages are at the core of the EnOcean application layer as a whole and the EnOcean Equipment Profile specification, [2] EnOcean Equipment Profiles v2.6.2, in particular. Every exchange of information within EnOcean networks is done with a dedicated message. The EnOceanMessage interface provides a set of getters. The latter enables OSGi applications to get the information contained in the payload of an EnOcean message and defined as data and optional data of the EnOcean Serial Protocol Type 1 (RADIO) message (see Table 2 in Section "1.6.1 Packet description" of [4] EnOcean System Specification - EnOcean Serial Protocol v1.17).

This model enables reading both the EnOcean radio telegram data and the associated metadata that may be attached to it in a single object, EnOceanMessage.

In case the 'Optional Data' section gets missing at the lowest level (the radio access layer not following ESP protocol for instance) it is the responsibility of the Base Driver to mock the missing field's (dBm, destinationID, …) values.

139.8.1 Mode of operation

Any EnOceanMessage object creation will be mirrored to Event Admin.

Details about the available topics, filters and properties can be found in Event API.

EnOceanMessage objects will be created only if the originating device has already been registered in the OSGi Service Registry, along with profile information.

139.8.2 Identification

The RORG of a message defines its shape and generic type; all the RORGs are defined in the EnOcean Radio Specification.

An addressed message will be encapsulated into an Addressed Telegram (ADT) by the base driver transparently; this means that from the application level, it will be represented under its original RORG, but with a valid destinationID.

A particular EnOcean Equipment Profile message is identified by three numbers: its RORG, and its FUNC, TYPE and EXTRA subtypes. In EnOcean, a (RORG, FUNC, TYPE) triplet is enough to identify a profile; though an EXTRA identifier is sometimes needed to identify a particular message layout for that profile.

Those identifiers allow for retrieving EnOceanMessageDescription objects within a registered EnOceanMessageDescriptionSet, which give the application more information to parse the message.

139.8.3 Interface

The methods available in the EnOceanMessage interface are:

Identification methods, retrieving the message's profile, sender ID, optional destination ID, status;
A method to get the raw bytes of payload data in the message. This data can then be passed to the deserializer of the EnOceanMessageDescription object to be converted to EnOceanChannel, which may -again- be documented (through EnOceanChannelDescription objects) or not.
Link quality information read-only methods that mirror some of the 'Optional Data' header information.

139.9 EnOcean Message Description

EnOceanMessageDescription objects exposes only two methods:

deserialize(byte[]): makes the user able to deserialize the payload bytes of a raw EnOceanMessage object, into a collection of EnOceanChannel objects.
serialize(EnOceanChannel[]): serializes the input EnOceanChannel objects into a collection of bytes.

139.10 EnOcean Channel

The EnOceanChannel interface is the first step of an abstraction to generate or interpret EnOceanMessage channels with plain Java types.

The simple EnOceanChannel interface provides a way to separate the different fields in a message payload, knowing their offset and size in the byte array that constitutes the full message's payload.

At the EnOceanChannel level, the only way to get/set the information contained in the channel is through a pair of getRawValue() and setRawValue(byte[]) methods, which act on plain bytes.

Those bytes are meant right-aligned, and the number of those bytes is the size of the data field, floored up to the next multiple of 8. For instance, a 3-bit long channel would be encoded on one byte, all the necessary information starting from bit 0.

Every EnOceanMessage as described in the EEP Specification contains a various amount of channels, each of them being identified by their unique ID.

This ID, or channelID, is constituted of the “Shortcut” field of this channel from the EEP 2.5 Specification, [2] EnOcean Equipment Profiles v2.6.2, and a number fixed by the order of appearance of such a “Shortcut” in the specification.

This unique identifier links a Channel to an EnOceanChannelDescription object that provides more information to encode and decode that channel's information; see below for more details. This enables for loose coupling of the raw Channel itself and a richer, 3rd-party provided, information.

As an example, if the platform being developed is an electronic display that waits for Messages from a well-known temperature sensor, the Client bundle on the platform may interpret the Temperature Channels in every Temperature Message without needing an appropriate TemperatureChannelDescription object; it may directly cast and convert the Byte[] array of every received message to a properly valued Double and display that.

Otherwise, it could as well use the channelID to get a TemperatureChannelDescription object that would properly handle the deserialization process from the raw bytes to a proper, physical unit-augmented, result.

Figure 139.6 EnOcean channel and EnOcean channel descriptions.

139.11 EnOcean Channel Description

The EnOceanChannelDescription interface enables the description of all the various channels as specified in the EnOcean specification, as well as the description of channels issued by 3rd party actors.

Those description objects are retrieved from the registered EnOceanChannelDescriptionSet interface using an unique ID known as the channelID.

Here are the Channel types defined in this specification:

TYPE_RAW: A collection of bytes. This type is used when the description is not provided, and is thus the default. For this type, the deserialize(byte[]) call actually returns a byte[] collection. The encryption key or a device ID on 4 bytes are examples of such raw types.
TYPE_DATA: A scaled physical value. Used when the data can be mapped to a physical value; for instance, the 'WND – Wind Speed' channel is a raw binary value, in a range from 0 to 255, that will be mapped as a wind speed between 0 and 70 m/s. For this type, the deserialize(byte[]) call actually returns a Double value.
TYPE_FLAG: A boolean value. Used when the Channel value can be either 1 or 0. The “Teach-In” Channel is a well-known example; this 1-bit field may either be 0 or 1, depending whether the Message is a teach-in one or not. For this type, the deserialize(byte[]) call actually returns a Boolean value.
TYPE_ENUM: An enumeration of possible values. Used when the Channel can only take a discrete number of values. More complicated than TYPE_FLAG, enumerated types may have thresholds: for instance, the A5-30 “Digital Input- Input State (IPS)” channel is a 8-bit value which means “Contact closed” between 0 and 195, and “Contact open” from 196 to 255. For this type, the deserialize(byte[]) call actually returns an EnOceanChannelEnumValue object.

According to the channel type, the actual description object should implement one of the following specialized interfaces. This will ease the use of casting to the specialized interfaces on documented channels.

139.11.1 EnOcean Data Channel Description

The EnOceanDataChannelDescription interface inherits from EnOceanChannelDescription interface.

Two more methods give access to the integer input domain of the data channel (such as 0-255) and to the floating-point output range of it (such as -30.0°C – 24.5°C). A method is also present to retrieve the physical unit of the channel. The serialize(Object) and deserialize(byte[]) methods are implemented to easily convert from the raw byte[] collection to a Double, and vice versa.

Here are a few samples of such Channels:

Table 139.1 EnOcean Data Channel Description example

Short	Description	Possible implemented name	Domain	Range	Unit
TMP	Temperature	TemperatureScaledChannel_X	0..255	-10°..+30°	°C
HUM	Humidity	HumidityScaledChannel_X	0..250	0..100	%

139.11.2 EnOcean Flag Channel Description

The EnOceanFlagChannelDescription interface inherits from the EnOceanChannelDescription interface.

Those channels, are typically used for On/Off reporting values (like a switch); they have no additional methods, though the deserialize(byte[]) method converts the input bit into a proper Boolean object.

139.11.3 EnOcean Enumerated Channel Description

The EnOceanEnumChannelDescription interface inherits from the EnOceanChannelDescription interface.

The additional method provided to this interface is getPossibleValues(), which returns an array of the available EnOceanChannelEnumValue objects accessible to this channel. Every EnOceanChannelEnumValue object contains its integer input range and a String identifier that defines its meaning.

The serialize(Object) and deserialize(byte[]) methods of an EnOceanEnumChannelDescription object thus convert an integer input value (say, 156) to an EnOceanChannelEnumValue, and vice versa.

Here is an example that shows the input range and the associated EnOceanChannelEnumValue:

Table 139.2 EnOcean Enumerated Channel Description example

Device profile	EnOceanChannelEnumValue	Start	Stop	Meaning
Fan speed stage switch	FanStageSwitch_Stage3	0	144	Fan speed: Stage 3
	FanStageSwitch_Stage2	145	164	Fan speed: Stage 2
	FanStageSwitch_Stage1	165	189	Fan speed: Stage 1
	FanStageSwitch_Stage0	190	209	Fan speed: Stage 0

139.12 EnOcean Remote Management

Remote Management is a feature which allows EnOcean devices to be configured and maintained over the air using radio messages.

The Remote Procedure Calls, or RPCs - as defined by the EnOcean Remote Management specification, [3] EnOcean System Specification - Remote Management v2.0 - are not related to any EnOcean Equipment Profile.

Note that EnOcean Remote Commissioning is detailed in an additional EnOcean document, [6] EnOcean Remote Commissioning Summary v1.0.

139.12.1 EnOcean RPC

An EnOceanRPC object enables client bundles to remotely manage EnOcean devices using already defined behavior.

RPCs are defined by a MANUFACTURER_ID (11 bits, 0x7FF for the EnOcean alliance) and a unique FUNCTION_ID code on 12 bits.

RPCs are called directly onto an EnOceanDevice object via the invoke(EnOceanRPC,EnOceanHandler) method, which accepts also a non-mandatory EnOceanHandler object as a parameter to retrieve the asynchronous answer.

Broadcasted RPCs can be addressed directly to the Base Driver using the relevant Event Admin topic; see Event API.

139.12.2 EnOcean Handler

Responses to RPCs are processed by the driver and sent back to a handler using notifyResponse(EnOceanRPC,byte[]) method when an EnOceanHandler is passed to the base driver.

139.13 Working With an EnOcean Device

139.13.1 Service Tracking

All discovered EnOcean devices in the local networks are registered under EnOceanDevice interface within the OSGi framework. Every time an EnOcean device appears or quits the network, the associated OSGi service is registered or unregistered in the OSGi service registry. Thanks to the EnOcean Base Driver, the OSGi service availability in the registry mirrors EnOcean device availability on EnOcean network, [1] Pervasive Service Composition in the Home Network.

Thanks to service events, a bundle is able to track the addition, modification and removal of an EnOceanDevice service.

The following example shows using a ServiceTracker to track EnOceanDevice services.

ServiceTracker<EnOceanDevice, EnOceanDevice> enOceanTracker = 
    new ServiceTracker<>(bundleContext, EnOceanDevice.class, null);
enOceanTracker.open(); // open the tracker

...

// get a snaphot of the current EnOceanDevice services
EnOceanDevice[] enOceanDeviceSnapshot = 
    enOceanTracker.getServices(new EnOceanDevice[0]);

...

enOceanTracker.close(); // close the tracker

139.14 Event API

EnOcean events must be delivered to the EventAdmin service by the EnOcean implementation, if present. EnOcean event topic follow the following form: org/osgi/service/enocean/EnOceanEvent/SUBTOPIC.

MESSAGE_RECEIVED and RPC_BROADCAST are the two available subtopics.

139.14.1 MESSAGE_RECEIVED

Properties (every event may dispatch some or all of the following properties):

CHIP_ID – . The chip ID of the sending device.
service.pid – The service PID of the exported device.
RORG – The RORG (Radio Telegram Type) of the sending device.
FUNC – The FUNC profile identifier of the sending device.
TYPE – The TYPE profile identifier of the sending device.
PROPERTY_MESSAGE – The EnOceanMessage object associated with this event.
PROPERTY_EXPORTED – The presence of this property means that this message has actually been exported from a locally implemented EnOcean Device.

139.14.2 RPC_BROADCAST

This event is used whenever an RPC is broadcasted on EnOcean networks, in IMPORT or EXPORT situations.

Properties (every event may dispatch some or all of the following properties):

MANUFACTURER_ID – The RPC's manufacturer ID.
FUNCTION_ID – The RPC's function ID .
PROPERTY_EXPORTED – The presence of this property means that this RPC has actually been exported from a locally implemented EnOcean Device.
PROPERTY_RPC – The EnOceanRPC object associated with this event.

139.15 EnOcean Exceptions

The EnOceanException can be thrown and holds information about the different EnOcean layers. Here below, ESP stands for EnOcean Serial Protocol. The following errors are defined:

ESP_UNEXPECTED_FAILURE – Operation was not successful.
ESP_RET_NOT_SUPPORTED – The ESP command was not supported by the driver.
ESP_RET_WRONG_PARAM – The ESP command was supplied wrong parameters.
ESP_RET_OPERATION_DENIED – The ESP command was denied authorization.
INVALID_TELEGRAM – The message was invalid.

139.16 Security

It is recommended that ServicePermission[EnOceanDevice|EnOceanHost, REGISTER|GET] be used sparingly and only for bundles that are trusted.

139.17 org.osgi.service.enocean

Version 1.0

EnOcean Package Version 1.0.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.

Example import for consumers using the API in this package:

Import-Package: org.osgi.service.enocean; version="[1.0,2.0)"

Example import for providers implementing the API in this package:

Import-Package: org.osgi.service.enocean; version="[1.0,1.1)"

139.17.1 Summary

EnOceanChannel - Holds the raw value and channel identification info of an EnOceanChannel.
EnOceanDevice - This interface represents a physical device that communicates over the EnOcean protocol.
EnOceanEvent - Constants for use in EnOcean events.
EnOceanException - This class contains code and definitions necessary to support common EnOcean exceptions.
EnOceanHandler - The interface used to get callback answers from a RPC or a Message.
EnOceanHost - This interface represents an EnOcean Host, a device that offers EnOcean networking features.
EnOceanMessage - Holds the necessary methods to interact with an EnOcean message.
EnOceanRPC - A very basic interface for RPCs.

139.17.2 public interface EnOceanChannel

Holds the raw value and channel identification info of an EnOceanChannel.

139.17.2.1 public String getChannelId()

ReturnsThe unique ID of this channel.

139.17.2.2 public int getOffset()

ReturnsThe offset, in bits, where this channel is found in the telegram.

139.17.2.3 public byte[] getRawValue()

□ Gets the raw value of this channel.

Returnscorresponding value.

139.17.2.4 public int getSize()

ReturnsThe size, in bits, of this channel.

139.17.2.5 public void setRawValue(byte[] rawValue)

rawValue

□ Sets the raw value of a channel.

139.17.3 public interface EnOceanDevice

This interface represents a physical device that communicates over the EnOcean protocol.

139.17.3.1 public static final String CHIP_ID = "enocean.device.chip_id"

Property name for the mandatory CHIP_ID of the device

139.17.3.2 public static final String DEVICE_CATEGORY = "EnOcean"

Property name for the mandatory DEVICE_CATEGORY of the device

139.17.3.3 public static final String ENOCEAN_EXPORT = "enocean.device.export"

Property name that defines if the device is exported or not. If present, the device is exported.

139.17.3.4 public static final String FUNC = "enocean.device.profile.func"

Property name for the radiotelegram functional type of the profile associated with this device.

139.17.3.5 public static final String MANUFACTURER = "enocean.device.manufacturer"

Property name for the manufacturer ID that may be specified by some teach-in messages.

139.17.3.6 public static final String RORG = "enocean.device.profile.rorg"

Property name for the radiotelegram main type of the profile associated with this device.

139.17.3.7 public static final String SECURITY_LEVEL_FORMAT = "enocean.device.security_level_format"

Property name for the security level mask for this device. The format of that mask is specified in EnOcean Security Draft.

139.17.3.8 public static final String TYPE = "enocean.device.profile.type"

Property name for the radiotelegram subtype of the profile associated with this device.

139.17.3.9 public int getChipId()

ReturnsThe EnOcean device chip ID.

139.17.3.10 public byte[] getEncryptionKey()

□ Returns the current encryption key used by this device.

ReturnsThe current encryption key, or null.

139.17.3.11 public int getFunc()

ReturnsThe EnOcean profile FUNC, or -1 if unknown.

139.17.3.12 public int[] getLearnedDevices()

□ Gets the list of devices the device already has learned.

ReturnsThe list of currently learned device's CHIP_IDs.

139.17.3.13 public int getManufacturer()

ReturnsThe EnOcean manufacturer code, -1 if unknown.

139.17.3.14 public int getRollingCode()

□ Get the current rolling code of the device.

ReturnsThe current rolling code in use with this device's communications.

139.17.3.15 public int getRorg()

ReturnsThe EnOcean profile RORG.

139.17.3.16 public Map<Integer, Integer> getRPCs()

□ Retrieves the currently available RPCs to this device; those are stored using their manfufacturerId:commandId identifiers.

ReturnsA list of the available RPCs, in a Map<Integer, Integer[]> form.

139.17.3.17 public int getSecurityLevelFormat()

ReturnsThe EnOcean security level format, or 0 as default (no security)

139.17.3.18 public int getType()

ReturnsThe EnOcean profile TYPE, or -1 if unknown.

139.17.3.19 public void invoke(EnOceanRPC rpc, EnOceanHandler handler)

rpc

handler

□ Sends an RPC to the remote device.

Throws IllegalArgumentException–

139.17.3.20 public void remove()

□ Removes the device's OSGi service from OSGi service platform.

139.17.3.21 public void setEncryptionKey(byte[] key)

keythe encryption key to be set.

□ Sets the encryption key of the device.

139.17.3.22 public void setFunc(int func)

functhe EEP func of the device;

□ Manually sets the EEP FUNC of the device.

139.17.3.23 public void setLearningMode(boolean learnMode)

learnModethe desired state: true for learning mode, false to disable it.

□ Switches the device into learning mode.

139.17.3.24 public void setRollingCode(int rollingCode)

rollingCodethe rolling code to be set or initiated.

□ Sets the rolling code of this device.

139.17.3.25 public void setType(int type)

typethe EEP type of the device;

□ Manually sets the EEP TYPE of the device.

139.17.4 public final class EnOceanEvent

Constants for use in EnOcean events.

139.17.4.1 public static final String PROPERTY_EXPORTED = "enocean.message.is_exported"

Property key used to tell apart messages that are exported or imported.

139.17.4.2 public static final String PROPERTY_MESSAGE = "enocean.message"

Property key for the EnOceanMessage object embedded in an event.

139.17.4.3 public static final String PROPERTY_RPC = "enocean.rpc"

Property key for the EnOceanRPC object embedded in an event.

139.17.4.4 public static final String TOPIC_MSG_RECEIVED = "org/osgi/service/enocean/EnOceanEvent/MESSAGE_RECEIVED"

Main topic for all OSGi dispatched EnOcean messages, imported or exported.

139.17.4.5 public static final String TOPIC_RPC_BROADCAST = "org/osgi/service/enocean/EnOceanEvent/RPC_BROADCAST"

Main topic for all OSGi broadcast EnOcean RPCs, imported or exported.

139.17.5 public class EnOceanException
extends Exception

This class contains code and definitions necessary to support common EnOcean exceptions. This class is mostly used with low-level, gateway-interacting code : EnOceanHost.

139.17.5.1 public static final short ESP_RET_NOT_SUPPORTED = 2

Operation is not supported by the target device.

139.17.5.2 public static final short ESP_RET_OPERATION_DENIED = 4

The operation was denied.

139.17.5.3 public static final short ESP_RET_WRONG_PARAM = 3

One of the parameters was badly specified or missing.

139.17.5.4 public static final short ESP_UNEXPECTED_FAILURE = 1

Unexpected failure.

139.17.5.5 public static final short INVALID_TELEGRAM = 240

The message was invalid.

139.17.5.6 public static final short SUCCESS = 0

SUCCESS status code.

139.17.5.7 public EnOceanException(String errordesc)

errordescexception error description

□ Constructor for EnOceanException

139.17.5.8 public EnOceanException(int errorCode, String errorDesc)

errorCodethe error code.

errorDescthe description.

□ Constructor for EnOceanException

139.17.5.9 public EnOceanException(int errorCode)

errorCodeAn error code.

□ Constructor for EnOceanException

139.17.5.10 public int errorCode()

□ Constructor for EnOceanException

ReturnsAn EnOcean error code, defined by the EnOcean Forum working committee or an EnOcean vendor.

139.17.6 public interface EnOceanHandler

The interface used to get callback answers from a RPC or a Message.

139.17.6.1 public void notifyResponse(EnOceanRPC original, byte[] payload)

originalthe original EnOceanRPC that originated this answer.

payloadthe payload of the response; may be deserialized to an EnOceanRPC object.

□ Notifies of the answer to a RPC.

139.17.7 public interface EnOceanHost

This interface represents an EnOcean Host, a device that offers EnOcean networking features.

139.17.7.1 public static final Object HOST_ID

The unique ID for this Host: this matches the CHIP_ID of the EnOcean Gateway Chip it embodies.

139.17.7.2 public static final int REPEATER_LEVEL_OFF = 0

repeater level to disable repeating; this is the default.

139.17.7.3 public static final int REPEATER_LEVEL_ONE = 1

repeater level to repeat every telegram at most once.

139.17.7.4 public static final int REPEATER_LEVEL_TWO = 2

repeater level to repeat every telegram at most twice.