Cumulocity

From Wiki for Dragino Project
Jump to: navigation, search

Introduction

Cumulocity is an open, application centric, cloud-enabled, free to try M2M solution. It is simple, fast and profitable. Cumulocity is now supported in Yun firmware since ver v1.1. With this new added feature, user is able to connect sensor project to Cumulocity in in a fast, friendly way.

This page introduce how to use MS14 with Cumulocity service.



Set up account

  • To use Cumulocity service, one has to sign up an accouny at Cumulocity first.
  • To link MS14 device to the account, open MS14 web --> sensor page and input the account info as below:
    • SEVER TYPE: Choose Cumulocity
    • TENANT: Your Tenant ID. As decribe in THIS LINK. For example, if your cumulocity panel is like: https://dragino.cumulocity.com. then your Tenant ID is dragino.
    • USERNAME: Your account's user in cumulocity.
    • PASSWORD: Your account's password in cumulocity.
    • APIKEY: Your Application Key Leave this to blank if you don't have a specify application.
    • DEVICENAME: Device name display in Cumulocity.
    • GLOBALID: Will display once the device is registered successfully.
set up ms14 to use cumulocity service

Note: every account can create mutliply devices in Cumulocity.


Use cumulocity.lua script

To communicate with Cumulocity, one can call the functions from cumulocity.lua script. This script locates on /usr/lib/lua/dragino/iot . This script can either be called in MS14 via SSH access or in mega32u4 via the Arduino Process library.

Below is the usage of this script via SSH access:

Append types command: -a

Append measurement types. Usage:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -a typestring

Used to append measurement types in Cumulocity, Valid measurement types name includes: all alphanumeric characters,space and _

  Example: lua /usr/lib/lua/dragino/iot/cumulocity.lua -a "Temperature Sensor,Motion Sensor"

Note:

    • The measurements will NOT shown in Cumulocity Web UI if there is no measurements.
    • This command is append mode. Replace mode of this command is -u


Clear Alarm command: -ca

clear alarm by alarmID, or clear all alarm from self device if alarmID is not set. Usage:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -ca [AlarmID] ;

Example: Clear Alarm 18800

lua /usr/lib/lua/dragino/iot/cumulocity.lua -ca 18800 ;


Delete command: -d

Delete this device from Cumulocity. Usage:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -d


Register command: -g

This command will register this device and get Global ID from Cumulocity. Usage:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -g

Every MS14 has a unique WiFi MAC address which acts as an external identify on Cumulocity. When running -g command, it will first check if this MAC is already registered in Cumulocity. If it is registered, ms14 will get its Global ID from Cumulocity and store for further process. If the MAC is not registered, MS14 will create a device in Cumulocity and link itself to the Global ID of this new created device.


Get Alarm command: -ga

Get Alarm ID by alarm type from a device which have the same Global ID. If Global ID is set to 0, set the alarm to self device. Usage:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -ga GlobalID Type

Example:get Overheated alarm status from device 14200

lua /usr/lib/lua/dragino/iot/cumulocity.lua -ga 14200 Overheated



HELP command: -h

Print help Usage:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -h


Post measurements command: -p

Post measurement(s). Usage:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -p sensorvalue

Used to post measurements to Cumulocity, The sensor value format should follow this link: http://www.cumulocity.com/guides/reference-guide/measurements?lang=en

Single sensor example:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -p '"Temperature Sensor": { "T": { "value": 35, "unit": "C" }}'

Multi sensor example:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -p '"Pressure Measurement": { "Point": { "value":1, "unit": "Pa" }},"Temperature Sensor": { "T": { "value": 35, "unit": "C" }}'



Set Alarm command: -sa

send an alarm to a device which have the same Global ID. If Global ID is set to 0, set the alarm to self device. Usage:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -sa GlobalID Type

Example: set an Overheated to self-device.

lua /usr/lib/lua/dragino/iot/cumulocity.lua -sa 0 Overheated



Update types command: -u

Update measurement types. Usage:

lua /usr/lib/lua/dragino/iot/cumulocity.lua -u typestring

Used to update measurement types in Cumulocity, Valid measurement types name includes: all alphanumeric characters,space and _

 Example: lua /usr/lib/lua/dragino/iot/cumulocity.lua -u "Temperature Sensor,Motion Sensor"

Note:

    • The measurements graph will NOT shown in Cumulocity Web UI if there is no measurements.
    • This command is replace mode. append mode of this command is -a




Example: Upload sensor data to Cumulocity

Upload Sensor Data to Cumulocity

Use Arduino IDE to program M32 with below code.and click serial monitor to start the Sketch.

Make sure you have Internet connection for your MS14 and you should see the device is created in Cumulocity automatically and get measurements plots after a while.

Get Source Code

/*
 Cumulocity client demo.  
 
 This sketch do below task:
 1) Check if the device is registed in Cumulocity, if not, create a device;if yes, get the device ID from Cumulocity
 and store it in MS14
 2) Set up measurement types in Cumulocity.
 3) Update measurements from different sensors. 
 
 Below firmware/hardware are required to run this sketch:
 1) hardware MS14-S and M32
 2) firmware on MS14-S: Yun firmware RC1.1
 
 Created 10, Feb, 2014
 by Dragino Technology Co., Limited
 
 Reference Link:
 
 */
 
// include all Libraries needed:
#include <Process.h>
 
// set up net client info:
const unsigned long postingInterval = 60000;  //delay between updates to cumulocity.com
unsigned long lastRequest = 0;      // when you last made a request
String dataString = "";
 
void setup() {
  // start serial port: 
  Bridge.begin();
  Console.begin();
 
  while(!Console);    // wait for Network Serial to open
  Console.println("Cumulocity client");
 
  registerDevice();
  setMeasurementTypes();
  lastRequest = millis();
}
 
void loop() {
  // get a timestamp so you can calculate reading and sending intervals:
  long now = millis();
 
  // if the sending interval has passed since your
  // last connection, then connect again and send data:
  if (now - lastRequest >= postingInterval) {
    updateData();
    lastRequest = now;
  }
}
 
 
//Post measurements to Cumulocity
void updateData() {
  // Send this command to MS14
  // lua /usr/lib/lua/dragino/iot/cumulocity.lua -p string
    //Single sensor example :  -p '"Customize Measurement": { "Point": { "value": 200, "unit": "ml" }}'
    //Multi sensor example : -p '"Customize Measurement": { "Point": { "value": 200, "unit": "ml" }},"TemperatureSensor": { "T": { "value": 35, "unit": "C" }}'
 
  // convert the readings to a String to send it:
  dataString = "\"Temperature Sensor\":{\"T\":{\"value\":";
  dataString += random(10) + 20;
  dataString += ",\"unit\":\"C\"}},";
  // add pressure:
  dataString += "\"Pressure Sensor\":{\"P\":{\"value\":";
  dataString += random(5) + 100;
  dataString += ",\"unit\":\"Pa\"}}";
 
  Process cumulocity;
  Console.print("\n\nPost Measurements... ");
  cumulocity.begin("lua");
  cumulocity.addParameter("/usr/lib/lua/dragino/iot/cumulocity.lua");
  cumulocity.addParameter("-p");
  cumulocity.addParameter(dataString);
  cumulocity.run();
  Console.println("done!");
 
  // Get return info
  while (cumulocity.available()>0) {
    char c = cumulocity.read();
    Console.write(c);
  }
}
 
// Registered this device on Cumulocity
void registerDevice() {
 
  // Send this command to MS14
  // lua /usr/lib/lua/dragino/iot/cumulocity.lua -g
  Process cumulocity;
  Console.print("\n\nRegister Device... ");
  cumulocity.begin("lua");
  cumulocity.addParameter("/usr/lib/lua/dragino/iot/cumulocity.lua");
  cumulocity.addParameter("-g");
  cumulocity.run();
  Console.println("done!");
 
  // Get return info
  while (cumulocity.available()>0) {
    char c = cumulocity.read();
    Console.write(c);
  }
 
}
 
// Setup measurement types
void setMeasurementTypes() {
 
  // Send this command to MS14
  // lua /usr/lib/lua/dragino/iot/cumulocity.lua -u "Temperature Sensor,Pressure Sensor"
  Process cumulocity;
  Console.print("\n\nSetup measurement types... ");
  cumulocity.begin("lua");
  cumulocity.addParameter("/usr/lib/lua/dragino/iot/cumulocity.lua");
  cumulocity.addParameter("-u");
  cumulocity.addParameter("\"Temperature Sensor,Pressure Sensor\"");
  cumulocity.run();
  Console.println("   done!");
 
  // Get return info
  while (cumulocity.available()>0) {
    char c = cumulocity.read();
    Console.write(c);
  }
 
}
MS14 is created in Cumulocity
Measurement Result



Example 2: Set and get an alarm

Overview

In this example, we will show how to use MS14-S to send an Alarm to Cumulocity. and show how to get this alarm from Cumulocity and displace on an OLED. we can also see how to use a button to clear this alarm.


Preparation

  • Both MS14-S has the latest Yun firmware RC1.2 installed
  • Both MS14-S has internet connection and has the correct Cumulocity account.


Test Setup

Connect Temperature and Humidity Sensor to ms14-s
Connect OLED and touch Sensor to ms14-s


Sketches and features

Sketch for Device 1 can be found in Temperature_Humidity_to_Cumulocity.ino. This sketch includes below features:

  • MS14 keep getting Temperature and Humidity info and send to Cumulocity every minute.
  • Once the temperature is higher than 40 degree. MS14 will send an Overheated alarm to Cumulocity.

Sketch for Device 2 can be found in OLED_128x64_Cumulocity_Show_Alarms.ino

  • MS14 check the Overheated Alarm status for Device 1 and show in OLED every minute.
  • If there is Overheated alarm. User can press the touch button and clear the Overheated Alarm for Device 1.

Note: user need to change the monitor Global ID to the correct ID for Device 1 in below line:

void isOverheated() {
...
cumulocity.addParameter("14200"); // Change this number to the monitored Global ID


Result

Overheated Alarm shown in Cumulocity User Panel
Overheated Alarm shown in OLED



Debug Option

There are three debug level which can be used to debug the communication between Dragino and Cumulocity.

  • Level 0: Disable Debug
  • Level 1: show REST body and return code.
  • Level 2: show REST body , return code and return HTML (return HTML only can be view via SSH debug).


If the cumulocity.lua is call in SSH, the debug info will shown in the console. If the cumulocity.lua is call in avr, the debug info will be used as the return string to avr and can be shown in Arduino Serial Console using below code in the Process call :

  while (cumulocity.available()>0) {
    char c = cumulocity.read();
    Console.write(c);
Show debug info in Arduino IDE Serial Console




Cumulocity.lua Version Log

v1.1

Loaded in Yun Firmware RC1.2

  • add command -ca
  • add command -ga
  • add command -sa
  • Set debug level and polish debug info,

v1.0

  • Initiate Release: Support Command:
    • Register command: -g
    • Delete command: -d
    • Update types command: -u
    • Append types command: -a
    • Post measurements command: -p
    • HELP command: -h