LoRa (Part 6) – A MachineQ Example Continued

Bob continues his article series on LoRa. Last time (in Part 5) he looked at a LoRa installation using one of MachineQ’s two starter kits. Here, in Part 6, Bob explores how to create your own back end for the MachineQ network.

Last night, in order to meet the insatiable demands of live streaming and video conferencing in our home, I called our service provider to purchase more bandwidth. The request was granted, my account was billed and I was told that I should power down my router for 15 minutes and then turn it back on. Voila! Faster Internet. Except that the router never recovered. No Internet, no TV and no phone service. After several hours with their tech support, they concluded that there must be something wrong with the incoming line and they would send a technician out within 48 hours to inspect the line. They eventually fixed what was wrong in the central office.

This morning I realized that the data I have been logging on my MachineQ network was lost except for the last 24 hours. As a side note, the MachineQ gateway never recovered either from this loss. In talking with their technical support, they said that “when it loses WiFi connection, the gateway will have to be rebooted to reconnect.” Keep that in mind when you design any system that has to be up 24/7. Our company always provides a way to automatically power down should you lose the connection.

For this, and other reasons we will discuss in this article, we need to have our own back end when we deploy a MachineQ system. This month I will talk a little about what resources MachineQ makes available for you to create your own back end.

MQCENTRAL
As a refresher, Figure 1 (reshown here from the last article) lays out the basic architecture. The sensor sends data over LoRa to the MachineQ gateway. The gateway sends the data to the cloud called MQCore. The user interfaces with MQCore with the MQCentral dashboard. There are a number of approaches that MachineQ could have gone with MQCentral. They chose to make the dashboard non-extensible. Instead, they decided to provide a large array of APIs for you to interrogate the gateway and communicate with the sensors. This requires you to create your own user interface back end. Other projects that we’ve worked on have a customer extensible back end that allows you to shape the user experience with a set of tools.

The reason we need to create our own back end is that MQCentral is not intended to be used as your customer interface. Here are some major features that are not available:

1. No branding. You cannot brand your user interface by deciding what shows on the dashboard and whose logo is displayed and so on.
2. No saved data across power outages. This is a critical feature in the server of a lot of IoT applications.
3. Refreshing of security keys: The dashboard doesn’t have a way to periodically refresh the security keys.
4. The graphing capability is very limited: It doesn’t include Zooming or Scrolling to back data and so on.
5. As I mentioned in the introduction, only 24 hours of data is stored.

All this means that you need to use the option MachineQ provides to create your own back end. And they have done a pretty good job of it. MachineQ provides the exact cURL code that you need to make changes to the downstream sensors as well as obtaining the data. They also provide a few examples of how to implement the APIs with Python. In addition, they give you the ability to set alerts to go to email or text messaging. You can even run the cURL code and see what you get back from MQCore.

WHAT ARE THE APIs?
The first thing we learn about the APIs is that they are RESTful. Just what we need after being quarantined at home for a while! What are RESTful APIs you ask? The REpresentational State Transfer (REST) paradigm is an attempt to put some constraints on the wild and wooly world of web services. The goal is interoperability and robustness through a uniform set of stateless operations. There are six guiding constraints that make up the RESTful paradigm and thus the APIs MachineQ provides.

They are:
Client-Server Architecture: Your back end will be a client and their MQCore will be the server.
Statelessness: This means that no client context is stored on the server. Every identical request to the server should get the same response. This implies that every client request has everything the server needs to know to make the response. We have found this an important feature (and also the one that is most violated by many “RESTful” servers). I have not found any non-RESTful APIs in MachineQ’s cadre of tools.
Cache-ability: This means that all server responses are stored in the client: your back end.
Layered system: This means that your back end can’t tell if it is talking to an intermediary or directly to the end server.
Code-on-demand: The server can extend the functionality of the client by sending it executable code as with Java applets and Javascript. You need to configure your back end to receive this from the MQCore.
Uniform interface: This means that there are a subset of things you can do with HTTP. But don’t worry— the subset is sufficient. GET, POST, PATCH and DELETE are included.

WHAT MACHINEQ APIs CAN DO
Some of the things the APIs (whether in Python or cURL) can do is to [1]:

• Provision and manage devices
• Provision and manage gateways
• View connectivity health and gather detailed logs
• View your devices’ payload data
• Send downstream messages to your devices
• Create output profiles to flow data to services such as Azure, AWS and so forth, where it can be stored and processed as needed
• Create and manage users
• Create and manage role permissions
• Send SMS and email alerts based on user defined thresholds
• Create custom groups for both devices and gateways

GETTING STARTED
MachineQ decided to use an API tool called Swagger (Figure 2) [2]. I was not familiar with Swagger before I started working with MachineQ, but I like it. The concept is so great. Why didn’t I think of it? In a nutshell, it is a tool to help you with API design, development, documentation and testing. It would take a whole article to tell you all that it does [3].

Using the link provided by MachineQ, you log into your MachineQ account and then go to their Swagger portal. From there you can see the APIs organized by groups (See the grouping on the left side of Figure 3).

Each session needs to start with an authorization where you log into the Swagger interface. This provides an authorization token that is good for one hour. All communications with the server should be encrypted (over HTTPS) since all cURL commands will have that token in it. The good news is that the token is different every time you log in. So, if the token was somehow intercepted, it would expire in one hour.

ADDING SOME ALERTS
Let’s assume that we want our devices to generate some alerts when a temperature goes outside a range. The alert can be either an email or text. One way to do it is with MQCentral and the other is through Swagger. With MQCentral you can click on Notifications (Alerts). You will see any Notifications that you created on MQCentral. A beef I have is that it doesn’t show Notifications/Alerts you create with Swagger. Also, the user interface on MQCentral doesn’t provide everything that you can do with the API. For example, from MQCentral, you cannot choose email or text on a per-alert basis like you can with the Swagger API.

The Swagger API allows for many more types of sensors than MQCentral. So, if you built your own sensor, you cannot set an alert from MQCentral. Also, Swagger allows you to send an alert either when you enter or leave the temperature zone. In addition, with Swagger, you can set the amount of time the temperature has to be out of the upper or lower bounds before it triggers the alert. So, in general, you will want to create these alerts using the Swagger API.

Once logged into Swagger, you will authorize your session. We can then start creating a new alert. We click on the Alerts item on the left of Figure 3 and then click on the Create Alert. Figure 4 shows what we get next.

We are given a JSON file to edit with all of the parameters necessary to create the cURL command. You can use the Swagger editor or you can use your own editor and copy and paste the data in. We enter the JSON and then execute the cURL command provided. I want to commend MachineQ because they have provided excellent descriptions of what each JSON parameter is.

COMMUNICATIONS CHAIN
When you execute the cURL command, Swagger communicates to MQCore, which communicates to the gateway. The JSON for creating the alert looks as shown in Listing 1. In cURL, the code looks as shown in Listing 2 (Swagger provides this for you to copy and paste into your back end).

{
"Name": "Temperature Alert Email", // A human-readable name
"ThresholdRules": [
{
"Type": "temperature", // A enum of all the types of sensors. We will use Temperature
"LowerBoundary": "12",
"UpperBoundary": "20", // These are in degrees C
"Include": false, // Sets whether the alert is sent when it enters or exits this range.
                  //If true, alert sent when it enters range.
                  //If false, alert sent when it exits range.
"StateTime": "1"  // Minutes the device must be in this state to trigger the alert.
}
],
"NotificationRules": [
{
"Type": "EMAIL", // EMAIL or SMS
"Contacts": [
"rjapenga@microtoolsinc.com"// An array of strings with either email addresses or phone #
],
"Message": "Help. It is getting too cold or too hot here", // The message you want sent
// The message to send. Note: You can use the following variables to build a message
//$Device = deveui
//$Name = Device name,
//$Type = Type field from the ThresholdRule
//$LowerBoundary = LowerBoundary field from the ThresholdRule
//$UpperBoundary = UpperBoundary field from the ThresholdRule
//$Value = Reported sensor value
"StartTime": "07:00:00", // Time to start sending alerts (ie: 07:00:00)
"StopTime": "22:00:00", // Time to stop sending alerts (ie: 22:00:00)
Days": [ // Not required
"Monday",”Tuesday”,”Wednesday”, //An array of days of the week (IE: ["Monday", ...] or ["Mon", ...])
],
"Timezone": "New York" //Timezone defines the target timezone
}
]

LISTING 1 – Shown here is the JSON for creating the alert.

curl -X POST "https://api.machineq.net/v1/alerts" -H "accept: application/json" -H "authorization: Bearer YOUR UNIQUE TOKEN" -H "Content-Type: application/json" -d "{ \"Name\": \"Temperature Alert\", \"ThresholdRules\": [ { \"Type\": \"temperature\", \"LowerBoundary\": \"12\", \"UpperBoundary\": \"20\", \"Include\": false, \"StateTime\": \"string\" } ], \"NotificationRules\": [ { \"Type\": \"EMAIL\", \"Contacts\": [ \"rjapenga@microtoolsinc.com\" ], \"Message\": \"Help. It is getting too cold or too hot here\", \"StartTime\": \"07:00:00\", \"StopTime\": \"22:00:00\", \"Days\": [ \"Monday\",\"Tuesday\", \"Wednesday\"], \"Timezone\": \"New York\" } ]}"

LISTING 2 – In cURL, the code looks as shown here. Swagger provides this for you to copy and paste into your back end.

With a successful HTTP 200 server response we have successfully set up an alert. The response also returns an identifier for the alert which can be used if you want to modify or inspect the alert.

SUMMARY
Of course, getting your back end to talk to the sensors is only part of the job. You will still need to store the data, back-up the data and create the user interface. But it has been my experience that one of the most difficult things in creating the back end is not the stuff that we do all the time, rather it is the code that talks to someone else’s devices. They either are not documented or don’t work as described. That is where it gets messy. With Swagger, you get the code snippets to put in your back end PLUS you can actually test that code on the device. Now you are all experts at creating a back end for MachineQ devices—but of course, only in thin slices! 

Read “LoRa (Part 1)” Here

Read “LoRa (Part 7)” Here

RESOURCES

References:

[1] https://support.machineq.com/s/article/What-are-the-MQ-APIs
[2] There is a good article on Wiki about them https://en.wikipedia.org/wiki/Swagger_(software)
[3] Check out all the possibilities at www.swagger.io

MachineQ | www.machineq.com
Swagger | www.swagger.io

PUBLISHED IN CIRCUIT CELLAR MAGAZINE • AUGUST 2020 #361 – Get a PDF of the issue

Sponsor this Article