Bob continues his article series on LoRa. Previously in the series he introduced MachineQ. In Part 5, he explores putting two LoRa devices on the MachineQ network. He looks at two different types of LoRa installations: one using off-the-shelf hardware and one using one of MachineQ’s two starter kits.
This morning as I was having breakfast with my wife, she was drinking her coffee out of a Contigo travel mug. She happened to have the instructions that came with the mug sitting at the breakfast table. There were about 500 words in the instructional guide [1] (about ¼ of the word count of this article) and 14 illustrations. This is for a device that has three items in the user interface: Two buttons and a twist top. How does that compare to the kind of devices that we use to design our embedded systems devices and how much documentation do they need? One of the starter kits we are going to talk about in this article has the following items with which we developers need to interface with: Two buttons, seven LEDs, more than 30 jumpers, over 100 interface pins, over 20 channels of ADCs, two DACs, more than 12 timers, over 10 serial interfaces, one radio, three processors and … I think you get the idea. How much more complex does this documentation have to be?
A few years back, one of our customers wanted a platform that would run Windows, Android and Linux as generic platforms on which their customers could create their own vertical market products. In addition, the platform needed to have its own proprietary code running on Linux. If that doesn’t take your breath away (we were both small companies), it should. But, an even more daunting task was to create the documentation that would tell the developers how to develop Windows, Android and Linux apps—normally called a Software Development Kit (SDK).
This month we will look at two different types of LoRa installations: one using off-the-shelf hardware and one using one of MachineQ’s two starter kits. In my more than 45 years of developing embedded systems I have never had such a hard time figuring out how to do what I wanted to do with something like this. And I am just starting out with my design. The documentation seemed to be complete, but there was no road map to get me to all of the documentation. All that aside, the MachineQ support team was great—but I kept feeling so stupid, asking what seemed to me pretty basic questions. With that said, most of the time the documentation was there and was clear. But, as I said at the beginning of this article, it is hard to create a documentation set that enables us to quickly get to what we need.
THE HARDWARE
The LoRa Device: There were two options we pursued for this project: buy an off-the-shelf ready to go sensor with an off-the-shelf gateway—like we talked about in the MachineQ article (Part 3) in this series [2]— and buy a starter kit to allow us to build our own sensors. MachineQ offers two starter kits: the MQSpark [3] based on an Arduino which is compatible with over 200 Grove sensors and the STMicroelectronics (ST) LoRa Dev Kit [4]. Although I was more familiar with the Arduino development platform, it looked like the ST LoRa Dev Kit was made for the more serious developer who would be developing their own sensors. So that’s where we went.
The ST LoRa Dev Kit: This kit comes with an 8-channel indoor gateway which we will describe later, a development board with the Keil development tool chain and a sensor package. The development board is a general-purpose radio interface platform that contains ST’s STM32L072CZ microcontroller and a Murata radio that supports not only LoRa but SigFox [5] and FSK/OOK for real do-it-yourselfers (Figure 1). The sensor package is an Arduino shield interface [6] that includes sensors for humidity, ambient pressure, temperature, a 3D accelerometer, 3D gyroscope, 3D accelerometer and 3D magnetometer. The shield can be extended to add additional Arduino shields (Figure 2).
The development board comes with a battery holder for three AAA batteries. One complication I ran into was that the battery pack is not designed to work with the debug interface (ST-Link). There is an intentional solder bridge (SB37) that needs to be removed for the battery pack to work. This solder bridge allows ST-Link to control the reset line. Once the solder bridge is removed, ST-Link is no longer powered and thus the debug interface doesn’t work. So, if you want to test the device running off the battery you would need to cut the jumper. Since I only had one board and wanted to be able to use the debug interface, I had to provide my own power source for my range testing. (We’ll look at range testing in the final article in this series in October.) For that, I bought an external phone battery with 10,000 mA-hours [7] of power and powered the device through the USB connector for my testing.
— ADVERTISMENT—
—Advertise Here—
The design is open source, so all of the schematics [8] are available. It is not, however, a reference design per se. The power consumption is significant. It drained my external phone battery in a week! That means it would drain my AAA batteries in a little more than a day—1,000 mA-hours is typical for a AAA battery. It does provide some test points to measure current drain and that is good. There are some minimal power saving options on the board (for example, eliminate one of the LEDs by removing SB18) but overall, the design is not a design for low power as is. The processor may be a more powerful processor than you would need as well. (And it’s slightly more expensive than the SAMD21 we evaluated in the Part 4 article). As we will see in the final article in this series in October, the software is intended as demonstration code and is also not designed to be a reference design and contributes significantly to the current drain. So, plan on taking a lot of time developing your own software using the sample code as a start.
The MQFlex: I wanted to test an off-the-self sensor and chose the MQFlex (Figure 3). The MQFlex offers similar sensors to those provided in the ST LoRa Dev Kit—humidity, ambient pressure, temperature and so on. I ordered mine from Mouser and it did not provide the EUI (extended unique identifier) and the keys necessary to install it from the web. The only way to install it was to use the MachineQ app on your phone. I understand tech support’s explanation that they don’t want to send the keys with the device. But how this is handled in large volume is still an unknown to me. The app is a bit odd in that it recognized my gateway but not my other sensor, which I added to the network via the web interface. It only is used for configuring, so you cannot take it on the road with you when you are doing range testing.
The LoRa Gateway Hardware: We purchased MachineQ’s 8-Channel Indoor Gateway (Figure 4) with the Ethernet and Wi-Fi option as the means to connect to the Internet. You can also purchase an Ethernet/Cell-modem option including a data plan if the installation does not have a local Internet connection. It comes with a built-in antenna (gain of 0 when you configure) which you use if the gateway is mounted, flat and an external antenna (gain of 1-2) if you mount the gateway on the wall. Knowing what to enter for the antenna gain required contacting tech support, but hopefully they will update that documentation by the time you read this. It was pretty seamless installing it as an Ethernet gateway, but when I tried to change it to a Wi-Fi, it somehow locked up and needed tech support to unlock it at their end. They were very quick in responding, but it did shake my confidence in their software
THE SOFTWARE
The MachineQ paradigm is best illustrated with the drawing in Figure 5. Your sensor is the device with a LoRa radio that sends the data to the gateway. The gateway is sensor data agnostic. The gateway in turn sends it to the cloud called MQCore. The MQCentral web site accesses the sensor data in MQCore and allows you to manage your system at a very rudimentary level. You can see graphs of the data over time; check on the health of the devices and the gateways; see where the gateways are located; as well as seeing the raw data. But MQCentral is not something that you can tailor or brand as your own. You need to create your own application for a tailored and branded user experience.
The good news in this is that MachineQ provides an interface to allow you to use cURL [9] commands to talk to MQCore—you can easily translate the script commands to cURL functions [10]. To interrogate the data in MQCore, they provide the exact cURL command needed which you can test out. This is done through another interface called Swagger [11]. For example, Figure 6 shows the cURL command and the URL needed to get the device information from the account. You can see the response in the JSON file provided on Circuit Cellar’s article code and files webpage [12]. Don’t use cURL? They also support Python code and provide you the Python snippets you need to access all of the data from your devices [13].
Finally, the other piece of the MachineQ paradigm is the concept of Profiles. You can create output profiles of the data that you wish to send to your application. This way you tell MQCore where to send the data, how often and what data to send.
MQFlex Software: One of the questions that we should ask is: How much flexibility does the off-the-shelf MQFlex give me with the data? Not a lot, but perhaps enough! What is it you would want to tailor in the sensor? The most obvious thing would be how often the device sends data. By default, it sends the data once an hour. But what if you wanted to change that? Not every application has the same requirements for this. Again, MachineQ provides the programmatic API to change that. And it has example code that you can try and cut and paste into your application. These changes are made through the Swagger interface and the “Sends the device a message” interface.
The other thing you can do is to set alerts. Let’s say that you only need the payload once a day unless the temperature drops below 32°F. Then you want to send data every 5 minutes until the alert condition is cleared. Again, MachineQ provides that interface through Swagger.
LoRa Device Software: The Keil development tool provides C code for developing your own sensor. In the final article in this series in October, we will look at the ST software and see how you can use the example code to create your custom sensor.
— ADVERTISMENT—
—Advertise Here—
LoRa Gateway Software: One of the challenges in documenting complicated systems is this: It’s not enough to tell me how something works. I also need to know what does it do when something doesn’t work. An example of this is with the gateway. During the LoRa Development kit webinar [14] a question was asked: “What happens to the data if the gateway loses Wi-Fi [or cell modem] connectivity? Does it store the data?” The question was answered in the affirmative, but that’s not sufficient. Yes, it is stored—but for how long? And how much data can you store for how long? This is where the documentation for this product challenges me. I am convinced that there are specifications that define these things—and they are critical to our design. But where are they? And do we have access to them? Once again, MachineQ’s tech support came through with the answer, but not the specification document. Another critical question of system design is: What is the acceptable Device-to-Gateway ratio? We looked at this with The Things Network (Circuit Cellar 353, December 2019) which was Part 2 of this article series.
SUMMARY
We looked briefly—dare I say in thin slices—at connecting a MachineQ gateway to the cloud (called MQCore) and connecting one off-the-shelf sensor (MQFlex) and a sensor Dev Kit to that gateway. The hardware was sound. The software and the documentation were voluminous, but somewhat scary. Next time—in “LoRa (Part 6): A MachineQ Example Continued” (Circuit Cellar 361, August 2020)—we will dig a little deeper and start making some changes to our sensors. 
RESOURCES
References:
[1] Contigo Travel Mug Care and User Guide https://s7d9.scene7.com/is/content/Ignite/Product%20PDFs/Westloop2.0%20Use%20and%20Care_web_Updated.pdf[2] LoRa (Part 3) February 2020. Circuit Cellar 355, Embedded in Thin Slices column
[3] MQSpark Development Kit https://support.machineq.com/s/article/MQspark-Dev-Kit-Tutorial
[4] ST LoRa Dev Kit https://support.machineq.com/s/article/ST-LoRa-Dev-Kit-Tutorial
[5] Here is a link comparing LoRa and SigFox https://www.link-labs.com/blog/sigfox-vs-lora
[6] For a description of an Arduino shield, look here: https://playground.arduino.cc/Main/SimilarBoards/#goShie
[7] Here is the phone battery I bought https://www.amazon.com/gp/product/B0194WDVHI/ref=ppx_yo_dt_b_asin_title_o01_s00?ie=UTF8&psc=1
[8] Here is a link to the schematics https://www.st.com/content/st_com/en/products/evaluation-tools/product-evaluation-tools/mcu-mpu-eval-tools/stm32-mcu-mpu-eval-tools/stm32-discovery-kits/b-l072z-lrwan1.html
[9] We have used cURL extensively in IoT projects. Here is a description of it: https://en.wikipedia.org/wiki/CURL
[10] This is yet another not easily found interface. https://swagger.machineq.net/#operations-Device-UpdateDevice
[11] Before you use this, you need to be authorized by signing into your MQCentral account. https://swagger.machineq.net
[12] See the .JSON Resource file provided on Circuit Cellar’s article code and files webpage.
[13] This link provides Python code for signing into MQCore allowing you to access your data https://support.machineq.com/s/article/Signing-In-with-MQ-API
[14] This is the link to the webinar introduction to the development kit https://www.st.com/content/st_com/en/about/events/events.html/accelerate-your-lora-implementation-webinar.html
Arm Keil | www.keil.com
MachineQ | www.machineq.com
STMicroelectronics | www.st.com
PUBLISHED IN CIRCUIT CELLAR MAGAZINE • JUNE 2020 #359 – Get a PDF of the issue
Sponsor this Article
Bob Japenga has been designing embedded systems since 1973. From 1988 - 2020, Bob led a small engineering firm specializing in creating a variety of real-time embedded systems. Bob has been awarded 11 patents in many areas of embedded systems and motion control. Now retired, he enjoys building electronic projects with his grandchildren. You can reach him at
Bob@ListeningToGod.org
