JavaScript MQTT WebSocket Monitor for the SmartEdge Agile

The Brainium portal provides several tools to interpret data while using AI to recognize specific motions (see my Quick Start example project) or repetitive pattern detection that can be used to detect irregularities for preventive maintenance. We can program the SmartEdge Agile to recognize motions or combinations of motions directly on the device, minimizing communications from the device to simple notifications. The ability of the device to process complex sensory data and react to it is called edge computing. The portal also provides an Application Programming Interface (API) or rather two of them, a REST or Restful API, and an API for the Message Queuing Telemetry Transport (MQTT), also known as Mosquito.

If you click on the API button on the tool bar in the brainium portal

it will open a page that has all of the documentation for both API's.

The REST API provides access to historic recorded data, detected motions, the users projects, widgets, devices, device status, and gateways. We are going to use the MQTT (Mosquito) API for our connection to access real-time data transmitted from the edge.

Mosquito

An MQTT system consists of a message Broker and it's clients, a client can publish information to the Broker or it can be a subscriber to messages hosted by the Broker. Data is organized by the broker in Topics, when a client publishes data to a topic the Broker then distributes that information to the subscribers of that topic. Messages are exchanged using JSON format.

In this tutorial we'll be connecting both a publisher and a subscriber to the Brainium MQTT Broker. The publisher will be the SmartEdge Agile, and our subscriber will be a web page we will build to connect to the Broker and display the messages we receive.

Lets start by configuring the SmartEdge Agile to publish telemetry data to the MQTT Broker on the Brainium portal. In order for that to happen we need to setup the device and then tell it what telemetry data we want it to publish.

Device Setup

If you haven't already you'll need to sign up for a user account on the Brainium website, enter your email address and you will receive an email with login information.

The next thing you will need to set up is a gateway for the SmartEdge Agile to connect to in order to communicate with the portal.

There are three different gateway devices that can be used currently, an Android or iOS smart phone, or a Raspberry Pi, the software for each of these devices can be downloaded with the following links.

• https://play.google.com/store/apps/details?id=com.brainium.android.gateway
• https://itunes.apple.com/us/app/brainium-gateway/id1446583825
• https://spa.brainium.com/apps/linux

Once the gateway is installed and you've logged into your account you can add the SmartEdge device through the gateway. Turn on the SmartEdge agile device an make sure the gateway software is running on your device, I noticed that it might not connect correctly when the screen on my phone is locked.

That's it for the device setup, pretty simple..

Publisher Setup

In order to configure the device with our requirements it needs to be assigned to a project, the SmartEdge Agile can only be assigned to one Project at a time so if you've already assigned it to one it should be removed to clear whatever rules were previously installed so we can add the new ones, or you might be able to add a new rule to your existing project.

on the projects page hit the big Plus sign in the corner and give your project a name, I'm calling mine API Test Project:

You can even drag and drop an image onto the wizard to personalize your project. Open your project and you will be asked to add a device, hit the big plus sign again and your Device should be available under the Candidates for the project: header, select add to the project and you will see a device page with the Device name, state, what Gateway it's connected to, the number of rules assigned to it, any AI Rules (both should be 0), and what sensors are available on board the device. If there is an update available to install under the State header, select it and wait for it to install, it's always best to keep your device up to date in case they add new features or fix errors.

Widget

Lets go back to the Data Tracking / Recording project page, you'll see the create widget wizard, select the blue 'Create Wizard' button.

This will open the Create New Widget page, Add a name to your widget and select Visible Lightness for the widget type, and plain data for the display type.

Press next and you will be asked to attach the widget to a device, you'll see the device name and the device ID below it, copy the Device ID and save it for later. next to the name is the device settings button, press that and change the transport rate for Visible Lightness frequency from low to Medium, press save and select the Back to the Create New Widget button at the top. Next we select Finish and our widget is now available.

We've programmed our publishing client with the information we want it to sent to the broker. The MQTT API separates the subscriber topics into 3 groups or types, telemetry, alerts triggered by the sensors, and programmed motions, we are telling it to send telemetry from the light sensor to the Broker. The topic the data will be published to is Visible Lightness, now let's set up a second client to subscribe to that topic.

WebSocketClient

We will need an HTML file to write our code in, you can use any text editor you want and create a file named index.html and open it for editing. First we want to add some basic code to define our web page:

<!DOCTYPE html>
<html>
<head>
<title>JavaScript MQTT Websocket Monitor</title>
</head>
<body>
 <h1 style="text-align:center;">MQTT Message Monitor</h1>
 <h3 style="text-align:center;">Status Messages:</h3>
 <p style="text-align:center;"div id="status_messages"></div></p>
 <h3 style="text-align:center;">Received Messages:</h3>
 <p style="text-align:center;"div id="out_messages"></div></p>
</body>
</html>

This will create a simple web page where we can publish the current status of our client and the telemetry messages we receive from the broker. If you save it and double click on the file it should look something like this in your browser:

Next we need to add an MQTT library that will take care of all of the connection and encryption protocols for us, so right above the </head> tag let's add the address for the Eclipse Paho MQTT JavaScript client library.

<script src="https://cdnjs.cloudflare.com/ajax/libs/paho-mqtt/1.0.1/mqttws31.js" type="text/javascript"></script>

Now we'll need to add the JavaScript functions to connect to the broker, subscribe to the Visible Lightness Topic, receive the messages published by the device, and display them on screen.

MQTTconnect

We will create a connect function to connect to the broker when the page loads, it will be called from within the body, so we will add this code between the body tags.

  
  <script type="text/javascript">
  MQTTconnect();
  </script>
  

We'll add the connect function above the body so that it is loaded before being called, add this code between the </header> and the <body> tags.

<script language="javascript">
  
function MQTTconnect() {
  
}
  
</script>

This function is empty, so we want to add some code to connect to the broker when it's called, first let's update the status message to tell the user that we are connecting to the broker.

status_messages.innerHTML = "connecting to "+ BrokerURI;

This code uses a variable with the Brokers URI that we want to connect to. This information is published in the API documentation under how to connect, the Brainium MQTT Broker is at wss://ns01-wss.brainium.com. In order to access the secure broker we will need to use an authentication method. This broker requires a user name that is common for everyone, and an external access token as the password, this is available on your profile page in the Brainium web site, we'll also grab the Platform User ID while we're in there, we'll need this when it's time to subscribe to our topic.

So let's go ahead and create the variables we will need to begin with above our function, HTML is a procedural language so they have to be listed first or the function code won't know about them. We'll create a variable for the Brokers URI, the username and the password we'll use to connect to the Broker, we'll also add a couple variables we will use in the function later.

    var BrokerURI="ns01-wss.brainium.com";
    var MQTTUserName="oauth2-user";
    var ExternalAccessToken=""; //put your access key here
    var PlatformUserId = ""; //put your User ID here
    var mqtt;
    var port = 443;    

Go to your profile in the Brainium portal and you'll see the External access token and the User ID on the left hand side under your name and email address, click on the access token and it will be copied automatically to the clipboard, paste it between the quote marks after the variable: ExternalAccessToken, copy and paste your User ID between the quotes after the PlatformUserId variable. The MQTTUserName and BrokerURI variables will be the same for everyone.

Let's add the code to the connect function that will create the connection string we can call to connect to the Broker with the options that we want to add.

mqtt = new Paho.MQTT.Client(BrokerURI,port,"clientjs");
var options = {userName: MQTTUserName,
               password: ExternalAccessToken,
               timeout: 3,   
               onSuccess: onConnect, };

This code assigns the connection string to the variable mqtt we created earlier, along with the port variable used to define the TCP port we want to connect to on the Broker. The code also assigns the username and password to the options object, a timeout of 3 seconds so we don't wait indefinitely for a connection and a function to call once we are connected to the Broker (onSuccess) that we will create later. Now we can add the connect function, passing the options.

mqtt.connect(options);

and we'll add two more function calls here that will be called if the connection drops and when we receive a message.

 mqtt.onConnectionLost = onConnectionLost;
 mqtt.onMessageArrived = onMessageArrived;

here we are pairing events that are returned by the connection to new functions onConnectionLost and onMessageArrived, that will be called by the events, we will add these functions later. Our script should now look like this:

 <script type = "text/javascript">
   var BrokerURI="ns01-wss.brainium.com";
   var MQTTUserName="oauth2-user";
   var ExternalAccessToken=""; //put your access key here
   var PlatformUserId = ""; //put your User ID here
   var mqtt;
   var port = 443;
  
function MQTTconnect() {
  
status_messages.innerHTML = "connecting to "+ BrokerURI;
  
mqtt = new Paho.MQTT.Client(BrokerURI,port,"clientjs");
   var options = {userName: MQTTUserName,
              password: ExternalAccessToken,
              timeout: 3,   
              onSuccess: onConnect, };
  
   mqtt.connect(options);
   mqtt.onConnectionLost = onConnectionLost;
   mqtt.onMessageArrived = onMessageArrived;
  
};
</script>

onConnectionLost

now let's add the other functions we need. We'll start with onConnectionLost, this will update the status message to tell us that's we're no longer connected to the Broker this code should be placed above the MQTTconnect() function, so it will be loaded before being called:

  function onConnectionLost(){
   status_messages.innerHTML ="Connection Lost";
  };

onConnect

The onConnect function will update our status message and subscribe to the Topic the SmartEdge Agile will be publishing to. We're going to subscribe to the lightness (visible spectrum) telemetry data, which can be subscribed to with this string, listed in the API documentation:/v1/users/{userId}/in/devices/{deviceId}/datasources/VISIBLE_SPECTRUM_LIGHTNESS

We need to replace the {userId} field with the User ID variable we created earlier, and we will replace the {deviceId} field with a new deviceID variable that will hold the device ID copied earlier from the create widget section.

Let's add three new variables, the DeviceID, the name of the topic we are subscribing to as topic, and the completed subscription string as Motiontopic. Make sure they are all below the PlatformUserId so it will be included, paste your device Id you copied earlier between the quotes:

  var DeviceID = ""; //put your Device ID here;
  var topic = "VISIBLE_SPECTRUM_LIGHTNESS";
  var MotionTopic = "/v1/users/" + PlatformUserId + "/in/devices/" + DeviceID + "/datasources/" + topic;

Now we can add the onConnect function to our code that will be called from the connect function when an onSuccess event is generated. The code is pretty simple:

  function onConnect() {
   mqtt.subscribe(MotionTopic);
   status_messages.innerHTML = "Subscribed to topic "+topic;
  }; 

the subscribe method subscribes to the topic we have designated, we could subscribe to other topics simultaneously if we wanted to monitor other sensors. The other line updates the status message to let the user know they are now subscribed to that topic.

onMessageArrived

Our last function will receive the messages published to our subscribed topic, parse them, and post them to the page so they will be visible:

  function onMessageArrived(r_message){
   };

This function is called with a parameter (r_message) which is the message object received from the Broker. we will want to extract the payload from the message and parse it:

    var payload = r_message.payloadString;

The payload has the telemetry data we are looking for, it is the only part of the message package we are interested in for this tutorial. There are some extra formatting characters in the extracted string that we will remove to clean it up, this will remove the square brackets:

    var messageString = payload.replace('[','').replace(']','');

next we'll split the string since there will probably be more than one telemetry entry that arrives, this way we can stack them and display all of them.

    var splitMessage = messageString.split("},{")

Now we need to get the number of telemetry entries that arrived and step through them to post them to the Received Messages: section of the web page.

    for (var i = 0; i < arraylength; i++){
        if (i==0){
          out_messages.innerHTML=splitMessage[i].replace('{','')+"<br/>";
        } else {
          out_messages.innerHTML+=splitMessage[i].replace('}','')+"<br/>";    		}
        }
     }

the first loop (i==0) will clear all of the previous messages posted and the next iterations will add successive telemetry data underneath. The telemetry will be displayed until a new message arrives, then the function will be called again. The final program code should look like this:

<!DOCTYPE html>
<html>
<head>
<title>JavaScript MQTT Websocket Monitor</title>
 <h1 style="text-align:center;">MQTT Message Monitor</h1>
 <h3 style="text-align:center;">Status Messages:</h3>
 <p style="text-align:center;"div id="status_messages"></div></p>
 <h3 style="text-align:center;">Received Messages:</h3>
 <p style="text-align:center;"div id="out_messages"></div></p>
<script src="https://cdnjs.cloudflare.com/ajax/libs/paho-mqtt/1.0.1/mqttws31.js" type="text/javascript"></script>
</head>
<script type = "text/javascript">
  var BrokerURI="ns01-wss.brainium.com";
  var MQTTUserName="oauth2-user";
  var ExternalAccessToken=""; //put your access key here
  var PlatformUserId = ""; //put your User ID here
  var mqtt;
  var port = 443;
  var DeviceID = ""; //put your Device ID here;
  var topic = "VISIBLE_SPECTRUM_LIGHTNESS";
  var MotionTopic = "/v1/users/" + PlatformUserId + "/in/devices/" + DeviceID + "/datasources/" + topic;
  function onConnectionLost(){
   status_messages.innerHTML ="Connection Lost";
  };
  function onConnect() {
   mqtt.subscribe(MotionTopic);
   status_messages.innerHTML = "Subscribed to topic "+topic;
  }; 
  function onMessageArrived(r_message){
   var payload = r_message.payloadString;
   var messageString = payload.replace('[','').replace(']','');
   var splitMessage = messageString.split("},{")
   var arraylength = splitMessage.length;
   for (var i = 0; i < arraylength; i++){
       if (i==0){
         out_messages.innerHTML=splitMessage[i].replace('{','')+"<br/>";
       } else {
         out_messages.innerHTML+=splitMessage[i].replace('}','')+"<br/>";
       }
    }
   };
  function MQTTconnect() {
   status_messages.innerHTML = "connecting to "+ BrokerURI;
   mqtt = new Paho.MQTT.Client(BrokerURI,port,"clientjs");
    var options = {userName: MQTTUserName,
             password: ExternalAccessToken,
             timeout: 3,   
             onSuccess: onConnect, };
   mqtt.connect(options);
   mqtt.onConnectionLost = onConnectionLost;
   mqtt.onMessageArrived = onMessageArrived;
  };
</script>
<body>
  <script type="text/javascript">
  MQTTconnect();
  </script>
</body>
</html>

If we save this file and open it with a browser it will connect to the broker and subscribe to the topic we designated. however, it will not receive any telemetry data from the SmartEdge Agile yet, because we haven't told it to start transmitting any.

Go back to the project and press the start tracking button, select your device and press Start Tracking at the bottom of the page. the widget will connect to the device and show the visible light level.

Start your web application, and you should see the received messages start to be displayed.

The timestamp is a linux timestamp, the amount of seconds that have passed since January 1, 1970, the scalar is the Lux telemetry value being published to the Broker by the SmartEdge Agile.