How-To - Build Cisco Kinetic Data Control Module Demo

Introduction

In this document we describe how to demo Cisco Kinetic  - DCM component. It will always be helpful to refer to the Help Docs for User Guide and www.ciscokinetic.com for Marketing materials.  And this Getting Started FAQ is a good starting point.

DCM Demo Video(as of Dec 2017)  https://cisco.box.com/s/levuzewl0m08r8fsrurc7yhkm6u4hf2i

Demo Overview

We will show the following capabilities using the Gateway and RaspberryPi with Sensehat module acting as the target device or sensor. 

1. Onboard a GW with Zero Touch Provisioning from Cisco Kinetic GMM
2. Install App on the GW from the Cisco Kinetic DCM
3. Configure Rules on the Edge App from DCM
4. Configure Policy to Route the data from devices / sensor behind the GW to right applications outside Cisco Kinetic cloud
5. Visualize using Freeboard 

Suggested Demo Steps (Should be < 30 mins)

1. Unbox a Cisco Kinetic Imaged Gateway
2. Insert SIM Or Connect to Ethernet
3. Power On
4. Claim the GW
5. Connect Sensor (Raspberry Pi here) (We support Serial Devices also, reach out to Product Team for help)
6. Install App
7. Configure App
8. Show data in Visualization

Requirements

Cisco Kinetic

1. Account in Cisco Kinetic cloud - Read FAQ http://go2.cisco.com/kinetic

Hardware

2. Cisco IR 8x9 - IR809 or IR829 Imaged for Cisco Kinetic 
3. Raspberry Pi + Sensehat Module

Software

4. Download Example IOX Application 
5. Download Binary to run on the Raspberry Pi

Setup

Gateway

1. Image the GW to run a support IOS/IOX version and required configurations - See here to image the GW and here to onboard  
2. Connect the Cisco IR8x9 via ethernet or cellular to the internet. See here for network and firewall related requirements

RaspberryPi

Install raspbian image on Pi (https://www.raspberrypi.org/downloads/raspbian/)

Once the Pi is ready and it boots up, do the following 

Default User/Password : pi/raspberry

You may need to connect the RPi to HDMI Monitor / Keyboard or access it over ssh to perform this operation. And follow README instructions to install it. If you hit issues, it may be due to time or package sources are invalid.

sudo apt-get update

sudo apt-get install python-dev -y to bring in some required header files like Python.h. 

Copy over the binaries (Binary to run on the Raspberry Pi) to raspberry Pi

If you have copied over the unzipped contents to /home/pi/Pi-sensehat/

Then run "pip install -r requirements.txt" under this directory.

This will bring in more libraries required and make take 10-15 mins to get it installed.

Then start the app as follows, If your setup is under the following path,

/home/pi/Pi-sensehat/sensehat-app> python app.py

On a browser open the URL http://<IP of PI>:5000/sensehat/ping

You should see a response JSON to indicate its all OK. And also the sensehat will blink the LEDs everytime you open this URL (hit refresh)

Connect RPi + Sensehat module via Ethernet to the Gateway (use GE 1) or over WiFi if using IR829 with WiFi Enabled. If using WiFi attach Pi to a battery pack and it is easier to demo.

At this point, if you have onboarded the GW via Claim Process you should see your org in Kinetic as follows, where the GW is Up and Healthy.

Then Click on the GW Name and you should see the following, where "App Management Health" is also Healthy. Sometime it takes a few mins before it goes Green.  Please wait for it to be Green.

If you have the RPi connected to GE1 (on IR8x9) or other ports on IR829, you should be able to discover them under "Devices Tab". 

Restarting a Pi forces it to fetch an IP faster over DHCP.

Add the discovered device using "Add as New Device". Name it "assetpi" to reuse the existing Rules that comes by default. 

Fog App Management

See Import Fog Apps section here Upload Sample IOX Application to Cisco Kinetic. The Sample IOX App is here Click Download

This App is built to talk to RPi and collect sensor values from Sensehat and publish it up. The App is built using Cisco Kinetic SDK, that provides the following features,

1. Rule Engine (same Rule Engine runs in the Cloud also. Same Rules can be applied on the Cloud and/or Edge).
2. Batching & Compression
3. MQTT Helper to publish data and subscribe to commands
4. Parser Helper to read from package_config.ini to configure the App Specific Params

This App can take Rules from Cisco Kinetic cloud and apply it on the data being published by the Application on the Gateway. This helps with

1. Edge Data Filtering for Thresholds
2. Bandwidth Reduction - by batching and compressing them
3. Do some transformations at edge, for example Degree C to Degree F before it is sent to the cloud
4. Publish part of the Data to the cloud for security or policy reasons

Install the App on the GW. See Install Fog Apps on a Gateway here

While installing you need to configure the following,

1. IP of the Raspberry Pi (This App does not discover the Pi.) Update the IP from Devices section here in the field "device1_ip".

2. Edit Rules (optional). 

3. Leave the "Profile" as "Medium"

Once the App is installed and it is running, verify the following using the Log Files.

Choose your GW where the App is running and click on the "Logs" icon. This opens up a viewer. Pick the following log file in the drop down list - "Multi-Devices.log.0"

The log file content as follows indicates successful install and data publish, (scroll down all the way in the app log )

Dec 19, 2017 11:15:59 PM com.cisco.iot.swp.edge.mqtt.client.MQTTClientEdgeSSL getMqttSSLClient INFO: msg='Using default memory persistence. Trying to connect to us.iotspprod.io:8883 for gateway 266'
Dec 19, 2017 11:16:06 PM com.cisco.iot.swp.edge.app.RESampleApp$2 connectComplete INFO: Reconnection status=false, serverURI=ssl://dcm-bmx-eu-ir.iotspprod.io:8883
Dec 19, 2017 11:16:06 PM com.cisco.iot.swp.edge.mqtt.client.MQTTClientEdgeSSL getMQTTClient INFO: msg='Connection to mqtt broker successful'
Dec 19, 2017 11:16:06 PM com.cisco.iot.swp.edge.app.RESampleApp main INFO: Done Initializing the IOTDC client
Dec 19, 2017 11:16:06 PM com.cisco.iot.swp.edge.app.RESampleApp subscribe INFO: Subscribing to topic : /v1/266:99037/json/app2dev/
Dec 19, 2017 11:16:06 PM com.cisco.iot.swp.edge.app.RESampleApp startSpecialMessageMonitoring INFO: Starting Special Message Monitoring Thread
Dec 19, 2017 11:16:08 PM com.cisco.iot.swp.edge.app.RESampleApp startSpecialMessageMonitoring INFO: java.util.concurrent.Executors$DelegatedScheduledExecutorService@1184ab05:com.cisco.iot.swp.edge.app.RESampleApp$$Lambda$3/1863932867@3aefe5e5:30:SECONDS
Dec 19, 2017 11:16:08 PM com.cisco.iot.swp.edge.app.RESampleApp main INFO: Start processing the data obtained using HTTP client....
Dec 19, 2017 11:16:09 PM com.cisco.iot.swp.edge.app.RESampleApp initHTTPClient INFO: Done Intializing HTTP client and request URIs
Dec 19, 2017 11:16:09 PM com.cisco.iot.swp.edge.app.RESampleApp initHTTPClientPost INFO: Http Post to sensehat display at URL http://10.8.168.180:5000/sensehat/display
Dec 19, 2017 11:16:09 PM com.cisco.iot.swp.edge.app.RESampleApp$3 run INFO: Special thread for posting commands created.
Dec 19, 2017 11:16:10 PM com.cisco.iot.swp.edge.app.RESampleApp sendMessageUpstream INFO: Publishing RE Message : {"assetpi":{"temperature":33.72954559326172,"ts":1513725369665}} -> /v1/266/json/dev2app/alertTemp
Dec 19, 2017 11:16:11 PM com.cisco.iot.swp.edge.app.RESampleApp sendMessageUpstream INFO: Publishing RE Message : {"assetpi":{"pressure":0,"gyroscope":{"pitch":7.741433735488124,"yaw":247.06742562133974,"roll":13.355270374706448},"magnetometer":{"y":48.439205169677734,"z":-6.579616069793701,"x":-21.426435470581055},"temperature":33.787498474121094,"humidity":17.29914093017578,"accelerometer":{"pitch":7.622635401480447,"roll":13.351842473516747,"yaw":247.06550633818298},"ts":1513725371422}} -> /v1/266/json/dev2app/alertTemp
Dec 19, 2017 11:16:13 PM com.cisco.iot.swp.edge.app.RESampleApp sendMessageUpstream INFO: Publishing RE Message : {"assetpi":{"pressure":1025.419921875,"gyroscope":{"pitch":7.694316529272438,"yaw":246.4411655763413,"roll":13.461681306880662},"magnetometer":{"y":142.6819305419922,"z":-20.019630432128906,"x":-63.03170394897461},"temperature":33.82613754272461,"humidity":21.571613311767578,"accelerometer":{"pitch":7.832305987300559,"roll":13.366739969870192,"yaw":246.49926999561058},"ts":1513725372886}} -> /v1/266/json/dev2app/alertTemp
Dec 19, 2017 11:16:14 PM com.cisco.iot.swp.edge.app.RESampleApp sendMessageUpstream INFO: Publishing RE Message : {"assetpi":

 API Keys

Generate API Keys for your organization. Always use API Keys for APIs / Data Extraction. This will make it easier to share demo / data / APIs with partners who need not have access to the Cisco Kinetic Cloud Web App.

Check Data Management (Read/Write) to generate the API Key.

For example if your GW is under org "Demo" you should choose the org "Demo" before generating the key.

Read more about API Keys in the User Guide.

Copy the Key and Store it.

Username is the part before '.'

Password is the part after '.'

 AMQP Integration Script

A way to extract data from DCM is via a simple script, that uses the same set of parameters as above. AMQP script is an example here. The data may go over MQTT to IBM or over AMQP 1.0 to Azure or to a private data center over AMQP 0.9-1. It depends on deployment and use case scenarios. To test the theory out if the data from the app is aggregated by DCM, test it as follows.

Run this as 

python amqp.py -r < us or eu >.ciscokinetic.io -e <orgid>-EXC -u 'APIKey before . ' -P 'API Key after. '

 Fetch orgid from your account - it is the number at the end of the URL https://us.ciscokinetic.io/organizations/<org id number>

Or from the field "Observations Exchange Name" in the "Internal Broker" details of

Data Destinations

This script requires python pika library installed. "sudo pip install pika"

Download the cert.crt file into the same folder as amqp.py

(See attachments)

This script subscribes to the exchange on a particular cluster using user name and password. As the Fog App publishes data from the edge, it is aggregated by the Cisco Kinetic cloud and made available via an exchange using AMQP 0.9.1 protocol.

You should see output as follows (varies depending on the messages being sent by the Fog App)

localhost > python amqp.py -r < us or eu >.ciscokinetic.io -e orgid-EXC -u 'APIKey before . ' -P 'API Key after. '

INFO:pika.adapters.base_connection:Connecting to 52.212.193.126:5671 with SSL

INFO:pika.adapters.blocking_connection:Created channel=1

 [*] Waiting for data [tags: None]. To exit press CTRL+C

 [x] rk: dev2app, headers: {'route_version': u'v1', 'route': u'/v1/348:101136/json/dev2app/', 'message_direction': u'dev2app', 'deviceId': u'101136', 'content_type': u'json', 'gatewayId': u'348', 'observation_receive_ts': u'1513979607439', 'accountId': u'16', 'device_id': u'101136'}, msg: {"Data": {"Auto": {"Color": null, "Model": "XC90", "Ticket": {"Date": "10/9/2014", "City": "Anyuan", "Misc": null}}, "id": 2012}}, ts: 2017-12-22T13:53:32

 [x] rk: dev2app, headers: {'route_version': u'v1', 'route': u'/v1/348:101136/json/dev2app/', 'message_direction': u'dev2app', 'deviceId': u'101136', 'content_type': u'json', 'gatewayId': u'348', 'observation_receive_ts': u'1513979610467', 'accountId': u'16', 'device_id': u'101136'}, msg: {"Data": {"Auto": {"Color": "Teal", "Model": "LS", "Ticket": {"Date": "9/5/2015", "City": "Araguari", "Misc": null}}, "id": 1999}}, ts: 2017-12-22T13:53:34

 [x] rk: dev2app, headers: {'route_version': u'v1', 'route': u'/v1/348:101136/json/dev2app/', 'message_direction': u'dev2app', 'deviceId': u'101136', 'content_type': u'json', 'gatewayId': u'348', 'observation_receive_ts': u'1513979612452', 'accountId': u'16', 'device_id': u'101136'}, msg: {"Data": {"Auto": {"Color": "Aquamarine", "Model": "S40", "Ticket": {"Date": "11/21/2015", "City": "Akhm\u012bm", "Misc": null}}, "id": 2003}}, ts: 2017-12-22T13:53:36