An Environmental Monitor You Can Update Over the Air

Last month, we at Blues announced an exciting new feature that allows you to update host firmware over the air: Notecard Outboard Firmware Update.

Notecard Outboard Firmware Update allows you to remotely update host firmware over cellular, and to do so in a way that’s independent of RTOS and programming language.

To show this new feature off, in this article we’re going to build an environmental monitoring project, place it in a remote location, and then see how to use Notecard Outboard Firmware Update to update the host firmware—without having to touch the hardware itself. Pretty cool!

If you follow along to the end, you’ll even have this nice dashboard you can use to impress your friends and family.

Let’s get started.

Hardware

For this project I’m using the new SparkFun Cellular Function Board, which comes prepackaged with a Blues Wireless Cellular Notecard.

The Notecard is a cellular and GPS/GNSS-enabled device-to-cloud data-pump that comes preloaded with 500 MB of data and 10 years of cellular service. The Notecard (as its name implies) will also be the key driver of Notecard Outboard Firmware Update.

The SparkFun Cellular Function Board (the red board above) gives us a convenient way to connect to the Notecard, and to tap into the SparkFun MicroMod ecosystem.

The MicroMod ecosystem makes it easy to use a variety of processors and function boards when building IoT projects. For this project I’m using a MicroMod STM32 Processor for running my code, an Environmental Function Board for its extensive onboard environmental sensors (the main source of data for this project), and a Double Main Board for holding everything.

The cool thing about the MicroMod architecture is everything slots together seamlessly—sort of like putting together the world’s easiest Lego set. Here’s what your hardware should look like with everything assembled.

NOTE: The Notecard also requires an SMA-compatible antenna for connecting to a cellular network, and optionally an SMA passive antenna for working with GPS/GNSS. If you’re unsure which to use, this antenna works great for cellular, and this one works for GPS/GNSS.

With everything assembled, our next tasks are to write firmware that can gather environmental data from the Environmental Function Board, and to then send that data to the cloud over cellular using the Notecard.

To do that, you first need to set up the Notecard's cloud backend, Notehub.

Cloud Setup

One of the great things about the Notecard is it knows how to send data to a cloud backend, Notehub, out of the box. Notehub is a hosted service designed to connect to Notecard devices and synchronize data.

If you’re following along and want to build this project yourself, you’ll need to set up a free account on notehub.io, and create a new project.

After you create the project, make sure you copy your new project’s ProductUID (see screenshot below), as you’ll need that identifier to connect your Notecard to your new Notehub project.

You’ll learn more about Notehub throughout this article, but now that you have the backend set up, let’s next look at the firmware that makes this project work.

Writing the Firmware

This project’s firmware is responsible for gathering environmental data from the Environmental Function Board, and to then send that data to the cloud using the Notecard.

The full firmware for the project is available on GitHub, but we’ll cover the most important parts in this article

We start by including two of the Environmental Board’s onboard sensors: the SHTC3 for measuring temperature and humidity, and the SGP40 for measuring air quality.

#include "SparkFun_SHTC3.h"
SHTC3 SHTC3sensor;

#include "SparkFun_SGP40_Arduino_Library.h"
SGP40 SGP40sensor;

Next, in setup() we initialize the two sensors.

if (SHTC3sensor.begin() != SHTC3_Status_Nominal)
{
  Serial.println(F("SHTC3 not detected. Please check wiring. Freezing..."));
  while (1)
    ; // Do nothing more
}

if (SGP40sensor.begin() == false)
{
  Serial.println(F("SGP40 not detected. Check connections. Freezing..."));
  while (1)
     ; // Do nothing more
}

The initialization is now complete, and you’re ready to use the sensor’s APIs to read environmental data. For example, the following code in loop() prints out relative humidity, temperature, and VOC index (air quality) to the serial log.

void loop()
{
  SHTC3_Status_TypeDef result = SHTC3sensor.update();

  float relativeHumidity = SHTC3sensor.toPercent();
  Serial.print(F("Relative Humidity = "));
  Serial.print(relativeHumidity);

  float temperature = SHTC3sensor.toDegF();
  Serial.print(temperature);
  Serial.print(F(" deg F"));

  float vocIndex = SGP40sensor.getVOCindex();
  Serial.print(F("VOC Index is: "));
  Serial.println(vocIndex);
}

Here’s what the log looks like if you run the code above on your device.

Now that we have sensor data, our next step is to use the Notecard to send our sensor data to the cloud.

We start by including the Notecard’s note-arduino library in our sketch.

#include <Notecard.h>
Notecard notecard;

Next, in setup(), we use the Notecard’s hub.set request to connect the device to a Notehub backend. (If you’re following along, you’ll want to paste in the ProductUID you copied from your Notehub project earlier.)

J *req = notecard.newRequest("hub.set");
if (req != NULL) {
  JAddStringToObject(req, "mode", "continuous");
  JAddStringToObject(req, "product", "YOUR_PRODUCT_UID_GOES_HERE");
  notecard.sendRequest(req);
}

Next, in loop(), we use the same code as before to read the humidity, temperature and VOC index (air quality) from the Function Board.

SHTC3_Status_TypeDef result = SHTC3sensor.update();

float relativeHumidity = SHTC3sensor.toPercent();
Serial.print(F("Relative Humidity = "));
Serial.print(relativeHumidity);

float temperature = SHTC3sensor.toDegF();
Serial.print(temperature);
Serial.print(F(" deg F"));

float vocIndex = SGP40sensor.getVOCindex();
Serial.print(F("VOC Index is: "));
Serial.println(vocIndex);

And finally we send those values to the cloud using the Notecard’s note.add request.

J *req = notecard.newRequest("note.add");
if (req != NULL)
{
  JAddBoolToObject(req, "sync", true);
  JAddStringToObject(req, "file", "readings.qo");
  J *body = JCreateObject();
  if (body != NULL)
  {
    JAddNumberToObject(body, "humidity", relativeHumidity);
    JAddNumberToObject(body, "temperature", temperature);
    JAddNumberToObject(body, "voc_index", vocIndex);
    JAddItemToObject(req, "body", body);
    notecard.sendRequest(req);
  }
}

At this point if you run this code on your device, and visit your project in Notehub, you’ll start seeing events with your data coming in at a regular interval.

NOTE: You can update how frequently your device takes readings by updating the firmware’s UPDATE_PERIOD constant.

With this code in place, I took my device, plugged in a small LiPo battery, and packed everything into a weatherproof enclosure.

Next, I took the device and set it on my deck to gather data for a few days.

Once data started coming in, I used the Blues tutorial for routing data to Datacake to build a custom dashboard for showing the environmental values. Here’s what that dashboard looks like.

And at this point, I was kind of done. I had a environmental monitor project that remotely captured sensor data, sent that data to the cloud, and allowed me to view my data on a cloud dashboard.

But the thing about IoT projects is that the work is never truly done. Although it’d be great if we could put devices in the field and forget about them forever, the reality is that unexpected things do happen in firmware that’s designed to run indefinitely—and no one wants to physically visit a remote device to debug what might have went wrong.

This is the context we had in mind when we developed Notecard Outboard Firmware Update. Let’s look at how it works.

Updating the Firmware

The SparkFun Environmental Function Board has three onboard sensors and we’re currently only using two of them. In this section we’ll look at how to add support for the third sensor remotely using Notecard Outboard Firmware Update.

Notecard Outboard Firmware Update allows you to remotely update host firmware over cellular, and to do so in a way that’s independent of RTOS and programming language. The Notecard controls the firmware update and not the host—meaning you can keep the complexity of the DFU process out of your host firmware, and you can even use the Notecard to recover bricked host devices in the field. Pretty cool!

To see this feature in action you must complete five steps:

• 1) Ensure your hardware is using the required wiring.
• 2) Enable Notecard Outboard Firmware Update on your Notecard.
• 3) Build your new firmware image file.
• 4) Upload your firmware on Notehub.
• 5) Wait for the Notecard to download the firmware, verify it, and perform the update.

1) Ensure your hardware is using the required wiring.

To take advantage of Notecard Outboard Firmware Update you must lay out several connections between the Notecard's AUX pins and your own host MCU's RESET, BOOT, and UART pins.

The SparkFun Cellular Function Board comes with this wiring out of the box, so for this project we’re good to go on this step. But if you’re using a different hardware setup, you can check out the Blues documentation on how to wire everything up.

2) Enable Notecard Outboard Firmware Update on your Notecard.

In order to use Notecard Outboard Firmware Update you must first configure your Notecard to receive firmware updates. To do so, you can run the Notecard's card.dfu request, setting "name" to the architecture of the host (e.g. stm32) and "on" to true.

If you look back at our firmware’s setup() function, you’ll see that it already makes the appropriate request, so we’re good on this step as well.

J *req = notecard.newRequest("card.dfu");
if (req != NULL) {
  // Use "stm32-bi" to target the SparkFun MicroMod STM32
  JAddStringToObject(req, "name", "stm32-bi");
  JAddBoolToObject(req, "on", true);
  notecard.sendRequest(req);
}

3) Build your firmware image file.

With the setup out of the way, we next have to update the firmware itself, and then build a firmware binary that we can send out to the device.

For the code update, recall that we want to add support for the Environmental Board’s third sensor, which is an STC3x sensor that can read CO2 levels from the air.

You can view the full code to use this additional sensor on GitHub, but the most important changes are below.

First, we must add a new include for the third sensor library.

#include "SparkFun_STC3x_Arduino_Library.h"
STC3x STC3xSensor;

Next, we need some new initialization code for the third sensor.

if (STC3xSensor.begin() == false)
{
  Serial.println(F("STC3x not detected. Please check wiring. Freezing..."));
  while (1)
    ; // Do nothing more
}

if (STC3xSensor.setBinaryGas(STC3X_BINARY_GAS_CO2_AIR_25) == false)
{
  Serial.println(F("Could not set the binary gas! Freezing..."));
  while (1)
    ; // Do nothing more
}

And then we need a bit of additional code that performs a read from the third sensor, as well as code that includes that CO2 reading on the Notes we send to Notehub. Here’s a diff that shows the new code in green.

And with that, our coding work is done. If we were using a normal IoT workflow, we’d physically visit our device, plug in a USB cable, and flash the new firmware.

But we’re not using a normal IoT workflow! Instead, with our code changes in place, we next need to generate a binary for this firmware. If you’re using Arduino IDE you can use the Sketch > Export Compiled Binary menu to generate the binary, which you can find in your file system alongside your sketch.

From there you’ll want to use the Notecard CLI’s binpack utility to wrap your binary, which optimizes the build for your device. Here’s the command you’ll want to run for the SparkFun hardware.

notecard -binpack stm32-bi 0x8000000:environmental_monitoring.ino.bin

After the command runs you’ll have a .binpack file ready for uploading to Notehub.

4) Upload your firmware on Notehub.

To actually perform the firmware update you’ll need to return to your Notehub project, and go to the Settings > Firmware page.

Here, you’ll want to upload your firmware binary, making sure to provide a note on what changes you’ve made in this updated version.

Once you’ve uploaded your firmware, return to the devices list, click the Host Firmware tab, select your device, and then click the Update button.

You’ll see a dialog that shows all available firmware that you can send to your host. At this point we only have one new version available, so click Apply on it to start the firmware update process.

5) Wait for the Notecard to download the firmware, verify it, and perform the update.

Once you kick off a firmware update you’ll have to wait for the next device sync for the Notecard to discover the new host firmware.

In our firmware we’ve configured the Notecard to perform a sync every time it takes a sensor reading, which is determined by the firmware’s UPDATE_PERIOD constant.

You can monitor the progress of the firmware update by double clicking your device in your Notehub project and scrolling down to the “Firmware Update Requests” section.

At first, your device will show “Pending device sync”; then it’ll show the progress as your Notecard downloads the updated host firmware over the cellular connection; and then finally it’ll show “Completed” when the Notecard has finished performing the firmware update on your host.

You can also monitor the firmware update progress by looking at your Notehub project’s events. Below you can see my device detecting the firmware update request at 9:59, completing the download at 10:00, and completing the host firmware update at 10:01.

And with the update complete, I could see that my device was running the updated firmware because my events immediately started including new CO2 concentration sensor readings.

As a last step I added CO2 concentration to my Datacake dashboard, which looked like this after I left things running outdoors for a few hours.

And that’s it! In just a few steps you’re able to easily update your firmware over cellular.

Wrapping Up

Notecard Outboard Firmware Update makes it trivial to update to host firmware over the air. In this article I used the feature to add support for a new sensor value, but you could use the same approach to add new features, fix bugs, or add logs to debug issues—all from your desk! You can even use Notehub to update firmware on entire fleets of devices at once.

If you want to learn more, check out our Notecard Outboard Firmware Update documentation guide, which goes into a lot more detail about how the feature works and what you can do with it. And if you have any questions, feel free to reach out in our forum.