Integrating your mobile device to Cumulocity using Node-RED - Part1

Introduction

This series of blogs lets you get a taste of managing an IoT environment using the Cumulocity platform by integrating a device using Node-RED. In this series you will:

Part1: Register your mobile device as a managed object in Cumulocity
Part2: Register your device to receive control operations and send measurements to Cumulocity
Part3: Create a custom widget on Cumulocity to leverage the capabilities of our mobile devices

The Cumulocity platform

Cumulocity is a leading independent Device and Application Management Internet of Things (IoT) Platform. It connects and manages your machines, devices and sensors and gives you insight in its operations. It does this in een open way: it provides an API for your devices to connect to the platform. And of course it comes packaged with a lot of predefined devices.

To follow the steps in this post, you will need a Cumulocity account. If you don’t have one, you can create a free 30-day trial on cumulocity.com

Node-red

Node-red is a programming tool for wiring together hardware devices, APIs and online services in new and interesting ways. It provides a browser-based editor that makes it easy to wire together flows using the wide range of nodes in the palette that can be deployed to its run-time in a single-click. As such it is an ideal tool to begin a journey into IoT and to connect your devices.

i8c’s Node-red library for Cumulocity

We created a palette for Node-RED. It incorporates the most used Cumulocity API functionalities. This allows you to set-up a Node-RED gateway or device and connect to Cumulocity more quickly. You can find the i8c Node-RED palette for Cumulocity on our Git page or directly on npm.

Turning your mobile phone into a connected device

STEP1. Setting up your phone

This setup is limited to Android devices. (on the iOS platform it seems to be more difficult to run a node-js instance).

If we want to run Node-RED, we will need a node-js server on our mobile phone. We’ll be using Termux for this.

You can simply install Termux and Termux-API from the Playstore. If you don’t have a google account, you can install it manually (follow the installation guidelines on the Termux page). Once installed, start up the Termux app. Next install node-js. Type the following in the Termux command-line:

apt update
apt upgrade
apt install coreutils nano nodejs
pkg install termux-api

Now we can install the Node-RED package:

npm i -g --unsafe-perm node-red

Next start Node-RED

node-red

STEP2. Install i8c’s Cumulocity palette

Once Node-RED is running, we can access it through the browser on port 1880.

http://[your device's ip address]:1880

This will open the Node-RED GUI. Then open the drop-down in the upper-right corner and select “manage palette” and select “install”. Now search for the node-red-contrib-i8c-cumulocity package and install it.

If your not able to install it through the GUI, you can manually install it by running following command in the Termux command-line:

npm install node-red-contrib-i8c-cumulocity

Once the package is installed you should have the Cumulocity nodes available in your palette:

You will see 2 sections: “cumulocity api” and “cumulocity base”. The nodes in the api section are related to a single api call to the Cumulocity API, whereas the base sections contains nodes that offer more high-level functionality that combines multiple calls.

To use the Termux functionality from within Node-RED, also install following packages in Node-RED:

node-red-contrib-termux-api

STEP3. Registering your device

You can find the source of these flows on our Git page under examples.

We start our first flow with an inject node to start our flow. Set it to inject at startup if you want the device to be registered on startup. To do the registration, we will be using the “check and register” node from the Cumulocity base palette. This node requires some input:

Create tenant configuration

First of all we will create our tenant configuration. This configuration item contains our connection information and can be reused throughout the flows. So click on the edit button next to the “Tenant” property. In the next window you need to fill in your credentials and url of your tenant. We can now set the other properties. We will set the DeviceIdType as “i8c_DeviceId” on the input properties, the rest of the input will come from the msg object.

Extract device information

Next we can extract some information from our device. In this case we used a mix of Termux-API and plain terminal commands to put the information on the msg object (deviceId and other information that comes in the managedObject). For clarity, we have can put this logic in a subflow. Next we call a template which contains the structure of the managedObject and fills in the variables.

Call the registration node and test

Now we’re ready to call the “register device” node. To test our flow, we launch the flow by deploying (or pressing the inject node if you haven’t enabled the run once feature).

You will see that the node outputs the managedObjectId. Success! Our device is registered, so check the Cumulocity Device Registration page to view your device.

Now that the management platform knows our device, let us do some neat stuff with it, so make sure you check out part 2 of this series.

Author: Stefan De Wandeleir