API Builder

API Builder and MQTT for IoT – Part 1

MQTT is a machine-to-machine (M2M)/Internet of Things (IoT) connectivity protocol and is the de facto communication protocol for IoT. While you could use HTTP(S) on an IoT device, it is pull-based only, while MQTT is push-based (actually subscribe/publish). So, for example, with HTTP, the IoT device would need to constantly ask (pull) if a change is required instead of being told (push) about a desired change. Also, MQTT requires a much smaller payload for communication and connection so using HTTP is both data and power intensive as compared to MQTT.

This blog post will introduce MQTT and how API Builder works in an MQTT-based IoT system including some basic code snippets. In future blog posts, we’ll dive deeper into the code to do more as well as integrate with some of the other Amplify components for enhancing your IoT system.

MQTT Intro

The MQTT protocol has Clients and a Broker. MQTT clients subscribe to, and publish on, topics. The MQTT clients communicate to one another through an MQTT Broker, which is primarily responsible for receiving all messages, filtering them, deciding who is interested in it and then sending the message to all subscribed clients.

A diagram showing three clients and a broker is shown below. The temperature sensor client publishes the current temperature on the “temp” topic. The computer and mobile device clients receive this temperature reading since they subscribed on the “temp” topic. The Broker manages the connections and message communications.

The above diagram has MQTT clients communicating to one another through the MQTT Broker. However, one may want to store temperature readings in a database or perhaps send a push notification to a mobile app when the temperature falls below a certain value. That’s where API Builder and Axway’s Amplify comes into play.

API Builder and MQTT

Axway’s Amplify Platform with API Builder, MBaaS and it’s NoSQL Database and ability to integrate and orchestrate disparate data sources is ideal for complex IoT applications. API Builder does not contain out of the box MQTT support, but since API Builder is based on Nodejs, we can easily leverage the MQTT npm and a small amount of Javascript code to leverage API Builder and MQTT communication with IoT devices. Furthermore, you will also be able to leverage API Builders API features for non IoT devices, such as connecting to back end data sources, web sites and mobile applications.

API Builder, as well as the IoT devices are all MQTT Clients that communicate through the MQTT Broker as shown below:

The basic concept is to:

  • Stand up an MQTT Broker or use a managed service, such as CloudMQTT
  • Use MQTT npm in your API Builder project
  • From API Builder and your IoT devices, Subscribe to and Publish on topics that facilitate in implementing your IoT system
  • Listen for and publish messages
  • Use programatic access to API Builder Models to store and retrieve data from the Amplify’s NoSQL database and/or external data sources
  • Use API Builder’s integration with Amplify’s MBaaS to send Push notifications to mobile devices

So, in order for an IoT device to send data to API Builder, API Builder needs to subscribe to a topic, e.g. temp, and the IoT device needs to publish on that same topic, temp.

Let’s get started with a simple example.

MQTT Broker

Before we do anything we need an MQTT Broker. You can install Eclipse Mosquitto on your machine or server or you can use a managed service such as HiveMQ or CloudMQTT.

For this demo, I used CloudMQTT since they offer a free tier for development. Go to https://www.cloudmqtt.com/, create a login account and select the free tier. When you are done, you can go to the management console as follows:

Note the information from Details tab:

  • Server
  • User
  • Password
  • Port

We will need this information for establishing a connection to the Broker.

Note that User and Password are masked (empty) in the screen shot above but will be populated for you

API Builder Setup

In order to enable MQTT in your API Builder application, you will need to do the following:

  • Create a new API Builder project by following the API Builder Getting Started Guide
  • Install the MQTT npm by executing the following in your project’s root folder:
    npm install mqtt --save
  • Edit app.js and require mqtt and connect to the MQTT Broker as follows:
    var mqtt = require('mutt');
    var client  = mqtt.connect('mqtt://<user>:<password>@m11.cloudmqtt.com:10424');
  • Add an ‘on connect’ handler and subscribe to topics you want in the callback (e.g. ‘my home’)
    client.on('connect', function () {
    console.log('client connected');
    client.subscribe('my home')
    });
    
  • Add an ‘on message’ handler and process the message in the callback (e.g. print to the console log):
    client.on('message', function (topic, message) {
    console.log('message received');
    console.log(message.toString());
    });

The complete app.js file is shown below:

var Arrow = require('arrow'),
    server = new Arrow();

var mqtt = require('mutt');
var client  = mqtt.connect(':@m11.cloudmqtt.com:10424');

client.on('connect', function () {
  console.log('client connected');
  client.subscribe('my home')
});

client.on('message', function (topic, message) {
  console.log('message received');
  console.log(message.toString());
});

// lifecycle examples
server.on('starting', function () {
    server.logger.debug('server is starting!');
});

server.on('started', function () {
    server.logger.debug('server started!');
});

// start the server
server.start();

Note that in this simple example, API Builder is only listening (subscribing) and not publishing. In future posts, we’ll cover more complex scenarios where API Builder is both subscribing and publishing.

Node.js Publisher

To keep things simple, let’s create a simple publisher that sends a message on the ‘myhome’ topic as follows:

  • Initialize a Node project by executing the following in a new folder on your computer and accept all defaults when prompted:
    nam init
  • Install the MQTT npm by executing the following in your project’s root folder:
    npm install mqtt --save
  • Create a file called index.js and paste the following inside:
    var mqtt = require('mqtt');
    var client  = mqtt.connect('mqtt://<user>:<password>@m11.cloudmqtt.com:10424');
    
    client.on('connect', function () {
      console.log('client connected');
      client.publish('myhome', 'Hello from publisher');
    });

Note that the index.js code above simply connects to the Broker and on ‘connect’ publishes on the ‘myhome’ topic

    • Run the Node.js publisher by executing the following:
      node index.js
    • You should see the following in the console:

    • You should see the message ‘Hello from publisher’ appear in the console of the API Builder app as follows:

    • You can see the two connected clients (API Builder as the subscriber and Node.js publisher) in the ‘Connections’ tab of the CloudMQTT dashboard as follows:

Note that you can also check the CloudMQTT Dashboard ‘Log’ tab to see the connections, disconnections and other useful information

Conclusion

In this blog post, we saw how easy it is to implement MQTT in API Builder in a few lines of code. In future blog posts, we’ll dive deeper into how to leverage the other features/components of API Builder as well as some other Amplify components for IoT applications.