Overview

Skill Level: Intermediate

Recipe expects skills on Edge Rule usage, Understanding of Edge Analytics concepts, Java

In this recipe, we are going to show how to use SDK for carrying out data filtering operation with Edge Analytics. We also describe the flow involved and provide sample SDK application to be used on any Edge Gateway device that supports Java Platform.

Ingredients

  • Hardware
    • Raspberry Pi 3
    • Arduino Uno (2 Numbers)
    • Arduino Base Groove Shields
    • Temperature Sensors
  • ¬†Software
    • BlueMix Account
    • IBM Watson IoT Service on BlueMix Account
    • Install JDK 1.8 on Raspberry Pi 3 referring to RpiBlog
    • Install Java RXTX Library in Raspberry Pi 3 for Serial Communication with Arduino Uno boards
    • Make ready the Arduino Uno devices with Sketch Program
  • Connectivity
    • Install Arduino Base Groove Shield on each of Arduino Uno
    • Attach temperature sensor to A0 pin on each of Arduino Uno
    • Connect each of Arduino Uno to Raspberry Pi using USB Cable
    • After connecting, make sure, we should see presence of devices /dev/ttyACM0 and /dev/ttyACM1 on Raspberry Pi 3

Step-by-step

  1. Introduction

    This recipe showcases how to use Edge SDK for Edge Analytics to write your own sample application to create, start Edge Analytics Agent and collect device events from attached devices using the File Connector.

    To know about IBM Edge Analytics concepts, refer to documentation on Edge Analytics.

    In this recipe, we are going to show

    • The flow involved in using SDK for Edge Analytics
    • Sample Java Application to collect device data from attached devices using the File Connector
    • Building and running SDK Java Sample for Edge Analytics
    • Creating and deploying an analytic rule to filter out unwanted data at the edge so it is not forwarded to Cloud
  2. Edge Analytics SDK

    The SDK is an Application Programming Interface (API) that allows you to implement your own code to enable your IOT devices to connect to Edge Analytics Agent. Once devices are connected, analytics can be applied against that device data triggering local actions, that you can define, as well, device data can be pushed to the Watson IOT Platform for further analytic processing. The Edge Analytics Agent will run an edge gateway device that supports the Java Platform. Below described are the steps involved in SDK usage flow for Edge Analytics:

    1. Get Gateway and Application Credentials from Watson IoT Platform.
    2. Create an instance of EdgeProperties Class.
    3. Create an instance of EdgeAnalyticsClient using the EdgeProperties instance.
    4. Get an instance for edge analytics agent using method EdgeAnalyticsClient.getAgent().
    5. Create instance(s) of attached devices that initialize the serial ports for communication and continuously get data from serial ports and then write into given file in chunks for further consumption by FileConnector.
    6. Start Edge Analytics Agent on Edge Gateway Device that internally establishes connection with Watson IoT Platform and runs indefinitely to get device data from the registered connectors.
    7. Register a File Connector that continuously monitors for a directory where device data from attached devices being dumped as files, reads file data and converts to JSON format, gives to agent to send device data to Watson IoT Platform.
    8. As the File Connector starts getting device data, we should be able to see the creation of attached devices on Watson IoT Platform and receive the device(s) data being sent to cloud.
    9. Define an Edge Rule to filter out device data based on condition and activate on Edge Gateway from Watson IoT Platform Dashboard.
    10. As Edge Rule gets activated on Edge Gateway, we should see only the device events passing the defined condition in Edge Rule being forwarded to cloud and rest are filtered out at the Edge Gateway itself.
    sdk_flw

    Below given is the picture that shows the devices setup that we are going to use as part of this recipe to build SDK Sample to carry out Data Filtering Activity using Edge SDK.

    rev_devs_setup

    These are the steps involved in making use of SDK for Edge Analytics. In next coming sections, we describe in detail writing Java Sample Application and building, executing the same for Edge Analytics.

  3. Write, Build and Run SDK Sample in Java

    In this section, we show the coding aspect for the SDK to collect and send device data using File Connector. First, we need SDK Jar to be available in our class path to write any application using the SDK. So, download the SDK Jar from the IBM Community Link and add to the class path.

    Here are the required SDK classes, import them:

    import com.ibm.iot.analytics.edgesdk.api.EdgeAnalyticsAgent;
    import com.ibm.iot.analytics.edgesdk.api.client.EdgeAnalyticsClient;
    import com.ibm.iot.analytics.edgesdk.api.client.EdgeProperties;
    import com.ibm.iot.analytics.edgesdk.api.connectors.StringConnector;
    import com.ibm.iot.analytics.edgesdk.api.connectors.file.FileConnector;
    import com.ibm.iot.analytics.edgesdk.api.connectors.transformers.string.JsonTransformer;

    We need some classes from RXTXcomm.jar for serial port communication. Install and copy Java RXTX Library and JAR into JAVA_HOME for Serial Communication with Arduino Uno board on Raspberry Pi 3:

    • sudo apt-get install librxtx-java
    • sudo¬† cp¬†¬† /usr/lib/jni/librxtxSerial.so¬†¬† $JAVA_HOME/jre/lib/arm
    • sudo¬† cp¬† /usr/share/java/RXTXcomm.jar¬†¬† $JAVA_HOME/jre/lib

    Here are the required RXTX classes for serial communication, import them:

    import gnu.io.CommPortIdentifier;
    import gnu.io.SerialPort;
    import gnu.io.SerialPortEvent;
    import gnu.io.SerialPortEventListener;

    We need Gateway Credentials and Application Credentials from Watson IoT Platform. Refer to Registering Gateway Recipe to create gateway and get credentials. Refer to Generate API Keys Section to get application credentials.

    Once we have required credentials from Watson IoT Platform, we define constants in our SDK sample to refer them:

    // Replace x's with actual values
    private final String ORG_ID = "xxxxxx";
    private final String APP_ID = "Edge_Sdk_Sample1_App_Id";
    private final String AUTH_KEY = "x-xxxxxx-xxxxxxxxxx";
    private final String AUTH_TOKEN = "xxxxxxxxxxxxxxxxxx";
    private final String GATEWAY_ID = "egDevice";
    private final String GATEWAY_TYPE = "egType";
    private final String GATEWAY_AUTH_TOKEN = "xxxxxxxxxx";

    Next, we create instance for EdgeProperties using the above obtained credentials, followed by EdgeAnalyticsClient instance and get edge agent:

    // Initialize EdgeProperties Instance
    edgeProps = new EdgeProperties(ORG_ID, APP_ID, AUTH_KEY, AUTH_TOKEN,GATEWAY_TYPE, GATEWAY_ID, GATEWAY_AUTH_TOKEN);

    // Create EdgeAnalyticsClient Instance using properties instance
    edgeAnalyticsClient = new EdgeAnalyticsClient(edgeProps);

    // Get Edge Analytics Agent
    eaa = edgeAnalyticsClient.getAgent();

    We define separate user defined class to represent each of the attached Arduino Uno devices to Raspberry Pi 3. Within the class, we put statements to initialize the separate serial port for each of the device and register a listener for the serial event. Listener continuously listens for coming serial events from Arduino Uno, buffers device events and writes to provided file. Now, we create 2 instances of attachedDevice class to represent 2 Arduino Uno devices connected to Raspberry Pi 3 at COM ports /dev/ttyACM0 and /dev/ttyACM1:

    // Create Instnaces for Attached Devices which inturn initialize
    // COM Ports for Serial Communication with actual attached devices
    dev1 = new attachedDevice(ATTACHED_DEV_1,COM_PORT_1,dev1FilePath);
    dev2 = new attachedDevice(ATTACHED_DEV_2,COM_PORT_2,dev2FilePath);

    Now, we reached to main entry Point to Edge Analytics Agent that’s get started and continuously collect devices data and send to Watson IoT Platform using File Connectors. Create SDK Sample instance which has member for Edge Analytics Agent and start it. Internally, it establishes connection with Watson IoT Platform, then we register FileConnector for each of attached device to collect and send device events stored in file:

    // Create an Instance for Edge SDK Sample
    EdgeSDKSample1 edgeApp = new EdgeSDKSample1();

    // Start edge analytics agent on gateway device.
    edgeApp.eaa.start();

    // Connector to read data from device-1 events text file
    final StringConnector dev1Connector = createJsonConnector(dev1DirPath);

    // Send dev1 data to WIoTP through agent
    edgeApp.eaa.deviceData(edgeApp.dev1.getDeviceName(), "sdkDevices", "eventType", dev1Connector);

    //Connector to read data from device-2 events text file
    final StringConnector dev2Connector = createJsonConnector(dev2DirPath);

    // Send dev2 data to WIoTP through agent
    edgeApp.eaa.deviceData(edgeApp.dev2.getDeviceName(), "sdkDevices", "eventType", dev2Connector);

    Within createJsonConnector Method, we create an instance for FileConnector, set Json transformer to convert file stream to Json Objects and a directory watcher to monitor for a given directory at an interval of 1 second to get newly dumped device data:

    //Connector to watch directory for new files and read the data for every 1 seconds
    private static StringConnector createJsonConnector(String dirPath) throws IOException {
    FileConnector connector = new FileConnector();
        connector.setTransformer(new JsonTransformer());
         connector.directoryWatcher(dirPath);
         connector.setPollPeriod(1, TimeUnit.SECONDS);
         return connector;
    }

    The started Edge Analytics Agent on Raspberry Pi 3 runs indefinitely and continuously keep collecting device data using the registered FileConnectors.

    Here is the link to our complete SDK Sample1 in Java to collect device data from 2 attached devices. Next, we see the steps to build our SDK Java Sample and run it to send devices data to Watson IoT Platform:

    • Let SDK Home be: export SDK_HOME=/home/pi/EAA-SDK
    • Let SDK Jar path be: export SDK_JAR_PATH=$SDK_HOME/edge-sdk-master.jar
    • Get IBM Edge SDK Jar from IBM Community Link
    • Place Edge SDK Jar into $SDK_HOME
    • Place SDK sample program into path¬† $SDK_HOME/edge-sdk/src/main/java/com/ibm/iot/analytics/edgesdk/samples
    • Go to samples path and run javac to compile the sample program
      • javac -cp $SDK_JAR_PATH EdgeSDKSample1.java
    • To execute the sample:
      • java -cp $SDK_JAR_PATH:$SDK_HOME/edge-sdk/src/main/java com.ibm.iot.analytics.edgesdk.samples.EdgeSDKSample1

    As we start executing the sample, we should see messages on console to indicate the connection established to Watson IoT Platform.

    sdk_app_exe

    Now, we move to Watson IoT Platform dashboard, we should see the gateway device status as connected and 2 new attached devices automatically getting created with the names as specified in SDK Sample.

    gway_status

    Next click on each of devices to see the device events continuously being sent to Watson IoT Platform.

     dev_events

     

    This concludes this section, in which, we described about writing SDK Sample, building and executing SDK Sample to connecting to Watson IoT Platform and send device data from attached devices.

  4. Working with Edge Rule for Data Filtering

    We have an earlier recipe on Edge Analytics using Cisco Platform, which has clear description on Defining Schema, Defining Edge Rule, Activating Edge Rule onto Gateway and Updating Edge Rule if required. Refer to the sections Setup Rules and Update Rules from our earlier recipe on Edge Analytics using Cisco Platform.

    In this section, we directly see the already defined Edge Rule to filter out device events that has temperature < 20 and send only the device events with temperature >= 20 to Cloud for further analytics, activate the rule onto Edge Gateway and observe the results on the platform for received device events.

    Here is the Edge Rule snapshot from the Watson IoT Platform, that we have already defined:

    sdk_df_rule

    Right now, the Edge Rule is inactive on the edge gateway. If we look at the devices page, we see all events from both devices getting sent to Cloud:

    dev1_temps
    dev2_temps

    To activate the edge rule on gateway, select the edge rule from Browse Rules and click on Manage Rule:

    select_edge_rule

    In the Edge Rule Gateways window, select Activate operation and click on submit command:

    activate_rule

    Activate submission notification appears, click on close:

    submit_notification

    After couple of seconds, we should see the edge rule is active on the gateway:

    rule_active

    Now, we if see the devices page on the dashboard, we should see only the device events with temperature >= 20 are being forwarded to cloud and rest of the events are filtered out at the edge gateway for both the attached devices.

    To get all the device events back to being sent to cloud, we need to deactivate the activated edge rule on gateway. Select the active rule -> Manage Rule -> Select Deactivate Operation -> Submit Command:

    deactivate_rule

    Click on Close for Deactivate submission notification. After couple of seconds, we see the edge rule state as Inactive.

     

    In this section, we have shown how to work with Edge Rule to filter out unwanted device data being sent to cloud by activating the edge rule on to edge gateway device.

  5. Conclusion

    This is the starting recipe in the series on Edge Analytics using SDK. We have demonstrated, how to,

    • Write our own Edge Analytics Agent code to collect device data from attached devices.
    • Work with Edge Rule on Watson IoT Platform dashboard to activate on to Edge Gateway for achieving data filtering feature
  6. What Next???

    We have couple of recipes on Edge Analytics using Cisco Platform to perform data filtering and handle alerts as part of edge rule:

    Here is link to recipe to handle alerts and device actions using SDK:

2 comments on"Getting started with the IBM Edge Analytics SDK in Watson IoT Platform"

  1. Angela Wrobel October 16, 2017

    Hi, I am trying to get this sample to run in my eclipse environment. I need some running code until Wednesday, for a very important customer demonstration. However, I do not find a main() in https://github.com/ibm-watson-iot/edge-analytics-samples/blob/master/edge-sdk/src/main/java/com/ibm/iot/analytics/edgesdk/samples/EdgeSDKSample1.java. Did I miss anything magic…? Can anybody point me to the main() function? That would be very helpful! Any code reading something from serial interface and doing Edge would be very much appreciated! Thank you!

    • Angela Wrobel October 17, 2017

      Sorry for the comment above… I should not post comments when I am in a hurry. My eclipse had raised launch error “Editor does not contain a main type”, and when I quickly browsed through the source, I didn’t see the main(). This morning, when I gave it a new try, it popped into my eyes… I’ll give it another try now… ūüėČ

Join The Discussion