Oracle IoT Cloud Service - Application Development Basics
by Juarez Junior
Introduction
Recent reports by Forrester and IDC about the IoT (Internet of Things) market and adoption concluded that first, IoT now reached a point where it is moving from experimentation to business scale and second, worldwide technology spending on the Internet of Things will reach $1.2 Trillion in 2022.
The Oracle IoT Cloud Service is a managed Platform as a Service (PaaS) cloud-based offering that helps you to connect your IoT devices to the cloud, analyze data from those devices in real-time and integrate your data with enterprise applications, mobile applications, microservices, web services or with other Oracle Cloud Services.
This tutorial shows the quick steps required to configure an IoT application on Oracle Internet of Things (IoT) Cloud Service, register a cloud-side device as well as activate the device.
It also explains how to code a simple client-side device application as well as how to use the device provisioning file that you can download from the cloud service to connect to your IoT application.
1) Access the Oracle IoT Cloud Service
Before you begin, we assume that you have:
· Access to an instance of Oracle IoT Cloud Service. In case you need to provision your IoT CS instance first, you can check the related blog post: Oracle IoT CS — How to Create the IoT Enterprise Service Instance.
· A computer with a Java development environment (required to run the sample code) or any other programming language development environment of your choice (C, C++, Javascript, Python, others) and a web browser;
· Familiarity with basic Oracle IoT Cloud Service management console operations.
In a web browser, enter the URL for your Oracle IoT Cloud Service instance. Normally the URL has the following form: https://myinstance-myidentitydomain.iot.us.oraclecloud.com
Enter your user ID and password, click Sign-In, and after the successful logon process the main screen is shown as below:
2) Create the IoT application (OracleIoTApp)
Follow the steps below to create your IoT application and provide the required information as described below.
From the main screen, select the hamburger user interface component at the top right corner of your screen (the one inside the red square below). You will see the right side actions bar with Home as the default, selected menu option.
Select Applications -> Browse Applications and click the Create Application button. You will see a popup window.
Enter the required information and click the Create button.
· Name: OracleIoTApp
· Description: Sample IoT App
You will see that your application is now created.
3) Create the Device Model
The next step is to create the Device Model. Select Applications -> OracleIoTApp -> Device Model and click the button with the plus (+) sign so that you can add a new device model.
Enter the following values in the Details section:
· Name: OracleIoTDeviceModel
· Description: Sample Device Model for Oracle IoT App
· URN: urn:test:oracleiotappsample (the URN will be used in the client Java code shortly)
In the Custom Attributes section, click the Add (+) button.
Enter the following values:
· Name: messagefromiotdevice
· Description: This attributes stores the string message from the Java device
· Type: String
· Writable: Checked (checkbox)
Click OK and then click Save. The attribute is saved and the Device Model page will show the device.
4) Register a device
The next step is to register a device. Select the hamburger user interface component at the top right corner of your screen again.
Then select Devices -> Registration -> Single Registration -> Register Single.
On the Register Single Device page, enter the following values and click Register:
· Activation ID: ORACLEIOTCSDEVICE
· Activation Secret: SampleSecret
· Name: OracleIoTDevice
· Manufacturer: Sample Oracle Device Manufacturer
· Serial Number: 123456789
· Model Number: Oracle-2018
On the confirmation page, enter a password for the provisioning file in the File Protection Password input field and confirm your password in the Confirm Password input field.
After that click the Download Provisioning File button and save the file as you will need to use it in the Java client code.
Take note of the Activation ID which is the same as the Provisioning File Name and the File Protection Password because you’ll need these values to activate the device from the Java client code.
4 ) Implement the Java Client Device by using the IoT Cloud Service Java API
Now you can implement the Java Client Device and leverage the IoT Cloud Service Java API to simulate and integrate an IoT device, then send a message from it to our cloud-side IoT Cloud Service application and device configurations.
The Java code sample below has only the bare bones of an implementation that will allow you to perform a couple of crucial steps:
a. Activate the Device — the device is activated by the client side, there’s no option available in the cloud console for that;
b. Test your configurations as well as make sure that your communication channel is working properly, that is, validate the network path as well as validate the IoT device configuration on both the client and cloud sides along the bi-directional communication.
We’ll send a message from the IoT device (client-side) to our IoT Cloud service, and retrieve the same message from the cloud side so that the entire network round trip and communication can be validated.
In order to implement the device client simulation, you need to leverage one of our existing IoT client libraries and APIs. There are many available such as Java, C, C++, Javascript, POSIX, Android, iOS, and even a REST API.
The example below uses the Java library and you can download the libraries here.
Regarding the Java code, you can check the full Javadocs documentation for the related API on the link below.
You can use any Java IDE to create the Java project and implement the code. As an example, you can use an Eclipse Java project. Note it is only a plain old Java project with no tricks or additional details at all. Just remember that as usual, you will need to download the JAR files from the link below and include them on your Java classpath (lib directory).
So without further ado, let’s implement the Java client device. The code is very basic and self-explanatory as it has all the comments that explain the different parts and steps regarding our Java IoT client device implementation.
5 ) Test and validate our IoT scenario - Java IoT device (client-side)
We can now test and validate it all: the device simulation and IoT Cloud Service configurations. It will allow us to test the end-to-end, bi-directional IoT interaction and communication.
Again remember that our cloud-side device configuration is activated by the client-side request, not with the selection and configuration of an option on the cloud side — there’s no option available on the console / GUI for that at all.
So on the Java code, we have this code excerpt below for that:
// The client activates the device if it not activated (so that you can run the code more// than once!)if (!dcd.isActivated()) {dcd.activate(URN);}
Note that after the first communication the device will change its status to an Activated one as expected.
Run the Java application on Eclipse. Right-click any area in the Eclipse code editor, then select Run As -> Java Application.
Provided that everything is OK regarding your Java project and the network path (firewalls, proxies, others) you will see the output below on Eclipse’s console tab:
ENDPOINT ID: BE640DE7-F9F5-4A18-8758-D3D7FE8DA453DEVICE MODELurn = urn:test:oracleiotappsample,name = OracleIoTDeviceModel,description = Sample Device Model for Oracle IoT App,attributes = [{urn = urn:test:oracleiotappsample, name = messagefromiotdevice, description = This attributes stores the string message from the Java device, type = STRING, lowerBound = null, upperBound = null, access = READ_WRITE, alias = null, defaultValue = null}],actions = [],formats = []Java - Message from Simulated IoT Device
Let’s explain the logged messages above.
First, we send the message from the Java IoT device client to our cloud service:
// Triggers a message to the Cloud Service.virtualDevice.set(TEST_ATTRIBUTE, "Java - Message from Simulated IoT Device");
Then provided that our message is sent from the Java IoT client to our Oracle IoT Cloud Service application, we can then retrieve the cloud IoT endpoint ID:
// Get the virtual device endpoint IDSystem.out.println("ENDPOINT ID: " + virtualDevice.getEndpointId());
The output is:
ENDPOINT ID: BE640DE7-F9F5-4A18-8758-D3D7FE8DA453Then we do almost the same as before but now for the device model — and remember that we created a custom model during the configuration steps:
// Get the endpoint device modelSystem.out.println("DEVICE MODEL" + virtualDevice.getDeviceModel());
The output is:
DEVICE MODELurn = urn:test:oracleiotappsample,name = OracleIoTDeviceModel,description = Sample Device Model for Oracle IoT App,attributes = [{urn = urn:test:oracleiotappsample, name = messagefromiotdevice, description = This attributes stores the string message from the Java device, type = STRING, lowerBound = null, upperBound = null, access = READ_WRITE, alias = null, defaultValue = null}
Here then we retrieve the same message (and its contents) we sent so that we can validate the bi-directional communication:
// Get the remote custom attribute value (from the IoT Cloud Service)System.out.println((String) virtualDevice.get(TEST_ATTRIBUTE));
The output is:
Java - Message from Simulated IoT Device6) Test and validate our IoT scenario — Oracle IoT Cloud service (cloud-side)
On the Oracle IoT Cloud Service side, we can now check the IoT device messages on the Oracle IoT Cloud Service side.
Select the hamburger user interface component at the top right corner of your screen once again and then select Devices -> Alerts and Messages.
You will see the screen below where you can see the details of the message received.
You can run the Java IoT client program again and see that more messages will be received and confirmed as below.
One last thing. Note that as usual you can use the Java Debugging perspective, set your breakpoints as well as introspect the Java code on the client side in order to further analyze and understand the communication scenario.
That’s it! I hope this blog post helped you understand how easy it is to develop IoT applications by leveraging the features of our Oracle IoT Cloud Service, combined with the available IoT application client APIs.
Give it a try! Get Started with Oracle Cloud for Free!
