Java is almost 20 years old, and has over the years gathered a very large community of developers that in turn fostered an even larger ecosystem of open-source components and frameworks.
Thanks to the recent efforts towards making Java a more than decent platform for embedded devices, as well as the help of Moore’s law always bringing more processing power to devices, everyone can benefit from two decades of innovation in the Java land to build IoT (Internet of Things) solutions.
It’s no news that there are many challenges when building an IoT application. One of the main challenges is to make sure that the application you’re building will be simple to operate once it is deployed on the field. It means you need to be able to perform many operations over-the-air, including things like:
- changing the settings of your running application – because a sensor you were attached to, for example, needs to be accessed with different settings,
- deploying a new version of your application – you found a nasty bug that causes your application to use all your tiny cellular data plan in minutes, so you want to deploy a hot-fix on your IoT gateway,
- ensuring the gateway has proper access to the network – because you care about your application and not necessarily about how you’ll actually get Internet connectivity, it’s important to have a framework taking care of your wireless modem of WiFi setup for you.
Eclipse Kura is an Eclipse IoT project that provides a platform for building IoT gateways. It is a smart application container that enables remote management of such gateways and provides a wide range of APIs for allowing you to write and deploy your own IoT application.
Kura runs on top of the Java Virtual Machine (JVM) and leverages OSGi, a dynamic component system for Java, to simplify the process of writing reusable software building blocks.
In this tutorial, we want to guide you through the steps for building your very own IoT gateway. We will first guide you through the (very simple!) process of installing Eclipse Kura on what will become your IoT gateway (we’ll be using a Raspberry Pi as the hardware platform), and we will then detail how you can install deploy existing IoT applications or develop your own using Kura’s application framework.
Kura provides a Java/OSGi-based container for IoT applications running in service gateways. By installing Kura on a device, not only can you turn it into a powerful IoT router that can be managed remotely, but you also have access to a complete application framework for deploying custom applications. These applications leverage OSGi and Kura API for making it easy to access the underlying hardware (serial port, GPIOs, etc.), communicate with an IoT server backend, manage the runtime settings, etc.
Learn more on Kura on the project’s website: https://www.eclipse.org/kura.
MQTT and Paho
In order to make the greenhouse sensors data available to the Internet, and therefore allow 3rd party applications (mobile, web, etc.) to consume this data, we will use the MQTT protocol.
MQTT is a lightweight messaging protocol based on the publish/subscribe model. A central broker is federating MQTT clients that are publishing messages on specific topics, allowing other clients subscribed to these topics to immediately receive those messages.
Eclipse Paho is an open-source project that provides MQTT client implementations in many programming languages, and Kura is using Paho to provide high-level OSGi services for IoT communications between a gateway and the Internet.
Learn more on Paho on the project’s website: https://www.eclipse.org/paho.
CoAP and Californium
CoAP (Constrained Application Protocol) is a RESTful protocol targeting constrained embedded devices and wireless networks. CoAP essentially replicates the HTTP resource model on top of UDP using a binary, bandwidth-efficient, encoding.
Eclipse Californium provides a Java implementation of CoAP, together with a security library (Scandium) for DTLS.
Learn more on Californium on the project’s website: https://www.eclipse.org/californium.
What are we going to build?
Whether we are talking about industrial control, wearables, home automation, or any other field where IoT is relevant, the core principle is always the same: we want to connect a reasonably smart device coupled with sensors and actuators, to the Internet so as the sensors and actuators can be monitored and controlled remotely.
A very simplified version of such a smart device could be a connected greenhouse that allows you to monitor the current temperature from wherever you are in the world, as well as turn artificial lighting on and off – and that’s exactly what we are going to build!
Setting up the hardware
We’ve kept the list of hardware elements needed for the greenhouse to a minimum to make it easy for anyone with no electronics skills to build it.
Here is what you will need:
- Raspberry Pi Model 2 and an SD card (min. 4GB) with the latest Debian Linux distribution. Raspbian should be downloaded from the Raspberry Pi Foundation’s Downloads page, and these instructions will help you put Raspbian on the SD Card.
- Grove temperature & humidity sensor,
- Grove LED,
- 4 pin Female Jumper to Grove 4 pin Conversion Cable,
- Ethernet cable.
You can easily order the parts from SeeedStudio thanks to the following wish list: http://tiny.cc/iot-greenhouse-parts.
You can also check for a distributor next to you on this web page.
Assembling the Raspberry Pi and the sensors
As indicated earlier, the hardware setup should be really just take a couple of minutes. Before to actually perform the wiring of all the sensors, now is a good time to briefly explain how the Raspberry Pi can be augmented with external sensors. The row of pins, along the edge of the board, is programmable from the Linux system, is allow you to interact with various kinds of sensors you can connect to them. You should think of these GPIOs (General Purpose Input Outputs) as switches you can control from the Raspberry Pi (outputs), or that external sensors can control (inputs). Some of the pins are more sophisticated and allow the use of higher-level protocols to exchange more than on/off signals ; such protocols include SPI, I2C or UART, and we will indeed use an I2C temperature sensor in this tutorial.
Now is time to hook up our temperature sensor and LED to the Raspberry Pi! The GPIO pins are numbered as follows (if you have a Raspberry Pi model B, no worries, the pin headers we’ll be using are the same):
- Connect the Grove cables to your temperature/humidity sensor and LED
- ⚠ Make sure that your Raspberry Pi is not powered!
- Temperature sensor:
- BLACK wire goes on PIN#06
- RED wire goes on PIN#01
- YELLOWwire goes on PIN#05
- WHITEwire goes on PIN#03
- BLACK wire goes on PIN#14
- RED wire goes on PIN#02
- YELLOWwire goes on PIN#11
- The WHITE wire is not used in the case of the LED – you only really need one pin to toggle a LED on or off, right? 🙂 – so you can leave it dangling or connect it to a Ground pin header.
- Connect the Raspberry Pi to your home router or to your PC using the Ethernet cable.
That’s all, really! Now let’s boot our Raspberry Pi for the first time and install Kura.
Booting the Raspberry Pi for the first time
After the first boot completes, make sure to run the configuration utility and expand the filesystem.
Follow these instructions from Adafruit on how to enable I2C properly.
Don’t forget to reboot for the changes to be applied.
Installing Eclipse Kura on the Raspberry Pi
It is really easy to install Kura on your Raspberry Pi. It is actually as simple as installing any other Debian package.
Assuming you are properly logged in on your Raspberry Pi, here’s how to install Kura:
cd ~ sudo apt-get update # let’s make sure Debian repositories descriptions are up-to-date wget https://s3.amazonaws.com/kura_downloads/raspbian/release/1.3.0/kura_1.3.0_raspberry-pi-2_installer.deb sudo dpkg -i kura_1.3.0_raspberry-pi-2_installer.deb
dpkg will complain about missing dependencies, and will fail. Indeed, Kura depends on some packages that you probably don’t have on your Raspberry Pi, so we must tell Aptitude to download those automatically for us:
sudo apt-get install -f
You should now reboot your Raspberry Pi to make sure all the Kura services are properly started.
In order to confirm that Kura is properly installed, you can try accessing its web UI from your favorite web browser. The URL should be something like: http://my-raspberry-pi/kura, default credentials are: admin / admin.
Deploying a ready-to-use greenhouse application
Before diving deeper into how to use the Kura application framework for developing your own application, let’s see by ourselves how easy it is to deploy an application in Kura.
Kura relies on the OSGi Deployment Admin standard to allow software packages to be managed. A deployment package is essentially a ZIP file containing a set of OSGi bundles and a Manifest providing the name, version, etc. of the application.
We have already prepared a software package containing the application that allows to control the greenhouse over MQTT or CoAP.
Installing the application from Kura web UI
If you correctly followed the previous steps, Kura should be now up and running on your Raspberry Pi, and you should be able to access its web-based administration interface from your browser.
- Navigate the “Packages” entry of the web UI
- Click the “Install/Upgrade” button and enter the following address in the “URL” tab of the popup dialog: http://iot.eclipse.org/java/demo/org.eclipse.greenhouse.iot-0.1.0.dp
- Refresh your web browser and notice there is a new entry in the Services section on the left-hand side: Greenhouse Publisher.
Configuring the application
Kura allows to easily manage the settings of the installed software components from its web UI, together with the ability to save snapshots of those settings that can be re-applied if and when needed. It is also possible to manage the settings over the air, by publishing specific MQTT messages to the broker the Kura gateway is configured to talk to.
Here are the settings you need to adjust:
- In the MqttDataTransport section, you need to change the broker-url to: mqtt://iot.eclipse.org:1883/- other settings can remain unchanged,
- In the DataService section, you want to make sure that the MQTT communication is automatically established when Kura starts, by setting connect.auto-on-startup to true,
- Finally, you have to change the prefix of the MQTT topic for the data related to the greenhouse. In the Greenhouse Publisher section, set publish.appTopicPrefix to whatever seems like a good name for your greenhouse (e.g. javaonedemo/bob-greenhouse)!
Communicating with the greenhouse remotely
Now that Kura and our Greenhouse application are properly configured, the current temperature is actually published over MQTT, and it’s also possible to toggle the LED by publishing a message on a specific topic.
The easiest way for you to control your now IoT-ized Raspberry Pi + greenhouse combo is to use a Web UI that uses MQTT over WebSockets to display the temperature and control the LED.
Simply replace the end of the URL with the topic prefix you picked earlier (for the example earlier, the URL would be http://iot.eclipse.org/java/demo/app/#/greenhouses/remote/bob-greenhouse)
Hopefully, you’re now more familiar with Kura, and we encourage you to play around with the Web UI to learn more about its capabilities in terms of network management, device-to-cloud communication, etc.
If you’d like to actually use the Kura application framework to develop your own IoT application, you may want to check out the source code of the “Greenhouse” app you’ve deployed earlier – it’s on Github .
Build your own greenhouse!
Head over to Thingiverse and download the blueprints of the acrylic greenhouse below. With them, just use the online laser-cutting service of your choice or go to a local Fab Lab to get all the pieces cut from a sheet of plexiglas! It shouldn’t cost you more than $20.
Retrieve the humidity
Similarly to how we retrieved the temperature, you could refer to the sensor’s datasheet to implement the proper I2C code to read the humidity. See in particular Section 3.1.1. Performing a Relative Humidity Measurement.
Use other I2C sensors
The great thing with I2C sensors is that it’s really easy to hook up several of them on the same host device. Just use your imagination and explore what you could do if you were to use a luminosity, barometric pressure, or carbon dioxide sensor!
Use Kura’s CloudService to publish data
The CloudService leverages Google Protocol Buffers to provide a very efficient binary communication between the Kura gateway and an IoT server. Browse the documentation of the CloudClient and KuraPayload APIs to learn more.
Setup a 6LoWPAN network
If you’re familiar with 802.15.4 Wireless Sensor Networks, you could easily setup your Raspberry Pi as a border router, that would expose the CoAP server on its radio interface. You could then use e.g. Contiki and the Erbium CoAP client to write a simple app that will run on a mote and talk CoAP to read the temperature, or control the LED!