tutorial-service-serial.md

-### Configuration
+# Serial Communication Service
+
+This service wraps the serial connection. Therefore several serial ports can be configured for communication. The service implements the [Communication Service Interface](https://ressel.fh-salzburg.ac.at/FREDOSAR/Framework/tree/master/core/org.fredosar.core.communication).
+If your Raspberry Pi is configured adequately, the serial service can be used for any serial ports (such as USB, GPIO, Bluetooth).
+
+<b>Hint: Be aware that using the serial comminication service could lead to conflicts with other FREDOSAR services using hardware ports of the Raspberry Pi.</b>
+
+**PID: org.fredosar.service.io.serial**
+
+# Content
+[[_TOC_]]
+
+# Serial Configuration example (Web Interface)
+## Bundle Configuration
+This example shows the standard bundle configuration. Serial Ports can be added and removed as needed for each, the 'allowed_ports' and the 'fredosar_device_ports'. Hint: If you add a port to the 'fredosar_device_ports' this port will always use ``EventDTO`` for communication. You won't be able to communicate to other devices then.
+
 ![image](/uploads/ed7d0fe8eb5249925146f35f441d4ceb/image.png)
 
-### Permissions
+## Permissions
+These are the standard permissions for the serial communication service. If you don't want do rewrite the serial service, you don't have to change them.
+
 ![image](/uploads/4751899eaedcc141609ae90caf11c69c/image.png)
 
-### Addresses
+## Addresses
+To start communicating via a serial port, the addresses of the sending and the receiving entity have to be added as an Address Object. 
+An example for being able to communicate with two different receivers could be:
+
+### Sender Address Configuration (e.g. fredosar12)
+| Identifier | Technology | Receiver information |
+|------------|------------|----------------------|
+|this.serial|org.fredosar.service.io.serial|this@/dev/ttyAMA0:9600|
+|fredosar2.serial|org.fredosar.service.io.serial|fredosar2@/dev/ttyAMA0:9600|
+
 ![image](/uploads/65806d62fa3862fe09d028febbeb43de/image.png)
 
-### Error solving
-To unlock a serial port after it has been initialized once you have to remove the lock-File as following:
-![image](/uploads/4cb2248780173b93b826e0527d81db3c/image.png)
+<b>Hint: Follow the notation: <identifier>@<port>:<baudrate> such as for example "fredosar2@/dev/ttyAMA0:9600"</b>
+
+### Receiver Address Configuration (e.g. fredosar2)
+![image](/uploads/664428a0ba53292c9435c0dae1723bcc/image.png)
+
+<b>Hint: For serial communication, both devices, the sender and the receiver, have to be configured with the right ``AddressDTOs`` (like in this example), otherwise the serial communication won't work.</b>
+
+# Example Usage
+Assumed that the Serial service is running properly and all Addresses and Permissinons are provided, the service can be triggered as follows: 
 
-### Encrypted Ping Pong Test via Serial
-#### Sender
+### Service triggered Serial Communication
+To use Serial communication via ``sendMessage(...)`` your Application has to implement ``AddressServiceAware`` and ``CommunicationServicesAware``.
+Then it can be used, after the ``CommunicationService`` has to be initialized for Serial:
+```java
+CommunicationService communicationService = serviceArray.get("org.fredosar.service.io.serial");
+```
+Then the service can be used straight forward:
+
+```java
+AddressDTO address = addressService.getAddress("fredosar2.serial");
+EventDTO event = DTOFactory.createEvent("this.serial", address.getIdentifier(), "any.topic", CipherMode.PLAIN, "Any Content here...");
+communicationService.sendMessage(address, event);
+```
+
+### Messaging topic triggered Serial Communication
+Having a ``MessagingServiceAware`` Application message can be sent as follows:
+
+```java
+EventDTO event = DTOFactory.createEvent("this.serial", "fredosar2.serial", "any.topic", CipherMode.PLAIN, "Any Content here...");
+messagingService.publishMessage("out.serial." + event.getTopic(), event);
+```
+
+Be sure that created ``event`` comprises the right sender ('this.serial') and receiver (e.g. 'fredosar2.serial') address.
+
+Hint: the Application that uses the Service must have the Messaging Access permissions for write to the `out.serial.*` topic.
+
+<b>Hint: If you have the port of the AddressDTO identifier 'fredosar2.serial' added to 'fredosar_device_ports' in the bundle configuration, the Serial Communication Service will
+send a string formated ``EventDTO`` here. If not, the Serial Service will only send the content of the 'EventDTO', which would for example be "Any Content here..." 
+for this example.</b>
+
+# Encrypted Serial Communication Example
+## Sender
 ![image](/uploads/80dfea729629d2407bb8e13a79e5213b/image.png)
 
-#### Receiver
+## Receiver
 ![image](/uploads/3db1bc0ab510eb63963afa0f5a1dc8f8/image.png)
+
+# Implementation
+This section gives a brief insight in how the Serial Bundle is implemented in Java and which external libraries it uses.
+
+## Components Model
+Not ready yet.
+
+## Used external libraries
+```xml
+<dependency>
+  <groupId>com.neuronrobotics</groupId>
+  <artifactId>nrjavaserial</artifactId>
+  <version>3.11.0</version>
+</dependency>
+```
+
+# Potential Errors
+To unlock a serial port after it has been initialized once you have to remove the lock-File as following:
+![image](/uploads/4cb2248780173b93b826e0527d81db3c/image.png)
+
+This error will also appear if you want to run two different FREDOSAR bundles (e.g. Enocean and Serial) on one Port or after stopping and restarting the Serial bundle.