Getting Started with IBM® IoTF - #1: Data Publish

This article is the first in a series on IBM® Internet of Things Foundation (IoTF). It teaches you how to develop an Internet of Things (IoT) application in IBM® Bluemix.

In this tutorial, you are going to develop a simple Weather Monitoring IoT application. As the figure below shows, this IoT application will sense temperature and humidity data and publish it to IoTF using the MQTT protocol.

Learning Objectives

At the end of this tutorial you will be able to:

• Design an IoT device that senses temperature and humidity
• Create an IoT application and add services in Bluemix
• Setup device type and devices in IoTF
• Write code to publish device data to IoTF
• View device data in IoTF

Hardware

Note: If the model of Arduino that you are using comes with built-in WiFi capabilities then you do not need a separate WiFi Shield.

• Arduino Uno
• Arduino WiFi Shield
• DHT11 (Humidity + Temperature Sensor)
• Jumper Cables

Software

• Arduino IDE

Circuit

Step 1: Make sure your Arduino is not connected to a power source.

Note: If the model of Arduino that you are using comes with built-in WiFi capabilities then you do not need a separate WiFi Shield and can skip this step.

Step 2: Attach WiFi Shield or Ethernet Shield on top of Arduino.

Step 3: Using jumper cables connect power (VNC) and ground (GND) ports on Arduino to power (+) and ground (-) ports on the breadboard.

Tip: It is a good practice to use red jumper cable for power (+ / VNC) and black jumper cable for ground (- / GND).

Step 4: Now that your breadboard has a power source, using jumper cables connect power (+) and ground (-) ports of your breadboard to power and ground ports of the DHT11 sensor.

Step 5: To read temperature and humidity values, you will need to connect a jumper cable from signal port of DHT11 sensor to D3 (Digital) port of your Arduino.

Your circuit is now complete and it should look similar to figures below.

IBM IoTF Setup

Signup for Bluemix.

Login to Bluemix, you will be redirected to the Dashboard.

Select Catalog from the top menu.

Select Internet of Things Foundation Starter from Starters > Boilerplates.

Enter WeatherMonitoringSystem in the Name field (application name has to be unique across Bluemix). Click Create button.

Bluemix will take some time to create your application. Once your application is ready it will be available at http://.mybluemix.net URL (in the case of this tutorial it will be http://WeatherMonitoringSystem.mybluemix.net).

To check if your application is running click on the link provided above. If an instance of Node-RED opens then your application was created as expected.

Application created using IoTF boilerplate uses Node.js as the runtime and by default includes a Cloudant NOSQL DB service and a Node-RED flow (this service will be used in upcoming tutorials).

To register your devices with IoTF you need to add Internet of Things Foundation service to the app. From Dashboard open WeatherMonitoringSystem application, and click on + ADD A SERVICE OR API button. You will be redirected to Catalog. Under Services select Internet of Things and click on Internet of Things Foundation service.

On service properties screen, leave Service name and default plan Free as-is or change according to your requirements. Click on Create button. Bluemix will add this service to your app.

Bluemix will need to re-stage your application before it can be added to the app.

Once the previous step is complete, on your Dashboard you will be able to see newly added IoTF service in WeatherMonitoringSystem application. From Dashboard under Services section click on IoTF service to open details screen.

The service details screen provides you options to Launch dashboard, Go to docs and Find out how. Click on Launch dashboard to open IoTF dashboard.

Overview tab provides you quick information about your Devices, Access, and Usage. Your device needs to be registered before it can start sending events to IoTF.  Click on + Add a device link under Devices section.

If you have added devices previously then you can choose an existing Device Type otherwise you will need to create a new Device Type. Click on Create device type button.

Note: Device Type can be considered a template for devices i.e. all devices belonging to same Device Type will be initialized with same attributes.

Select Create device type.

Enter Name and Description of the Device Type. Click Next to proceed.

Note: Later on in Arduino code, you will need to use this Name and depending on your version of MQTT client library that you are using to publish sensor data there might be a length limit, so check your client library for client name length limit.

 

Select Description from attributes list. Click on Next button.

Whichever Attribute you chose, on Submit Information screen you will need to provide values for them. Click Next.

Click Create button to complete Device Type setup.

You will be taken back to Add Device screen. Make sure you have selected the newly created Device Type from the list of values. Click Next.

On Device Info screen enter unique Device ID, and if you see Description is pre-filled with information that you entered while creating a new Device Type. Click Next.

Leave Metadata screen empty and click Next.

On Security screen, you have the option to either auto-generate a token or provide your own token. Leave Provide a token (optional) field empty and click Next button, this will make sure that a token is auto-generated.

Review your Device information on Summary screen and click Add button.

On next screen, the system will display auto-generated device token, make sure you copy and save the token as it will not be displayed again.

Your device setup is now complete and will be visible on the dashboard.

Arduino Code

IoTF is ready to receive events. Next, you are going to write Arduino code that will sense and publish events. Start your Arduino IDE and either type the code provided below or download it from GitHub. All the code goes into a single source file (*.ino) but in order to make it easy to understand and reuse, it has been divided into 5 sections.

• External Libraries: includes all libraries required to run the program
  • – https://github.com/arduino/Arduino/tree/master/libraries/Ethernet
  • – https://github.com/arduino/Arduino/tree/master/libraries/WiFi
  • – http://playground.arduino.cc/main/DHT11Lib
  • – https://github.com/knolleary/pubsubclient/releases/tag/v2.3
• Internet Connectivity Setup: code for WiFi connectivity, you simply need to replace

[code lang=”js”]
char ssid[] = "<SSID_HERE>";
char pass[] = "<PASSWORD_HERE>";
[/code]

• Sensor Setup: code for reading sensor data
• Data Publish: code for publishing sensor data to IoTF, make sure to provide custom values in following fields

[code lang=”js”]
char server[] = "<Organization_ID_HERE>.messaging.internetofthings.ibmcloud.com";
int port = 1883;
char topic[] = "iot-2/evt/<EVENT_NAME>/fmt/<EVENT_FORMAT>";
String clientName = String("d:<Organization_ID_HERE>:<Device_Type_HERE>:<Device_ID_HERE>");
char token[] = "<DEVICE_TOKEN>";
[/code]

• Standard Arduino Functions: implementation of standard Arduino functions setup() and loop()

[code lang=”js”]
/***************************************************************************
* External Libraries
**************************************************************************/

#include <SPI.h>
#include <WiFi.h>
#include <dht11.h>
#include <PubSubClient.h>

/***************************************************************************
* Internet Connectivity Setup – Variables & Functions
**************************************************************************/

char ssid[] = "<SSID_HERE>"; // Network SSID (name)
char pass[] = "<PASSWORD_HERE>"; // Network Password (use for WPA,
// or use as key for WEP)

int keyIndex = 0; // Network Key Index Number
// (needed only for WEP)

int status = WL_IDLE_STATUS;

WiFiClient client;

void connectToInternet()
{
status = WiFi.status();

// Check for the presence of the shield
if (status == WL_NO_SHIELD)
{
Serial.println("[ERROR] WiFi Shield Not Present");
// Do nothing
while (true);
}

// Attempt to connect to WPA/WPA2 Wifi network
while ( status != WL_CONNECTED)
{
Serial.print("[INFO] Attempting Connection – WPA SSID: ");
Serial.println(ssid);

status = WiFi.begin(ssid, pass);
}

// Connection successful
Serial.print("[INFO] Connection Successful");
Serial.print("");
printConnectionInformation();
Serial.println("———————————————–");
Serial.println("");
}

void printConnectionInformation()
{
// Print Network SSID
Serial.print("[INFO] SSID: ");
Serial.println(WiFi.SSID());

// Print Router’s MAC address
byte bssid[6];
WiFi.BSSID(bssid);
Serial.print("[INFO] BSSID: ");
Serial.print(bssid[5], HEX);
Serial.print(":");
Serial.print(bssid[4], HEX);
Serial.print(":");
Serial.print(bssid[3], HEX);
Serial.print(":");
Serial.print(bssid[2], HEX);
Serial.print(":");
Serial.print(bssid[1], HEX);
Serial.print(":");
Serial.println(bssid[0], HEX);

// Print received signal strength
long rssi = WiFi.RSSI();
Serial.print("[INFO] Signal Strength (RSSI): ");
Serial.println(rssi);

// Print encryption type
byte encryption = WiFi.encryptionType();
Serial.print("[INFO] Encryption Type: ");
Serial.println(encryption, HEX);

// Print WiFi Shield’s IP address
IPAddress ip = WiFi.localIP();
Serial.print("[INFO] IP Address: ");
Serial.println(ip);

// Print MAC address
byte mac[6];
WiFi.macAddress(mac);
Serial.print("[INFO] MAC Address: ");
Serial.print(mac[5], HEX);
Serial.print(":");
Serial.print(mac[4], HEX);
Serial.print(":");
Serial.print(mac[3], HEX);
Serial.print(":");
Serial.print(mac[2], HEX);
Serial.print(":");
Serial.print(mac[1], HEX);
Serial.print(":");
Serial.println(mac[0], HEX);
}

/*****************************************************************************
* Sensor Setup – Variables & Functions
****************************************************************************/

dht11 DHT11;

#define DHT11PIN 3

float humidity = 0.0;
float tempC = 0.0;

void readSensorData()
{
int chk = DHT11.read(DHT11PIN);

Serial.print("[INFO] DHT11 Read: ");

switch (chk)
{
case DHTLIB_OK:
Serial.println("OK");

humidity = (float)DHT11.humidity;
tempC = (float)DHT11.temperature;

Serial.print("[INFO] Humidity (%): ");
Serial.print(humidity, 2);
Serial.print(" Temperature (*C): ");
Serial.println(tempC, 2);
break;
case DHTLIB_ERROR_CHECKSUM:
Serial.println("Checksum Error");
break;
case DHTLIB_ERROR_TIMEOUT:
Serial.println("Time Out Error");
break;
default:
Serial.println("Unknown Error");
break;
}
}

/***************************************************************************
* Data Publish – Variables & Functions
**************************************************************************/

// IP address of the IBM MQTT server
char server[] = "<Organization_ID_HERE>.messaging.internetofthings.ibmcloud.com";
int port = 1883;
char topic[] = "iot-2/evt/<EVENT_NAME>/fmt/<EVENT_FORMAT>";
String clientName = String("d:<Organization_ID_HERE>:<Device_Type_HERE>:<Device_ID_HERE>");
char token[] = "<DEVICE_TOKEN>";

PubSubClient pubSubClient(server, port, 0, client);

void publishData()
{
// Connect MQTT Broker
Serial.println("[INFO] Connecting to MQTT Broker");

char clientStr[60];
clientName.toCharArray(clientStr,60);

if (pubSubClient.connect(clientStr, "use-token-auth", token))
{
Serial.println("[INFO] Connection to MQTT Broker Successfull");
}
else
{
Serial.println("[INFO] Connection to MQTT Broker Failed");
}

// Publish to MQTT Topic
if (pubSubClient.connected())
{
//Read sensor data
readSensorData();

Serial.println("[INFO] Publishing to IBM IoTF");
String data = "{"d": {"humidity": "" + String(humidity) + "", "tempC": "" + String(tempC) + ""}}";

char jsonStr[50];
data.toCharArray(jsonStr,50);

Serial.print("[INFO] JSON Data: ");
Serial.println(jsonStr);

char topicStr[33];
String topicName = topic;
topicName.toCharArray(topicStr,33);

if (pubSubClient.publish(topicStr,jsonStr))
{
Serial.println("[INFO] Data Published Successfully");
}
else
{
Serial.println("[INFO] Failed to Publish Data");
}

Serial.println("[INFO] Disconnecting Server");
pubSubClient.disconnect();
}

Serial.println("[INFO] Publish to MQTT Broker Complete");
Serial.println("———————————————–");

pubSubClient.loop();
}

/***************************************************************************
* Standard Arduino Functions – setup(), loop()
**************************************************************************/

void setup()
{
// Initialize serial port
Serial.begin(9600);

// Connect Arduino to internet
connectToInternet();
}

void loop()
{
//readSensorData();
publishData();

delay(5000);
}
[/code]

Final Product

Make sure your Arduino is powered on and IoTF publish code has been deployed. As soon as the code has been deployed, open serial monitor.

Log in to IBM IoTF dashboard and open your device, the Recent Events section will list all the events with their JSON message.

Click on any Event to see payload.

Sensor Information section shows the latest value of each data point.

The Connection Log section will provide you information about the status of connection attempts from your device.