In this article I describe an integration between Eclipse Kura and Oracle IoT. (last update: 15/12/2018, English version).
Introduction.
In the context of a Proof of Concept realized for a customer, to show how you can implement a client for Oracle IoT Cloud, integrated in an OSGi-based Gateway, I decided to adopt the Open framework Eclipse Kura and I have developed a working version of the integration.
At a later time, we decided to adopt Kura for a demo project based on the concept of Smart City: Oracle Proxima City.
Finally, the integration achieved was described in the first version of the IoT Workshop held in Rome in September 2018.
In this short article I have documented how the integration has been developed. A pointer to the Github repository with the code is provided.
Why an IoT Gateway?
A Gateway is often a fundamental component of an IoT architecture.
Frequently, devices that are directly connected to sensors and/or actuators can not be directly connected to an IoT Cloud.
The reasons can be multiple:
- the device does not support IP
- the device does not have the memory/computational capacity to use the chosen communication protocol
- for security reasons
In this case, N Gateways are used. The devices speak, with a common supported protocol , with the Gateway. Then, the Gateway relays the messages to the Cloud.
The Gateway, as seen in the short note above, simplifies and enhances the security model. For example, it is an advantage that in face of a large number of devices in the field, the number of gateways that must be connected to the Cloud is largely reduced. Obviously, the relationship between device and gateway must be “trusted”.
Eclipse Kura.
From the Eclipse Kura site:
Eclipse Kura™ is an extensible open source IoT Edge Framework based on Java/OSGi. Kura offers API access to the hardware interfaces of IoT Gateways (serial ports, GPS, watchdog, GPIOs, I2C, etc.). It features ready-to-use field protocols (including Modbus, OPC-UA, S7), an application container, and a web-based visual data flow programming to acquire data from the field, process it at the edge, and publish it to leading IoT Cloud Platforms through MQTT connectivity.
Kura was born from the work done in Eurotech. Part of the code they created for the ESF framework was donated to the Eclipse Foundation and was the starting point for the Kura project, now in version 4.0 (the latest stable build is 3.2, April 2018).
In short, Kura is an open, open source framework, to implement IoT gateways and custom applications to run on the Gateway.
Kura provides a layer that is positioned on the operating system (Linux) and simplifies:
- device management (ex: network, firewall)
- the development of integrated applications
- the connection with devices equipped with sensors and/or actuators
- the connection with a management Cloud (see, in this regard, Eclipse Kapua)
Kura supports a whole set of protocols (ex: BLE, Modbus, ...) to communicate with devices.
In our integration we assume that the data from the device (example: an Arduino MKR WiFi 1010 board with sensors) will arrive via MQTT, but we could have used BLE or another of the protocols for which drivers exist. Obviously, we should change part of the implementation.
The application components are developed as OSGi Bundles. They can be installed via the Kura WebUI or its API, and distributed as a Deployment Bundle.
The native development language for Kura is Java.
Oracle Gateway Device Virtualization API.
Oracle (which is the company I work for) provides libraries for the development of IoT applications for the most commonly used languages (Java, C, NodeJS).
A higher level library is the Device Virtualization API. There are two versions of this:
- the version for Directly Connected Device (DCD)
- the version for Gateway
The documentation is available at the URL: https://docs.oracle.com/en/cloud/paas/iot-cloud/iotcp/overview-summary.html
In this integration we have obviously used the Java libraries and the Gateway version.
The fundamental difference lies in the fact that, in principle, a Gateway can be connected to N devices and therefore, when sending messages to the Cloud, it must do "on behalf of these devices", impersonating the "devices" and not himself.
The integration realized.
What I have done is an "application module", which can be installed in Kura, which reads JSON messages from an MQTT topic, transforms them and sends them to Oracle IoT Cloud. By installing in Kura this component, a Raspberry PI, with Kura on board, becomes an IoT Gateway for Oracle IoT.
The module is implemented as an OSGi bundle, which contains Java bytecode (JAR), a manifest file that defines dependencies, libraries and a configuration file.
The main class is the IoTGateway class, which implements two interfaces:
- ConfigurableComponent
- DataServiceListener
Another important class is the Oracle IoTClient class that encapsulates the Oracle DeviceLibrary code, which allows messages to be sent to the Oracle Cloud IoT.
Finally, there are a number of support classes: classes implementing supported data formats (OBD2, Aircare, ...).
The module is distributed, as expected in Kura, through a deployment package, a file extension ".dp".
For more information on how to make an OSGi bundle for Kura, it is advisable to consult the official documentation. There is an excellent, detailed "how-to" that can serve as a starting point:
https://eclipse.github.io/kura/dev/hello-example.html
Github repository.
The integration code is accessible in the GitHub repository created for this purpose: https://github.com/luigisaetta/kuragateway2019.
The JAR files of the libraries used have been also placed in the repository.
Kura installation.
In the following I refer to an installation on a Raspberry PI 3 B +. The operating system version adopted is Raspbian Stretch.
The first step is to install the S.O. on RPI 3. After installing it, it is worthwhile:
- enable connections via SSH
- change the user password "pi"
- set the correct timezone and the WiFi zone
- upgrade to the latest packages available with
sudo apt-get update
sudo apt-get upgrade
Finally, install a JDK 8 (for now the additions have been tested with this version).
To install Oracle JDK 8:
sudo apt-get install oracle-java8-jdk
Then precisely follow the steps given in the Eclipse Kura online installation guide:
In the guide we refer to a previous version of Rapbian, but, as mentioned, I verified that it works on Stretch. Care must be taken to implement the changes indicated in the note dedicated to Stretch.
Important: Kura takes over the WiFi network. During installation it is essential that the RPI is connected to the router via an Ethernet cable, otherwise, after rebooting, the RPI will no longer be reachable on the network.
The file to download to install the latest available version of Kura (today, 3.2) is:
kura_3.2.0_raspberry-pi-2–3_installer.deb
After rebooting, the Kura Web UI is accessible at the URL
Kura configuration.
After the installation, through the Web UI, the following preparatory operations must be carried out:
- WiFi network configuration
- Enabling, on the firewall, port 1883 (for the MQTT protocol)
- Enabling the "Simple Artemis MQTT Broker"
- Cloud Service configuration
- Finally, before installing the Kura integration bundle - Oracle IoT you must change the contents of the file:
start_kura_background.sh
contained in:
/opt/eclipse/kura/bin
Inserting the following two lines:
-Dhttps.protocols=TLSv1.2 \
-Dorg.osgi.framework.system.packages.extra=sun.net.www.protocol.https\
and modifying the row
-Djdk.tls.trustNameService=false \
After making these changes, Kura must be restarted with:
sudo systemctl stop kura
sudo systemctl start kura
To verify that there are no errors, it is advisable to examine the contents of the two files:
kura.log
kura-console.log
placed in the directory
/var/log
OSGi bundle installation.
The integration is packaged as an OSGi Bundle and is distributed via a deployment package: the IoTGateway.dp file.
The package can be installed via the "Packages" Menu.
After the installation, in the Kura WebUI, on the left side, the entry "IoTGateway" appears, through which you access the configuration page.
Test of the integration.
The integration achieved involves a test mode. In this mode, set by the IoTGateway configuration page
setting "mode.test" to "YES", the messages sent via MQTT to the topic defined , always on the same page, are read, de-serialized and printed in the kura.log, without any message being actually sent to Oracle IoT CS.
Obviously, the message format must be one of the expected formats (msg.type field). It could be useful, for those who want to try, use the Simulator that I described in the article:
found in the github repository:
This simulator uses the format I have called "Aircare". The data is read from files. Obviously, in the Python file you have to define correctly: credentials for the MQTT connection and topic name.
If the test described above is positively passed, as verified by the kura.log, you can proceed to the complete test, sending the messages to Oracle IoT Cloud.
To proceed with this second test, you must:
- create an application in Oracle IoT Cloud
- define the DeviceModel, which describes the data used
- register the Device Gateway (RPI) and download the provisioning file (trusted assett store)
- place this file in the directory defined in the bundle configuration (see above bundle configuration page), setting in the configuration the password chosen to protect the file
- Set the "mode.test" to "NO".
(The first three steps are described in detail in the previously mentioned Medium article).
After making changes to the IoT Gateway configuration, restart Kura.
If all the configurations have been completed correctly, you will see the messages gradually arrive on the IoT Cloud, for example in the defined application Dashboard.
Security.
The conversation between the device and the Kura Gateway takes place via the MQTT protocol. In the adopted configuration the traffic is not encrypted, but it can be done simply by configuring the device and the integrated Artemis MQTT broker.
The device must use a pair (user, pwd) for the MQTT connection, defined in the Broker configuration. These details can be configured via the Kura Web UI.
Troubleshooting.
The log file to read in case of troubles is
/var/log/kura.log
A good sign that the messages are actually sent to Oracle IoT Cloud is the presence in this message file:
o.e.k.e.I.OracleIoTClient - Msg sent to Iot ...
Cool, have fun.