Skip to content

Changes

Page history
EN-481 rename Wiki authored by Lukas Altenhuber's avatar Lukas Altenhuber
Show whitespace changes
Inline Side-by-side
tutorial-service-enocean.md
View page @ 3142e656
# EnOcean IO Service
The EnOcean implementation in ENOSAR is a service to handle incoming and outgoing messages from/to EnOcean Devices.
The EnOcean implementation in FREDOSAR is a service to handle incoming and outgoing messages from/to EnOcean Devices.
To do this a [EnOcean Pi](http://at.farnell.com/enocean/enocean-pi-868/mod-soc-gateway-trx-8051-mcu-868/dp/2322460?CMP=KNC-GAT-GEN-KWL-ENOCEAN&mckv=2734Iz1a_dc|pcrid|199139075407|&gclid=EAIaIQobChMIz7Kq_uOz1QIVogvTCh0o-wJmEAAYASAAEgLj1PD_BwE) is required for the Raspberry Pi.
So this Service is fowarding incoming EnOcean messages to the MessagingService in ENOSAR and can receive commands via the CommunicationService and sends them to the EnOcean device. This Service does not save the actual state of devices.
So this Service is fowarding incoming EnOcean messages to the MessagingService in FREDOSAR and can receive commands via the CommunicationService and sends them to the EnOcean device. This Service does not save the actual state of devices.
**PID: org.enosar.service.io.enocean**
**PID: org.fredosar.service.io.enocean**
## Content
[[_TOC_]]
......@@ -14,12 +14,12 @@ So this Service is fowarding incoming EnOcean messages to the MessagingService i
### Incoming EnOcean Messages (from a EnOcean device)
The EnOcean Service receives messages from EnOcean devices. It accepts only devices that are registered in the Address Management (see [Device and Address Management](#device)). The Service also handles also Teach-In and Teach-Out messages.
If a device has an entry in the Address Management the Service mapps the data to Enosar DTO's(Data Transfer Objects) and publishes the messages to the [MessagingService](https://ressel.fh-salzburg.ac.at/ENOSAR/Framework/wikis/tutorial-core-service-messaging).
The **topic** of the messages are:`in.homeatomation.enocean.[EnosarDevice].[EnosarID]`
* EnosarDevice: is the type of the device and is a constant from org.enosar.core.types
* EnosarID: is the ID of the device as it is in the Address Management
If a device has an entry in the Address Management the Service mapps the data to Fredosar DTO's(Data Transfer Objects) and publishes the messages to the [MessagingService](https://ressel.fh-salzburg.ac.at/FREDOSAR/Framework/wikis/tutorial-core-service-messaging).
The **topic** of the messages are:`in.homeatomation.enocean.[FredosarDevice].[FredosarID]`
* FredosarDevice: is the type of the device and is a constant from org.fredosar.core.types
* FredosarID: is the ID of the device as it is in the Address Management
The Message is a `List<EnosarType>` that is mapped to a JSON String.
The Message is a `List<FredosarType>` that is mapped to a JSON String.
For more information see [Device and Address Management](#device).
Not all devices send data. Some are only receiving commands for details of the devices see [Implemented Devices/Packets](#implDev).
......@@ -27,22 +27,22 @@ Not all devices send data. Some are only receiving commands for details of the d
### Outgoing EnOcean Messages (to a EnOcean device)
The EnOcean Service can send messages/controls to EnOcean devices (only if the device supports). The device must be registered in the Address Management (see [Device and Address Management](#device)). There are 2 possible ways to send controls to a device via the EnOcean Service:
* [CommunicationService](https://ressel.fh-salzburg.ac.at/ENOSAR/Framework/wikis/tutorial-core-service-communication) with the PID **org.enosar.service.io.enocean**.
* [MessagingService](https://ressel.fh-salzburg.ac.at/ENOSAR/Framework/wikis/tutorial-core-service-messaging) with the topic **out.homeautomation.enocean**
* [CommunicationService](https://ressel.fh-salzburg.ac.at/FREDOSAR/Framework/wikis/tutorial-core-service-communication) with the PID **org.fredosar.service.io.enocean**.
* [MessagingService](https://ressel.fh-salzburg.ac.at/FREDOSAR/Framework/wikis/tutorial-core-service-messaging) with the topic **out.homeautomation.enocean**
If the device supports receiving commands the EnOcean Service will send the command to the device (see [Implemented Devices/Packets](#implDev) for supported devices).
The EnOcean service can receive `List<EnosarType>` or `EnosarType` to control devices. If a list of EnosarType is sent the Service will send the commands in the order they are in the list.
The EnOcean service can receive `List<FredosarType>` or `FredosarType` to control devices. If a list of FredosarType is sent the Service will send the commands in the order they are in the list.
<a name="device"></a>
## Device and Address Management
Every EnOcean device has to have an entry in the Address Management of ENOSAR. Access the Address Management via the Web Interface of ENOSAR.
Every EnOcean device has to have an entry in the Address Management of FREDOSAR. Access the Address Management via the Web Interface of FREDOSAR.
A entry for a device has:
* Identifier: An unique ID in ENOSAR to identify the device (ENOSAR ID)(e.g.: switch1, socket1)
* Technology: For the EnOcean Service `org.enosar.service.io.enocean`
* Identifier: An unique ID in FREDOSAR to identify the device (FREDOSAR ID)(e.g.: switch1, socket1)
* Technology: For the EnOcean Service `org.fredosar.service.io.enocean`
* Receiver Information: Consists out of 2 information's. The EnOcean device ID and the EEP packet description. The syntax is `0x[EnOcean ID in hex].[EEP]`:
* EnOcean ID: Is the unique ID of the EnOcean device. The EnOcean ID is displayed in the terminal when the device sends a message and is not in the Address Management.
* EEP: Describes the data packet that is sent of the device. This information can be found in the manual of the device (EnOcean Equipment Profile (EEP)). All in ENOSAR implemented data packets are listed in [Implemented Devices/Packets](#implDev)
* EEP: Describes the data packet that is sent of the device. This information can be found in the manual of the device (EnOcean Equipment Profile (EEP)). All in FREDOSAR implemented data packets are listed in [Implemented Devices/Packets](#implDev)
Here is an example for an entry in the Address Management:
......@@ -157,8 +157,8 @@ Here is a List of implemented EEP packets and devices
In the manual of devices is a description called EnOcean Equipment Profile (EEP).
This information is necessary to get the detailed information of the sent packet and data. All EEP are described in this PDF <http://www.enocean-alliance.org/eep/>. This document contains the information which byte contains which data in the data packet.
To add a new EEP a new class must be created in the Package `org.enosar.service.io.enocean.eep`. This class inherits from `EEPRadioPacket.java`.
The new class matches the incoming bytes to EnosarType DTO's. The class also handles sending new EnOcean Messages to the device and maps the EnosarType DTO's to a EnOceanMessage that can be sent to the EnOcean device. To send a EnOcean Message to a device the ResponseRadioPacket is implemented (as new EnOcean Message).
To add a new EEP a new class must be created in the Package `org.fredosar.service.io.enocean.eep`. This class inherits from `EEPRadioPacket.java`.
The new class matches the incoming bytes to FredosarType DTO's. The class also handles sending new EnOcean Messages to the device and maps the FredosarType DTO's to a EnOceanMessage that can be sent to the EnOcean device. To send a EnOcean Message to a device the ResponseRadioPacket is implemented (as new EnOcean Message).
Here is an example of the strcutre and methods of such a implementation
```java
......@@ -201,10 +201,10 @@ public class D5_00_01Device extends EEPRadioPacket {
}
@Override
public List<EnosarType> getAllEnosarTypesOfDevice() {
public List<FredosarType> getAllFredosarTypesOfDevice() {
//Called when the Service sends the publishes the data in the MessagingService
//here the private variables are Mapped to EnosarTypes DTO's
List<EnosarType> returnList = new ArrayList<EnosarType>();
//here the private variables are Mapped to FredosarTypes DTO's
List<FredosarType> returnList = new ArrayList<FredosarType>();
SwitchDTO switchDTO = new SwitchDTO();
if (closed) {
switchDTO.setState(SwitchDTO.State.ON);
......@@ -217,22 +217,22 @@ public class D5_00_01Device extends EEPRadioPacket {
}
@Override
public List<EnOceanMessage> setStatusOrControlDevice(List<EnosarType> deviceDTO) {
public List<EnOceanMessage> setStatusOrControlDevice(List<FredosarType> deviceDTO) {
//called when data/controls from the CommunicatinService received and should be sent to a EnOcean device
//here EnOceanMessages are generated from the EnosarType DTO's that can be sent to the device
//here EnOceanMessages are generated from the FredosarType DTO's that can be sent to the device
return null; // Cannot send data to this device
}
@Override
public String getEnosarDevice() {
public String getFredosarDevice() {
//A identifier for the SmartHome device type
return EnosarDevice.CONTACT;
return FredosarDevice.CONTACT;
}
}
```
The new implemented class then must be added to a list of all implemented Devices in the Package `org.enosar.service.io.enocean.impl` in the Class `DeviceHandler.java`.
The new implemented class then must be added to a list of all implemented Devices in the Package `org.fredosar.service.io.enocean.impl` in the Class `DeviceHandler.java`.
There is a Map called `radioProtocols` add there an entry for the packet/device as shown in the example below.
```java
/** A Map with all Implemented EEP Radio protocols to generate new instances */
......