Before You Begin

This tutorial shows you how to build and run an application that simulates a virtual device communicating with Oracle Internet of Things (IoT) Cloud Service through the Apache Felix framework. This tutorial takes approximately 15 minutes to complete.

Background

Oracle IoT Cloud Service provides communication services between devices and enterprise applications. Using an Open Services Gateway initiative (OSGi) framework like Apache Felix, an application can communicate with Oracle IoT Cloud Service.

In this tutorial, you:

• Build an application using the core libraries for the Apache Felix framework.
• Run an application that sends a message to Oracle IoT Cloud Service through a simulator device using the Apache Felix framework.

This tutorial assumes that you are familiar with OSGi.

What Do You Need?

• Access to an instance of the Oracle IoT Cloud Service
• A computer running Windows 7 or later, Apple macOS 10.9 or later, or Linux with a web browser and a recent version of Java Developer Kit (JDK) installed
• Completion of the following tutorial: Configuring an Application in Oracle Internet of Things Cloud Service tutorial to obtain the provisioning file
• The latest version of the Java SE Client Software Library from Oracle Technologies Network
• The latest version of the Apache Felix framework
• The HumiditySensor.json and TemperatureSensor.json files
• The SampleActivator.java file
• A REST client utility, such as RESTClient for Firefox or Advanced REST Client for Google Chrome
• Knowledge of Java, basic knowledge of command-line tools. For information on how to correctly configure your Java Environment, see Setting Up Your Java SE Development Environment to Use Oracle IoT Cloud Service Client Software Libraries

Install and Configure the Required Software

1. Download the latest version of the Java SE Client Software Library binary, source and sample files from the Oracle Technologies Network downloads page.
   The name of the zip files are iotcs-csl-javase-bin-release.zip, iotcs-cls-javase-src-release.zip and iotcs-csl-javase-samples-release.zip, where release is the release and version number.
2. Extract the iotcs-csl-javase-bin-release.zip, iotcs-cls-javase-src-release.zip and iotcs-csl-javase-samples-release.zip files.
   The following subdirectories are listed under the iotcs/csl/javase directory:
   • bin
   • lib
   • samples
   • src
   
   CL_HOME refers to the iotcs/csl/javase directory.
3. Download the latest version of the Apache Felix framework.
   The name of the file is org.apache.felix.main.distribution-release, where release is the release and version number.
4. Extract the org.apache.felix.main.distribution-release file.
   Apache_Felix_path refers to the Apache Felix installation directory.

Register Your Device Models

This tutorial uses JavaScript Object Notation (JSON) files to register your device models.

1. Download and save the HumiditySensor.json and TemperatureSensor.json JSON files that contain descriptions of your device models (links in the prerequisites section).
2. Open your REST client and use the following information to register the humidity sensor device model:
   • Method: POST
   • URL: Oracle_IoT_Cloud_Service_Instance:443/iot/api/v2/deviceModels
   • Headers: Content-Type:application/json
   • Body: Content of the HumiditySensor.json file
3. Use the following information to register the temperature sensor device model:
   • Method: POST
   • URL: Oracle_IoT_Cloud_Service_Instance:443/iot/api/v2/deviceModels
   • Headers: Content-Type:application/json
   • Body: Content of the TemperatureSensor.json file
4. On the Oracle IoT Cloud Service home page, click Action , select Devices and Model, and verify that your device models are registered correctly.

   

Run Your Application

1. Change directories to CL_HOME, edit the build.gradle file and locate the following line:

    def OSGI_IMPORT_PACKAGE = "javax.crypto,javax.crypto.spec,javax.net.ssl,org.json,javax.sql,org.apache.derby.jdbc"

   Then replace it with this line:

    def OSGI_IMPORT_PACKAGE = "javax.crypto,javax.crypto.spec,javax.net.ssl,org.json,javax.sql,org.apache.derby.jdbc,sun.net.www.protocol.https"

2. Open a command-line interface and change your directory to CL_HOME/samples.
3. Run the following command:

    gradle

4. In the CL_HOME/samples/src/main/java/com/oracle/iot/sample directory, save the SampleActivator.java file.
5. Change your directory to CL_HOME/samples.
6. Build the SampleActivator application.
   Command for Linux / macOS

   javac -d ./build/classes -cp Apache_Felix_path/bin/felix.jar:../lib/device-library.jar src/main/java/com/oracle/iot/sample/GatewayDeviceSample.java 
   src/main/java/com/oracle/iot/sample/SampleActivator.java 
   src/main/java/com/oracle/iot/sample/TemperatureSensor.java 
   src/main/java/com/oracle/iot/sample/HumiditySensor.java

   
   Command for Windows

   javac -d .\build\classes -cp Apache_Felix_path\bin\felix.jar;..\lib\device-library.jar 
   src\main\java\com\oracle\iot\sample\GatewayDeviceSample.java 
   src\main\java\com\oracle\iot\sample\SampleActivator.java 
   src\main\java\com\oracle\iot\sample\TemperatureSensor.java 
   src\main\java\com\oracle\iot\sample\HumiditySensor.java

   
   This command adds the .class files in the CL_HOME/samples/build/classes/com/oracle/iot/sample directory.
7. In the CL_HOME/samples directory, create a MANIFEST.MF file with the following content:

   Bundle-ManifestVersion: 2
   Bundle-Name: GatewayDevice Sample
   Bundle-SymbolicName: com.oracle.iot.sample
   Bundle-Version: 1.0.0
   Bundle-Activator: com.oracle.iot.sample.SampleActivator
   Import-Package: org.osgi.framework,oracle.iot.client.device,oracle.iot.client
   	
   

   
   Note: Make sure that there is a line break after the last line of the MANIFEST.MF file.
8. Create the bundle jar file.
   Command for Linux / macOS

   jar -cmf MANIFEST.MF osgi-sample.jar -C ./build/classes com

   
   Command for Windows

   jar -cmf MANIFEST.MF osgi-sample.jar -C .\build\classes com

9. Change your directory to Apache_Felix_path.
10. Copy the provisioning file your downloaded from the Oracle IoT Cloud Service into that directory.
11. Run the application using the Apache Felix framework:
    Command for Linux / macOS

     java -Dorg.osgi.framework.system.packages.extra=sun.net.www.protocol.https -Dsample.name=GatewayDeviceSample -Dsample.args="Activation_ID5 File_Protection_Password6" -jar bin/felix.jar

    
    Command for Windows

     java -Dorg.osgi.framework.system.packages.extra=sun.net.www.protocol.https -Dsample.name=GatewayDeviceSample -Dsample.args="Activation_ID5 File_Protection_Password6" -jar .\bin\felix.jar

12. Install the device library bundle, and then start your bundle.

    
    Welcome to Apache Felix Gogo
    g! install CL_HOME/lib/derby-10.11.1.1.jar
    Bundle ID: 
    g! install CL_HOME/lib/device-library.jar
    Bundle ID: 5
    g! install CL_HOME/lib/json-20160212.jar
    Bundle ID: 6
    g! install CL_HOME/samples/osgi-sample.jar
    Bundle ID: 7
    g! start 7
    Starting to listen for service events.
    Creating the gateway instance...
    Created virtural temperature sensor 0-2UJQ
    Created virtural humidity sensor 0-2YJQ
        Press enter to exit.
    Tue Aug 02 17:18:18 EDT 2016 : 0-2YJQ : Set : "humidity"=81,"maxThreshold"=90
    Tue Aug 02 17:18:17 EDT 2016 : 0-2UJQ : Set : "power"=true,"temp"=58.5,"unit"=°C,"minTemp"=58.5,"maxTemp"=58.5,"minThreshold"=0,"maxThreshold"=65
    

    
    Note: The bundle ID values may vary.
    Note: To stop the application, enter the stop command and the bundle ID of the osgi-sample.jar file.
    Command for Windows / Linux / macOS

    stop 7

Want to Learn More?

• Oracle Help Center
• Quick Start Tutorial Using a Java Application