User Manual - GoranErdeljan/TINF19C-Team-4-Service-Registry GitHub Wiki
- 1. Glossar
- 2. Introduction
- 3. Installation
- 4. User Interface
OI4-Service-Registry: Development by the OI4-Alliance.
MQTT: Message Queuing Telemetry Transport (MQTT) is an open network protocol for machine-to-machine (M2M) communications that enables the transmission of telemetry data in the form of messages between devices, despite high delays or limited networks.
Docker: Docker is a software that enables container virtualization of applications. Applications can be packed into an image including their dependencies. Using a special engine, the packaged application can then be executed in a Docker container.
The goal of the project is to add service discovery functionalities to the existing OI4-Service-Registry, developed by the OI4-Alliance. To be added features are the registration of devices, which are announced via DNS-SD but also to take the services, which are already registered at the OI4-Service-Registry and announce them to the network using the DNS-SD mechanism. These features are implemented in an application running in a Docker-Container.
The project consists of two main parts: the Docker-Container connecting the DNS-SD mechanism with the OI4-Service-Registry and the Docker-Container, which tests and showcases the functionalities of the system. To realize a working system, there need to be other applications running in the environment. These are the OI4-Service-Registry developed by the OI4-Alliance and a MQTT-Broker on which the communication with the OI4-Service-Registry takes place. The communication using the MQTT-Protocoll is specified by the OI4-Alliance.
Conceptually the main Docker-Container is just another MQTT-Client. The OI4-Service-Registry also acts as a MQTT-Client. Both communicate with each other over the MQTT-Broker. In most cases the MQTT-Broker of choice will be Eclipse-Mosquitto, as it is available as a Docker-Image and therefore easy to deploy. All Communication over MQTT must be conform with the specifications published by the OI4-Alliance. In the context of the systems specified by the OI4-Alliance this way of communicating is called the OI4-MessageBus. Services can use the MessageBus to be registered at the OI4-Service-Registry. The Test Application shall also be able to connect to the MessageBus, if it is configured to register itself at the OI4-Service-Registry.
The DNS-SD mechanism on the other hand is used to announce important information about a service in the network. It is not limited to services, which are part of the OI4-ecosystem. In this use-case it is not only used to announce the services registered at the Service-Registry, but if configured to, also collect information about not yet registered services, which may announce themselves to the network and register them at the OI4-Service-Registry.
A MQTT-Broker and OI4-Registry software must be fully functional pre-installed. We use Mosquitto as a MQTT-Broker. Once these requirements are met, you can proceed with the rest of the installation / setup.
First you have to download the Git repository at an arbitrary location. Please remember the path of the folder!
We use mosquitto as a MQTT-Broker.
Command: sudo docker run --net=host --restart always -d --name mqtt eclipse-mosquitto
With the command all Docker containers can be viewed: sudo docker ps -a
command: sudo docker run --net=host --restart always -d --name oi4-registry oi4-registry
The latter is only an example name and must be adapted according to the circumstances.
The OI4 registry can be reached at localhost:5000 (default port from the OI4 registry).
You can view all Docker containers with the command: sudo docker ps -a.
After a successful start of the Mosquitto Docker, the interface must be started. To do this, navigate to the folder MOD_10_DNS-SD-to-OI4-Service-Registry-Interface. This is located in the path [DownloadPath]/TINF19C-Team-4-Service-Registry/SOURCE/MOD_10_DNS-SD-to-OI4-Service-Registry-Interface where [DownloadPath] should be replaced with the path of your download folder for the Git repository.
Once inside this folder, check to see if the Dockerfile file exists. To do this, use the dir command to display the contents of the folder. If this is not the case, the git need to be downloaded again!
Command to build the docker image of the interface: sudo docker build --tag oi4-dns-sd-interface .
After entering the command some steps will be executed. If all of them are executed and the message "Successfully..." is displayed at the end, the interface was started correctly.
After starting the interface, the test application is also started. This is located in the folder [DownloadPath]/TINF19C-Team-4-Service-Registry/SOURCE/MOD_20_Application where [DownloadPath] is to be replaced by the path of your download folder for the Git repository.
Once inside this folder, check if the Dockerfile file exists. To do this, use the dir command to display the contents of the folder. If this is not the case, the git need to be downloaded again!
Command to build the docker image of the test application: sudo docker build --tag oi4-dns-sd-test .
After entering the command some steps will be executed. If all of them are executed and the message "Successfully..." is displayed at the end, the interface was started correctly.
Command to display all images: sudo docker images
Please check if the previously created Dockers are listed. In the first column (REPOSITORY), the names oi4-dns-sd-interface and oi4-dns-sd-test should be listed.
Command to run the Docker container (test): sudo docker run -d --restart always --net=host --name oi4-dns-sd-test oi4-dns-sd-test.
The test application can be accessed via localhost:8080. If you want to call via another machine, you have to take the IP address of the server instead of localhost.
Command to run the Docker container (interface): sudo docker run -d --restart always --net=host --name oi4-dns-sd-interface oi4-dns-sd-interface.
To configure the individual Docker containers, the following must be inserted --env [ENV].
Command to convert: sudo docker run -d --restart always --net=host **--env [ENV]**--name oi4-dns-sd-[name] oi4-dns-sd-[name].
Here [name] is replaced by the respective docker name of the application.
[ENV] is replaced by the environment variables. The following list is available for selection:
Test application:
- WEB_INTERFACE_PORT: Port on which the test application's web interface should be accessible (default 8080).
Common:
- MDNS_HOSTPORT: Port to be entered in the SRV record of a DNS SD response (default 8080).
- MDNS_HOSTIP: IP address to be entered in the A-record of a DNS SD response (default 192.168.0.1)
- MQTT_HOSTNAME: IP address or host name of the MQTT broker (default 'localhost')
- MQTT_PORT: Port on which the MQTT broker can be reached (default 1883)
- OI4_SERIALNUMBER: Serial number to be used for communication on the OI4 measurement bus (default 'undefined')
- OI4_MODEL: Model to be used for communication on the OI4 measurement bus (default 'DNS_SD_INTERFACE')
- OI4_PRODUCTCODE: Product code to be used for communication on the OI4 measurement bus (default 'DNS_SD_INTERFACE')
- OI4_DEVICECLASS: DeviceClass to be used for communication on the OI4 measurement bus (default 'Aggregation').
- OI4_URN: URN to be used when communicating on the OI4 measurement bus (default 'urn:undefined.com').
Interface only:
- REGISTER_DNS_SD_AT_OI4: Specifies whether the interface should support the inclusion of DNS SD entries in the OI4 registry (default true).
- ANNOUNCE_OI4_REGISTERED_SERVICES: Specifies whether the interface should support promoting entries to the OI4 registry via DNS-SD (default true).
To set a value, the following syntax is used [VALUE] is replaced with the value: MDNS_HOSTIP="[VALUE]".
Example: sudo docker run -d --restart always --net=host --env MDNS_HOSTIP="192.168.0.164" --name oi4-dns-sd-[name] oi4-dns-sd-[name]
For multiple environment variables, the above syntax must be repeated: sudo docker run -d --restart always --net=host --env MDNS_HOSTIP="192.168.0.164" --env MDNS_HOSTPORT="192.168.0.164" --name oi4-dns-sd-[name] oi4-dns-sd-[name]
The test application interface is used to test the extension for registering DNS-SD entries in the OI4 registry. This application is not required for the end user. The interface can be reached under the IP address, which is stored in your system under the port :8080.
The interface of the OI4 registry serves as communication for the end user. Here all entries, which were seized by the OI4 Registry and those of the written extension, are indicated. The interface can be reached under the IP address which is stored in your system under the port :5000 (see OI4 Registry default port).
Due to certain circumstances, in this example the OI4 registry can be reached under the port :5001.
If you open an entry in the OI4 registry, you will see a detailed display of the entry. These can also be found in the TXT field in the test application. However, there is it not so clear.
This user manual is up to date 05.05.2021