Close

Cloud application

The cloud platform is provided by IBM. IBM Cloud is previously known as Bluemix. IBM Cloud provides dozens of readily available services, easy to integrate with your own application software, including APIs for Watson analytics, cognitive computing, and more. Many populer programming environments, including Node.js, Ruby, Python and Java.

Graphical Node-RED environment makes it easy for people with no background in programming to get started. Advanced users may prefer Docker containers, serverless programing with OpenWhisk, 

Getting started

Create user account

First, create your own IBM Id and free user account at IBM Cloud login page. This will create you a Lite plan with unlimited time period for evaluation but with limited capacity and services.

https://console.bluemix.net/

Active working e-mail address is needed for the purpose only. After verifying your email account, you get access to the dashboard. Take a while to browse around. Available services and build-packs are listed under Catalog menu.

If you already have existing IBM Cloud account, either free or commercial one, you may use that instead of creating a new one.

Upgrade the master account

Each team participating the Future City Challenge competition are supplied with two Promo / Feature codes; one to convert standard Lite account to Trial account, and another code to upgrade the Trial account enabling more features and extended evaluation period.

Each member of a team may have their own personal account in IBM Cloud. Only one account per team can be upgraded to  enable full power of IBM Cloud, that is considered as "master account" for the team. Codes can be applied only once, thus care must be taken not to loose the feature.

Both codes are applied the same way. Select Billing and usage -> Billing from the Manage menu in right-top corner of the dashboard of the IBM Cloud web user interface. In Feature and promo codes section, enter the given promo codes one by one.

1. Apply the code to convert the master account from Lite to Trial. This code is provided at paper slip with text "Convert IBM Cloud Lite to Trial"

2. Apply another code to upgrade the master account. This code is provided to the teams at paper slip together with Digita's LoRaWAN keys.

If you get "Server error", you may have tried to enter the codes in wrong order. Double check that you enter first the conversion code and after that the upgrade code.

Once the procedure is performed successfully, the master account should have 120 days evaluation with all services enabled and 4GB of RAM available for applications.

Non-upgraded Lite accounts have access to limited set of services and can run only one application at a time. Lite accounts are not time limited.

For beginners: Node-RED

In upgraded master account, the Node-RED is available as boilerplate template of it's own. In standard Lite account, Node-Red is only available as bundled with Watson IoT.

Under Catalog -> Boilerplates, there there is Node-RED starter (for Lite account it's Internet of Things Platform Starter, bundled with Watson IoT and Node-RED). Node-RED is web-based graphical editor a top of Node.js (javascript) programming language. Node-RED makes it easy to create applications by connecting different nodes of different functions with wires. A special node called function makes it possible to enter any Node.js (javascript) code into your program, and as such Node-RED does not limit the expression power of underlaying programming language. Node-RED is good starting point for anybody with no prior experience in web and cloud programming.

Documentation and introductory videos are available at Node-RED web site: https://nodered.org/There are plenty of other resources available in the internet, just do some google to get further help.

In the IBM Cloud Catalog, choose Internet of Things Platform Starter to create a new service with unique name and selected domain (data center location). Staging process (Starting) takes a while, and once it's finalised you're ready to begin programming with your new environment. 

When first time entering Node-RED (Visit App URL), you're requested to set username and password for the editor. It is important to choose your credentials with care, as the editor is accessible directly from the public internet, without login in to IBM Cloud first. Do not allow anyone to access your code editor, as that may cause significant harm.

Node-RED editor

The Node-RED editor has three segments: selection of nodes on the left, actual program in the middle, and info/debug print of the right. At the beginning, there is some sample code provided by IBM. You may safely delete any example code from the editor.

Create your program by drag-and-drop nodes from left to the center, and connected them with wires. Activate your changes by clicking Deploy button in right top corner. Always remember to deploy your changes, otherwise your code does not get executed.

Receive data

In order to receive data from Digita's IoT network, you need to create a Node-RED flow as shown below.

Node-RED flow to receive data

Configure Watson IoT

IBM IoT node receives data from Watson IoT platform, which is the route from IoT device to Cloud. Configure the IBM IoT node as follows:

FCC-NodeRED-ibmiot-node.png

Device Id is the Hardware EUI of your device, with 16 characters [0..9][A..F].

In API Key, select Add new ibmiot... and click the pen symbol to edit credentials.

FCC-NodeRED-ibmiot-credentials.png

Credentials:
API Key:     a-nnoy6b-ljuzwbyzht
API Token:   hqijcDFWB9H?l?fgQq
Server-Name: nnoy6b.messaging.internetofthings.ibmcloud.com

 

Once the IBM IoT node is properly configured and changes deployed, all the data from your device received by Digita's network will appear in this node. Note that the data is individually encrypted, and next you need to decrypt your data.

Install crypto nodes

Crypto nodes are not included in the Node-RED editor by default, thus first it needs to be installed using Manage palette menu item in top-right corner. In Palette tab, install module:

node-red-contrib-crypto-js

More information at the project npm web site: https://www.npmjs.com/package/node-red-contrib-crypto-js

After succesfull installation, you get set of new crypto nodes in Function nodes menu.

FCC-NodeRED-crypto-nodes.png

In order to decrypt your data, choose decrypt node, select AES and enter the Device Address DevAddr of your board as the Secret key. DevAddr, which is 8 characters long [0..9][A..F], is unique to all devices in the same network, and is used here as the encryption key for your own data.

FCC-NodeRED-decrypt-node.png

After decrypt, the data in in stringified format. Put it through json node to get it in Object format for further access.

Finally in the debug windows you may see the complete received data in JSON format, where payload_hex is the actual data you transmitted from the device.

FCC-NodeRED-received-data.png

LrrRSSI stands for Received Signal Strength Indicator, given in dBmW. Bigger is better and -120..-130 dBm is the typical lower limit for reception. LrrSNR stands for Signal to Noise Ratio, a quality indicator telling where the signal level is compared to noise floor.

Lrrid is identifier of the LoRa gateway which received the data with highest signal strength (RSSI). LrrLAT and LrrLON are the coordinates of the gateway. Lrrs gives list of other gateways which did received the data simultaneously. Signal strength is given but no gateway coordinates. 

Receive data

Payload data coming from LoRa Network Server is hex encoded, as the name 'payload_hex' indicates. In order to use the data, it needs to be coverted into usable number. Assuming the data consist JSON formatted structure or plain single number, following code can be used inside function node:

msg.payload.data = JSON.parse(new Buffer(msg.payload.payload_hex,'hex').toString());

If data is ascii string like 'hello world', then left the JSON.parse function away. 

FCC_payload_hex.png

FCC_payload_hex_code.png

Above Node-RED example is available below. Copy-paste the code to Node-RED -> Menu -> Import -> Clipboard

[{"id":"b19b0774.20b988","type":"ibmiot in","z":"a4a9ae34.36629","authentication":"apiKey","apiKey":"95682d97.a084","inputType":"evt","deviceId":"0004A30B001A5777","applicationId":"","deviceType":"LoRaWAN","eventType":"data","commandType":"","format":"buffer","name":"IBM IoT","service":"registered","allDevices":false,"allApplications":"","allDeviceTypes":true,"allEvents":true,"allCommands":"","allFormats":true,"qos":0,"x":140,"y":133,"wires":[["55b0506e.25389"]]},{"id":"139b5938.0c9c47","type":"debug","z":"a4a9ae34.36629","name":"DECODED DATA","active":true,"console":"false","complete":"payload","x":550,"y":220,"wires":[]},{"id":"55b0506e.25389","type":"decrypt","z":"a4a9ae34.36629","name":"","algorithm":"AES","key":"75317531","x":295,"y":133,"wires":[["efd259e0.9707f8"]]},{"id":"efd259e0.9707f8","type":"json","z":"a4a9ae34.36629","name":"","pretty":false,"x":457,"y":133,"wires":[["ef39c1ad.e634c"]]},{"id":"ef39c1ad.e634c","type":"function","z":"a4a9ae34.36629","name":"payload_hex","func":"msg.payload.data = JSON.parse(new Buffer(msg.payload.payload_hex,'hex').toString());\nreturn msg;","outputs":1,"noerr":0,"x":330,"y":220,"wires":[["139b5938.0c9c47"]]},{"id":"95682d97.a084","type":"ibmiot","z":"","name":"FCC Watson IoT","keepalive":"60","serverName":"nnoy6b.messaging.internetofthings.ibmcloud.com","cleansession":true,"appId":"","shared":false}]

Remember to set the Watson IoT credentials as instructed earlier.

Advanced user: Node.js

Easiest way the get started with Node.js programming is creating application with Node.js with Cloudant DB Web starter boilerplate.

Note that Lite plan in IBM Cloud does not allow running Node-RED and Node.js applications simultaneously in the same account. If you already created Node-RED application, you need to delete it prior creating Node.js application, or alternatively acquire commercial account.